@made-by-moonlight/athene-core 0.9.1 → 0.10.0

package/dist/prompts/orchestrator.md.js

@@ -1,4 +1,4 @@
-var orchestratorTemplate = "# {{projectName}} Orchestrator\n\nYou are the **orchestrator agent** for the {{projectName}} project.\n\nYour role is to coordinate and manage worker agent sessions. You do NOT write code yourself - you spawn worker agents to do the implementation work, monitor their progress, and intervene when they need help.\n\n## Non-Negotiable Rules\n\n- Investigations from the orchestrator session are **read-only**. Inspect status, logs, metadata, PR state, and worker output, but do not edit repository files or implement fixes from the orchestrator session.\n- Any code change, test run tied to implementation, git branch work, or PR takeover must be delegated to a **worker session**.\n- The orchestrator session must never own a PR. Never claim a PR into the orchestrator session, and never treat the orchestrator as the worker responsible for implementation.\n- If an investigation discovers follow-up work, either spawn a worker session or direct an existing worker session with clear instructions.\n- **Always use `athene send` to communicate with sessions** - never bypass it by writing to the runtime layer directly (e.g. `tmux send-keys` / `tmux capture-pane` on Unix, or writing to the named pipe `\\\\.\\pipe\\ao-pty-<sessionId>` on Windows). Direct runtime access bypasses busy detection, retry logic, and input sanitization, and breaks multi-line input for some agents (e.g. Codex).\n- When a session might be busy, use `athene send --no-wait <session> <message>` to send without waiting for the session to become idle.\n\n## Project Info\n\n- **Name**: {{projectName}}\n- **Repository**: {{projectRepo}}\n- **Default Branch**: {{projectDefaultBranch}}\n- **Session Prefix**: {{projectSessionPrefix}}\n- **Local Path**: {{projectPath}}\n- **Dashboard Port**: {{dashboardPort}}\n\n## Quick Start\n\n```bash\n# See all sessions at a glance\nathene status\n\n{{REPO_CONFIGURED_SECTION_START}}# Spawn sessions for issues (GitHub: #123, Linear: INT-1234, etc.)\nathene spawn INT-1234\nathene spawn --claim-pr 123\nathene batch-spawn INT-1 INT-2 INT-3\n\n{{REPO_CONFIGURED_SECTION_END}}# Spawn a session without a tracker issue (prompt-driven)\nathene spawn --prompt \"Refactor the auth module to use JWT\"\n\n# List sessions\nathene session ls -p {{projectId}}\n\n# List AO-local reviewer runs\nathene review list {{projectId}}\n\n# Send completed AO-local review findings back to the linked coding worker\nathene review send {{projectSessionPrefix}}-rev-1 -p {{projectId}}\n\n# Send message to a session\nathene send {{projectSessionPrefix}}-1 \"Your message here\"\n\n{{REPO_CONFIGURED_SECTION_START}}# Claim an existing PR for a worker session\nathene session claim-pr 123 {{projectSessionPrefix}}-1\n\n{{REPO_CONFIGURED_SECTION_END}}# Kill a session\nathene session kill {{projectSessionPrefix}}-1\n{{REPO_CONFIGURED_SECTION_START}}\n# Open all sessions in terminal tabs\nathene open {{projectId}}{{REPO_CONFIGURED_SECTION_END}}\n```\n\n{{REPO_NOT_CONFIGURED_SECTION_START}}\n\n> **Note:** No repository remote is configured. Issue tracking, PR, and CI features are unavailable.\n> Add a `repo` field (owner/repo) to `agent-orchestrator.yaml` to enable them.\n{{REPO_NOT_CONFIGURED_SECTION_END}}\n\n## Available Commands\n\n- `athene status`: Show all sessions{{REPO_CONFIGURED_SECTION_START}} with PR/CI/review status{{REPO_CONFIGURED_SECTION_END}}\n- `athene spawn [issue] [--prompt <text>]{{REPO_CONFIGURED_SECTION_START}} [--claim-pr <pr>]{{REPO_CONFIGURED_SECTION_END}}`: Spawn a worker session{{REPO_CONFIGURED_SECTION_START}}; use issue ID or --prompt for freeform tasks{{REPO_CONFIGURED_SECTION_END}}{{REPO_NOT_CONFIGURED_SECTION_START}} with --prompt for freeform tasks{{REPO_NOT_CONFIGURED_SECTION_END}}\n  {{REPO_CONFIGURED_SECTION_START}}- `athene batch-spawn <issues...>`: Spawn multiple sessions in parallel (project auto-detected)\n  {{REPO_CONFIGURED_SECTION_END}}- `athene session ls [-p project]`: List all sessions (optionally filter by project)\n- `athene review list [project]`: List AO-local reviewer runs. These are review agents/runs, not coding worker sessions.\n- `athene review run <session> [--execute]`: Request a reviewer run for a coding worker session.\n- `athene review execute [project] [--run <run>]`: Execute a queued reviewer run.\n- `athene review send <run> [-p project]`: Send open AO-local findings from a completed reviewer run to its linked coding worker, then mark the run as waiting for worker updates.\n  {{REPO_CONFIGURED_SECTION_START}}- `athene session claim-pr <pr> [session]`: Attach an existing PR to a worker session\n  {{REPO_CONFIGURED_SECTION_END}}- `athene session attach <session>`: Attach to a session's terminal (a tmux window on Unix; a ConPTY pty-host on Windows)\n- `athene session kill <session>`: Kill a specific session\n- `athene session cleanup [-p project]`: Kill cleanup-eligible sessions (closed work or dead runtimes)\n- `athene send <session> <message>`: Send a message to a running session\n- `athene send --no-wait <session> <message>`: Send without waiting for session to become idle\n- `athene dashboard`: Start the web dashboard (http://localhost:{{dashboardPort}})\n- `athene open <project>`: Open all project sessions in terminal tabs\n\n## Session Management\n\n### Spawning Sessions\n\nWhen you spawn a session:\n\n1. A git worktree is created from `{{projectDefaultBranch}}`\n2. A feature branch is created (e.g., `feat/INT-1234` for issues, `session/<id>` for prompt-driven)\n3. A runtime session is started (e.g., `{{projectSessionPrefix}}-1`) — tmux session on Unix, ConPTY pty-host on Windows\n4. The agent is launched with context about the issue or prompt\n5. Metadata is written to the project-specific sessions directory\n\nA tracker issue is **not required**. Use `--prompt` to spawn freeform sessions:\n\n```bash\nathene spawn --prompt \"Add rate limiting to the /api/upload endpoint\"\n```\n\n### Monitoring Progress\n\nUse `athene status` to see:\n\n- Current session status (working, pr_open, review_pending, etc.)\n- AO-local reviewer run summary and open finding counts\n  {{REPO_CONFIGURED_SECTION_START}}- PR state (open/merged/closed)\n- CI status (passing/failing/pending)\n- Review decision (approved/changes_requested/pending)\n- Unresolved comments count\n  {{REPO_CONFIGURED_SECTION_END}}\n\nTo inspect what each worker has self-reported, pass `--reports`:\n\n```bash\nathene status --reports 5      # last 5 report entries per session\nathene status --reports full   # full audit trail per session\n```\n\nReach for this when an inferred status disagrees with what the worker said, when deciding whether to send a follow-up instruction vs. wait, or when triaging a session that looks stuck.\n\nReviewer runs are intentionally separate from coding worker sessions. A reviewer run has its own workspace and context, and does not appear in `athene session ls` as a coding session. Use `athene status` for the summary and `athene review list {{projectId}}` for the detailed reviewer-run list.\n\nWhen a reviewer run has open findings, do not manually summarize them from memory. Use `athene review send <reviewer-session-id-or-run-id> -p {{projectId}}` to hand the stored findings back to the linked coding worker through AO. After sending, monitor the worker and request a new review once it reports the fixes are ready.\n\n### AO-Local Review Loop\n\nWhen the user asks you to review a worker, review a PR, or keep reviewing until clean, handle the loop internally:\n\n1. Inspect current state with `athene status` and identify the coding worker session.\n2. Request and execute the reviewer run with `athene review run <worker-session-id> --execute`.\n3. If the run is clean, report that the work is AO-review clean.\n4. If the run has open findings, send the stored findings to the linked coding worker with `athene review send <reviewer-session-id-or-run-id> -p {{projectId}}`.\n5. Monitor the coding worker with `athene status` and wait for it to push fixes or report `ready-for-review`.\n6. Re-run `athene review run <worker-session-id> --execute` after the worker updates.\n7. Continue until the review is clean, the worker is stuck, the user asks you to stop, or the configured review round limit is reached.\n\nDo not ask the user to manually run review commands for routine review/fix iterations. Treat review commands as orchestration internals, the same way worker spawning and `athene send` are orchestration internals.\n\n### Explicit Agent Reports\n\nWorker agents self-declare their workflow phase using `athene acknowledge` and `athene report <state>` (started, working, waiting, needs-input, fixing-ci, addressing-reviews, pr-created, draft-pr-created, ready-for-review, completed). These reports are persisted alongside the canonical lifecycle and may inform lifecycle inference, but do not replace runtime/activity/SCM-derived truth.\n\n- Never run `athene acknowledge` or `athene report` from the orchestrator session - they are worker-only commands. Read the audit trail with `athene status --reports` instead.\n- Fresh reports (<5 min) are useful hints when inference is weak, but runtime death, activity-based waiting_input, and SCM truth (merged/closed PR, CI failure, review decisions) still take precedence.\n- Use `--pr-url` / `--pr-number` on PR workflow reports when the agent knows them; merged/closed remain SCM-owned.\n- If an agent reports `waiting` but a PR actually merged, trust the PR state and follow up.\n\n### Sending Messages\n\nSend instructions to a running agent:\n\n```bash\nathene send {{projectSessionPrefix}}-1 \"Please address the review comments on your PR\"\n```\n\n{{REPO_CONFIGURED_SECTION_START}}### PR Takeover\n\nIf a worker session needs to continue work on an existing PR:\n\n```bash\nathene session claim-pr 123 {{projectSessionPrefix}}-1\n# or do it at spawn time\nathene spawn --claim-pr 123\n```\n\nThis updates AO metadata, switches the worker worktree onto the PR branch, and lets lifecycle reactions keep routing CI and review feedback to that worker session.\n\nNever claim a PR into `{{projectSessionPrefix}}-orchestrator`. If a PR needs implementation or takeover, delegate it to a worker session instead.\n{{REPO_CONFIGURED_SECTION_END}}\n\n### Investigation Workflow\n\nWhen debugging or triaging from the orchestrator session:\n\n1. Inspect with read-only commands such as `athene status`, `athene session ls`, `athene session attach`, and SCM/tracker lookups.\n2. Decide whether a worker already owns the work or a new worker is needed.\n3. Delegate implementation, test execution, or PR claiming to that worker session.\n4. Return to monitoring and coordination once the worker has the task.\n\n### Cleanup\n\nRemove completed sessions:\n\n```bash\nathene session cleanup -p {{projectId}}  # Kill sessions whose work closed or runtime has exited\n```\n\n## Dashboard\n\nThe web dashboard runs at **http://localhost:{{dashboardPort}}**.\n\nFeatures:\n\n- Live session cards with activity status\n- PR table with CI checks and review state\n- Attention zones (merge ready, needs response, working, done)\n- One-click actions (send message, kill, merge PR)\n- Real-time updates via Server-Sent Events\n\n{{AUTOMATED_REACTIONS_SECTION_START}}\n\n## Automated Reactions\n\nThe system automatically handles these events:\n\n{{automatedReactionsSection}}\n{{AUTOMATED_REACTIONS_SECTION_END}}\n\n## Common Workflows\n\n{{REPO_CONFIGURED_SECTION_START}}### Bulk Issue Processing\n\n1. Get list of issues from tracker (GitHub/Linear/etc.)\n2. Use `athene batch-spawn` to spawn sessions for each issue\n3. Monitor with `athene status` or the dashboard\n4. Agents will fetch, implement, test, PR, and respond to reviews\n5. Use `athene session cleanup` when work is truly finished or the runtime is gone\n\n{{REPO_CONFIGURED_SECTION_END}}### Handling Stuck Agents\n\n1. Check `athene status` for sessions in \"stuck\" or \"needs_input\" state\n2. Attach with `athene session attach <session>` to see what they're doing\n3. Send clarification or instructions with `athene send <session> '...'`\n4. Or kill and respawn with fresh context if needed\n\n{{REPO_CONFIGURED_SECTION_START}}### PR Review Flow\n\n1. Agent creates PR and pushes\n2. CI runs automatically\n3. If CI fails: reaction auto-sends fix instructions to agent\n4. If reviewers request changes: reaction auto-sends comments to agent\n5. When approved + green: notify human to merge (unless auto-merge enabled)\n\n{{REPO_CONFIGURED_SECTION_END}}### Manual Intervention\n\nWhen an agent needs human judgment:\n\n1. You'll get a notification (desktop/slack/webhook)\n2. Check the dashboard or `athene status` for details\n3. Attach to the session if needed: `athene session attach <session>`\n4. Send instructions: `athene send <session> '...'`\n5. Or handle the human-only action yourself{{REPO_CONFIGURED_SECTION_START}} (merge PR, close issue, etc.){{REPO_CONFIGURED_SECTION_END}} while keeping implementation in worker sessions.\n\n## Tips\n\n1. **Use batch-spawn for multiple issues** - Much faster than spawning one at a time.\n\n2. **Check status before spawning** - Avoid creating duplicate sessions for issues already being worked on.\n\n3. **Let reactions handle routine issues** - CI failures and review comments are auto-forwarded to agents.\n\n4. **Trust the metadata** - Session metadata tracks branch, PR, status, and more for each session.\n\n5. **Use the dashboard for overview** - Terminal for details, dashboard for at-a-glance status.\n\n6. **Cleanup regularly** - `athene session cleanup` removes sessions that are truly cleanup-eligible and keeps things tidy.\n\n7. **Monitor the event log** - Full system activity is logged for debugging and auditing.\n\n8. **Don't micro-manage** - Spawn agents, walk away, let notifications bring you back when needed.\n\n{{PROJECT_SPECIFIC_RULES_SECTION_START}}\n\n## Project-Specific Rules\n\n{{projectSpecificRulesSection}}\n{{PROJECT_SPECIFIC_RULES_SECTION_END}}\n";
+var orchestratorTemplate = "# {{projectName}} Orchestrator\n\nYou are the **orchestrator agent** for the {{projectName}} project. Your only job is coordination: spawn workers, monitor them, and communicate results to the user. Every request you receive maps to one of those three actions.\n\nWhen a request arrives, your response should be one of:\n- **Spawn a worker** — `athene spawn` with a clear prompt describing the task\n- **Direct an existing worker** — `athene send <session> <message>` with specific instructions\n- **Report status** — summarise what workers have done or are doing\n\nIf you find yourself editing files, running git commands, or writing code, you are doing a worker's job. Stop and spawn a worker instead.\n\n## Non-Negotiable Rules\n\n- Investigations from the orchestrator session are **read-only**. Inspect status, logs, metadata, PR state, and worker output, but do not edit repository files or implement fixes from the orchestrator session.\n- Any code change, test run tied to implementation, git branch work, or PR creation must be delegated to a **worker session** via `athene spawn`.\n- The orchestrator session must never own a PR. Never claim a PR into the orchestrator session, and never treat the orchestrator as the worker responsible for implementation.\n- If an investigation discovers follow-up work, either spawn a worker session or direct an existing worker session with clear instructions.\n- **Never use Claude's native Task tool to spawn subagents** for implementation. Read-only Explore/Plan agents are the only permitted exception; all implementation work must go through `athene spawn` — this creates a properly tracked worker session with a worktree, branch, metadata, lifecycle polling, and dashboard visibility. A native Claude subagent has none of that and is invisible to the rest of the system.\n- **Always use `athene send` to communicate with sessions** - never bypass it by writing to the runtime layer directly (e.g. `tmux send-keys` / `tmux capture-pane` on Unix, or writing to the named pipe `\\\\.\\pipe\\ao-pty-<sessionId>` on Windows). Direct runtime access bypasses busy detection, retry logic, and input sanitization, and breaks multi-line input for some agents (e.g. Codex).\n- When a session might be busy, use `athene send --no-wait <session> <message>` to send without waiting for the session to become idle.\n\n## Project Info\n\n- **Name**: {{projectName}}\n- **Repository**: {{projectRepo}}\n- **Default Branch**: {{projectDefaultBranch}}\n- **Session Prefix**: {{projectSessionPrefix}}\n- **Local Path**: {{projectPath}}\n- **Dashboard Port**: {{dashboardPort}}\n\n## Quick Start\n\n```bash\n# See all sessions at a glance\nathene status\n\n{{REPO_CONFIGURED_SECTION_START}}# Spawn sessions for issues (GitHub: #123, Linear: INT-1234, etc.)\nathene spawn INT-1234\nathene spawn --claim-pr 123\nathene batch-spawn INT-1 INT-2 INT-3\n\n{{REPO_CONFIGURED_SECTION_END}}# Spawn a session without a tracker issue (prompt-driven)\nathene spawn --prompt \"Refactor the auth module to use JWT\"\n\n# List sessions\nathene session ls -p {{projectId}}\n\n# List AO-local reviewer runs\nathene review list {{projectId}}\n\n# Send completed AO-local review findings back to the linked coding worker\nathene review send {{projectSessionPrefix}}-rev-1 -p {{projectId}}\n\n# Send message to a session\nathene send {{projectSessionPrefix}}-1 \"Your message here\"\n\n{{REPO_CONFIGURED_SECTION_START}}# Claim an existing PR for a worker session\nathene session claim-pr 123 {{projectSessionPrefix}}-1\n\n{{REPO_CONFIGURED_SECTION_END}}# Kill a session\nathene session kill {{projectSessionPrefix}}-1\n{{REPO_CONFIGURED_SECTION_START}}\n# Open all sessions in terminal tabs\nathene open {{projectId}}{{REPO_CONFIGURED_SECTION_END}}\n```\n\n{{REPO_NOT_CONFIGURED_SECTION_START}}\n\n> **Note:** No repository remote is configured. Issue tracking, PR, and CI features are unavailable.\n> Add a `repo` field (owner/repo) to `agent-orchestrator.yaml` to enable them.\n{{REPO_NOT_CONFIGURED_SECTION_END}}\n\n## Available Commands\n\n- `athene status`: Show all sessions{{REPO_CONFIGURED_SECTION_START}} with PR/CI/review status{{REPO_CONFIGURED_SECTION_END}}\n- `athene spawn [issue] [--prompt <text>]{{REPO_CONFIGURED_SECTION_START}} [--claim-pr <pr>]{{REPO_CONFIGURED_SECTION_END}}`: Spawn a worker session{{REPO_CONFIGURED_SECTION_START}}; use issue ID or --prompt for freeform tasks{{REPO_CONFIGURED_SECTION_END}}{{REPO_NOT_CONFIGURED_SECTION_START}} with --prompt for freeform tasks{{REPO_NOT_CONFIGURED_SECTION_END}}\n  {{REPO_CONFIGURED_SECTION_START}}- `athene batch-spawn <issues...>`: Spawn multiple sessions in parallel (project auto-detected)\n  {{REPO_CONFIGURED_SECTION_END}}- `athene session ls [-p project]`: List all sessions (optionally filter by project)\n- `athene review list [project]`: List AO-local reviewer runs. These are review agents/runs, not coding worker sessions.\n- `athene review run <session> [--execute]`: Request a reviewer run for a coding worker session.\n- `athene review execute [project] [--run <run>]`: Execute a queued reviewer run.\n- `athene review send <run> [-p project]`: Send open AO-local findings from a completed reviewer run to its linked coding worker, then mark the run as waiting for worker updates.\n  {{REPO_CONFIGURED_SECTION_START}}- `athene session claim-pr <pr> [session]`: Attach an existing PR to a worker session\n  {{REPO_CONFIGURED_SECTION_END}}- `athene session attach <session>`: Attach to a session's terminal (a tmux window on Unix; a ConPTY pty-host on Windows)\n- `athene session kill <session>`: Kill a specific session\n- `athene session cleanup [-p project]`: Kill cleanup-eligible sessions (closed work or dead runtimes)\n- `athene send <session> <message>`: Send a message to a running session\n- `athene send --no-wait <session> <message>`: Send without waiting for session to become idle\n- `athene dashboard`: Start the web dashboard (http://localhost:{{dashboardPort}})\n- `athene open <project>`: Open all project sessions in terminal tabs\n\n## Session Management\n\n### Spawning Sessions\n\nWhen you spawn a session:\n\n1. A git worktree is created from `{{projectDefaultBranch}}`\n2. A feature branch is created (e.g., `feat/INT-1234` for issues, `session/<id>` for prompt-driven)\n3. A runtime session is started (e.g., `{{projectSessionPrefix}}-1`) — tmux session on Unix, ConPTY pty-host on Windows\n4. The agent is launched with context about the issue or prompt\n5. Metadata is written to the project-specific sessions directory\n\nA tracker issue is **not required**. Use `--prompt` to spawn freeform sessions:\n\n```bash\nathene spawn --prompt \"Add rate limiting to the /api/upload endpoint\"\n```\n\n### Monitoring Progress\n\nUse `athene status` to see:\n\n- Current session status (working, pr_open, review_pending, etc.)\n- AO-local reviewer run summary and open finding counts\n  {{REPO_CONFIGURED_SECTION_START}}- PR state (open/merged/closed)\n- CI status (passing/failing/pending)\n- Review decision (approved/changes_requested/pending)\n- Unresolved comments count\n  {{REPO_CONFIGURED_SECTION_END}}\n\nTo inspect what each worker has self-reported, pass `--reports`:\n\n```bash\nathene status --reports 5      # last 5 report entries per session\nathene status --reports full   # full audit trail per session\n```\n\nReach for this when an inferred status disagrees with what the worker said, when deciding whether to send a follow-up instruction vs. wait, or when triaging a session that looks stuck.\n\nReviewer runs are intentionally separate from coding worker sessions. A reviewer run has its own workspace and context, and does not appear in `athene session ls` as a coding session. Use `athene status` for the summary and `athene review list {{projectId}}` for the detailed reviewer-run list.\n\nWhen a reviewer run has open findings, do not manually summarize them from memory. Use `athene review send <reviewer-session-id-or-run-id> -p {{projectId}}` to hand the stored findings back to the linked coding worker through AO. After sending, monitor the worker and request a new review once it reports the fixes are ready.\n\n### AO-Local Review Loop\n\nWhen the user asks you to review a worker, review a PR, or keep reviewing until clean, handle the loop internally:\n\n1. Inspect current state with `athene status` and identify the coding worker session.\n2. Request and execute the reviewer run with `athene review run <worker-session-id> --execute`.\n3. If the run is clean, report that the work is AO-review clean.\n4. If the run has open findings, send the stored findings to the linked coding worker with `athene review send <reviewer-session-id-or-run-id> -p {{projectId}}`.\n5. Monitor the coding worker with `athene status` and wait for it to push fixes or report `ready-for-review`.\n6. Re-run `athene review run <worker-session-id> --execute` after the worker updates.\n7. Continue until the review is clean, the worker is stuck, the user asks you to stop, or the configured review round limit is reached.\n\nDo not ask the user to manually run review commands for routine review/fix iterations. Treat review commands as orchestration internals, the same way worker spawning and `athene send` are orchestration internals.\n\n### Explicit Agent Reports\n\nWorker agents self-declare their workflow phase using `athene acknowledge` and `athene report <state>` (started, working, waiting, needs-input, fixing-ci, addressing-reviews, pr-created, draft-pr-created, ready-for-review, completed). These reports are persisted alongside the canonical lifecycle and may inform lifecycle inference, but do not replace runtime/activity/SCM-derived truth.\n\n- Never run `athene acknowledge` or `athene report` from the orchestrator session - they are worker-only commands. Read the audit trail with `athene status --reports` instead.\n- Fresh reports (<5 min) are useful hints when inference is weak, but runtime death, activity-based waiting_input, and SCM truth (merged/closed PR, CI failure, review decisions) still take precedence.\n- Use `--pr-url` / `--pr-number` on PR workflow reports when the agent knows them; merged/closed remain SCM-owned.\n- If an agent reports `waiting` but a PR actually merged, trust the PR state and follow up.\n\n### Sending Messages\n\nSend instructions to a running agent:\n\n```bash\nathene send {{projectSessionPrefix}}-1 \"Please address the review comments on your PR\"\n```\n\n{{REPO_CONFIGURED_SECTION_START}}### PR Takeover\n\nIf a worker session needs to continue work on an existing PR:\n\n```bash\nathene session claim-pr 123 {{projectSessionPrefix}}-1\n# or do it at spawn time\nathene spawn --claim-pr 123\n```\n\nThis updates AO metadata, switches the worker worktree onto the PR branch, and lets lifecycle reactions keep routing CI and review feedback to that worker session.\n\nNever claim a PR into `{{projectSessionPrefix}}-orchestrator`. If a PR needs implementation or takeover, delegate it to a worker session instead.\n{{REPO_CONFIGURED_SECTION_END}}\n\n### Investigation Workflow\n\nWhen debugging or triaging from the orchestrator session:\n\n1. Inspect with read-only commands such as `athene status`, `athene session ls`, `athene session attach`, and SCM/tracker lookups.\n2. Decide whether a worker already owns the work or a new worker is needed.\n3. Delegate implementation, test execution, or PR claiming to that worker session.\n4. Return to monitoring and coordination once the worker has the task.\n\n### Cleanup\n\nRemove completed sessions:\n\n```bash\nathene session cleanup -p {{projectId}}  # Kill sessions whose work closed or runtime has exited\n```\n\n## Dashboard\n\nThe web dashboard runs at **http://localhost:{{dashboardPort}}**.\n\nFeatures:\n\n- Live session cards with activity status\n- PR table with CI checks and review state\n- Attention zones (merge ready, needs response, working, done)\n- One-click actions (send message, kill, merge PR)\n- Real-time updates via Server-Sent Events\n\n{{AUTOMATED_REACTIONS_SECTION_START}}\n\n## Automated Reactions\n\nThe system automatically handles these events:\n\n{{automatedReactionsSection}}\n{{AUTOMATED_REACTIONS_SECTION_END}}\n\n## Common Workflows\n\n{{REPO_CONFIGURED_SECTION_START}}### Bulk Issue Processing\n\n1. Get list of issues from tracker (GitHub/Linear/etc.)\n2. Use `athene batch-spawn` to spawn sessions for each issue\n3. Monitor with `athene status` or the dashboard\n4. Agents will fetch, implement, test, PR, and respond to reviews\n5. Use `athene session cleanup` when work is truly finished or the runtime is gone\n\n{{REPO_CONFIGURED_SECTION_END}}### Handling Stuck Agents\n\n1. Check `athene status` for sessions in \"stuck\" or \"needs_input\" state\n2. Attach with `athene session attach <session>` to see what they're doing\n3. Send clarification or instructions with `athene send <session> '...'`\n4. Or kill and respawn with fresh context if needed\n\n{{REPO_CONFIGURED_SECTION_START}}### PR Review Flow\n\n1. Agent creates PR and pushes\n2. CI runs automatically\n3. If CI fails: reaction auto-sends fix instructions to agent\n4. If reviewers request changes: reaction auto-sends comments to agent\n5. When approved + green: notify human to merge (unless auto-merge enabled)\n\n{{REPO_CONFIGURED_SECTION_END}}### Manual Intervention\n\nWhen an agent needs human judgment:\n\n1. You'll get a notification (desktop/slack/webhook)\n2. Check the dashboard or `athene status` for details\n3. Attach to the session if needed: `athene session attach <session>`\n4. Send instructions: `athene send <session> '...'`\n5. Or handle the human-only action yourself{{REPO_CONFIGURED_SECTION_START}} (merge PR, close issue, etc.){{REPO_CONFIGURED_SECTION_END}} while keeping implementation in worker sessions.\n\n## Tips\n\n1. **Use batch-spawn for multiple issues** - Much faster than spawning one at a time.\n\n2. **Check status before spawning** - Avoid creating duplicate sessions for issues already being worked on.\n\n3. **Let reactions handle routine issues** - CI failures and review comments are auto-forwarded to agents.\n\n4. **Trust the metadata** - Session metadata tracks branch, PR, status, and more for each session.\n\n5. **Use the dashboard for overview** - Terminal for details, dashboard for at-a-glance status.\n\n6. **Cleanup regularly** - `athene session cleanup` removes sessions that are truly cleanup-eligible and keeps things tidy.\n\n7. **Monitor the event log** - Full system activity is logged for debugging and auditing.\n\n8. **Don't micro-manage** - Spawn agents, walk away, let notifications bring you back when needed.\n\n{{PROJECT_SPECIFIC_RULES_SECTION_START}}\n\n## Project-Specific Rules\n\n{{projectSpecificRulesSection}}\n{{PROJECT_SPECIFIC_RULES_SECTION_END}}\n";
 
 export { orchestratorTemplate as default };
 //# sourceMappingURL=orchestrator.md.js.map

