feat(workspace): gate stale worktree creation + opt-in rebase (#54)

chubes4 · web-flow · commit c0cc6dd595c9 · 2026-04-24T13:11:18.000-04:00
Closes #52 Builds on #53's non-breaking staleness signal. `worktree add` now refuses to materialize a worktree that would be more than `datamachine_worktree_stale_threshold` commits (default 50) behind its upstream, tearing the half-cooked checkout down and returning a `worktree_stale` WP_Error with remediation options. Pass `--allow-stale` to opt in, or `--rebase-base` to auto-rebase onto the upstream tip before returning. On rebase conflicts the rebase is aborted — `--rebase-base` is not a silent bypass. ## Behavior change Previously: `worktree add` happily cooked on top of any local branch, no matter how stale. Agents discovered multi-hundred-commit drift at PR-review time when GitHub flagged conflicts. Now: by default, a worktree that would land >50 commits behind upstream is rolled back at create-time with a WP_Error pointing at four concrete remediation paths: Worktree base is 51 commits behind origin/main (threshold: 50). Options: - workspace git-pull data-machine-code --allow-primary-mutation - worktree add … --from=origin/main - worktree add … --rebase-base - worktree add … --allow-stale Threshold is filterable per-site/per-repo via `datamachine_worktree_stale_threshold`. ## Rebase semantics `--rebase-base` picks the right target per path: - Existing-local-branch: rebase onto `@{upstream}` - New-branch-off-local-base: rebase onto `origin/<base>` Success clears the behind-count (worktree passes the gate cleanly). Failure aborts the rebase, the worktree stays at its pre-rebase HEAD, and `rebase_succeeded: false` + `rebase_error: <tail>` are surfaced. Critically, the staleness gate STILL fires after a failed rebase — `--rebase-base` alone on a conflicting rebase isn't a silent `--allow-stale` bypass. ## Changes - `Workspace::worktree_add()` — new `$allow_stale` + `$rebase_base` params. Rebase runs before the gate (success nullifies gate). Gate runs after staleness probe, computes filterable threshold, tears the worktree down + returns WP_Error on violation. - `effective_behind_count()` helper — picks the one behind-count that matters for gating (existing-branch or new-branch-off-local-base, whichever is present). - `try_rebase_worktree()` helper — selects upstream target, runs rebase, aborts on failure, zeroes the relevant behind-count on success. - `WorkspaceAbilities` — input schema gains `allow_stale` + `rebase_base` (both default false). Output schema gains `gate_threshold`, `rebase_attempted`, `rebase_target`, `rebase_succeeded`, `rebase_error`. - `WorkspaceCommand` — new `--allow-stale` + `--rebase-base` flags with full help blocks + examples. `render_worktree_freshness()` gains a rebase block that renders BEFORE staleness (success: "rebased onto <target>", failure: "⚠ rebase onto <target> failed" + error tail). - `tests/smoke-worktree-staleness.php` — 7 new real-git-fixture assertions for rebase success (branch 2 behind → 0 behind after rebase, consumer commit preserved) and rebase conflict handling (non-zero exit, abort restores pre-rebase SHA, behind-count preserved).
diff --git a/inc/Abilities/WorkspaceAbilities.php b/inc/Abilities/WorkspaceAbilities.php
@@ -731,6 +731,14 @@ private function registerAbilities(): void {
 								'type'        => 'boolean',
 								'description' => 'Run detected bootstrap steps (submodule init, package-manager install, composer install) after creating the worktree. Default true. Steps are skipped gracefully when their trigger file or tool is missing. Set false for a bare checkout (e.g. when only reading code).',
 							),
+							'allow_stale'    => array(
+								'type'        => 'boolean',
+								'description' => 'Bypass the staleness gate. When false (default) and the new worktree would be more than `datamachine_worktree_stale_threshold` commits behind upstream, worktree creation is rolled back and a `worktree_stale` error is returned. Set true to opt in to a known-stale checkout.',
+							),
+							'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.',
+							),
 						),
 						'required'   => array( 'repo', 'branch' ),
 					),
