feat(worktree): run a repo-declared command after worktree creation

[obogoni]

What

A repo can declare one shell command that runs automatically in every newly created worktree, with cwd set to that worktree:

// <repo>/.app/config.json — checked in, so it travels with the repo
{ "postCreateCommand": ".\SetupSkills.cmd" }

Motivating case: m:\triade\source\Code ships SetupSkills.cmd, which creates the .claude\skills / .codex\skills junctions that let several coding agents share one skills source. Until now that had to be remembered and double-clicked in every new worktree — and worktrees created by a workflow for an agent never got it at all, which is the case that needs it most.

Behaviour

• Runs on all three create paths — New Worktree, Start Work, and workflow ctx.worktree.create.
• Runs iff a worktree was actually produced. A branch-exists conflict, an empty rendered template, an existing target, a blocked base refresh or a failed git worktree add all skip it; the successful reuse/recreate paths do run it.
• A failing command never costs you the worktree. git worktree add already succeeded, so the create still returns ok: true and the failure rides along in a hook payload (exit code + last 4000 chars of combined output). Nothing in this feature deletes a worktree.
• The dialogs show an amber advisory (amber, not red — the create succeeded) with the created path, the command, the exit code or a timeout label, and the output tail. Continue runs the same post-create flow as the happy path, so the worktree is never stranded.
• A repo that declares nothing gets no hook key at all — the pre-feature result shape is byte-identical.
• Command context: inherited env plus PLAYGROUND_WORKTREE_PATH, PLAYGROUND_REPO_PATH, PLAYGROUND_BRANCH. Killed after 120 s.

Design

withPostCreateHook(create, deps) is a decorator with a signature identical to createWorktree, wired once in index.ts and handed to both the IPC handler and ctxDeps.worktree.create — so no call site can opt out, structurally rather than by convention. Chosen over a 7th positional param, a trailing options object, and a module-level setter because it is the only option that leaves worktree-manager.ts (and its ~40 real-git tests) and workflow-ctx.ts completely untouched, and it makes the run-iff-created rule unit-testable against a fake create with no git and no spawn.

Rationale and the rejected alternatives are recorded as AD-013 in .specs/STATE.md.

Review notes

One accepted trade-off, stated up front: the command is repo content. Cloning an untrusted repo into a registered workspace means its postCreateCommand runs on your next worktree create for that repo. No prompt, no allowlist in v1 — this was a deliberate decision (it's what makes the command travel with the repo), recorded in the spec's Assumptions table, not an oversight.

An independent Verifier (author ≠ verifier) returned FAIL on the first pass, on a real blocker: runHookShell resolved on close, which waits for stdio EOF. spawn's timeout kills only cmd.exe, so a surviving grandchild holds the inherited pipes — measured exit at 1665 ms vs close at 12969 ms, and 21000 ms with a detached grandchild. For a genuinely hung script the promise never settled: worktrees:create never resolved and the dialog stuck on busy forever.

Fixed in 0291a70 + 663e2d3 by settling on whichever comes first — close (complete output, normal path) or exit plus a 250 ms flush grace (guaranteed progress) — and extracted to src/main/hook-shell.ts so the settle condition carries real-process tests. Re-probed after the fix: pipe-holding child +119 ms, detached grandchild +467 ms, pause +152 ms, infinite loop +94 ms; output verified complete to a 1 MB single burst. Round 2 PASS, 4/4 findings closed. Full report: .specs/features/worktree-post-create-hook/validation.md.

Two mutation survivors were accepted with reasons, not papered over: HOOK_FLUSH_GRACE_MS 250→0 and removing the close handler are equivalent mutants — queued data events drain before the timer callback either way, so only latency differs, and asserting sub-250 ms latency would be flaky. Verified empirically both directions.

Gates

npm run typecheck clean · npm run lint 0 errors (18 pre-existing warnings in scripts/) · 533 tests / 39 files green (baseline 489) · npm run build and npm run build:win clean.

⚠️ npm test with the default worker count is unreliable on my machine — real-git tests in tree.test.ts / worktree-manager.test.ts intermittently exceed their 5000 ms default timeout under load (observed 5.1 / 6.1 / 8.4 / 44 s), then cascade into EPERM in afterEach because the timed-out git child still holds the temp dir. The failing subset differs per run and both files pass 71/71 in isolation; neither is modified by this PR. npx vitest run --maxWorkers=2 runs the identical suite reliably and faster (81–125 s vs 300 s). A testTimeout/maxWorkers setting in vitest.config.ts would fix it properly — deliberately not done here as it is outside this feature's scope, and worth its own change.

Not verified

The dialog UI has not been visually confirmed. WPC-12..16 are marked Built † in the spec, not Verified: implemented, typechecked, built and inspected, but the renderer carries no unit tests by project convention and these dialogs have never been rendered. The spec's Success Criteria (real junctions appearing in a real worktree for m:\triade\source\Code, and the same via a workflow) are likewise unconfirmed on hardware.

No linked issue — none existed for this feature, so there is no closing keyword.

Scope

21 P1 requirements delivered (WPC-01..16, WPC-20..24). WPC-17..19 — a hook detail box on the workflow run timeline — are deferred to P2: they need a new shared StepDetail variant plus a RunDetail branch, and result.hook is already reachable by a workflow author without them.

🤖 Generated with Claude Code