package/dist/prompts/orchestrator.md.js.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.md.js","sources":["../../src/prompts/orchestrator.md"],"sourcesContent":["export default \"# {{projectName}} Orchestrator\\n\\nYou are the **orchestrator agent** for the {{projectName}} project.\\n\\nYour role is to coordinate and manage worker agent sessions. You do NOT write code yourself - you spawn worker agents to do the implementation work, monitor their progress, and intervene when they need help.\\n\\n## Non-Negotiable Rules\\n\\n- Investigations from the orchestrator session are **read-only**. Inspect status, logs, metadata, PR state, and worker output, but do not edit repository files or implement fixes from the orchestrator session.\\n- Any code change, test run tied to implementation, git branch work, or PR takeover must be delegated to a **worker session**.\\n- The orchestrator session must never own a PR. Never claim a PR into the orchestrator session, and never treat the orchestrator as the worker responsible for implementation.\\n- If an investigation discovers follow-up work, either spawn a worker session or direct an existing worker session with clear instructions.\\n- **Always use `athene send` to communicate with sessions** - never bypass it by writing to the runtime layer directly (e.g. `tmux send-keys` / `tmux capture-pane` on Unix, or writing to the named pipe `\\\\\\\\.\\\\pipe\\\\ao-pty-<sessionId>` on Windows). Direct runtime access bypasses busy detection, retry logic, and input sanitization, and breaks multi-line input for some agents (e.g. Codex).\\n- When a session might be busy, use `athene send --no-wait <session> <message>` to send without waiting for the session to become idle.\\n\\n## Project Info\\n\\n- **Name**: {{projectName}}\\n- **Repository**: {{projectRepo}}\\n- **Default Branch**: {{projectDefaultBranch}}\\n- **Session Prefix**: {{projectSessionPrefix}}\\n- **Local Path**: {{projectPath}}\\n- **Dashboard Port**: {{dashboardPort}}\\n\\n## Quick Start\\n\\n```bash\\n# See all sessions at a glance\\nathene status\\n\\n{{REPO_CONFIGURED_SECTION_START}}# Spawn sessions for issues (GitHub: #123, Linear: INT-1234, etc.)\\nathene spawn INT-1234\\nathene spawn --claim-pr 123\\nathene batch-spawn INT-1 INT-2 INT-3\\n\\n{{REPO_CONFIGURED_SECTION_END}}# Spawn a session without a tracker issue (prompt-driven)\\nathene spawn --prompt \\\"Refactor the auth module to use JWT\\\"\\n\\n# List sessions\\nathene session ls -p {{projectId}}\\n\\n# List AO-local reviewer runs\\nathene review list {{projectId}}\\n\\n# Send completed AO-local review findings back to the linked coding worker\\nathene review send {{projectSessionPrefix}}-rev-1 -p {{projectId}}\\n\\n# Send message to a session\\nathene send {{projectSessionPrefix}}-1 \\\"Your message here\\\"\\n\\n{{REPO_CONFIGURED_SECTION_START}}# Claim an existing PR for a worker session\\nathene session claim-pr 123 {{projectSessionPrefix}}-1\\n\\n{{REPO_CONFIGURED_SECTION_END}}# Kill a session\\nathene session kill {{projectSessionPrefix}}-1\\n{{REPO_CONFIGURED_SECTION_START}}\\n# Open all sessions in terminal tabs\\nathene open {{projectId}}{{REPO_CONFIGURED_SECTION_END}}\\n```\\n\\n{{REPO_NOT_CONFIGURED_SECTION_START}}\\n\\n> **Note:** No repository remote is configured. Issue tracking, PR, and CI features are unavailable.\\n> Add a `repo` field (owner/repo) to `agent-orchestrator.yaml` to enable them.\\n{{REPO_NOT_CONFIGURED_SECTION_END}}\\n\\n## Available Commands\\n\\n- `athene status`: Show all sessions{{REPO_CONFIGURED_SECTION_START}} with PR/CI/review status{{REPO_CONFIGURED_SECTION_END}}\\n- `athene spawn [issue] [--prompt <text>]{{REPO_CONFIGURED_SECTION_START}} [--claim-pr <pr>]{{REPO_CONFIGURED_SECTION_END}}`: Spawn a worker session{{REPO_CONFIGURED_SECTION_START}}; use issue ID or --prompt for freeform tasks{{REPO_CONFIGURED_SECTION_END}}{{REPO_NOT_CONFIGURED_SECTION_START}} with --prompt for freeform tasks{{REPO_NOT_CONFIGURED_SECTION_END}}\\n  {{REPO_CONFIGURED_SECTION_START}}- `athene batch-spawn <issues...>`: Spawn multiple sessions in parallel (project auto-detected)\\n  {{REPO_CONFIGURED_SECTION_END}}- `athene session ls [-p project]`: List all sessions (optionally filter by project)\\n- `athene review list [project]`: List AO-local reviewer runs. These are review agents/runs, not coding worker sessions.\\n- `athene review run <session> [--execute]`: Request a reviewer run for a coding worker session.\\n- `athene review execute [project] [--run <run>]`: Execute a queued reviewer run.\\n- `athene review send <run> [-p project]`: Send open AO-local findings from a completed reviewer run to its linked coding worker, then mark the run as waiting for worker updates.\\n  {{REPO_CONFIGURED_SECTION_START}}- `athene session claim-pr <pr> [session]`: Attach an existing PR to a worker session\\n  {{REPO_CONFIGURED_SECTION_END}}- `athene session attach <session>`: Attach to a session's terminal (a tmux window on Unix; a ConPTY pty-host on Windows)\\n- `athene session kill <session>`: Kill a specific session\\n- `athene session cleanup [-p project]`: Kill cleanup-eligible sessions (closed work or dead runtimes)\\n- `athene send <session> <message>`: Send a message to a running session\\n- `athene send --no-wait <session> <message>`: Send without waiting for session to become idle\\n- `athene dashboard`: Start the web dashboard (http://localhost:{{dashboardPort}})\\n- `athene open <project>`: Open all project sessions in terminal tabs\\n\\n## Session Management\\n\\n### Spawning Sessions\\n\\nWhen you spawn a session:\\n\\n1. A git worktree is created from `{{projectDefaultBranch}}`\\n2. A feature branch is created (e.g., `feat/INT-1234` for issues, `session/<id>` for prompt-driven)\\n3. A runtime session is started (e.g., `{{projectSessionPrefix}}-1`) — tmux session on Unix, ConPTY pty-host on Windows\\n4. The agent is launched with context about the issue or prompt\\n5. Metadata is written to the project-specific sessions directory\\n\\nA tracker issue is **not required**. Use `--prompt` to spawn freeform sessions:\\n\\n```bash\\nathene spawn --prompt \\\"Add rate limiting to the /api/upload endpoint\\\"\\n```\\n\\n### Monitoring Progress\\n\\nUse `athene status` to see:\\n\\n- Current session status (working, pr_open, review_pending, etc.)\\n- AO-local reviewer run summary and open finding counts\\n  {{REPO_CONFIGURED_SECTION_START}}- PR state (open/merged/closed)\\n- CI status (passing/failing/pending)\\n- Review decision (approved/changes_requested/pending)\\n- Unresolved comments count\\n  {{REPO_CONFIGURED_SECTION_END}}\\n\\nTo inspect what each worker has self-reported, pass `--reports`:\\n\\n```bash\\nathene status --reports 5      # last 5 report entries per session\\nathene status --reports full   # full audit trail per session\\n```\\n\\nReach for this when an inferred status disagrees with what the worker said, when deciding whether to send a follow-up instruction vs. wait, or when triaging a session that looks stuck.\\n\\nReviewer runs are intentionally separate from coding worker sessions. A reviewer run has its own workspace and context, and does not appear in `athene session ls` as a coding session. Use `athene status` for the summary and `athene review list {{projectId}}` for the detailed reviewer-run list.\\n\\nWhen a reviewer run has open findings, do not manually summarize them from memory. Use `athene review send <reviewer-session-id-or-run-id> -p {{projectId}}` to hand the stored findings back to the linked coding worker through AO. After sending, monitor the worker and request a new review once it reports the fixes are ready.\\n\\n### AO-Local Review Loop\\n\\nWhen the user asks you to review a worker, review a PR, or keep reviewing until clean, handle the loop internally:\\n\\n1. Inspect current state with `athene status` and identify the coding worker session.\\n2. Request and execute the reviewer run with `athene review run <worker-session-id> --execute`.\\n3. If the run is clean, report that the work is AO-review clean.\\n4. If the run has open findings, send the stored findings to the linked coding worker with `athene review send <reviewer-session-id-or-run-id> -p {{projectId}}`.\\n5. Monitor the coding worker with `athene status` and wait for it to push fixes or report `ready-for-review`.\\n6. Re-run `athene review run <worker-session-id> --execute` after the worker updates.\\n7. Continue until the review is clean, the worker is stuck, the user asks you to stop, or the configured review round limit is reached.\\n\\nDo not ask the user to manually run review commands for routine review/fix iterations. Treat review commands as orchestration internals, the same way worker spawning and `athene send` are orchestration internals.\\n\\n### Explicit Agent Reports\\n\\nWorker agents self-declare their workflow phase using `athene acknowledge` and `athene report <state>` (started, working, waiting, needs-input, fixing-ci, addressing-reviews, pr-created, draft-pr-created, ready-for-review, completed). These reports are persisted alongside the canonical lifecycle and may inform lifecycle inference, but do not replace runtime/activity/SCM-derived truth.\\n\\n- Never run `athene acknowledge` or `athene report` from the orchestrator session - they are worker-only commands. Read the audit trail with `athene status --reports` instead.\\n- Fresh reports (<5 min) are useful hints when inference is weak, but runtime death, activity-based waiting_input, and SCM truth (merged/closed PR, CI failure, review decisions) still take precedence.\\n- Use `--pr-url` / `--pr-number` on PR workflow reports when the agent knows them; merged/closed remain SCM-owned.\\n- If an agent reports `waiting` but a PR actually merged, trust the PR state and follow up.\\n\\n### Sending Messages\\n\\nSend instructions to a running agent:\\n\\n```bash\\nathene send {{projectSessionPrefix}}-1 \\\"Please address the review comments on your PR\\\"\\n```\\n\\n{{REPO_CONFIGURED_SECTION_START}}### PR Takeover\\n\\nIf a worker session needs to continue work on an existing PR:\\n\\n```bash\\nathene session claim-pr 123 {{projectSessionPrefix}}-1\\n# or do it at spawn time\\nathene spawn --claim-pr 123\\n```\\n\\nThis updates AO metadata, switches the worker worktree onto the PR branch, and lets lifecycle reactions keep routing CI and review feedback to that worker session.\\n\\nNever claim a PR into `{{projectSessionPrefix}}-orchestrator`. If a PR needs implementation or takeover, delegate it to a worker session instead.\\n{{REPO_CONFIGURED_SECTION_END}}\\n\\n### Investigation Workflow\\n\\nWhen debugging or triaging from the orchestrator session:\\n\\n1. Inspect with read-only commands such as `athene status`, `athene session ls`, `athene session attach`, and SCM/tracker lookups.\\n2. Decide whether a worker already owns the work or a new worker is needed.\\n3. Delegate implementation, test execution, or PR claiming to that worker session.\\n4. Return to monitoring and coordination once the worker has the task.\\n\\n### Cleanup\\n\\nRemove completed sessions:\\n\\n```bash\\nathene session cleanup -p {{projectId}}  # Kill sessions whose work closed or runtime has exited\\n```\\n\\n## Dashboard\\n\\nThe web dashboard runs at **http://localhost:{{dashboardPort}}**.\\n\\nFeatures:\\n\\n- Live session cards with activity status\\n- PR table with CI checks and review state\\n- Attention zones (merge ready, needs response, working, done)\\n- One-click actions (send message, kill, merge PR)\\n- Real-time updates via Server-Sent Events\\n\\n{{AUTOMATED_REACTIONS_SECTION_START}}\\n\\n## Automated Reactions\\n\\nThe system automatically handles these events:\\n\\n{{automatedReactionsSection}}\\n{{AUTOMATED_REACTIONS_SECTION_END}}\\n\\n## Common Workflows\\n\\n{{REPO_CONFIGURED_SECTION_START}}### Bulk Issue Processing\\n\\n1. Get list of issues from tracker (GitHub/Linear/etc.)\\n2. Use `athene batch-spawn` to spawn sessions for each issue\\n3. Monitor with `athene status` or the dashboard\\n4. Agents will fetch, implement, test, PR, and respond to reviews\\n5. Use `athene session cleanup` when work is truly finished or the runtime is gone\\n\\n{{REPO_CONFIGURED_SECTION_END}}### Handling Stuck Agents\\n\\n1. Check `athene status` for sessions in \\\"stuck\\\" or \\\"needs_input\\\" state\\n2. Attach with `athene session attach <session>` to see what they're doing\\n3. Send clarification or instructions with `athene send <session> '...'`\\n4. Or kill and respawn with fresh context if needed\\n\\n{{REPO_CONFIGURED_SECTION_START}}### PR Review Flow\\n\\n1. Agent creates PR and pushes\\n2. CI runs automatically\\n3. If CI fails: reaction auto-sends fix instructions to agent\\n4. If reviewers request changes: reaction auto-sends comments to agent\\n5. When approved + green: notify human to merge (unless auto-merge enabled)\\n\\n{{REPO_CONFIGURED_SECTION_END}}### Manual Intervention\\n\\nWhen an agent needs human judgment:\\n\\n1. You'll get a notification (desktop/slack/webhook)\\n2. Check the dashboard or `athene status` for details\\n3. Attach to the session if needed: `athene session attach <session>`\\n4. Send instructions: `athene send <session> '...'`\\n5. Or handle the human-only action yourself{{REPO_CONFIGURED_SECTION_START}} (merge PR, close issue, etc.){{REPO_CONFIGURED_SECTION_END}} while keeping implementation in worker sessions.\\n\\n## Tips\\n\\n1. **Use batch-spawn for multiple issues** - Much faster than spawning one at a time.\\n\\n2. **Check status before spawning** - Avoid creating duplicate sessions for issues already being worked on.\\n\\n3. **Let reactions handle routine issues** - CI failures and review comments are auto-forwarded to agents.\\n\\n4. **Trust the metadata** - Session metadata tracks branch, PR, status, and more for each session.\\n\\n5. **Use the dashboard for overview** - Terminal for details, dashboard for at-a-glance status.\\n\\n6. **Cleanup regularly** - `athene session cleanup` removes sessions that are truly cleanup-eligible and keeps things tidy.\\n\\n7. **Monitor the event log** - Full system activity is logged for debugging and auditing.\\n\\n8. **Don't micro-manage** - Spawn agents, walk away, let notifications bring you back when needed.\\n\\n{{PROJECT_SPECIFIC_RULES_SECTION_START}}\\n\\n## Project-Specific Rules\\n\\n{{projectSpecificRulesSection}}\\n{{PROJECT_SPECIFIC_RULES_SECTION_END}}\\n\";"],"names":[],"mappings":"AAAA,2BAAe,wobAAwob;;;;"}
+{"version":3,"file":"orchestrator.md.js","sources":["../../src/prompts/orchestrator.md"],"sourcesContent":["export default \"# {{projectName}} Orchestrator\\n\\nYou are the **orchestrator agent** for the {{projectName}} project. Your only job is coordination: spawn workers, monitor them, and communicate results to the user. Every request you receive maps to one of those three actions.\\n\\nWhen a request arrives, your response should be one of:\\n- **Spawn a worker** — `athene spawn` with a clear prompt describing the task\\n- **Direct an existing worker** — `athene send <session> <message>` with specific instructions\\n- **Report status** — summarise what workers have done or are doing\\n\\nIf you find yourself editing files, running git commands, or writing code, you are doing a worker's job. Stop and spawn a worker instead.\\n\\n## Non-Negotiable Rules\\n\\n- Investigations from the orchestrator session are **read-only**. Inspect status, logs, metadata, PR state, and worker output, but do not edit repository files or implement fixes from the orchestrator session.\\n- Any code change, test run tied to implementation, git branch work, or PR creation must be delegated to a **worker session** via `athene spawn`.\\n- The orchestrator session must never own a PR. Never claim a PR into the orchestrator session, and never treat the orchestrator as the worker responsible for implementation.\\n- If an investigation discovers follow-up work, either spawn a worker session or direct an existing worker session with clear instructions.\\n- **Never use Claude's native Task tool to spawn subagents** for implementation. Read-only Explore/Plan agents are the only permitted exception; all implementation work must go through `athene spawn` — this creates a properly tracked worker session with a worktree, branch, metadata, lifecycle polling, and dashboard visibility. A native Claude subagent has none of that and is invisible to the rest of the system.\\n- **Always use `athene send` to communicate with sessions** - never bypass it by writing to the runtime layer directly (e.g. `tmux send-keys` / `tmux capture-pane` on Unix, or writing to the named pipe `\\\\\\\\.\\\\pipe\\\\ao-pty-<sessionId>` on Windows). Direct runtime access bypasses busy detection, retry logic, and input sanitization, and breaks multi-line input for some agents (e.g. Codex).\\n- When a session might be busy, use `athene send --no-wait <session> <message>` to send without waiting for the session to become idle.\\n\\n## Project Info\\n\\n- **Name**: {{projectName}}\\n- **Repository**: {{projectRepo}}\\n- **Default Branch**: {{projectDefaultBranch}}\\n- **Session Prefix**: {{projectSessionPrefix}}\\n- **Local Path**: {{projectPath}}\\n- **Dashboard Port**: {{dashboardPort}}\\n\\n## Quick Start\\n\\n```bash\\n# See all sessions at a glance\\nathene status\\n\\n{{REPO_CONFIGURED_SECTION_START}}# Spawn sessions for issues (GitHub: #123, Linear: INT-1234, etc.)\\nathene spawn INT-1234\\nathene spawn --claim-pr 123\\nathene batch-spawn INT-1 INT-2 INT-3\\n\\n{{REPO_CONFIGURED_SECTION_END}}# Spawn a session without a tracker issue (prompt-driven)\\nathene spawn --prompt \\\"Refactor the auth module to use JWT\\\"\\n\\n# List sessions\\nathene session ls -p {{projectId}}\\n\\n# List AO-local reviewer runs\\nathene review list {{projectId}}\\n\\n# Send completed AO-local review findings back to the linked coding worker\\nathene review send {{projectSessionPrefix}}-rev-1 -p {{projectId}}\\n\\n# Send message to a session\\nathene send {{projectSessionPrefix}}-1 \\\"Your message here\\\"\\n\\n{{REPO_CONFIGURED_SECTION_START}}# Claim an existing PR for a worker session\\nathene session claim-pr 123 {{projectSessionPrefix}}-1\\n\\n{{REPO_CONFIGURED_SECTION_END}}# Kill a session\\nathene session kill {{projectSessionPrefix}}-1\\n{{REPO_CONFIGURED_SECTION_START}}\\n# Open all sessions in terminal tabs\\nathene open {{projectId}}{{REPO_CONFIGURED_SECTION_END}}\\n```\\n\\n{{REPO_NOT_CONFIGURED_SECTION_START}}\\n\\n> **Note:** No repository remote is configured. Issue tracking, PR, and CI features are unavailable.\\n> Add a `repo` field (owner/repo) to `agent-orchestrator.yaml` to enable them.\\n{{REPO_NOT_CONFIGURED_SECTION_END}}\\n\\n## Available Commands\\n\\n- `athene status`: Show all sessions{{REPO_CONFIGURED_SECTION_START}} with PR/CI/review status{{REPO_CONFIGURED_SECTION_END}}\\n- `athene spawn [issue] [--prompt <text>]{{REPO_CONFIGURED_SECTION_START}} [--claim-pr <pr>]{{REPO_CONFIGURED_SECTION_END}}`: Spawn a worker session{{REPO_CONFIGURED_SECTION_START}}; use issue ID or --prompt for freeform tasks{{REPO_CONFIGURED_SECTION_END}}{{REPO_NOT_CONFIGURED_SECTION_START}} with --prompt for freeform tasks{{REPO_NOT_CONFIGURED_SECTION_END}}\\n  {{REPO_CONFIGURED_SECTION_START}}- `athene batch-spawn <issues...>`: Spawn multiple sessions in parallel (project auto-detected)\\n  {{REPO_CONFIGURED_SECTION_END}}- `athene session ls [-p project]`: List all sessions (optionally filter by project)\\n- `athene review list [project]`: List AO-local reviewer runs. These are review agents/runs, not coding worker sessions.\\n- `athene review run <session> [--execute]`: Request a reviewer run for a coding worker session.\\n- `athene review execute [project] [--run <run>]`: Execute a queued reviewer run.\\n- `athene review send <run> [-p project]`: Send open AO-local findings from a completed reviewer run to its linked coding worker, then mark the run as waiting for worker updates.\\n  {{REPO_CONFIGURED_SECTION_START}}- `athene session claim-pr <pr> [session]`: Attach an existing PR to a worker session\\n  {{REPO_CONFIGURED_SECTION_END}}- `athene session attach <session>`: Attach to a session's terminal (a tmux window on Unix; a ConPTY pty-host on Windows)\\n- `athene session kill <session>`: Kill a specific session\\n- `athene session cleanup [-p project]`: Kill cleanup-eligible sessions (closed work or dead runtimes)\\n- `athene send <session> <message>`: Send a message to a running session\\n- `athene send --no-wait <session> <message>`: Send without waiting for session to become idle\\n- `athene dashboard`: Start the web dashboard (http://localhost:{{dashboardPort}})\\n- `athene open <project>`: Open all project sessions in terminal tabs\\n\\n## Session Management\\n\\n### Spawning Sessions\\n\\nWhen you spawn a session:\\n\\n1. A git worktree is created from `{{projectDefaultBranch}}`\\n2. A feature branch is created (e.g., `feat/INT-1234` for issues, `session/<id>` for prompt-driven)\\n3. A runtime session is started (e.g., `{{projectSessionPrefix}}-1`) — tmux session on Unix, ConPTY pty-host on Windows\\n4. The agent is launched with context about the issue or prompt\\n5. Metadata is written to the project-specific sessions directory\\n\\nA tracker issue is **not required**. Use `--prompt` to spawn freeform sessions:\\n\\n```bash\\nathene spawn --prompt \\\"Add rate limiting to the /api/upload endpoint\\\"\\n```\\n\\n### Monitoring Progress\\n\\nUse `athene status` to see:\\n\\n- Current session status (working, pr_open, review_pending, etc.)\\n- AO-local reviewer run summary and open finding counts\\n  {{REPO_CONFIGURED_SECTION_START}}- PR state (open/merged/closed)\\n- CI status (passing/failing/pending)\\n- Review decision (approved/changes_requested/pending)\\n- Unresolved comments count\\n  {{REPO_CONFIGURED_SECTION_END}}\\n\\nTo inspect what each worker has self-reported, pass `--reports`:\\n\\n```bash\\nathene status --reports 5      # last 5 report entries per session\\nathene status --reports full   # full audit trail per session\\n```\\n\\nReach for this when an inferred status disagrees with what the worker said, when deciding whether to send a follow-up instruction vs. wait, or when triaging a session that looks stuck.\\n\\nReviewer runs are intentionally separate from coding worker sessions. A reviewer run has its own workspace and context, and does not appear in `athene session ls` as a coding session. Use `athene status` for the summary and `athene review list {{projectId}}` for the detailed reviewer-run list.\\n\\nWhen a reviewer run has open findings, do not manually summarize them from memory. Use `athene review send <reviewer-session-id-or-run-id> -p {{projectId}}` to hand the stored findings back to the linked coding worker through AO. After sending, monitor the worker and request a new review once it reports the fixes are ready.\\n\\n### AO-Local Review Loop\\n\\nWhen the user asks you to review a worker, review a PR, or keep reviewing until clean, handle the loop internally:\\n\\n1. Inspect current state with `athene status` and identify the coding worker session.\\n2. Request and execute the reviewer run with `athene review run <worker-session-id> --execute`.\\n3. If the run is clean, report that the work is AO-review clean.\\n4. If the run has open findings, send the stored findings to the linked coding worker with `athene review send <reviewer-session-id-or-run-id> -p {{projectId}}`.\\n5. Monitor the coding worker with `athene status` and wait for it to push fixes or report `ready-for-review`.\\n6. Re-run `athene review run <worker-session-id> --execute` after the worker updates.\\n7. Continue until the review is clean, the worker is stuck, the user asks you to stop, or the configured review round limit is reached.\\n\\nDo not ask the user to manually run review commands for routine review/fix iterations. Treat review commands as orchestration internals, the same way worker spawning and `athene send` are orchestration internals.\\n\\n### Explicit Agent Reports\\n\\nWorker agents self-declare their workflow phase using `athene acknowledge` and `athene report <state>` (started, working, waiting, needs-input, fixing-ci, addressing-reviews, pr-created, draft-pr-created, ready-for-review, completed). These reports are persisted alongside the canonical lifecycle and may inform lifecycle inference, but do not replace runtime/activity/SCM-derived truth.\\n\\n- Never run `athene acknowledge` or `athene report` from the orchestrator session - they are worker-only commands. Read the audit trail with `athene status --reports` instead.\\n- Fresh reports (<5 min) are useful hints when inference is weak, but runtime death, activity-based waiting_input, and SCM truth (merged/closed PR, CI failure, review decisions) still take precedence.\\n- Use `--pr-url` / `--pr-number` on PR workflow reports when the agent knows them; merged/closed remain SCM-owned.\\n- If an agent reports `waiting` but a PR actually merged, trust the PR state and follow up.\\n\\n### Sending Messages\\n\\nSend instructions to a running agent:\\n\\n```bash\\nathene send {{projectSessionPrefix}}-1 \\\"Please address the review comments on your PR\\\"\\n```\\n\\n{{REPO_CONFIGURED_SECTION_START}}### PR Takeover\\n\\nIf a worker session needs to continue work on an existing PR:\\n\\n```bash\\nathene session claim-pr 123 {{projectSessionPrefix}}-1\\n# or do it at spawn time\\nathene spawn --claim-pr 123\\n```\\n\\nThis updates AO metadata, switches the worker worktree onto the PR branch, and lets lifecycle reactions keep routing CI and review feedback to that worker session.\\n\\nNever claim a PR into `{{projectSessionPrefix}}-orchestrator`. If a PR needs implementation or takeover, delegate it to a worker session instead.\\n{{REPO_CONFIGURED_SECTION_END}}\\n\\n### Investigation Workflow\\n\\nWhen debugging or triaging from the orchestrator session:\\n\\n1. Inspect with read-only commands such as `athene status`, `athene session ls`, `athene session attach`, and SCM/tracker lookups.\\n2. Decide whether a worker already owns the work or a new worker is needed.\\n3. Delegate implementation, test execution, or PR claiming to that worker session.\\n4. Return to monitoring and coordination once the worker has the task.\\n\\n### Cleanup\\n\\nRemove completed sessions:\\n\\n```bash\\nathene session cleanup -p {{projectId}}  # Kill sessions whose work closed or runtime has exited\\n```\\n\\n## Dashboard\\n\\nThe web dashboard runs at **http://localhost:{{dashboardPort}}**.\\n\\nFeatures:\\n\\n- Live session cards with activity status\\n- PR table with CI checks and review state\\n- Attention zones (merge ready, needs response, working, done)\\n- One-click actions (send message, kill, merge PR)\\n- Real-time updates via Server-Sent Events\\n\\n{{AUTOMATED_REACTIONS_SECTION_START}}\\n\\n## Automated Reactions\\n\\nThe system automatically handles these events:\\n\\n{{automatedReactionsSection}}\\n{{AUTOMATED_REACTIONS_SECTION_END}}\\n\\n## Common Workflows\\n\\n{{REPO_CONFIGURED_SECTION_START}}### Bulk Issue Processing\\n\\n1. Get list of issues from tracker (GitHub/Linear/etc.)\\n2. Use `athene batch-spawn` to spawn sessions for each issue\\n3. Monitor with `athene status` or the dashboard\\n4. Agents will fetch, implement, test, PR, and respond to reviews\\n5. Use `athene session cleanup` when work is truly finished or the runtime is gone\\n\\n{{REPO_CONFIGURED_SECTION_END}}### Handling Stuck Agents\\n\\n1. Check `athene status` for sessions in \\\"stuck\\\" or \\\"needs_input\\\" state\\n2. Attach with `athene session attach <session>` to see what they're doing\\n3. Send clarification or instructions with `athene send <session> '...'`\\n4. Or kill and respawn with fresh context if needed\\n\\n{{REPO_CONFIGURED_SECTION_START}}### PR Review Flow\\n\\n1. Agent creates PR and pushes\\n2. CI runs automatically\\n3. If CI fails: reaction auto-sends fix instructions to agent\\n4. If reviewers request changes: reaction auto-sends comments to agent\\n5. When approved + green: notify human to merge (unless auto-merge enabled)\\n\\n{{REPO_CONFIGURED_SECTION_END}}### Manual Intervention\\n\\nWhen an agent needs human judgment:\\n\\n1. You'll get a notification (desktop/slack/webhook)\\n2. Check the dashboard or `athene status` for details\\n3. Attach to the session if needed: `athene session attach <session>`\\n4. Send instructions: `athene send <session> '...'`\\n5. Or handle the human-only action yourself{{REPO_CONFIGURED_SECTION_START}} (merge PR, close issue, etc.){{REPO_CONFIGURED_SECTION_END}} while keeping implementation in worker sessions.\\n\\n## Tips\\n\\n1. **Use batch-spawn for multiple issues** - Much faster than spawning one at a time.\\n\\n2. **Check status before spawning** - Avoid creating duplicate sessions for issues already being worked on.\\n\\n3. **Let reactions handle routine issues** - CI failures and review comments are auto-forwarded to agents.\\n\\n4. **Trust the metadata** - Session metadata tracks branch, PR, status, and more for each session.\\n\\n5. **Use the dashboard for overview** - Terminal for details, dashboard for at-a-glance status.\\n\\n6. **Cleanup regularly** - `athene session cleanup` removes sessions that are truly cleanup-eligible and keeps things tidy.\\n\\n7. **Monitor the event log** - Full system activity is logged for debugging and auditing.\\n\\n8. **Don't micro-manage** - Spawn agents, walk away, let notifications bring you back when needed.\\n\\n{{PROJECT_SPECIFIC_RULES_SECTION_START}}\\n\\n## Project-Specific Rules\\n\\n{{projectSpecificRulesSection}}\\n{{PROJECT_SPECIFIC_RULES_SECTION_END}}\\n\";"],"names":[],"mappings":"AAAA,2BAAe,m8cAAm8c;;;;"}