@@ -779,6 +787,26 @@ private function registerAbilities(): void {
 								'type'        => 'string',
 								'description' => 'Paired with base_stale_commits_behind: the origin ref the local base was compared against (e.g. `origin/main`).',
 							),
+							'gate_threshold'      => array(
+								'type'        => 'integer',
+								'description' => 'Echo of the staleness threshold (in commits) that was evaluated. Present whenever the gate ran (i.e. `allow_stale` was false and fetch succeeded).',
+							),
+							'rebase_attempted'    => array(
+								'type'        => 'boolean',
+								'description' => 'Set when `rebase_base=true` AND there was meaningful staleness to rebase over. Absent when rebase was not requested or there was nothing to do.',
+							),
+							'rebase_target'       => array(
+								'type'        => 'string',
+								'description' => 'Paired with `rebase_attempted`: the ref the worktree was rebased onto (e.g. `@{upstream}` or `origin/main`).',
+							),
+							'rebase_succeeded'    => array(
+								'type'        => 'boolean',
+								'description' => 'Paired with `rebase_attempted`: true when the rebase landed cleanly, false when it hit conflicts and was aborted.',
+							),
+							'rebase_error'       => array(
+								'type'        => 'string',
+								'description' => 'Present only when `rebase_succeeded=false`. Trimmed error output from the failing rebase.',
+							),
 						),
 					),
 					'execute_callback'    => array( self::class, 'worktreeAdd' ),
@@ -1215,12 +1243,18 @@ public static function worktreeAdd( array $input ): array|\WP_Error {
 		$inject_context = array_key_exists( 'inject_context', $input ) ? (bool) $input['inject_context'] : true;
 		// Default bootstrap=true; only false when explicitly provided.
 		$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 rebase_base=false; only true when explicitly requested.
+		$rebase_base = array_key_exists( 'rebase_base', $input ) ? (bool) $input['rebase_base'] : false;
 		return $workspace->worktree_add(
 			$input['repo'] ?? '',
 			$input['branch'] ?? '',
 			$input['from'] ?? null,
 			$inject_context,
-			$bootstrap
+			$bootstrap,
+			$allow_stale,
+			$rebase_base
 		);
 	}
 
