feat: add targeted worktree safety lookup

Author: homeboy-ci[bot]

inc/Abilities/WorkspaceAbilities.php

@@ -1764,6 +1764,10 @@ private function registerAbilities(): void {
 								'type'        => 'string',
 								'description' => 'Optional repo name to limit the list.',
 							),
+							'handle'         => array(
+								'type'        => 'string',
+								'description' => 'Optional exact worktree handle. Filters before status and disk probes.',
+							),
 							'state'          => array(
 								'type'        => 'string',
 								'description' => 'Optional lifecycle state filter.',
@@ -4006,6 +4010,7 @@ public static function worktreeList( array $input ): array|\WP_Error {
 		$opts = array(
 			'include_status' => array_key_exists('include_status', $input) ? (bool) $input['include_status'] : false,
 			'include_disk'   => array_key_exists('include_disk', $input) ? (bool) $input['include_disk'] : false,
+			'handle'         => isset($input['handle']) ? (string) $input['handle'] : '',
 		);
 
 		return $workspace->worktree_list($repo, $state, $opts);

inc/Cli/Commands/WorkspaceCommand.php

@@ -43,6 +43,7 @@ class WorkspaceCommand extends BaseCommand {
 	private const WORKTREE_OPERATIONS = array(
 		'add'                                     => array( 'ability' => 'datamachine-code/workspace-worktree-add' ),
 		'list'                                    => array( 'ability' => 'datamachine-code/workspace-worktree-list' ),
+		'get'                                     => array( 'ability' => 'datamachine-code/workspace-worktree-list' ),
 		'remove'                                  => array( 'ability' => 'datamachine-code/workspace-worktree-remove' ),
 		'prune'                                   => array( 'ability' => 'datamachine-code/workspace-worktree-prune' ),
 		'cleanup'                                 => array( 'ability' => 'datamachine-code/workspace-worktree-cleanup' ),
@@ -3872,7 +3873,7 @@ public function worktree( array $args, array $assoc_args ): void {
 		$operation = $args[0] ?? '';
 
 		if ( '' === $operation ) {
-			WP_CLI::error('Usage: wp datamachine-code workspace worktree <add|list|remove|prune|locks|cleanup|cleanup-artifacts|abandoned|bounded-cleanup-eligible-apply|cleanup-eligible-drain|emergency-cleanup|reconcile-metadata|backfill-origin-session|active-no-signal-report|active-no-signal-finalized-apply|active-no-signal-equivalent-clean-apply|active-no-signal-merged-apply|active-no-signal-remote-clean-apply|active-no-signal-drain|refresh-context|finalize|mark-cleanup-eligible> [<repo>] [<branch>] [--flags]');
+			WP_CLI::error('Usage: wp datamachine-code workspace worktree <add|get|list|remove|prune|locks|cleanup|cleanup-artifacts|abandoned|bounded-cleanup-eligible-apply|cleanup-eligible-drain|emergency-cleanup|reconcile-metadata|backfill-origin-session|active-no-signal-report|active-no-signal-finalized-apply|active-no-signal-equivalent-clean-apply|active-no-signal-merged-apply|active-no-signal-remote-clean-apply|active-no-signal-drain|refresh-context|finalize|mark-cleanup-eligible> [<repo>] [<branch>] [--flags]');
 			return;
 		}
 
@@ -4060,6 +4061,16 @@ public function worktree( array $args, array $assoc_args ): void {
 				$input['include_disk']   = $want_disk;
 				break;
 
+			case 'get':
+				if ( empty($args[1]) ) {
+					WP_CLI::error('Usage: worktree get <handle> [--with-status] [--format=json]');
+					return;
+				}
+				$input['handle']         = (string) $args[1];
+				$input['include_status'] = true;
+				$input['include_disk']   = false;
+				break;
+
 			case 'remove':
 				// Accept either the two-arg `<repo> <branch>` form or a single
 				// `<repo>@<branch-slug>` handle (as printed by `list`/`path`/cleanup
@@ -4512,6 +4523,7 @@ private function renderWorktreeResult( string $operation, array $result, array $
 		}
 
 		switch ( $operation ) {
+			case 'get':
 			case 'list':
 				$worktrees = $result['worktrees'] ?? array();
 				if ( ! empty($assoc_args['stale']) ) {

inc/Workspace/WorkspaceWorktreeLifecycle.php

@@ -767,6 +767,10 @@ public function worktree_refresh_context( string $handle ): array|\WP_Error {
 	public function worktree_list( ?string $repo = null, ?string $state = null, array $opts = array() ): array|\WP_Error {
 		$include_status = array_key_exists('include_status', $opts) ? (bool) $opts['include_status'] : true;
 		$include_disk   = array_key_exists('include_disk', $opts) ? (bool) $opts['include_disk'] : true;
+		$handle         = isset($opts['handle']) ? trim( (string) $opts['handle']) : '';
+		if ( '' !== $handle && null === $repo ) {
+			$repo = str_contains($handle, '@') ? strstr($handle, '@', true) : $handle;
+		}
 
 		$skipped_groups = array();
 		if ( ! $include_status ) {
@@ -841,6 +845,9 @@ public function worktree_list( ?string $repo = null, ?string $state = null, arra
 					// Show the absolute path so it is still useful, even though it has no `<repo>@<slug>` handle.
 					$handle = $wt['path'];
 				}
+				if ( '' !== (string) ( $opts['handle'] ?? '' ) && $handle !== (string) $opts['handle'] ) {
+					continue;
+				}
 
 				if ( $include_status ) {
 					$dirty_result = $this->run_git($wt['path'], 'status --porcelain');

tests/worktree-add-lifecycle.php

@@ -271,6 +271,18 @@ function create_primary_checkout( string $workspace_root ): void {
 	$list    = $workspace->worktree_list('homeboy', null, array( 'include_status' => false, 'include_disk' => false ));
 	$handles = array_map(static fn( array $row ): string => (string) $row['handle'], $list['worktrees'] ?? array());
 	assert_true(in_array('homeboy@audit-primitives-20260616', $handles, true), 'persisted worktree is not visible to worktree_list');
+	$targeted = $workspace->worktree_list(
+		null,
+		null,
+		array(
+			'handle'         => 'homeboy@audit-primitives-20260616',
+			'include_status' => true,
+			'include_disk'   => false,
+		)
+	);
+	assert_true(1 === count($targeted['worktrees'] ?? array()), 'targeted worktree lookup returned unrelated rows');
+	assert_true('homeboy@audit-primitives-20260616' === ( $targeted['worktrees'][0]['handle'] ?? '' ), 'targeted worktree lookup returned the wrong handle');
+	assert_true(null !== ( $targeted['worktrees'][0]['dirty'] ?? null ), 'targeted worktree lookup did not run the requested status probe');
 
 	update_option(
 		'datamachine_code_remote_workspace_state',