feat(workspace): surface worktree staleness at create-time (refs #52)

[chubes4]

Summary

worktree add now unconditionally fetches origin before creating the new checkout, then compares the materialized branch (or the local base it was cut from) against its origin counterpart and surfaces the behind-count in the ability response + CLI output. Agents see at creation time that they're about to cook on top of a 47-commit-stale base, instead of discovering it at PR-review time.

Refs #52 (does not close — this is PR 1 of 2; the --allow-stale gate + --rebase-base opt-in live in a follow-up).

What changed

Non-breaking and purely additive. No gating, no auto-rebase, no new required inputs. Default invocations behave identically except for a freshness line in CLI output when the probe has something meaningful to say.

New: WorktreeStalenessProbe

Pure helper under inc/Workspace/. Two public static methods plus parse utilities:

• fetch( $repo_path ) — wraps git fetch --quiet origin, returns ['ok' => bool, 'error' => string?]. Never throws. Offline work stays possible; the caller just learns staleness data is untrustworthy.
• behind_count( $repo_path, $ref, $upstream ) — returns int on success, null when no upstream is configured, WP_Error on unexpected git failure. Callers MUST distinguish null from 0 — 0 means "up to date", null means "cannot tell".
• parse_count() + is_missing_upstream() — tolerant parsing of rev-list output and a heuristic for git's many ways of saying "no upstream configured" (unknown revision / ambiguous argument / bad revision / etc.).

Modified: Workspace::worktree_add()

Three tweaks:

1. Unconditional fetch at the top (right after input validation, before show-ref). Moved out of the new-branch arm where it used to live. Cheap — shared object store. Fetch failure is recorded in the response as fetch_failed: true + fetch_error: <tail> but does not abort worktree creation.

2. Post-creation staleness computation in two forms:

   • Existing-local-branch path: rev-list --count <branch>..@{upstream} from the new worktree. Surfaces stale_commits_behind + upstream (best-effort derived via rev-parse --abbrev-ref --symbolic-full-name). When no @{upstream} is configured, fields are silently omitted.
   • New-branch-off-local-base path: when the resolved base is NOT a remote-tracking ref, compare it against origin/<base>. Surfaces base_stale_commits_behind + base_upstream. When the origin counterpart doesn't exist, silently omitted.

3. is_remote_tracking_ref() helper — recognizes both refs/remotes/origin/* (what resolve_default_base() returns for the default-base path) and the shorter origin/* form a caller might pass explicitly. Both are "already at-tip post-fetch"; comparing them against themselves would produce nonsense. Caught this in live testing before opening the PR — the first pass used str_starts_with($resolved_base, 'origin/') which missed the fully-qualified form.

Modified: WorkspaceAbilities

datamachine/workspace-worktree-add output schema gains six optional fields: fetch_failed, fetch_error, stale_commits_behind, upstream, base_stale_commits_behind, base_upstream. All optional — omitted when no meaningful value to report.

Modified: WorkspaceCommand

New render_worktree_freshness() runs after the bootstrap block:

Bootstrap: ok
  - submodules skipped (no .gitmodules)
  ✓ packages   ran: npm ci
  ✓ composer   ran: composer install --no-interaction --prefer-dist
Warning: Freshness: ⚠ 47 commits behind origin/main
  Rebase before opening a PR:
    git -C /Users/…/data-machine@fix-foo pull --rebase origin main

Priority order: fetch_failed → existing-branch staleness → base staleness → up-to-date-with-label → elide. The "elide when no signal available" case is deliberate — a default invocation off origin/HEAD with no explicit base has no comparison to make, and printing "up to date" there would be claiming something we can't actually vouch for.

Testing

Smoke suite: 85/85 passing

$ php tests/smoke-worktree-staleness.php
23 total, 23/23 passed

$ php tests/smoke-worktree-bootstrap.php
30/30 passed

$ php tests/smoke-worktree-handles.php
Result: 32/32 passed

Covers: parse_count() tolerance, is_missing_upstream() heuristics across git phrasings, real-git fixtures for fetch success + fetch failure (repo with no origin), behind_count() returning int when behind, null when no upstream configured, null when upstream ref doesn't exist, 0 when at tip (distinct from null).

Live CLI tests on intelligence-chubes4 Studio site

Scenario	--from	Expected	Actual
Default base (origin/HEAD)	origin/main	elide (already remote-tracking)	✓ elided
Local stale base	feat/workspace-worktrees (36 behind origin/main, no origin counterpart)	elide (no origin ref)	✓ elided
First-pass bug	origin/main resolved to refs/remotes/origin/main	should elide	✗ hit broken guard — fixed with is_remote_tracking_ref()

The first-pass bug is what motivated the is_remote_tracking_ref() helper. Without it, default invocations would have tried to compute rev-list refs/remotes/origin/main..origin/refs/remotes/origin/main and produced garbage output. Caught before commit, test added implicitly via the origin/ short-form guard staying intact.

Out of scope (follow-up PR)

• Hard --allow-stale gate with a configurable behind-threshold (default 50). This is the behavior-change half of Worktree add doesn't check staleness — primary drift and stale local branches ship PRs with day-one merge conflicts #52.
• --rebase-base opt-in auto-rebase.
• Both deserve separate review. Non-breaking additive signal ships here first so the ergonomic surface is in hand before we start gating on it.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Code (Opus 4.7)
• Used for: Drafted the full implementation (probe helper, Workspace integration, ability schema, CLI rendering, smoke test, PR body). Live-tested against data-machine-code on this Studio site — caught the refs/remotes/origin/* guard bug mid-session and added the is_remote_tracking_ref() helper before commit. Chris steered the scope (PR 1 = non-breaking additive, PR 2 = gating behavior change) and caught the original session-spawn mistake that had the work happening in the wrong checkout.