package/dist/runtime-orphans.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Runtime orphan reconciliation.
+ *
+ * AO spawns one runtime session (tmux session / pty-host) per worker. When a
+ * session's tracked metadata is removed or marked terminal but its runtime
+ * session lingers, that runtime session becomes an *orphan* — it leaks memory
+ * and CPU with nothing tracking it. This module reconciles the set of live
+ * runtime sessions against tracked session metadata and reaps the orphans.
+ *
+ * CRITICAL SAFETY: only sessions whose names match the AO naming convention
+ * (`<sessionPrefix>-<number>`) are ever considered. Human-created tmux sessions
+ * — or AO orchestrator sessions, which are deliberately excluded — are never
+ * selected for reaping. See `isAoRuntimeSessionName`.
+ */
+import type { Runtime, RuntimeSessionSummary } from "./types.js";
+/** Default grace period before a never-tracked runtime session can be reaped. */
+export declare const DEFAULT_ORPHAN_GRACE_MS = 120000;
+/**
+ * CRITICAL SAFETY filter. Returns true ONLY for runtime session names that
+ * follow AO's worker naming convention `<sessionPrefix>-<number>` for one of the
+ * supplied project prefixes. Anchored and prefix-escaped so arbitrary human
+ * sessions can never match. Orchestrator sessions (`<prefix>-orchestrator[-n]`)
+ * are intentionally NOT matched — they are long-lived coordinators and are left
+ * alone.
+ */
+export declare function isAoRuntimeSessionName(name: string, sessionPrefixes: Iterable<string>): boolean;
+export interface RuntimeOrphanInput {
+    /** Every live runtime session observed (across one runtime). */
+    liveSessions: RuntimeSessionSummary[];
+    /** Ids of tracked sessions that are NON-terminal (still alive in AO's view). */
+    activeTrackedIds: Set<string>;
+    /** Project session prefixes the matcher is allowed to consider. */
+    sessionPrefixes: string[];
+    /** Sessions younger than this (by createdAt) are spared (create/race window). */
+    graceMs: number;
+    /** Current time in epoch ms. */
+    nowMs: number;
+}
+/**
+ * Pure reconciliation: an AO-named runtime session is an orphan when it has no
+ * non-terminal tracked session AND it is older than the grace period. Sessions
+ * with an unknown createdAt cannot be grace-gated and are eligible immediately.
+ */
+export declare function findRuntimeOrphans(input: RuntimeOrphanInput): RuntimeSessionSummary[];
+export interface RuntimeForReconcile {
+    runtime: Runtime;
+    /** Prefixes whose sessions this runtime may own. */
+    sessionPrefixes: string[];
+}
+export interface OrphanReapOutcome {
+    id: string;
+    runtimeName: string;
+    reaped: boolean;
+    error?: string;
+}
+export interface RuntimeOrphanReport {
+    /** Every live AO-named runtime session seen, across all runtimes. */
+    liveAoSessions: RuntimeSessionSummary[];
+    /** The subset judged to be orphans. */
+    orphans: RuntimeSessionSummary[];
+    /** Per-orphan reap outcomes (empty when reap is false). */
+    outcomes: OrphanReapOutcome[];
+}
+export interface ReconcileRuntimeOrphansOptions {
+    runtimes: RuntimeForReconcile[];
+    activeTrackedIds: Set<string>;
+    graceMs?: number;
+    nowMs?: number;
+    /** When true, orphans are destroyed; otherwise the report is detection-only. */
+    reap?: boolean;
+    /** Optional logger invoked once per reaped (or failed) orphan. */
+    log?: (message: string, data: Record<string, unknown>) => void;
+}
+/**
+ * Enumerate live runtime sessions, find orphans, and (optionally) reap them via
+ * `Runtime.destroy()`. Best-effort and resilient: runtimes without
+ * `listSessions` are skipped, enumeration failures are swallowed, and a single
+ * failed destroy is recorded without aborting the rest.
+ */
+export declare function reconcileRuntimeOrphans(options: ReconcileRuntimeOrphansOptions): Promise<RuntimeOrphanReport>;
+export interface RuntimeResourceUsage {
+    pid: number;
+    rssMb?: number;
+    cpuPercent?: number;
+}
+/**
+ * Parse `ps -o pid=,rss=,pcpu=` output (rss in KB) into per-pid usage with RSS
+ * converted to MB. Malformed rows are ignored.
+ */
+export declare function parsePsResourceOutput(output: string): Map<number, RuntimeResourceUsage>;
+/**
+ * Best-effort RSS/CPU lookup for a set of pids via `ps`. POSIX-only; returns an
+ * empty map on Windows, when given no pids, or on any failure.
+ */
+export declare function readProcessResourceUsage(pids: number[]): Promise<Map<number, RuntimeResourceUsage>>;
+//# sourceMappingURL=runtime-orphans.d.ts.map

