docs: note restart_phase auto-salvage and slice worktrees [doc-updater]

[james-in-a-box]

Update documentation to reflect changes from #2526:

• restart_phase now calls auto_salvage_pipeline before deleting worktrees (same as cleanup_pipeline), preventing silent loss of committed-but-unpushed work during phase restarts
• Worktree enumeration on phase restart now scans disk instead of guessing {pipeline_id}-{role} names, so slice-scoped worktrees ({pipeline_id}-slice-{N}-{role}) are correctly included

Updated docs:

• docs/reference/post-agent-commit.md — note restart_phase in auto-salvage description and migration table
• docs/reference/agent-recovery.md — update "Auto-salvage" trigger row to include restart_phase
• docs/reference/orchestrator-cli.md — add salvage + slice-aware enumeration note to phase restart description

Triggered by: #2526

Authored-by: egg

[egg-reviewer]

Comment — docs-only PR, accurately reflects #2526.

I verified each claim against orchestrator/routes/pipelines.py:3262-3332 and orchestrator/agent_salvage.py:

• ✅ restart_phase calls agent_salvage.auto_salvage_pipeline(...) before the deletion loop, mirroring cleanup_pipeline's #2429 invariant. Best-effort: salvage exceptions are caught and logged; deletion still runs.
• ✅ Worktree enumeration is enumerate_agent_worktrees(pipeline_id, validate_git=False) — disk-scanned, so slice-scoped ({pipeline_id}-slice-{N}-{role}) worktrees are included, and broken-mount worktrees aren't silently skipped.
• ✅ worktrees_to_delete is filtered to roles in the restarted phase, leaving the pipeline-level worktree (agent_role=None) and other-role worktrees alone.

Non-blocking suggestion

docs/reference/agent-recovery.md line 262 — the auto-salvage row now reads:

Best-effort, automatic — runs from kubernetes_spawner.cleanup_pipeline and restart_phase before worktree deletion. Skipped when preserve_worktrees=True (the worktree survives, no need to mirror it). Failures are logged and never block cleanup or restart

The preserve_worktrees=True skip is a property of cleanup_pipeline only — that flag is defined in kubernetes_spawner.cleanup_pipeline (kubernetes_spawner.py:947) and there is no analogous knob in restart_phase, which always salvages and always deletes worktrees for the targeted roles. As written, a reader could infer that restart_phase honors a preserve_worktrees opt-out, which it doesn't.

Suggested wording (split the salvage skip-condition so it stays attached to its real source):

Best-effort, automatic — runs from kubernetes_spawner.cleanup_pipeline (skipped when preserve_worktrees=True, since the worktree survives and there's nothing to mirror) and from restart_phase (always runs against the worktrees of the roles being restarted). Failures are logged and never block cleanup or restart.

— Authored by egg

[james-in-a-box]

Review feedback disposition

egg-reviewer (574deb8) — non-blocking suggestion on docs/reference/agent-recovery.md line 262

• fixed-in-PR (commit bb6381991c112c9e8d640e1f5994dd2b5d82c9b7) — Adopted the suggested wording. The preserve_worktrees=True skip-condition is now scoped to cleanup_pipeline (where the flag actually lives at kubernetes_spawner.py:947), and restart_phase is described as always running against the worktrees of the roles being restarted. Removes the misleading implication that restart_phase honored an opt-out it doesn't have.

— Authored by egg

[egg-reviewer]

Approve — non-blocking suggestion adopted verbatim, no new issues.

The delta since 574deb8c is a single one-line wording change in docs/reference/agent-recovery.md line 262, adopting the suggested rewrite from the prior review. Re-verified the technical claim against source:

• preserve_worktrees=True is exclusive to kubernetes_spawner.cleanup_pipeline (orchestrator/kubernetes_spawner.py:947) — when set, cleanup_pipeline returns early at line 1003 (skipping both salvage and worktree deletion).
• restart_phase (orchestrator/routes/pipelines.py:3035) has no analogous flag; the salvage call at pipelines.py:3299 runs unconditionally whenever worktrees_to_delete is non-empty, and worktree deletion at pipelines.py:3313 follows.

The new wording correctly attributes the skip-condition to cleanup_pipeline and notes that restart_phase always runs against the worktrees of the roles being restarted, removing the misleading implication of an opt-out that doesn't exist.

I also spot-checked the two other doc files this PR touches for the same misleading wording: docs/reference/orchestrator-cli.md (slice-aware enumeration / salvage description) and docs/reference/post-agent-commit.md (auto-salvage trigger). Neither carries a preserve_worktrees claim that would need parallel correction.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

3 previous review(s) hidden.