diff --git a/inc/Cli/Commands/WorkspaceCommand.php b/inc/Cli/Commands/WorkspaceCommand.php
@@ -920,6 +920,24 @@ private function renderGitOperationResult( string $operation, array $result, arr
 	 *   `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 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. The ability-level input is
+	 *   `allow_stale=true`.
+	 *
+	 * [--rebase-base]
+	 * : After creating the worktree, rebase onto the upstream tip (applies
+	 *   to `add` only). For existing branches this is `@{upstream}`; for
+	 *   new branches cut off a local base this is `origin/<base>`. On
+	 *   rebase conflicts the rebase is aborted and the worktree stays at
+	 *   its pre-rebase state — `--rebase-base` is not a silent
+	 *   `--allow-stale` bypass. The ability-level input is
+	 *   `rebase_base=true`.
+	 *
 	 * [--force]
 	 * : Force-remove a worktree even if it is dirty (applies to `remove` and
 	 *   `cleanup`). Does NOT override the unpushed-commits safety in cleanup.
@@ -976,6 +994,12 @@ private function renderGitOperationResult( string $operation, array $result, arr
 	 *     # Create a bare worktree (skip the default bootstrap pass)
 	 *     wp datamachine workspace worktree add data-machine fix/foo --skip-bootstrap
 	 *
+	 *     # Proceed with a known-stale base (bypass the staleness gate)
+	 *     wp datamachine workspace worktree add data-machine fix/foo --allow-stale
+	 *
+	 *     # Auto-rebase onto upstream after creation
+	 *     wp datamachine workspace worktree add data-machine fix/foo --rebase-base
+	 *
 	 *     # Re-read the originating site's agent memory into an existing worktree
 	 *     wp datamachine workspace worktree refresh-context data-machine@fix-foo
 	 *
@@ -1015,7 +1039,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>] [--skip-context-injection] [--skip-bootstrap]' );
+					WP_CLI::error( 'Usage: worktree add <repo> <branch> [--from=<ref>] [--skip-context-injection] [--skip-bootstrap] [--allow-stale] [--rebase-base]' );
 					return;
 				}
 				$input['repo']   = $args[1];
@@ -1027,6 +1051,10 @@ public function worktree( array $args, array $assoc_args ): void {
 				$input['inject_context'] = empty( $assoc_args['skip-context-injection'] );
 				// --skip-bootstrap disables the default-on bootstrap step.
 				$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'] );
+				// --rebase-base auto-rebases onto upstream after creation (default: off).
+				$input['rebase_base'] = ! empty( $assoc_args['rebase-base'] );
 				break;
 
 			case 'refresh-context':
@@ -1218,6 +1246,7 @@ private function renderWorktreeResult( string $operation, array $result, array $
 	 *
 	 * States, in priority order:
 	 *   - fetch_failed=true         → `⚠ fetch failed — staleness unknown` (warning)
+	 *   - rebase_attempted=true     → success or conflict status (log or warning)
 	 *   - stale_commits_behind>0    → `⚠ <N> commits behind <upstream>` (warning + rebase hint)
 	 *   - base_stale_commits_behind>0 → `⚠ base was <N> commits behind <base_upstream>` (warning + rebase hint)
 	 *   - otherwise                 → `Freshness: up to date` (log)
@@ -1239,6 +1268,24 @@ private function render_worktree_freshness( array $result ): void {
 			return;
 		}
 
+		if ( ! empty( $result['rebase_attempted'] ) ) {
+			$target = isset( $result['rebase_target'] ) ? (string) $result['rebase_target'] : 'upstream';
+			if ( ! empty( $result['rebase_succeeded'] ) ) {
+				WP_CLI::log( sprintf( 'Freshness: rebased onto %s', $target ) );
+				// Fall through in case either behind-count is still set (e.g. the
+				// "other" path's metadata is present but zeroed). Renderer below
+				// handles the 0-case correctly.
+			} else {
+				$msg = sprintf( 'Freshness: ⚠ rebase onto %s failed — worktree stayed at pre-rebase HEAD', $target );
+				if ( ! empty( $result['rebase_error'] ) ) {
+					$msg .= "\n  " . $result['rebase_error'];
+				}
+				WP_CLI::warning( $msg );
+				// Staleness block below will still fire with the pre-rebase
+				// behind-count so the agent sees exactly how stale it is.
+			}
+		}
+
 		if ( isset( $result['stale_commits_behind'] ) ) {
 			$behind   = (int) $result['stale_commits_behind'];
 			$upstream = isset( $result['upstream'] ) ? (string) $result['upstream'] : 'upstream';
diff --git a/inc/Workspace/Workspace.php b/inc/Workspace/Workspace.php
@@ -871,14 +871,26 @@ public function git_diff( string $name, ?string $from = null, ?string $to = null
 	 * Pass `$bootstrap = false` (or `--no-bootstrap` on the CLI) for a bare
 	 * checkout when you only need to read code on that branch.
 	 *
+	 * When the materialized branch (or its local base) is more than
+	 * `datamachine_worktree_stale_threshold` commits behind upstream and
+	 * neither `$allow_stale` nor `$rebase_base` is set, the worktree is
+	 * torn down and the call returns a `worktree_stale` WP_Error with
+	 * remediation guidance. Pass `$allow_stale = true` to proceed anyway,
+	 * or `$rebase_base = true` to auto-rebase onto the upstream tip before
+	 * returning. On rebase conflicts the rebase is aborted (worktree stays
+	 * at its pre-rebase state) and `rebase_failed: true` is surfaced in
+	 * the response so the agent can resolve manually.
+	 *
 	 * @param string      $repo           Primary repo name (no @-suffix).
 	 * @param string      $branch         Branch to check out (e.g. "fix/foo-bar").
 	 * @param string|null $from           Base ref when creating the branch.
 	 * @param bool        $inject_context Whether to inject site-agent context (default true).
 	 * @param bool        $bootstrap      Whether to run submodule/package/composer install after creation (default true).
-	 * @return array{success: bool, handle: string, path: string, branch: string, slug: string, created_branch: bool, message: string, 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}|\WP_Error
+	 * @param bool        $allow_stale    Bypass the staleness gate (default false).
+	 * @param bool        $rebase_base    Rebase onto upstream after creation (default false).
+	 * @return array{success: bool, handle: string, path: string, branch: string, slug: string, created_branch: bool, message: string, 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, 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 ): 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 ): array|\WP_Error {
 		$repo   = $this->sanitize_name( $repo );
 		$branch = trim( $branch );
 
@@ -987,6 +999,69 @@ public function worktree_add( string $repo, string $branch, ?string $from = null
 			}
 		}
 
+		// Rebase BEFORE gating: if the agent explicitly asked to rebase, try
+		// that first. Success cancels the gate trigger entirely. Failure leaves
+		// the worktree at its pre-rebase state AND still trips the gate, so
+		// --rebase-base alone on a conflicting rebase isn't a silent bypass.
+		if ( $rebase_base && ! $fetch_failed ) {
+			$rebase_result = $this->try_rebase_worktree( $wt_path, $response, $created_branch );
+			if ( null !== $rebase_result ) {
+				$response = array_merge( $response, $rebase_result );
+			}
+		}
+
+		// Staleness gate. Threshold filterable per-site / per-repo. Only fires
+		// when fetch succeeded (otherwise behind-counts are unreliable) and
+		// rebase didn't already zero out the staleness.
+		if ( ! $allow_stale && ! $fetch_failed ) {
+			/**
+			 * Filters the staleness threshold above which `worktree_add` refuses
+			 * to return a stale worktree without explicit `--allow-stale` opt-in.
+			 *
+			 * @param int    $threshold Default 50 commits behind upstream.
+			 * @param string $repo      Repository name.
+			 * @param string $branch    Branch being materialized.
+			 */
+			$threshold                   = (int) apply_filters( 'datamachine_worktree_stale_threshold', 50, $repo, $branch );
+			$response['gate_threshold']  = $threshold;
+			$effective_behind            = $this->effective_behind_count( $response );
+
+			if ( null !== $effective_behind && $effective_behind > $threshold ) {
+				// Tear the worktree down so we don't leak a half-cooked
+				// checkout on the user's disk.
+				$this->run_git( $primary_path, sprintf( 'worktree remove --force %s', escapeshellarg( $wt_path ) ) );
+
+				$label = $response['upstream'] ?? ( $response['base_upstream'] ?? 'upstream' );
+				$guidance = sprintf(
+					"Worktree base is %d commits behind %s (threshold: %d).\n"
+					. "Options:\n"
+					. "  - workspace git-pull %s --allow-primary-mutation  (refresh primary first)\n"
+					. "  - worktree add … --from=origin/%s  (cut from remote ref directly)\n"
+					. "  - worktree add … --rebase-base  (auto-rebase onto upstream)\n"
+					. "  - worktree add … --allow-stale  (proceed with known-stale base)",
+					$effective_behind,
+					$label,
+					$threshold,
+					$repo,
+					ltrim( (string) ( $response['upstream'] ?? $resolved_base ?? 'main' ), 'origin/' )
+				);
+
+				return new \WP_Error(
+					'worktree_stale',
+					$guidance,
+					array(
+						'status'                    => 409,
+						'stale_commits_behind'      => $response['stale_commits_behind'] ?? null,
+						'base_stale_commits_behind' => $response['base_stale_commits_behind'] ?? null,
+						'upstream'                  => $response['upstream'] ?? null,
+						'base_upstream'             => $response['base_upstream'] ?? null,
+						'gate_threshold'            => $threshold,
+						'fetch_failed'              => false,
+					)
+				);
+			}
+		}
+
 		if ( ! $inject_context ) {
 			$response['context_injected']    = false;
 			$response['context_skip_reason'] = 'inject_context flag disabled';
@@ -1678,6 +1753,107 @@ private function is_remote_tracking_ref( string $ref ): bool {
 		return str_starts_with( $ref, 'refs/remotes/' ) || str_starts_with( $ref, 'origin/' );
 	}
 
+	/**
+	 * Pull the single behind-count that matters for gate decisions.
+	 *
+	 * The staleness probe records up to two behind-counts depending on
+	 * the path: `stale_commits_behind` for an existing branch vs its
+	 * upstream, or `base_stale_commits_behind` for a new branch cut off a
+	 * stale local base. At most one of these is present in practice;
+	 * whichever exists is the one we gate on.
+	 *
+	 * @param array $response Accumulated response payload.
+	 * @return int|null Behind-count, or null if no staleness data was collected.
+	 */
+	private function effective_behind_count( array $response ): ?int {
+		if ( isset( $response['stale_commits_behind'] ) ) {
+			return (int) $response['stale_commits_behind'];
+		}
+		if ( isset( $response['base_stale_commits_behind'] ) ) {
+			return (int) $response['base_stale_commits_behind'];
+		}
+		return null;
+	}
+
+	/**
+	 * Attempt to rebase the worktree onto its upstream.
+	 *
+	 * Target selection:
+	 *   - Existing-local-branch path → rebase onto `@{upstream}` if one is
+	 *     configured AND we observed stale_commits_behind > 0.
+	 *   - New-branch-off-local-base path → rebase onto `<base_upstream>` if
+	 *     we observed base_stale_commits_behind > 0.
+	 *
+	 * Returns an associative array to merge into the response:
+	 *   rebase_attempted, rebase_target, rebase_succeeded [, rebase_error]
+	 *
+	 * On success, clears the relevant staleness field (behind-count zeroes
+	 * out and the gate will not trip). On conflict the rebase is aborted
+	 * so the worktree stays at its pre-rebase state, and the gate may
+	 * still trip — `--rebase-base` is not a silent `--allow-stale`.
+	 *
+	 * Returns null when there's nothing meaningful to rebase (up to date,
+	 * no upstream, or staleness couldn't be computed).
+	 *
+	 * @param string $wt_path        Worktree path.
+	 * @param array  $response       Accumulated response payload.
+	 * @param bool   $created_branch Whether this was a freshly-created branch.
+	 * @return array|null
+	 */
+	private function try_rebase_worktree( string $wt_path, array &$response, bool $created_branch ): ?array {
+		$target = null;
+		$clear  = null;
+
+		if ( ! $created_branch
+			&& isset( $response['stale_commits_behind'] )
+			&& (int) $response['stale_commits_behind'] > 0
+		) {
+			$target = '@{upstream}';
+			$clear  = 'stale_commits_behind';
+		} elseif ( $created_branch
+			&& isset( $response['base_stale_commits_behind'] )
+			&& (int) $response['base_stale_commits_behind'] > 0
+			&& ! empty( $response['base_upstream'] )
+		) {
+			$target = (string) $response['base_upstream'];
+			$clear  = 'base_stale_commits_behind';
+		}
+
+		if ( null === $target ) {
+			return null;
+		}
+
+		$result = $this->run_git( $wt_path, sprintf( 'rebase %s', escapeshellarg( $target ) ) );
+
+		if ( is_wp_error( $result ) ) {
+			// Abort so the worktree stays at its pre-rebase HEAD. Agent can
+			// retry manually after resolving conflicts.
+			$this->run_git( $wt_path, 'rebase --abort' );
+
+			$data  = $result->get_error_data();
+			$tail  = is_array( $data ) && isset( $data['output'] ) ? trim( (string) $data['output'] ) : '';
+			$error = '' !== $tail ? $tail : $result->get_error_message();
+
+			return array(
+				'rebase_attempted' => true,
+				'rebase_target'    => $target,
+				'rebase_succeeded' => false,
+				'rebase_error'     => $error,
+			);
+		}
+
+		// Success: zero out the behind-count so the gate sees a fresh worktree.
+		if ( null !== $clear ) {
+			unset( $response[ $clear ] );
+		}
+
+		return array(
+			'rebase_attempted' => true,
+			'rebase_target'    => $target,
+			'rebase_succeeded' => true,
+		);
+	}
+
 	/**
 	 * Parse a `git worktree list --porcelain` block.
 	 *
diff --git a/tests/smoke-worktree-staleness.php b/tests/smoke-worktree-staleness.php
