Correct the Worktrees docs and the worktree lifecycle contract

[selfcontained]

Nightly docs audit. Deep-dive on the docs-pane Worktrees section (the next_focus carried over from #988), audited against apps/server/src/shared/git/worktree.ts, apps/server/src/agents/tmux/setup-script.ts, apps/server/src/agents/archive.ts, apps/server/src/agents/manager.ts and the create-agent dialog.

Diff since the last audit (301b1f6a) was #986 (tilde resolution, already documented in the runbook), #989 (wire types), #990 (tests) and #988 (the previous run's own docs PR) — nothing doc-bearing, so no pivot.

Verified clean (no change needed)

Creation flow and .env copy; lockfile priority pnpm → yarn → npm → bun and the terminal-type deps skip; the failure path (markSetupFailed writes stopped + a blocked latest event, partial worktree/branch removed, no fallback to the primary checkout); both branch modes; the origin fetch and its local-branch fallback; archive cleanup semantics (auto/keep/force, dispatchOwnsBranch, existing-branch worktrees keeping their branch); the per-cwd new-branch preference.

Fixed

• Worktree location setting is not universal.crud-routes.ts, mcp-handlers.ts (dispatch_launch_agent) and release.ts all read it, but neither TemplateService.launchTemplate nor JobService.runJob passes worktreeLocation, so input.worktreeLocation ?? "sibling" silently forces the sibling path for every template launch and job run. Documented; the code fix is on the audit backlog.
• Pointed at Settings → Agents rather than just "Settings".
• Added the cross-reference that templates and jobs create worktrees through the same machinery (nothing said so on any surface).
• The starting branch is remembered per working directory too, not just the new-branch checkbox.
• docs/03-api-spec.md: createNewBranch: false checks out baseBranch and ignoresworktreeBranch — the sentence had it backwards. Also noted that placement comes from /agents/settings, not the create payload.
• docs/04-agent-lifecycle.md: the setup script never posts setup/phase: worktree (it's the initial value written at row insert); it unsets DATABASE_URL before sourcing ~/.dispatch/env; worktree creation is the only unrecoverable step (a failed install or missing .env is not). Documented the git branch -D that cleanupGitWorktree performs on archive, and that cleanup failures are swallowed.

Deferred to a future run

• Code: pass worktreeLocation through TemplateService and JobService so the setting actually applies to template launches and job runs.
• UI copy: the "Archive and remove worktree" button still doesn't mention that it force-deletes the branch (the docs do).
• Existing backlog items, unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WBq8dmFViUshsBQodr8UXa