diff --git a/docs/reference/agent-recovery.md b/docs/reference/agent-recovery.md index 340a86f233..825aaadc40 100644 --- a/docs/reference/agent-recovery.md +++ b/docs/reference/agent-recovery.md @@ -259,7 +259,7 @@ When an agent's pushes to its assigned branch are wedged — gateway branch-allo | **API (read)** | `GET /api/v1/pipelines/{id}/local-commits[?agent_role=&slice_id=]` — list unpushed commits per worktree (read-only) | | **API (write)** | `POST /api/v1/pipelines/{id}/salvage[?agent_role=&slice_id=]` — push HEAD to `egg/recovered/...` | | **MCP tool** | `list_agent_local_commits(task_id, agent_role?, slice_id?)` and `salvage_agent_commits(task_id, agent_role?, slice_id?)` | -| **Auto-salvage** | Best-effort, automatic — runs from `kubernetes_spawner.cleanup_pipeline` before worktree deletion. Skipped when `preserve_worktrees=True` (the worktree survives, no need to mirror it). Failures are logged and never block cleanup | +| **Auto-salvage** | 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 | ### Recovery Workflow diff --git a/docs/reference/orchestrator-cli.md b/docs/reference/orchestrator-cli.md index 2167d66eed..fe8bf3bc6e 100644 --- a/docs/reference/orchestrator-cli.md +++ b/docs/reference/orchestrator-cli.md @@ -200,7 +200,7 @@ egg-orch phase restart implement \ --context "Previous attempt stalled during BRC convergence — focus on completing reviews first" ``` -Agent restart preserves the agent's existing worktree (including committed work on the branch) and resets only that agent's consensus state (proposals, ACKs, NACKs, confirmations). Phase restart resets all consensus state and review cycle counters for the phase, then respawns all agents from scratch while preserving prior phase artifacts and branch commits. +Agent restart preserves the agent's existing worktree (including committed work on the branch) and resets only that agent's consensus state (proposals, ACKs, NACKs, confirmations). Phase restart resets all consensus state and review cycle counters for the phase, then respawns all agents from scratch while preserving prior phase artifacts and branch commits. Before deleting worktrees, phase restart enumerates all per-agent worktrees from disk (including slice-scoped worktrees) and auto-salvages any committed-but-unpushed work to `egg/recovered/…` refs — the same salvage path as `cleanup_pipeline`. > **Note:** CLI commands for restart are pending implementation. In the meantime, use the REST API directly or the MCP tools: > ```bash diff --git a/docs/reference/post-agent-commit.md b/docs/reference/post-agent-commit.md index d4c512924f..16a73736e5 100644 --- a/docs/reference/post-agent-commit.md +++ b/docs/reference/post-agent-commit.md @@ -16,7 +16,7 @@ When an agent container exits, the gateway **no longer** automatically commits a - It committed files outside the agent's role boundaries, blocking downstream agents' pushes - WIP commits broke CI and confused reviewers -With per-agent worktree isolation, each agent's uncommitted work persists safely in its own worktree on disk until the pipeline cleans up. For committed-but-unpushed work (pushes wedged by gateway rejection or infra failure), `cleanup_pipeline` now auto-salvages to `egg/recovered/…` refs before deleting worktrees — see [Committed but Unpushed: Auto-Salvage](#committed-but-unpushed-auto-salvage) below. +With per-agent worktree isolation, each agent's uncommitted work persists safely in its own worktree on disk until the pipeline cleans up. For committed-but-unpushed work (pushes wedged by gateway rejection or infra failure), `cleanup_pipeline` and `restart_phase` both auto-salvage to `egg/recovered/…` refs before deleting worktrees — see [Committed but Unpushed: Auto-Salvage](#committed-but-unpushed-auto-salvage) below. Source: `gateway/post_agent_commit.py` @@ -38,7 +38,7 @@ Per-agent worktrees persist after container exit (until pipeline cleanup). Uncom A different failure class exists when an agent **commits** work locally but its **pushes** to the remote are wedged — gateway branch-allowlist rejection from a wrong-branch spawn-time env var, transient infra failure, or restart-reconciliation marking a still-running pipeline `failed`. In these cases the commits sit on the local `egg/{worktree_id}/work` branch and are lost when `cleanup_pipeline` deletes the worktree. -Since [#2438](https://github.com/jwbron/egg/pull/2438), `cleanup_pipeline` automatically calls `auto_salvage_pipeline` before deleting any worktree. Every per-agent worktree with local commits not reachable from `origin/` is pushed to a recovery ref: +Since [#2438](https://github.com/jwbron/egg/pull/2438), `cleanup_pipeline` automatically calls `auto_salvage_pipeline` before deleting any worktree. Since [#2526](https://github.com/jwbron/egg/pull/2526), `restart_phase` does the same — making phase restart (the scenario most likely to produce wedged pushes) a safe worktree-deletion path. Every per-agent worktree with local commits not reachable from `origin/` is pushed to a recovery ref: ``` egg/recovered/// @@ -102,7 +102,7 @@ await mcp.call_tool("list_agent_local_commits", { | WIP commits pushed to branch automatically | No automatic push; HITL decides | | Phase-restricted files filtered before commit | No filtering needed — nothing is auto-committed | | Symlink filtering applied | No filtering needed | -| `egg/salvage-` branches created for main | `egg/recovered//...` refs auto-created by `cleanup_pipeline` for committed-but-unpushed work | +| `egg/salvage-` branches created for main | `egg/recovered//...` refs auto-created by `cleanup_pipeline` or `restart_phase` for committed-but-unpushed work | ### What operators should know