@oh-my-pi/pi-coding-agent 15.10.12 → 15.11.1

package/src/prompts/system/workflow-notice.md

@@ -13,8 +13,8 @@ Worth it when the task benefits from decomposition + parallel coverage, or from
 <helpers>
 State persists across cells, so scout in one cell and fan out in the next. Every cell has:
 
-- `agent(prompt, *, agent_type="task", model=None, context=None, label=None, schema=None)` — run ONE subagent; returns its final text, or the validated object when `schema` (a JSON Schema dict) is given. With `schema` the subagent is forced to emit structured output that is validated for you — branch on the object, not on parsed prose. `agent_type` picks a discovered agent ("explore", "reviewer", "oracle", …); `context` is shared background; `label` names the artifact. Subagents are told their final text IS the return value, so they hand back raw data. `agent()` blocks until the subagent finishes; eval-spawned agents nest at most 3 deep.
-- `parallel(thunks)` — run zero-arg callables concurrently through a bounded pool, preserving input order; returns once all finish. The pool runs as wide as a `task` tool batch — don't hand-tune it; fan out as wide as the work divides. A thunk that raises propagates — wrap risky work in `try/except` inside the thunk to keep partial results. In a loop, bind each closure's value with a default arg (`lambda d=d: …`) or every thunk captures the last one.
+- `agent(prompt, *, agent_type="task", model=None, label=None, schema=None)` — run ONE subagent; returns its final text, or the validated object when `schema` (a JSON Schema dict) is given. With `schema` the subagent is forced to emit structured output that is validated for you — branch on the object, not on parsed prose. `agent_type` picks a discovered agent ("explore", "reviewer", "oracle", …); `label` names the artifact. Shared background goes in a `local://` file referenced from each prompt, not a parameter. Subagents are told their final text IS the return value, so they hand back raw data. `agent()` blocks until the subagent finishes; eval-spawned agents nest at most 3 deep.
+- `parallel(thunks)` — run zero-arg callables concurrently through a bounded pool, preserving input order; returns once all finish. The pool is bounded by the session's `task` concurrency — don't hand-tune it; fan out as wide as the work divides. A thunk that raises propagates — wrap risky work in `try/except` inside the thunk to keep partial results. In a loop, bind each closure's value with a default arg (`lambda d=d: …`) or every thunk captures the last one.
 - `pipeline(items, *stages)` — map items through `stages` left-to-right. There is a BARRIER between stages: ALL items clear stage N before stage N+1 begins. Each stage is a one-arg callable; stage 1 gets the original item, later stages get the previous result. Same pool width as `parallel()`.
 - `completion(prompt, *, model="default", system=None, schema=None)` — oneshot, stateless model call (no tools, no history). Tiers: "smol", "default", "slow". Cheap classification/scoring inside a fan-out.
 - `log(message)` — emit a progress line above the status tree. `phase(title)` — start a phase; the status lines that follow group under it.

package/src/prompts/tools/eval.md

