fix: fail closed on unverified worktree freshness (#756)

Co-authored-by: homeboy-ci[bot] <266378653+homeboy-ci[bot]@users.noreply.github.com>

Author: chubes4

inc/Abilities/WorkspaceAbilities.php

@@ -1283,7 +1283,7 @@ private function registerAbilities(): void {
 				'datamachine-code/workspace-worktree-add',
 				array(
 					'label'               => 'Add Workspace Worktree',
-					'description'         => 'Create a git worktree for a branch under `<repo>@<branch-slug>`. Branches are created off the supplied `from` ref (default `origin/HEAD`) when they do not yet exist locally. When `inject_context` is true (default), the originating site\'s composed AGENTS.md is made visible to OpenCode: symlinked into the worktree root when no repo-owned AGENTS.md exists, otherwise added via local OpenCode instructions so both files load. Site agent memory is snapshotted into `.claude/CLAUDE.local.md`, and injected paths are added to the worktree\'s per-checkout `info/exclude`. When `bootstrap` is true (default), submodule init plus root or one-level nested package-manager/composer installs run after creation so the worktree is immediately test/build-ready; set false to create a bare checkout.',
+					'description'         => 'Create a git worktree for a branch under `<repo>@<branch-slug>`. Branches are created off the supplied `from` ref (default `origin/HEAD`) when they do not yet exist locally. Creation fails closed when remote freshness cannot be verified; set `allow_unverified_freshness=true` only for intentional offline work. When `inject_context` is true (default), the originating site\'s composed AGENTS.md is made visible to OpenCode: symlinked into the worktree root when no repo-owned AGENTS.md exists, otherwise added via local OpenCode instructions so both files load. Site agent memory is snapshotted into `.claude/CLAUDE.local.md`, and injected paths are added to the worktree\'s per-checkout `info/exclude`. When `bootstrap` is true (default), submodule init plus root or one-level nested package-manager/composer installs run after creation so the worktree is immediately test/build-ready; set false to create a bare checkout.',
 					'category'            => 'datamachine-code-workspace',
 					'input_schema'        => array(
 						'type'       => 'object',
@@ -1312,6 +1312,10 @@ private function registerAbilities(): void {
 								'type'        => 'boolean',
 								'description' => 'Bypass the staleness gate. When false (default), any branch/base behind the remote default branch is refused, and a new worktree more than `datamachine_worktree_stale_threshold` commits behind upstream is rolled back with a staleness error. Set true to opt in to a known-stale checkout.',
 							),
+							'allow_unverified_freshness' => array(
+								'type'        => 'boolean',
+								'description' => 'Bypass the fetch-failure freshness gate. When false (default), worktree creation is refused if remote freshness cannot be verified. Set true only for intentional offline work with local refs.',
+							),
 							'rebase_base'    => array(
 								'type'        => 'boolean',
 								'description' => 'After creating the worktree, rebase onto the upstream tip (the branch\'s @{upstream} for existing branches, origin/<base> for new branches off a local base). Default false. On rebase conflicts the rebase is aborted; the worktree stays at its pre-rebase state and `rebase_succeeded: false` is surfaced.',
@@ -1354,7 +1358,7 @@ private function registerAbilities(): void {
 							),
 							'fetch_failed'              => array(
 								'type'        => 'boolean',
-								'description' => 'Present only when the pre-create `git fetch origin` failed. Worktree creation continues either way; staleness fields are omitted when true.',
+								'description' => 'Present only when the pre-create `git fetch origin` failed and allow_unverified_freshness=true allowed creation to continue. Staleness fields are omitted when true.',
 							),
 							'fetch_error'               => array(
 								'type'        => 'string',
@@ -3535,6 +3539,8 @@ public static function worktreeAdd( array $input ): array|\WP_Error {
 		$bootstrap = array_key_exists('bootstrap', $input) ? (bool) $input['bootstrap'] : true;
 		// Default allow_stale=false (gate enforced); only true when explicitly opted in.
 		$allow_stale = array_key_exists('allow_stale', $input) ? (bool) $input['allow_stale'] : false;
+		// Default allow_unverified_freshness=false (fetch-failure gate enforced).
+		$allow_unverified_freshness = array_key_exists('allow_unverified_freshness', $input) ? (bool) $input['allow_unverified_freshness'] : false;
 		// Default rebase_base=false; only true when explicitly requested.
 		$rebase_base = array_key_exists('rebase_base', $input) ? (bool) $input['rebase_base'] : false;
 		$force       = ! empty($input['force']);
@@ -3557,7 +3563,8 @@ public static function worktreeAdd( array $input ): array|\WP_Error {
 				$allow_stale,
 				$rebase_base,
 				$force,
-				$task
+				$task,
+				$allow_unverified_freshness
 			);
 		}
 
@@ -3581,7 +3588,8 @@ public static function worktreeAdd( array $input ): array|\WP_Error {
 			$allow_stale,
 			$rebase_base,
 			$force,
-			$task
+			$task,
+			$allow_unverified_freshness
 		);
 	}
 

inc/Cli/Commands/WorkspaceCommand.php

@@ -3248,20 +3248,28 @@ private function renderGitOperationResult( string $operation, array $result, arr
 	 *   read use (faster, no deps installed). The ability-level input is
 	 *   `bootstrap=false`; this flag is the CLI shorthand (matches the
 	 *   existing `--skip-context-injection` convention).
-	 *
-	 * [--allow-stale]
-	 * : Bypass the staleness gate (applies to `add` only). By default,
-	 *   `worktree add` refuses any branch/base that is behind the remote
-	 *   default branch after fetch, and refuses to return a worktree that
-	 *   would be more than
-	 *   `datamachine_worktree_stale_threshold` commits (default 50) behind
-	 *   upstream — the stale checkout is torn down and a `worktree_stale`
-	 *   error is returned with remediation options. Pass `--allow-stale` to
-	 *   opt in to a known-stale checkout. Default-branch freshness is
-	 *   zero-tolerance: one missing default-branch commit is stale. The
-	 *   ability-level input is
-	 *   `allow_stale=true`.
-	 *
+		 *
+		 * [--allow-stale]
+		 * : Bypass the staleness gate (applies to `add` only). By default,
+		 *   `worktree add` refuses any branch/base that is behind the remote
+		 *   default branch after fetch, fails closed when fetch cannot verify
+		 *   remote freshness, and refuses to return a worktree that
+		 *   would be more than
+		 *   `datamachine_worktree_stale_threshold` commits (default 50) behind
+		 *   upstream — the stale checkout is torn down and a `worktree_stale`
+		 *   error is returned with remediation options. Pass `--allow-stale` to
+		 *   opt in to a known-stale checkout. Default-branch freshness is
+		 *   zero-tolerance: one missing default-branch commit is stale. The
+		 *   ability-level input is
+		 *   `allow_stale=true`.
+		 *
+		 * [--allow-unverified-freshness]
+		 * : Bypass the fetch-failure freshness gate (applies to `add` only).
+		 *   By default, `worktree add` refuses to create a checkout when `git fetch`
+		 *   fails because remote freshness cannot be verified. Use this only for
+		 *   intentional offline work with local refs. The ability-level input is
+		 *   `allow_unverified_freshness=true`.
+		 *
 	 * [--rebase-base]
 	 * : After creating the worktree, rebase onto the upstream tip (applies
 	 *   to `add` only). For existing branches this is `@{upstream}`; for
@@ -3534,11 +3542,14 @@ private function renderGitOperationResult( string $operation, array $result, arr
 	 *
 	 *     # Create a bare worktree (skip the default bootstrap pass)
 	 *     wp datamachine-code workspace worktree add data-machine fix/foo --skip-bootstrap
-	 *
-	 *     # Proceed with a known-stale base/branch (bypass the staleness gate)
-	 *     wp datamachine-code workspace worktree add data-machine fix/foo --allow-stale
-	 *
-	 *     # Auto-rebase onto upstream after creation
+		 *
+		 *     # Proceed with a known-stale base/branch (bypass the staleness gate)
+		 *     wp datamachine-code workspace worktree add data-machine fix/foo --allow-stale
+		 *
+		 *     # Proceed intentionally while offline when fetch cannot verify freshness
+		 *     wp datamachine-code workspace worktree add data-machine fix/foo --allow-unverified-freshness
+		 *
+		 *     # Auto-rebase onto upstream after creation
 	 *     wp datamachine-code workspace worktree add data-machine fix/foo --rebase-base
 	 *
 	 *     # Re-read the originating site's agent memory into an existing worktree
@@ -3653,7 +3664,7 @@ public function worktree( array $args, array $assoc_args ): void {
 		switch ( $operation ) {
 			case 'add':
 				if ( empty($args[1]) || empty($args[2]) ) {
-					WP_CLI::error('Usage: worktree add <repo> <branch> [--from=<ref>|--base=<ref>|--base-ref=<ref>|--base-branch=<branch>] [--skip-context-injection] [--skip-bootstrap] [--allow-stale] [--rebase-base] [--force]');
+					WP_CLI::error('Usage: worktree add <repo> <branch> [--from=<ref>|--base=<ref>|--base-ref=<ref>|--base-branch=<branch>] [--skip-context-injection] [--skip-bootstrap] [--allow-stale] [--allow-unverified-freshness] [--rebase-base] [--force]');
 					return;
 				}
 				$input['repo']    = $args[1];
@@ -3685,6 +3696,8 @@ public function worktree( array $args, array $assoc_args ): void {
 				$input['bootstrap'] = empty($assoc_args['skip-bootstrap']);
 				// --allow-stale opts in to a known-stale worktree (default: gate enforced).
 				$input['allow_stale'] = ! empty($assoc_args['allow-stale']);
+				// --allow-unverified-freshness opts in when fetch cannot verify remote refs.
+				$input['allow_unverified_freshness'] = ! empty($assoc_args['allow-unverified-freshness']);
 				// --rebase-base auto-rebases onto upstream after creation (default: off).
 				$input['rebase_base'] = ! empty($assoc_args['rebase-base']);
 				// --force is an explicit disk-budget override for add.

inc/Tools/WorkspaceTools.php

@@ -560,7 +560,7 @@ public function handleWorktreeAdd( array $parameters ): array
             }
         }
 
-        foreach ( array( 'inject_context', 'bootstrap', 'allow_stale', 'rebase_base', 'force' ) as $key ) {
+        foreach ( array( 'inject_context', 'bootstrap', 'allow_stale', 'allow_unverified_freshness', 'rebase_base', 'force' ) as $key ) {
             if (array_key_exists($key, $parameters) ) {
                 $input[ $key ] = (bool) $parameters[ $key ];
             }
@@ -1414,7 +1414,8 @@ public function getWorktreeAddDefinition(): array
             'from'           => array( 'type' => 'string', 'description' => 'Base ref when creating the branch. Defaults to origin/HEAD.' ),
             'inject_context' => array( 'type' => 'boolean', 'description' => 'Inject originating agent context into the worktree. Default true.' ),
             'bootstrap'      => array( 'type' => 'boolean', 'description' => 'Run detected bootstrap steps after creation. Default true.' ),
-            'allow_stale'    => array( 'type' => 'boolean', 'description' => 'Bypass the staleness gate. Default false.' ),
+            'allow_stale'    => array( 'type' => 'boolean', 'description' => 'Bypass the verified staleness gate. Default false.' ),
+            'allow_unverified_freshness' => array( 'type' => 'boolean', 'description' => 'Bypass fetch-failure freshness verification for intentional offline work. Default false.' ),
             'rebase_base'    => array( 'type' => 'boolean', 'description' => 'Rebase the worktree onto the upstream tip after creation. Default false.' ),
             'force'          => array( 'type' => 'boolean', 'description' => 'Bypass disk-budget refusal threshold. Default false.' ),
             'task_url'       => array( 'type' => 'string', 'description' => 'Optional task or issue URL to record on the worktree.' ),

inc/Workspace/WorkspaceWorktreeLifecycle.php

@@ -41,6 +41,10 @@ trait WorkspaceWorktreeLifecycle {
 	 * Pass `$bootstrap = false` (or `--no-bootstrap` on the CLI) for a bare
 	 * checkout when you only need to read code on that branch.
 	 *
+	 * When remote freshness cannot be verified, worktree creation is refused
+	 * unless `$allow_unverified_freshness` is set. This keeps default operation
+	 * fail-closed while preserving intentional offline workflows.
+	 *
 	 * When the branch/base is behind the remote default branch, worktree
 	 * creation is refused unless `$allow_stale` is set. This check is
 	 * zero-tolerance: any default-branch commits missing from the requested
@@ -64,9 +68,11 @@ trait WorkspaceWorktreeLifecycle {
 	 * @param  bool        $allow_stale    Bypass the staleness gate (default false).
 	 * @param  bool        $rebase_base    Rebase onto upstream after creation (default false).
 	 * @param  bool        $force          Bypass the disk-budget refusal threshold (default false).
+	 * @param  array       $task           Optional task metadata recorded on the worktree.
+	 * @param  bool        $allow_unverified_freshness Bypass fetch-failure freshness verification (default false).
 	 * @return array{success: bool, handle: string, path: string, branch: string, slug: string, created_branch: bool, message: string, disk_budget?: array, context_injected?: bool, context_files?: string[], context_skip_reason?: string, bootstrap?: array, fetch_failed?: bool, fetch_error?: string, stale_commits_behind?: int, upstream?: string, base_stale_commits_behind?: int, base_upstream?: string, default_branch_commits_behind?: int, default_branch_ref?: string, gate_threshold?: int, rebase_attempted?: bool, rebase_succeeded?: bool, rebase_error?: string, rebase_target?: string}|\WP_Error
 	 */
-	public function worktree_add( string $repo, string $branch, ?string $from = null, bool $inject_context = true, bool $bootstrap = true, bool $allow_stale = false, bool $rebase_base = false, bool $force = false, array $task = array() ): array|\WP_Error {
+	public function worktree_add( string $repo, string $branch, ?string $from = null, bool $inject_context = true, bool $bootstrap = true, bool $allow_stale = false, bool $rebase_base = false, bool $force = false, array $task = array(), bool $allow_unverified_freshness = false ): array|\WP_Error {
 		$visible = $this->require_workspace_visible();
 		if ( null !== $visible ) {
 			return $visible;
@@ -146,7 +152,8 @@ public function worktree_add( string $repo, string $branch, ?string $from = null
 				$wt_handle,
 				$wt_path,
 				$primary_path,
-				$task
+				$task,
+				$allow_unverified_freshness
 			)
 		);
 
@@ -207,6 +214,8 @@ public function worktree_add( string $repo, string $branch, ?string $from = null
 	 * @param  string      $wt_handle      Worktree handle.
 	 * @param  string      $wt_path        Worktree path.
 	 * @param  string      $primary_path   Primary checkout path.
+	 * @param  array       $task           Optional task metadata recorded on the worktree.
+	 * @param  bool        $allow_unverified_freshness Bypass fetch-failure freshness verification.
 	 * @return array|\WP_Error
 	 */
 	private function worktree_add_locked(
@@ -220,18 +229,31 @@ private function worktree_add_locked(
 		string $wt_handle,
 		string $wt_path,
 		string $primary_path,
-		array $task = array()
+		array $task = array(),
+		bool $allow_unverified_freshness = false
 	): array|\WP_Error {
 		if ( is_dir($wt_path) ) {
 			return new \WP_Error('worktree_exists', sprintf('Worktree handle "%s" already exists.', $wt_handle), array( 'status' => 400 ));
 		}
 
 		// Always fetch first so staleness data (and the default base) reflects the
-		// current remote. Failure is logged but never aborts — offline work should
-		// still be possible, the agent just needs to know staleness is unknown.
+		// current remote. If fetch fails, default to fail-closed unless the caller
+		// explicitly opts into unverified/offline freshness.
 		$fetch        = WorktreeStalenessProbe::fetch($primary_path);
 		$fetch_failed = ! $fetch['ok'];
 		$fetch_error  = $fetch['error'] ?? null;
+		if ( $fetch_failed && ! $allow_unverified_freshness ) {
+			return new \WP_Error(
+				'worktree_freshness_unverified',
+				'Refusing to create worktree because remote freshness could not be verified. Retry after connectivity is restored, or pass allow_unverified_freshness=true only when intentionally working offline with stale local refs.',
+				array(
+					'status'                     => 409,
+					'fetch_failed'               => true,
+					'fetch_error'                => $fetch_error,
+					'allow_unverified_freshness' => false,
+				)
+			);
+		}
 
 		// Does the branch already exist locally?
      // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.system_calls_exec

tests/worktree-add-lifecycle.php

@@ -238,6 +238,18 @@ function create_primary_checkout( string $workspace_root ): void {
 	assert_true('worktree_inventory_persist_failed' === $failed->get_error_code(), 'unexpected persistence failure error code');
 	assert_true(! is_dir($workspace_root . '/homeboy@audit-primitives-persist-fails'), 'failed persistence left a worktree directory behind');
 
+	$GLOBALS['wpdb'] = new Datamachine_Code_Test_Wpdb();
+	run_command('git remote set-url origin ' . escapeshellarg($workspace_root . '/missing-origin.git'), $workspace_root . '/homeboy');
+	$fetch_failed_default = $workspace->worktree_add('homeboy', 'audit-primitives-fetch-fails', 'origin/main', false, false, false, false, true);
+	assert_true(is_wp_error($fetch_failed_default), 'fetch failure reported success without explicit opt-in');
+	assert_true('worktree_freshness_unverified' === $fetch_failed_default->get_error_code(), 'unexpected fetch failure error code');
+	assert_true(! is_dir($workspace_root . '/homeboy@audit-primitives-fetch-fails'), 'fetch failure left a worktree directory behind');
+
+	$fetch_failed_allowed = $workspace->worktree_add('homeboy', 'audit-primitives-fetch-fails-allowed', 'origin/main', false, false, false, false, true, array(), true);
+	assert_true(! is_wp_error($fetch_failed_allowed), is_wp_error($fetch_failed_allowed) ? $fetch_failed_allowed->get_error_message() : 'fetch failure opt-in failed');
+	assert_true(! empty($fetch_failed_allowed['fetch_failed']), 'fetch failure opt-in did not surface fetch_failed');
+	assert_true(is_dir($fetch_failed_allowed['path']), 'fetch failure opt-in worktree path is not accessible');
+
 	remove_tree($workspace_root);
 	fwrite(STDOUT, "worktree-add-lifecycle ok\n");
 } catch (Throwable $e) {