Add workspace remote backend hygiene diagnostics (#641)

Author: chubes4

inc/Workspace/WorkspaceHygieneReport.php

@@ -59,6 +59,7 @@ public function workspace_hygiene_report( array $opts = array() ): array|\WP_Err
 		$cleanup       = null;
 		$cleanup_error = null;
 		$locks         = WorkspaceMutationLock::status($this->workspace_path);
+		$remote_backend = $this->build_remote_workspace_backend_report();
 
 		if ( $include_cleanup ) {
 			$cleanup = $this->worktree_cleanup_merged(
@@ -92,6 +93,7 @@ public function workspace_hygiene_report( array $opts = array() ): array|\WP_Err
 			),
 			'worktrees'                 => $worktree_summary,
 			'worktree_status_mode'      => $worktree_status_mode,
+			'remote_backend'            => $remote_backend,
 			'top_repos_by_worktrees'    => $this->top_repos_by_worktree_count($worktrees, 10),
 			'top_repos_by_size'         => $this->top_repos_by_size( (array) ( $size_report['entries'] ?? array() ), 10),
 			'locks'                     => $locks,
@@ -105,12 +107,40 @@ public function workspace_hygiene_report( array $opts = array() ): array|\WP_Err
 						$include_cleanup ? 'Cleanup summary uses inventory-only dry-run detection (--inventory-only --skip-github); no per-worktree git probes or GitHub API lookups are required.' : 'Cleanup dry-run disabled by request.',
 						! empty($worktree_summary['stale_primaries']) ? 'One or more primary checkouts are behind their configured upstream according to local remote refs; refresh before using a primary for verification.' : '',
 						! empty($worktree_summary['base_branch_worktree_count']) ? 'One or more non-primary worktrees have a base branch checked out; gh pr merge --delete-branch can merge remotely but fail local cleanup.' : '',
+						! empty($remote_backend['registered_state']) ? 'Remote workspace state is registered; local checkout commands should fall back to local workspace discovery when the remote backend misses a handle.' : '',
 					)
 				)
 			),
 		);
 	}
 
+	/**
+	 * Summarize the GitHub API remote workspace backend state for diagnostics.
+	 *
+	 * @return array<string,mixed>
+	 */
+	private function build_remote_workspace_backend_report(): array {
+		$available = class_exists(RemoteWorkspaceBackend::class);
+		if ( ! $available ) {
+			return array(
+				'available'        => false,
+				'active'           => false,
+				'registered_state' => false,
+				'mode'             => 'local_git',
+			);
+		}
+
+		$registered_state = RemoteWorkspaceBackend::has_registered_state();
+		$active           = $registered_state ? true : RemoteWorkspaceBackend::should_handle();
+
+		return array(
+			'available'        => true,
+			'active'           => $active,
+			'registered_state' => $registered_state,
+			'mode'             => $active ? 'remote_or_fallback' : 'local_git',
+		);
+	}
+
 	/**
 	 * Run age-gated workspace retention cleanup and return a compact report.
 	 *

tests/smoke-workspace-hygiene-report.php

@@ -66,14 +66,31 @@ function is_wp_error( $value ): bool
         return $value instanceof \WP_Error;
     }
 
-    function get_option( string $name, $default = false )  // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed
+    function get_option( string $name, $default = false )
     {
+        if ('datamachine_code_remote_workspace_state' === $name ) {
+            return array(
+            'repos'     => array(
+            'github-only' => array(
+            'repo' => 'Extra-Chill/github-only',
+            'url'  => 'https://github.com/Extra-Chill/github-only.git',
+            ),
+            ),
+            'worktrees' => array(),
+            );
+        }
+
+        if ('datamachine_worktree_metadata' !== $name ) {
+            return $default;
+        }
+
         return $GLOBALS['__dmc_hygiene_metadata'];
     }
 
     include __DIR__ . '/../inc/Workspace/WorkspaceLockStore.php';
     include __DIR__ . '/../inc/Workspace/WorkspaceMutationLock.php';
     include __DIR__ . '/../inc/Workspace/WorktreeContextInjector.php';
+    include __DIR__ . '/../inc/Workspace/RemoteWorkspaceBackend.php';
     include __DIR__ . '/../inc/Workspace/Workspace.php';
 
     function datamachine_code_hygiene_report_assert( bool $condition, string $message ): void
@@ -157,6 +174,9 @@ public function worktree_list( ?string $repo = null, ?string $state = null, arra
         datamachine_code_hygiene_report_assert(1 === (int) ( $minimal['worktrees']['missing_metadata'] ?? 0 ), 'inventory counts missing metadata from registry only');
         datamachine_code_hygiene_report_assert('alpha' === ( $minimal['top_repos_by_worktrees'][0]['repo'] ?? '' ), 'inventory builds repo count leaders');
         datamachine_code_hygiene_report_assert(1 === (int) ( $minimal['top_repos_by_worktrees'][0]['worktree_count'] ?? 0 ), 'repo count leaders ignore primaries and missing-metadata repo still sorts after alpha');
+        datamachine_code_hygiene_report_assert(true === ( $minimal['remote_backend']['registered_state'] ?? false ), 'hygiene reports registered remote workspace state');
+        datamachine_code_hygiene_report_assert('remote_or_fallback' === ( $minimal['remote_backend']['mode'] ?? '' ), 'hygiene reports remote backend fallback mode');
+        datamachine_code_hygiene_report_assert(in_array('Remote workspace state is registered; local checkout commands should fall back to local workspace discovery when the remote backend misses a handle.', $minimal['notes'] ?? array(), true), 'hygiene notes remote backend local fallback expectation');
 
         echo "\n[1a] Size report exposes top offenders and kind grouping\n";
         $with_sizes = $workspace->workspace_hygiene_report(