@@ -46,9 +46,9 @@ tool.<name>(args) → unknown
     Invoke any session tool by name. `args` is the tool's parameter object.
 completion(prompt, model?="default", system?=None, schema?=None) → str | dict
     Oneshot, stateless completion (no history, no tools). `model` picks a tier: "smol" (fast), "default" (this session's model), "slow" (most capable). Pass `system` for a system prompt. Pass a JSON-Schema `schema` to force structured output and get the parsed object back; otherwise returns the completion text.
-{{#if spawns}}agent(prompt, agent_type?="task", model?=None, context?=None, label?=None, schema?=None) → str | dict
-    Run a subagent and return its final output. Defaults to the bundled "task" agent; pass `agent_type`/`agentType` for another discovered agent. Pass a JSON-Schema `schema` to force structured output and get the parsed object back.
-{{#if js}}    In JS, pass options as one trailing object — never positional: agent(prompt, { agentType, context, schema }).
+{{#if spawns}}agent(prompt, agent_type?="task", model?=None, label?=None, schema?=None) → str | dict
+    Run a subagent and return its final output. Defaults to the bundled "task" agent; pass `agent_type`/`agentType` for another discovered agent. Pass a JSON-Schema `schema` to force structured output and get the parsed object back. Share background by writing a `local://` file and referencing it in the prompt.
+{{#if js}}    In JS, pass options as one trailing object — never positional: agent(prompt, { agentType, schema }).
 {{/if}}
 {{/if}}
 parallel(thunks) → list

package/src/prompts/tools/irc.md

@@ -1,11 +1,15 @@
-Sends short text messages to other live agents in this process and receives their prose replies.
+Sends short text messages to other agents in this process and receives theirs.
 
 <instruction>
 - The main agent is addressable as `Main`. Subagents reuse their task id (e.g. `AuthLoader`, or `AuthLoader-2` when the name repeats).
-- `op: "list"` returns the current set of visible peers. Use it before sending if you are not sure who is live.
-- `op: "send"` delivers `message` to `to`. `to` may be a specific id or `"all"` to broadcast.
-- Replies are generated on a side channel that does not wait for the recipient's main loop, so it is safe to IRC an agent that is mid tool call.
-- The exchange (question + auto-reply) is injected into the recipient's history; they see it on their next turn and can follow up.
+- `op: "list"` — every addressable peer with status (`running` | `idle` | `parked`), unread count, parent, and last activity. Use it before sending if you are not sure who exists.
+- `op: "send"` — fire-and-forget delivery of `message` to `to` (a peer id, or `"all"` to broadcast to live peers). Returns per-recipient receipts immediately; it NEVER waits for the recipient to act. Receipt outcomes: `injected` (recipient was mid-turn; message folded in at their next step boundary), `woken` (idle recipient started a turn), `revived` (parked recipient was brought back and woken), `failed`.
+- Messaging an `idle` or `parked` peer is how you wake it — there is no separate revive call.
+- `send` with `await: true` — convenience round-trip: send, then block until the next message from that peer arrives (or the timeout passes). Invalid with `to: "all"`.
+- `op: "wait"` — block until a message arrives (optionally only `from` a specific peer); consumes and returns it. A timeout is a clean "no message" result, not an error.
+- `op: "inbox"` — drain pending messages without blocking (`peek: true` to leave them unread).
+- `replyTo` — set it to the id of the message you are answering so the sender can correlate.
+- Nobody answers on a peer's behalf anymore: a reply only arrives when the recipient actually sends one. For background on what a peer has been doing, `read` `history://<id>` instead of interrogating them.
 </instruction>
 
 <when_to_use>
@@ -21,29 +25,35 @@ NEVER use `irc` for: routine progress updates, things a tool call can verify, or
 <etiquette>
 These rules apply to both sending and replying.
 - **Plain prose only.** NEVER send structured JSON status payloads (e.g. `{"type":"task_completed",…}`). Write a normal sentence: "Done with the auth refactor — left a TODO in `src/server/auth.ts` for the rate limiter."
-- **NEVER quote the message you are replying to.** Lead with the answer.
-- **Use IRC, not terminal tools, to learn about peers.** NEVER `grep` artifacts, read other sessions' JSONL files, or shell-poke to figure out what another agent is doing. DM them.
-- **One round-trip is enough.** Replies arrive synchronously when the recipient is reachable. NEVER follow up with "did you get my message?". If `delivered` is empty or the result was `failed`, the peer is unavailable — move on or report the blocker; NEVER retry in a loop.
+- **NEVER quote the message you are replying to.** Lead with the answer; set `replyTo` instead.
+- **Use IRC, not terminal tools, to learn about peers.** NEVER `grep` artifacts, read other sessions' JSONL files, or shell-poke to figure out what another agent is doing. DM them, or `read` `history://<id>`.
+- **Send, then keep working.** `send` returns immediately — only `wait` (or `await: true`) when you genuinely cannot proceed without the answer. NEVER follow up with "did you get my message?"; a `failed` receipt means the peer is unreachable — move on or report the blocker; NEVER retry in a loop.
+- **Answer when a response is expected.** When an incoming message asks something, reply with `irc send` to the sender (you may finish your current step first).
 - **Stay terse.** A DM is a chat message, not a memo. One question per send. Share file paths and artifacts via `local://` / `memory://` / `artifact://` URLs instead of pasting blobs.
 - **Address peers by id.** Use the exact id from `op: "list"` (e.g. `AuthLoader`, `Main`). NEVER invent friendly names.
 - **NEVER IRC for things a tool would answer.** If a `read`, `grep`, or build command resolves the question, do that first.
-- **Answer incoming IRC messages before continuing.** Address the question directly; do not repeat it back to the user.
 </etiquette>
 
 <output>
-- `send`: returns each recipient that received the message and any prose replies that arrived.
-- `list`: returns peers and channels visible to the caller.
+- `send`: per-recipient delivery receipts (`injected` / `woken` / `revived` / `failed`); with `await: true`, also the reply (or a timeout notice).
+- `wait`: the consumed message, or a clean timeout notice.
+- `inbox`: pending messages, oldest first.
+- `list`: peers with status, unread count, parent, and last activity.
 </output>
 
 <examples>
 # List peers
 `{"op": "list"}`
-# Direct message to the main agent (waits for prose reply)
-`{"op": "send", "to": "Main", "message": "Should I prefer JWT or session cookies for the auth flow?"}`
-# Unexpected state — ask the originator
-`{"op": "send", "to": "Main", "message": "Assignment says edit src/auth/jwt.ts but the file does not exist. Is the new path src/server/auth/jwt.ts?"}`
-# Blocked by a peer — ask them directly
-`{"op": "send", "to": "AuthLoader", "message": "Are you still touching src/server/auth.ts? I need to add a 401 path; OK to proceed or should I wait?"}`
-# Broadcast to discover who owns something (no replies, just informs them)
-`{"op": "send", "to": "all", "message": "About to refactor src/server/middleware/*. Anyone already in there?", "awaitReply": false}`
+# Fire-and-forget DM — keep working, check inbox later
+`{"op": "send", "to": "AuthLoader", "message": "Are you still touching src/server/auth.ts? I need to add a 401 path."}`
+# Round-trip when you cannot proceed without the answer
+`{"op": "send", "to": "Main", "message": "Should I prefer JWT or session cookies for the auth flow?", "await": true}`
+# Wake a parked agent (same send — the bus revives it)
+`{"op": "send", "to": "SchemaMigrator", "message": "The users table changed again; please re-check your migration."}`
+# Block until a specific peer answers
+`{"op": "wait", "from": "AuthLoader", "timeoutMs": 60000}`
+# Drain pending messages
+`{"op": "inbox"}`
+# Broadcast to live peers (no replies expected)
+`{"op": "send", "to": "all", "message": "About to refactor src/server/middleware/*. Anyone already in there?"}`
 </examples>

package/src/prompts/tools/read.md

@@ -8,7 +8,7 @@ Read files, directories, archives, SQLite databases, images, documents, internal
 
 ## Parameters
 
-- `path` — required. Local path, internal URI (`skill://`, `agent://`, `artifact://`, `memory://`, `rule://`, `local://`, `vault://`, `mcp://`, `omp://`, `issue://`, `pr://`), or URL. Append `:<sel>` for line ranges, raw mode, or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).
+- `path` — required. Local path, internal URI (`skill://`, `agent://`, `artifact://`, `history://`, `memory://`, `rule://`, `local://`, `vault://`, `mcp://`, `omp://`, `issue://`, `pr://`), or URL. Append `:<sel>` for line ranges, raw mode, or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).
 
 ## Selectors
 
@@ -74,7 +74,7 @@ For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 
 # Internal URIs
 
-`skill://<name>`, `agent://<id>`, `artifact://<id>`, `memory://root`, `rule://<name>`, `local://<name>.md`, `vault://<vault>/<path>`, `mcp://<uri>`, `omp://<doc>.md`, `issue://<N>`, and `pr://<N>` resolve transparently and accept the same line selectors as filesystem paths. Use `artifact://<id>` to recover full output that a previous bash/eval/tool result spilled or truncated.
+`skill://<name>`, `agent://<id>`, `artifact://<id>`, `history://<agentId>`, `memory://root`, `rule://<name>`, `local://<name>.md`, `vault://<vault>/<path>`, `mcp://<uri>`, `omp://<doc>.md`, `issue://<N>`, and `pr://<N>` resolve transparently and accept the same line selectors as filesystem paths. Use `artifact://<id>` to recover full output that a previous bash/eval/tool result spilled or truncated. `history://<agentId>` is an agent's transcript as concise markdown; bare `history://` lists agents.
 
 <critical>
 - You MUST use `read` for every file, directory, archive, and URL inspection. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, `wget` are FORBIDDEN — any such bash call is a bug, regardless of how short or convenient it looks.

package/src/prompts/tools/task-summary.md

@@ -1,28 +1,17 @@
-<task-summary>
-<header>{{successCount}}/{{totalCount}} succeeded{{#if hasCancelledNote}} ({{cancelledCount}} cancelled){{/if}} [{{duration}}]</header>
-
-{{#each summaries}}
-<agent id="{{id}}" agent="{{agent}}">
-<status>{{status}}</status>
+<task-result id="{{id}}" agent="{{agentName}}" status="{{status}}" duration="{{duration}}">
 {{#if meta}}<meta lines="{{meta.lineCount}}" size="{{meta.charSize}}" />{{/if}}
 {{#if truncated}}
-<preview full-path="agent://{{id}}">
+<preview full-output="agent://{{id}}">
 {{preview}}
 </preview>
 {{else}}
-<result>
+<output>
 {{preview}}
-</result>
+</output>
 {{/if}}
-</agent>
-{{#unless @last}}
----
-{{/unless}}
-{{/each}}
-
 {{#if mergeSummary}}
 <merge-summary>
 {{mergeSummary}}
 </merge-summary>
 {{/if}}
-</task-summary>
+</task-result>

package/src/prompts/tools/task.md

@@ -1,43 +1,56 @@
-Launches subagents to parallelize workflows.
+{{#if asyncEnabled}}{{#if batchEnabled}}Spawns subagents to work in the background — one per `tasks[]` item; a single spawn is a one-item batch.{{else}}Spawns ONE subagent per call to work in the background.{{/if}}
 
-{{#if asyncEnabled}}
-- Results are delivered automatically when complete.
-- The tool result lists the assigned task ids (e.g. `AuthLoader`) — those are the live agent ids.
-{{#if ircEnabled}}
-- Coordinate with running tasks via `irc` using those ids. `job cancel` terminates a task and **cannot carry a message** — only use it for stalled/abandoned work.
-- If genuinely blocked on completion, wait with `job poll`; otherwise keep working.
-{{else}}
-- If genuinely blocked on completion, wait with `job poll`; otherwise keep working.
-- Use `job list` to snapshot manager state; `cancel: [id]` only to actually stop a stuck task.
-{{/if}}
-{{/if}}
+- Spawning is non-blocking: the call returns immediately with the agent id{{#if batchEnabled}}s{{/if}} and job id{{#if batchEnabled}}s{{/if}}; each result is delivered automatically when that agent yields.
+- Parallelism = {{#if batchEnabled}}`tasks[]` items in one call, and/or multiple `task` calls in one assistant message{{else}}multiple `task` calls in one assistant message{{/if}}. Concurrency is bounded at {{MAX_CONCURRENCY}} running subagents per session.
+- If genuinely blocked on a result, wait with `job poll`; otherwise keep working. `job cancel` terminates a task and **cannot carry a message** — only for stalled/abandoned work.
+{{else}}{{#if batchEnabled}}Runs subagents synchronously — one per `tasks[]` item; a single spawn is a one-item batch.{{else}}Runs ONE subagent synchronously per call.{{/if}}
 
+- Spawning is blocking: the call returns only after the agent{{#if batchEnabled}}s{{/if}} finish; results arrive inline.
+- Parallelism = {{#if batchEnabled}}`tasks[]` items in one call, and/or multiple `task` calls in one assistant message{{else}}multiple `task` calls in one assistant message{{/if}}. Concurrency is bounded at {{MAX_CONCURRENCY}} running subagents per session.
+{{/if}}
 {{#if ircEnabled}}
-Subagents have no conversation history, but they can reach you and their siblings live via the `irc` tool. Front-load every fact, file path, and direction they need in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.
-{{else}}
-Subagents have no conversation history. Every fact, file path, and direction they need MUST be explicit in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.
+- Coordinate with agents via `irc` using their ids. Agents reach you and their siblings live the same way.
 {{/if}}
 
+<lifecycle>
+- Finished agents stay alive: `idle` first, then `parked` after a TTL.{{#if ircEnabled}} Both remain addressable and revivable: messaging one via `irc` wakes it and runs your message as a follow-up turn. **Prefer messaging an agent that already holds the relevant context over spawning fresh** — check `irc` op:"list" for candidates.{{/if}}
+- `history://<id>` is the agent's transcript; `agent://<id>` its latest output artifact.
+</lifecycle>
+
 <parameters>
-- `agent`: agent type for all tasks
-- `tasks`: tasks to execute in parallel
- - `.id`: CamelCase, ≤32 chars
- - `.description`: UI label only — subagent never sees it
- - `.assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED
-{{#if contextEnabled}}- `context`: shared background prepended to every assignment; session-specific only{{/if}}
-{{#if customSchemaEnabled}}- `schema`: JTD schema for expected structured output (do not put format rules in assignments){{/if}}
-{{#if isolationEnabled}}- `isolated`: run in isolated env; use when tasks edit overlapping files{{/if}}
+- `agent`: agent type to spawn
+{{#if batchEnabled}}
+- `context`: shared background prepended to every assignment — goal, constraints, shared contract (see context-fmt); REQUIRED, session-specific only
+- `tasks`: tasks to spawn — one subagent per item, all in parallel:
+  - `assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED
+  - `id`: stable agent id, CamelCase, ≤32 chars; generated when omitted
+  - `description`: UI label only — subagent never sees it
+{{#if isolationEnabled}}
+  - `isolated`: run this spawn in an isolated env; returns patches. Isolated agents are torn down at completion — not addressable afterwards
+{{/if}}
+{{else}}
+- `id`: stable agent id, CamelCase, ≤32 chars; generated when omitted
+- `description`: UI label only — subagent never sees it
+- `assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED
+{{#if isolationEnabled}}
+- `isolated`: run in isolated env; returns patches. Isolated agents are torn down at completion — not addressable afterwards
+{{/if}}
+{{/if}}
 </parameters>
 
 <rules>
-- **Maximize batch width.** Spawn the widest parallel set the work decomposes into. NEVER spawn a single-task batch for divisible work, or defer work that could have been concurrent.
-- **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates, formatters, and project-wide build/test/lint. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.
+- **Maximize fan-out.** Issue the widest {{#if batchEnabled}}`tasks[]` batch (or set of parallel `task` calls){{else}}set of parallel `task` calls{{/if}} the work decomposes into. NEVER serialize work that could run concurrently.
+- **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates, formatters, and project-wide build/test/lint. You run them once at the end across the union of changed files.
 - No globs, no "update all", no package-wide scope. Fan out.
 - NEVER slow down or serialize because tasks might overlap on some files. Agents resolve collisions among themselves in real time.
-- Pass large payloads via `local://<path>` URIs, not inline. {{#if contextEnabled}} (other than the context){{/if}}
-{{#if contextEnabled}}- Put shared constraints in `context` once; do not duplicate across assignments.{{/if}}
+- Subagents have no conversation history. Every fact, file path, and direction they need MUST be explicit in {{#if batchEnabled}}`context` or the item's `assignment`{{else}}the `assignment`{{/if}}.
+{{#if batchEnabled}}
+- **Shared background** lives in `context` once — never duplicated across assignments. Pass large payloads via `local://<path>` URIs, not inline.
+{{else}}
+- **Shared background**: write it ONCE to a `local://` file (e.g. `local://ctx.md`) and reference that path in each assignment. Pass large payloads via `local://<path>` URIs, not inline.
+{{/if}}
 - Prefer agents that investigate **and** edit in one pass; only spin a read-only discovery step when affected files are genuinely unknown.
-- **Read-only agents**: Agents tagged READ-ONLY (e.g. `explore`) have no edit/write/command tools. NEVER hand them an assignment that requires changing files or running commands — they cannot do it and the turn is wasted. Use them to investigate and report back; do the edits yourself or delegate to a writing agent (`task`, `oracle`, `designer`).
+- **Read-only agents**: Agents tagged READ-ONLY (e.g. `explore`) have no edit/write/command tools. NEVER hand them an assignment that requires changing files or running commands. Use them to investigate and report back; do the edits yourself or delegate to a writing agent (`task`, `oracle`, `designer`).
 - **No reasoning offload**: NEVER offload reasoning, analysis, design, or decision-making to `quick_task` or `explore` — they run minimal-effort / small models for mechanical lookups and data collection only. Keep judgment and synthesis in your own context; delegate hard thinking to `task`, `plan`, or `oracle`.
 </rules>
 
@@ -51,9 +64,10 @@ Test: can task B run correctly without seeing A's output? If no, sequence A →
 Sequential when one task produces a contract (types, API, schema, core module) the other consumes.
 Parallel when tasks touch disjoint files or are independent refactors/tests.
 {{/if}}
+{{#if ircEnabled}}Sequenced follow-ups SHOULD message the agent that produced the prerequisite — it already holds the context.{{/if}}
 </parallelization>
 
-{{#if contextEnabled}}
+{{#if batchEnabled}}
 <context-fmt>
 # Goal         ← one sentence: what the batch accomplishes
 # Constraints  ← MUST/NEVER rules and session decisions

package/src/registry/agent-lifecycle.ts

@@ -0,0 +1,218 @@
+/**
+ * AgentLifecycleManager - Owns the idle → parked → revived lifecycle of
+ * adopted subagents.
+ *
+ * The task executor hands a finished agent over via {@link AgentLifecycleManager.adopt};
+ * from then on the manager arms a TTL timer whenever the agent goes `idle`,
+ * parks it on expiry (disposes the live session, keeps the AgentRef +
+ * sessionFile), and revives it on demand through
+ * {@link AgentLifecycleManager.ensureLive}. Only this manager flips
+ * `parked` ↔ `idle`.
+ */
+
+import { logger } from "@oh-my-pi/pi-utils";
+import type { AgentSession } from "../session/agent-session";
+import { AgentRegistry, MAIN_AGENT_ID, type RegistryEvent } from "./agent-registry";
+
+export type AgentReviver = () => Promise<AgentSession>;
+
+export interface AdoptOptions {
+	/** TTL before an idle agent is parked. <= 0 disables parking. */
+	idleTtlMs: number;
+	/** Recreates a live AgentSession from the ref's sessionFile. Absent => not resumable after park (e.g. isolated runs). */
+	revive?: AgentReviver;
+}
+
+interface AdoptedAgent {
+	idleTtlMs: number;
+	revive?: AgentReviver;
+	timer?: NodeJS.Timeout;
+}
+
+export class AgentLifecycleManager {
+	static #global: AgentLifecycleManager | undefined;
+
+	static global(): AgentLifecycleManager {
+		if (!AgentLifecycleManager.#global) {
+			AgentLifecycleManager.#global = new AgentLifecycleManager();
+		}
+		return AgentLifecycleManager.#global;
+	}
+
+	/** Reset the global manager. Test-only. */
+	static resetGlobalForTests(): void {
+		const current = AgentLifecycleManager.#global;
+		if (current) {
+			current.#unsubscribe?.();
+			current.#unsubscribe = undefined;
+			for (const adopted of current.#adopted.values()) {
+				clearTimeout(adopted.timer);
+			}
+			current.#adopted.clear();
+			current.#revivals.clear();
+			current.#parking.clear();
+		}
+		AgentLifecycleManager.#global = undefined;
+	}
+
+	readonly #registry: AgentRegistry;
+	readonly #adopted = new Map<string, AdoptedAgent>();
+	/** Ids whose session is being disposed by {@link park} right now. */
+	readonly #parking = new Set<string>();
+	/** In-flight revives, so concurrent {@link ensureLive} calls coalesce. */
+	readonly #revivals = new Map<string, Promise<AgentSession>>();
+	#unsubscribe: (() => void) | undefined;
+
+	constructor(registry: AgentRegistry = AgentRegistry.global()) {
+		this.#registry = registry;
+		this.#unsubscribe = registry.onChange(event => this.#onRegistryEvent(event));
+	}
+
+	/**
+	 * Take ownership of a finished subagent. Caller has already set registry
+	 * status to "idle". Arms the TTL timer (idleTtlMs <= 0 adopts without one).
+	 */
+	adopt(id: string, opts: AdoptOptions): void {
+		if (id === MAIN_AGENT_ID) return;
+		if (!this.#registry.get(id)) {
+			logger.warn("AgentLifecycleManager.adopt: unknown agent id", { id });
+			return;
+		}
+		const existing = this.#adopted.get(id);
+		clearTimeout(existing?.timer);
+		const adopted: AdoptedAgent = { idleTtlMs: opts.idleTtlMs, revive: opts.revive };
+		this.#adopted.set(id, adopted);
+		this.#armTimer(id, adopted);
+	}
+
+	/** True if the id is adopted (parked or live). */
+	has(id: string): boolean {
+		return this.#adopted.has(id);
+	}
+
+	/** True while {@link park} is disposing this agent's session (lets dispose hooks distinguish park from teardown). */
+	isParking(id: string): boolean {
+		return this.#parking.has(id);
+	}
+
+	/**
+	 * Dispose the live session, detach it from the registry, and mark the
+	 * agent `parked`. No-op unless the id is adopted and live.
+	 */
+	async park(id: string): Promise<void> {
+		const adopted = this.#adopted.get(id);
+		if (!adopted) return;
+		const ref = this.#registry.get(id);
+		if (!ref?.session) return;
+		if (adopted.timer) {
+			clearTimeout(adopted.timer);
+			adopted.timer = undefined;
+		}
+		this.#parking.add(id);
+		try {
+			try {
+				await ref.session.dispose();
+			} catch (error) {
+				logger.warn("AgentLifecycleManager.park: session dispose failed", { id, error: String(error) });
+			}
+			this.#registry.detachSession(id);
+			this.#registry.setStatus(id, "parked");
+		} finally {
+			this.#parking.delete(id);
+		}
+	}
+
+	/**
+	 * Return the live session, reviving from the sessionFile if parked.
+	 * Throws a plain Error if the id is unknown or parked without a reviver.
+	 * Concurrent calls share one in-flight revive.
+	 */
+	async ensureLive(id: string): Promise<AgentSession> {
+		const ref = this.#registry.get(id);
+		if (!ref) {
+			throw new Error(
+				`Unknown agent "${id}" — it was never registered or has been released. If a transcript exists, read history://${id}.`,
+			);
+		}
+		if (ref.session) return ref.session;
+		const inflight = this.#revivals.get(id);
+		if (inflight) return inflight;
+		const adopted = this.#adopted.get(id);
+		if (ref.status !== "parked" || !adopted?.revive) {
+			throw new Error(
+				`Agent "${id}" is ${ref.status} and cannot be revived${adopted?.revive ? "" : " (no reviver registered)"}. Its transcript remains readable at history://${id}.`,
+			);
+		}
+		const revival = this.#revive(id, adopted.revive, ref.sessionFile);
+		this.#revivals.set(id, revival);
+		try {
+			return await revival;
+		} finally {
+			this.#revivals.delete(id);
+		}
+	}
+
+	/** Hard removal: dispose if live, unregister from registry, drop timers. */
+	async release(id: string): Promise<void> {
+		const adopted = this.#adopted.get(id);
+		clearTimeout(adopted?.timer);
+		this.#adopted.delete(id);
+		const ref = this.#registry.get(id);
+		if (ref?.session) {
+			try {
+				await ref.session.dispose();
+			} catch (error) {
+				logger.warn("AgentLifecycleManager.release: session dispose failed", { id, error: String(error) });
+			}
+		}
+		this.#registry.unregister(id);
+	}
+
+	/** Teardown everything (process exit / main session dispose). */
+	async dispose(): Promise<void> {
+		this.#unsubscribe?.();
+		this.#unsubscribe = undefined;
+		const ids = [...this.#adopted.keys()];
+		await Promise.all(ids.map(id => this.release(id)));
+		this.#revivals.clear();
+		this.#parking.clear();
+	}
+
+	async #revive(id: string, revive: AgentReviver, sessionFile: string | null): Promise<AgentSession> {
+		const session = await revive();
+		this.#registry.attachSession(id, session, sessionFile);
+		// Emits status_changed → "idle", which re-arms the TTL timer below.
+		this.#registry.setStatus(id, "idle");
+		return session;
+	}
+
+	#armTimer(id: string, adopted: AdoptedAgent): void {
+		if (adopted.idleTtlMs <= 0) return;
+		clearTimeout(adopted.timer);
+		const timer = setTimeout(() => {
+			adopted.timer = undefined;
+			void this.park(id);
+		}, adopted.idleTtlMs);
+		timer.unref?.();
+		adopted.timer = timer;
+	}
+
+	#onRegistryEvent(event: RegistryEvent): void {
+		const adopted = this.#adopted.get(event.ref.id);
+		if (!adopted) return;
+		if (event.type === "removed") {
+			clearTimeout(adopted.timer);
+			this.#adopted.delete(event.ref.id);
+			return;
+		}
+		if (event.type !== "status_changed") return;
+		if (event.ref.status === "running") {
+			if (adopted.timer) {
+				clearTimeout(adopted.timer);
+				adopted.timer = undefined;
+			}
+		} else if (event.ref.status === "idle") {
+			this.#armTimer(event.ref.id, adopted);
+		}
+	}
+}

package/src/registry/agent-registry.ts

@@ -1,16 +1,26 @@
 /**
- * AgentRegistry - Process-global registry of live AgentSession instances.
+ * AgentRegistry - Process-global registry of agents (the main session plus
+ * every subagent), keyed by stable id.
  *
- * Tracks every alive agent (the main session plus every subagent) so the
- * `irc` tool can address peers by id. Sessions are registered explicitly at
- * creation and removed when the owner releases them.
+ * Tracks each agent's status and (when live) its AgentSession so peers can be
+ * addressed by id (`irc`, `task resume`, `history://`). Sessions are
+ * registered explicitly at creation; finished agents stay registered as
+ * `idle` (live) or `parked` (session disposed, ref + sessionFile retained for
+ * revival) and are only removed on explicit release/teardown.
  */
 
 import type { AgentSession } from "../session/agent-session";
 
 export const MAIN_AGENT_ID = "Main";
 
-export type AgentStatus = "running" | "idle" | "completed" | "aborted";
+/**
+ * - `running`: a turn is in flight.
+ * - `idle`: live AgentSession in memory, awaiting work. Finished agents are
+ *   `idle`, not removed.
+ * - `parked`: session disposed; AgentRef + sessionFile retained, revivable.
+ * - `aborted`: hard-killed, terminal.
+ */
+export type AgentStatus = "running" | "idle" | "parked" | "aborted";
 export type AgentKind = "main" | "sub";
 
 export interface AgentRef {
@@ -19,6 +29,7 @@ export interface AgentRef {
 	kind: AgentKind;
 	parentId?: string;
 	status: AgentStatus;
+	/** Null exactly when parked/aborted. */
 	session: AgentSession | null;
 	sessionFile: string | null;
 	createdAt: number;

package/src/sdk.ts

@@ -34,7 +34,7 @@ import {
 	Snowflake,
 } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
-import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled } from "./async";
+import { type AsyncJob, AsyncJobManager } from "./async";
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability, setActiveRules } from "./capability/rule";
 import { bucketRules } from "./capability/rule-buckets";
@@ -93,6 +93,7 @@ import { createSessionMemoryRuntimeContext, resolveMemoryBackend } from "./memor
 import type { MnemopiSessionState } from "./mnemopi/state";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
 import lateDiagnosticTemplate from "./prompts/tools/lsp-late-diagnostic.md" with { type: "text" };
+import { AgentLifecycleManager } from "./registry/agent-lifecycle";
 import { AgentRegistry, MAIN_AGENT_ID } from "./registry/agent-registry";
 import {
 	collectEnvSecrets,
@@ -1293,7 +1294,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	let hasSession = false;
 	let hasRegistered = false;
 	const enableLsp = options.enableLsp ?? true;
-	const backgroundJobsEnabled = isBackgroundJobSupportEnabled(settings);
 	const asyncMaxJobs = Math.min(100, Math.max(1, settings.get("async.maxJobs") ?? 100));
 	const ASYNC_INLINE_RESULT_MAX_CHARS = 12_000;
 	const ASYNC_PREVIEW_MAX_CHARS = 4_000;
@@ -1326,7 +1326,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	// (issue #1923). The `instance()` guard means later sessions also skip
 	// constructing an orphaned manager that nothing would ever route to.
 	const asyncJobManager =
-		backgroundJobsEnabled && !options.parentTaskPrefix && !AsyncJobManager.instance()
+		!options.parentTaskPrefix && !AsyncJobManager.instance()
 			? new AsyncJobManager({
 					maxRunningJobs: asyncMaxJobs,
 					onJobComplete: async (jobId, result, job) => {
@@ -1351,6 +1351,17 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const resolvedAgentId = options.agentId ?? options.parentTaskPrefix ?? MAIN_AGENT_ID;
 	const resolvedAgentDisplayName =
 		options.agentDisplayName ?? ((options.taskDepth ?? 0) > 0 || options.parentTaskPrefix ? "sub" : "main");
+	const agentKind = (options.taskDepth ?? 0) > 0 || options.parentTaskPrefix ? ("sub" as const) : ("main" as const);
+	/**
+	 * Forget the agent ref on teardown — unless the agent is being parked (or is
+	 * already parked). Parking disposes the session but keeps the ref addressable
+	 * (history://, revive); only process teardown / explicit kill unregisters.
+	 */
+	const unregisterUnlessParked = (): void => {
+		if (agentRegistry.get(resolvedAgentId)?.status === "parked") return;
+		if (AgentLifecycleManager.global().isParking(resolvedAgentId)) return;
+		agentRegistry.unregister(resolvedAgentId);
+	};
 	const evalKernelOwnerId = `agent-session:${Snowflake.next()}`;
 
 	try {
@@ -1409,7 +1420,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			getTurnBudget: () => sessionManager.getTurnBudget(),
 			recordEvalSubagentUsage: output => sessionManager.recordEvalSubagentOutput(output),
 			getClientBridge: () => session?.clientBridge,
-			getCompactContext: () => session.formatCompactContext(),
 			queueDeferredDiagnostics: entry => session?.yieldQueue.enqueue(LSP_LATE_DIAGNOSTIC_MESSAGE_TYPE, entry),
 			bumpFileMutationVersion: path => {
 				const next = (fileMutationVersions.get(path) ?? 0) + 1;
@@ -2083,7 +2093,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		agentRegistry.register({
 			id: resolvedAgentId,
 			displayName: resolvedAgentDisplayName,
-			kind: (options.taskDepth ?? 0) > 0 || options.parentTaskPrefix ? "sub" : "main",
+			kind: agentKind,
 			parentId: options.parentTaskPrefix,
 			session: null,
 			sessionFile: sessionManager.getSessionFile() ?? null,
@@ -2320,7 +2330,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			ttsrManager,
 			obfuscator,
 			agentId: resolvedAgentId,
-			agentRegistry,
 			providerSessionId: options.providerSessionId,
 			parentEvalSessionId: options.parentEvalSessionId,
 		});
@@ -2341,15 +2350,26 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 		// Attach the live session to the pre-registered ref so peers can route IRC
 		// messages here. Refresh sessionFile in case it was unavailable at pre-register
-		// time. The dispose wrapper below unregisters on teardown.
+		// time. The dispose wrapper below unregisters on teardown (unless parked).
 		agentRegistry.attachSession(resolvedAgentId, session, sessionManager.getSessionFile() ?? null);
 		{
 			const originalDispose = session.dispose.bind(session);
 			session.dispose = async () => {
 				try {
+					// Reject new session work (Python/eval starts) the moment disposal
+					// begins — the lifecycle await below opens an async gap before
+					// AgentSession.dispose() would otherwise set its guards.
+					session.beginDispose();
+					if (agentKind === "main") {
+						// Top-level teardown owns the global agent lifecycle: park timers,
+						// adopted subagent sessions, revivers. Tear it down while shared
+						// resources (kernels, MCP, LSP) are still live. Subagent disposal
+						// must NOT touch the global lifecycle.
+						await AgentLifecycleManager.global().dispose();
+					}
 					await originalDispose();
 				} finally {
-					agentRegistry.unregister(resolvedAgentId);
+					unregisterUnlessParked();
 					unsubscribeCredentialDisabled?.();
 				}
 			};
@@ -2502,7 +2522,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (hasSession) {
 				await session.dispose();
 			} else {
-				if (hasRegistered) agentRegistry.unregister(resolvedAgentId);
+				if (hasRegistered) unregisterUnlessParked();
 				if (asyncJobManager) {
 					if (AsyncJobManager.instance() === asyncJobManager) {
 						AsyncJobManager.setInstance(undefined);