package/dist/runtime-orphans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-orphans.d.ts","sourceRoot":"","sources":["../src/runtime-orphans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAIjE,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,SAAU,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,GAChC,OAAO,CAOT;AAED,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,YAAY,EAAE,qBAAqB,EAAE,CAAC;IACtC,gFAAgF;IAChF,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,mEAAmE;IACnE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,qBAAqB,EAAE,CAQrF;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,cAAc,EAAE,qBAAqB,EAAE,CAAC;IACxC,uCAAuC;IACvC,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,2DAA2D;IAC3D,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAChE;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,mBAAmB,CAAC,CAgE9B;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAavF;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAa5C"}

package/dist/runtime-orphans.js

@@ -0,0 +1,158 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { isWindows } from './platform.js';
+
+/**
+ * Runtime orphan reconciliation.
+ *
+ * AO spawns one runtime session (tmux session / pty-host) per worker. When a
+ * session's tracked metadata is removed or marked terminal but its runtime
+ * session lingers, that runtime session becomes an *orphan* — it leaks memory
+ * and CPU with nothing tracking it. This module reconciles the set of live
+ * runtime sessions against tracked session metadata and reaps the orphans.
+ *
+ * CRITICAL SAFETY: only sessions whose names match the AO naming convention
+ * (`<sessionPrefix>-<number>`) are ever considered. Human-created tmux sessions
+ * — or AO orchestrator sessions, which are deliberately excluded — are never
+ * selected for reaping. See `isAoRuntimeSessionName`.
+ */
+const execFileAsync = promisify(execFile);
+/** Default grace period before a never-tracked runtime session can be reaped. */
+const DEFAULT_ORPHAN_GRACE_MS = 120_000;
+/**
+ * CRITICAL SAFETY filter. Returns true ONLY for runtime session names that
+ * follow AO's worker naming convention `<sessionPrefix>-<number>` for one of the
+ * supplied project prefixes. Anchored and prefix-escaped so arbitrary human
+ * sessions can never match. Orchestrator sessions (`<prefix>-orchestrator[-n]`)
+ * are intentionally NOT matched — they are long-lived coordinators and are left
+ * alone.
+ */
+function isAoRuntimeSessionName(name, sessionPrefixes) {
+    for (const prefix of sessionPrefixes) {
+        if (!prefix)
+            continue;
+        const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        if (new RegExp(`^${escaped}-\\d+$`).test(name))
+            return true;
+    }
+    return false;
+}
+/**
+ * Pure reconciliation: an AO-named runtime session is an orphan when it has no
+ * non-terminal tracked session AND it is older than the grace period. Sessions
+ * with an unknown createdAt cannot be grace-gated and are eligible immediately.
+ */
+function findRuntimeOrphans(input) {
+    const { liveSessions, activeTrackedIds, sessionPrefixes, graceMs, nowMs } = input;
+    return liveSessions.filter((s) => {
+        if (!isAoRuntimeSessionName(s.id, sessionPrefixes))
+            return false; // SAFETY gate
+        if (activeTrackedIds.has(s.id))
+            return false; // tracked & non-terminal → keep
+        if (typeof s.createdAt === "number" && nowMs - s.createdAt < graceMs)
+            return false;
+        return true;
+    });
+}
+/**
+ * Enumerate live runtime sessions, find orphans, and (optionally) reap them via
+ * `Runtime.destroy()`. Best-effort and resilient: runtimes without
+ * `listSessions` are skipped, enumeration failures are swallowed, and a single
+ * failed destroy is recorded without aborting the rest.
+ */
+async function reconcileRuntimeOrphans(options) {
+    const { runtimes, activeTrackedIds, graceMs = DEFAULT_ORPHAN_GRACE_MS, nowMs = Date.now(), reap = false, log, } = options;
+    const liveAoSessions = [];
+    const orphans = [];
+    const outcomes = [];
+    for (const { runtime, sessionPrefixes } of runtimes) {
+        if (typeof runtime.listSessions !== "function")
+            continue;
+        let live;
+        try {
+            live = await runtime.listSessions();
+        }
+        catch {
+            continue; // enumeration is best-effort
+        }
+        for (const session of live) {
+            if (isAoRuntimeSessionName(session.id, sessionPrefixes))
+                liveAoSessions.push(session);
+        }
+        const runtimeOrphans = findRuntimeOrphans({
+            liveSessions: live,
+            activeTrackedIds,
+            sessionPrefixes,
+            graceMs,
+            nowMs,
+        });
+        for (const orphan of runtimeOrphans) {
+            orphans.push(orphan);
+            if (!reap)
+                continue;
+            try {
+                await runtime.destroy({
+                    id: orphan.id,
+                    runtimeName: runtime.name,
+                    data: orphan.handleData ?? {},
+                });
+                outcomes.push({ id: orphan.id, runtimeName: runtime.name, reaped: true });
+                log?.(`reaped orphan runtime session ${orphan.id}`, {
+                    sessionId: orphan.id,
+                    runtime: runtime.name,
+                    reason: "no non-terminal tracked session",
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                outcomes.push({ id: orphan.id, runtimeName: runtime.name, reaped: false, error: message });
+                log?.(`failed to reap orphan runtime session ${orphan.id}`, {
+                    sessionId: orphan.id,
+                    runtime: runtime.name,
+                    error: message,
+                });
+            }
+        }
+    }
+    return { liveAoSessions, orphans, outcomes };
+}
+/**
+ * Parse `ps -o pid=,rss=,pcpu=` output (rss in KB) into per-pid usage with RSS
+ * converted to MB. Malformed rows are ignored.
+ */
+function parsePsResourceOutput(output) {
+    const usage = new Map();
+    for (const rawLine of output.replaceAll("\r\n", "\n").split("\n")) {
+        const parts = rawLine.trim().split(/\s+/);
+        if (parts.length < 3)
+            continue;
+        const pid = Number(parts[0]);
+        const rssKb = Number(parts[1]);
+        const cpu = Number(parts[2]);
+        if (!Number.isInteger(pid) || pid <= 0)
+            continue;
+        if (!Number.isFinite(rssKb) || !Number.isFinite(cpu))
+            continue;
+        usage.set(pid, { pid, rssMb: Math.round(rssKb / 1024), cpuPercent: cpu });
+    }
+    return usage;
+}
+/**
+ * Best-effort RSS/CPU lookup for a set of pids via `ps`. POSIX-only; returns an
+ * empty map on Windows, when given no pids, or on any failure.
+ */
+async function readProcessResourceUsage(pids) {
+    const valid = [...new Set(pids.filter((p) => Number.isInteger(p) && p > 0))];
+    if (isWindows() || valid.length === 0)
+        return new Map();
+    try {
+        const { stdout } = await execFileAsync("ps", ["-o", "pid=,rss=,pcpu=", "-p", valid.join(",")], { windowsHide: true, maxBuffer: 1024 * 1024 });
+        return parsePsResourceOutput(stdout);
+    }
+    catch {
+        return new Map();
+    }
+}
+
+export { DEFAULT_ORPHAN_GRACE_MS, findRuntimeOrphans, isAoRuntimeSessionName, parsePsResourceOutput, readProcessResourceUsage, reconcileRuntimeOrphans };
+//# sourceMappingURL=runtime-orphans.js.map

package/dist/runtime-orphans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-orphans.js","sources":["../src/runtime-orphans.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/session-manager.d.ts

@@ -13,6 +13,22 @@
 import { type OpenCodeSessionManager, type OrchestratorConfig, type PluginRegistry } from "./types.js";
 /** Re-export so existing core test-utils + session-manager call sites keep working. */
 export declare function resetOpenCodeSessionListCache(): void;
+/**
+ * Whether a waiter may reap an existing spawn.lock:
+ *  - over the absolute age ceiling → always reapable (any lock); or
+ *  - holder PID is parseable and provably dead → reapable immediately.
+ * A fresh lock held by a live PID (or in its brief no-token mid-write window) is
+ * NOT reaped. Exported for tests.
+ */
+export declare function isSpawnLockReapable(lockPath: string, now?: number): boolean;
+/**
+ * Release a spawn.lock ONLY if it still records our owner token. If the file is
+ * missing or holds a different token — meaning we were reaped (age ceiling) and
+ * another process now owns it — leave it alone. This closes the lock-steal race
+ * where a holder that overran the ceiling would otherwise delete the new owner's
+ * lock. Exported for tests.
+ */
+export declare function releaseSpawnLockIfOwned(lockPath: string, ownerToken: string): void;
 export interface SessionManagerDeps {
     config: OrchestratorConfig;
     registry: PluginRegistry;

package/dist/session-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,OAAO,EAQL,KAAK,sBAAsB,EAW3B,KAAK,kBAAkB,EAQvB,KAAK,cAAc,EAKpB,MAAM,YAAY,CAAC;AAoGpB,uFAAuF;AACvF,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AA0ND,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,wCAAwC;AACxC,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,sBAAsB,CAixGrF"}
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,OAAO,EAQL,KAAK,sBAAsB,EAY3B,KAAK,kBAAkB,EAQvB,KAAK,cAAc,EAKpB,MAAM,YAAY,CAAC;AAwGpB,uFAAuF;AACvF,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAiOD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAsBvF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAQlF;AA6ED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,wCAAwC;AACxC,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,sBAAsB,CAquHrF"}