From 574deb8c3b6041f8f27b0249f6e7ba5ec5235a3b Mon Sep 17 00:00:00 2001 From: jwbron <8340608+jwbron@users.noreply.github.com> Date: Thu, 7 May 2026 05:19:49 +0000 Subject: [PATCH 1/2] docs: note restart_phase auto-salvage and slice-aware enumeration Update agent-recovery, post-agent-commit, and orchestrator-cli docs to reflect that restart_phase now also calls auto_salvage_pipeline before deleting worktrees (#2526), and that it enumerates worktrees from disk rather than guessing names so slice-scoped worktrees are included. Authored-by: egg --- docs/reference/agent-recovery.md | 2 +- docs/reference/orchestrator-cli.md | 2 +- docs/reference/post-agent-commit.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/reference/agent-recovery.md b/docs/reference/agent-recovery.md index 340a86f233..3629e28cc8 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` 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 | ### 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 From bb6381991c112c9e8d640e1f5994dd2b5d82c9b7 Mon Sep 17 00:00:00 2001 From: "egg-reviewer[bot]" <261018737+egg-reviewer[bot]@users.noreply.github.com> Date: Thu, 7 May 2026 06:11:09 +0000 Subject: [PATCH 2/2] docs: clarify preserve_worktrees only applies to cleanup_pipeline Address review feedback: the previous wording could mislead readers into thinking restart_phase honors a preserve_worktrees opt-out, but that flag only exists on kubernetes_spawner.cleanup_pipeline. restart_phase always salvages and always deletes worktrees for the targeted roles. Authored-by: egg --- docs/reference/agent-recovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/agent-recovery.md b/docs/reference/agent-recovery.md index 3629e28cc8..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` 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 | +| **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