From 24e4c976efffc83ff50221909bdfeddb8d7ae6ae Mon Sep 17 00:00:00 2001 From: nikhil achale Date: Sat, 23 May 2026 11:49:36 +0530 Subject: [PATCH] fix: document session restore workflow (#2029) --- packages/core/src/prompts/orchestrator.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/packages/core/src/prompts/orchestrator.md b/packages/core/src/prompts/orchestrator.md index 2551bc287..386f18483 100644 --- a/packages/core/src/prompts/orchestrator.md +++ b/packages/core/src/prompts/orchestrator.md @@ -78,6 +78,7 @@ ao open {{projectId}}{{REPO_CONFIGURED_SECTION_END}} {{REPO_CONFIGURED_SECTION_END}}- `ao session attach `: Attach to a session's terminal (a tmux window on Unix; a ConPTY pty-host on Windows) - `ao session kill `: Kill a specific session - `ao session cleanup [-p project]`: Kill cleanup-eligible sessions (closed work or dead runtimes) +- `ao session restore `: Restore a dead session in-place when work should be preserved - `ao send `: Send a message to a running session - `ao send --no-wait `: Send without waiting for session to become idle - `ao dashboard`: Start the web dashboard (http://localhost:{{dashboardPort}}) @@ -227,6 +228,14 @@ The system automatically handles these events: 3. Send clarification or instructions with `ao send '...'` 4. Or kill and respawn with fresh context if needed +### Session Recovery + +Before concluding that a session is dead, stale, or unrecoverable, always run `ao status` to re-check the current lifecycle state. Sessions can be restored manually through another surface, such as the dashboard, and cached observations may be out of date. + +Use `ao session restore ` when a dead session has meaningful in-progress work that should be preserved, such as open PRs, uncommitted changes, or branch state that matters. Restore is preferred over kill+respawn in those cases because it restores the session in-place with the same worktree, same branch, and same uncommitted changes. + +Restore preserves and re-attaches the session's system prompt file. The worker receives a fresh LLM conversation, but keeps full code context from the worktree plus session metadata from AO. + {{REPO_CONFIGURED_SECTION_START}}### PR Review Flow 1. Agent creates PR and pushes