@earendil-works/pi-durable 0.99.0 → 0.99.2

package/docs/pico-v5.md

@@ -22,11 +22,13 @@ import type {
   ModelThinkingLevel,
   TextContent,
   Tool,
+  ToolCall,
   ToolReference,
   ToolResultMessage,
   Transport,
   UserMessage,
 } from "@earendil-works/pi-ai";
+import type { ExecutionEnv } from "@earendil-works/pi-durable/env";
 
 type JsonObject = { [key: string]: JsonValue };
 type TaskOutcomeError = { message: string; detail?: JsonValue };
@@ -340,6 +342,8 @@ type AnyTask = {
 type HarnessOptions<Tool extends ToolRegistration = ToolRegistration> = {
   readonly models: Models; // the pi-ai Models interface
   readonly registry: RegistryReader<Tool>; // section 7.1
+  /** Default execution environment offered to tools (section 7.3). */
+  readonly env?: ExecutionEnv;
   readonly now?: () => number;
   readonly onReport?: (error: unknown) => void;
 };
@@ -365,12 +369,37 @@ type ConversationRetryPolicy = {
   maxAgentDelayMs?: number;
 };
 
+/** Automatic compaction thresholds (section 8.7); manual compaction ignores `enabled`. */
+type CompactionPolicy = {
+  /** Threshold and overflow compaction. */
+  enabled: boolean;
+  /** Room kept free for the answer: generation blocks to compact above `contextWindow - reserveTokens`. */
+  reserveTokens: number;
+  /** Approximate size of the recent context a summary keeps verbatim. */
+  keepRecentTokens: number;
+  /** Background compaction starts `backgroundTokens` below the blocking threshold; `0` disables it. */
+  backgroundTokens: number;
+};
+
+type ToolExecutionMode = "parallel" | "sequential";
+
+/** How many queued items of one mode a boundary selects (section 6). */
+type QueueMode = "all" | "one-at-a-time";
+
 type ConversationConfigState = {
   model?: ModelRef;
   thinkingLevel: ModelThinkingLevel;
   activeTools: string[];
   streamOptions?: ConversationStreamOptions;
   retry?: ConversationRetryPolicy;
+  /** Default `parallel`; see section 8.3. */
+  toolExecution?: ToolExecutionMode;
+  /** Default `one-at-a-time`; see section 6. */
+  steeringMode?: QueueMode;
+  /** Default `one-at-a-time`; see section 6. */
+  followUpMode?: QueueMode;
+  /** Default `DEFAULT_COMPACTION_POLICY`; see section 8.7. */
+  compaction?: CompactionPolicy;
 };
 
 /** Built-in rewindable configuration document; see below. */
@@ -393,6 +422,8 @@ function defineEntry<D extends JsonValue = never>(kind: string): Entry<D>;
 type ContextView = {
   readonly head: EntryRecord | undefined;
   readonly entries: readonly EntryRecord[];
+  /** Per entry of `entries`, its model messages after edits and rule 9, before rules 7 and 8. */
+  readonly contributions: readonly (readonly Message[])[];
   readonly messages: readonly Message[];
 };
 
@@ -417,6 +448,8 @@ type TaskInspection = {
     | { readonly kind: "running" }
     | { readonly kind: "ready"; readonly migrates: boolean }
     | { readonly kind: "waiting"; readonly on: readonly TaskId[] }
+    /** Outcome held until its ordinary owned work drains (section 5.5). */
+    | { readonly kind: "completing" }
     | {
         readonly kind: "blocked";
         readonly reason: "missing_task" | "task_too_old" | "migration_failed";
@@ -452,6 +485,14 @@ interface Conversation {
   setStreamOptions(options: ConversationStreamOptions, context: Context): Promise<void>;
   getRetryPolicy(context: Context): Promise<ConversationRetryPolicy>;
   setRetryPolicy(policy: ConversationRetryPolicy | undefined, context: Context): Promise<void>;
+  getToolExecution(context: Context): Promise<ToolExecutionMode>;
+  setToolExecution(mode: ToolExecutionMode | undefined, context: Context): Promise<void>;
+  getSteeringMode(context: Context): Promise<QueueMode>;
+  setSteeringMode(mode: QueueMode | undefined, context: Context): Promise<void>;
+  getFollowUpMode(context: Context): Promise<QueueMode>;
+  setFollowUpMode(mode: QueueMode | undefined, context: Context): Promise<void>;
+  getCompaction(context: Context): Promise<CompactionPolicy>;
+  setCompaction(policy: CompactionPolicy | undefined, context: Context): Promise<void>;
 
   commit<T>(
     change: (tx: Tx) => T | Promise<T>,
@@ -469,9 +510,10 @@ interface Conversation {
     options: ConversationCreateOptions,
     context: Context,
   ): Promise<Conversation>;
-  collapse(instructions: string | undefined, context: Context): Promise<TaskId>;
+  compact(instructions: string | undefined, context: Context): Promise<TaskId<CompactionResult>>;
   reset(handoff: string | undefined, context: Context): Promise<void>;
-  abort(context: Context): Promise<void>;
+  /** `{ background: true }` also aborts background work under the conversation (section 5.4). */
+  abort(context: Context, options?: { readonly background?: boolean }): Promise<void>;
   waitForIdle(context: Context): Promise<void>;
   viewState(context: Context): Promise<AttachedReplicatedState<ConversationView>>;
   watch(context: Context): Promise<ConversationWatch>;
@@ -498,6 +540,8 @@ interface Harness extends Session {
   abortTask(id: TaskId, context: Context): Promise<"marked" | "terminal">;
   waitForTask<R>(id: TaskId<R>, context: Context): Promise<SettledTask<R>>;
   waitForIdle(context: Context): Promise<void>;
+  /** Session total of every conversation's `pi.usage` (section 8.6). */
+  usage(context: Context): Promise<UsageState>;
 }
 
 declare const Harness: {
@@ -520,9 +564,10 @@ settlement.
 7.1). `createRegistry()` pre-registers the built-in task definitions (section 8);
 they cannot be disposed or replaced, and open rejects a registry whose snapshot
 lacks any of them or the built-in `pi` conversation setup.
-Open changes surviving `running` tasks to `pending` and does nothing else to
-task records: it never migrates or terminalizes a task because its definition
-is missing or unmigratable. Such a task stays `pending` and is **blocked**: the
+Open changes surviving `running` tasks to `pending`, keeps `waiting` tasks
+waiting, and re-evaluates finalization and `failFast` for `completing` and
+`waiting` tasks (section 5.5). It never migrates or terminalizes a task because
+its definition is missing or unmigratable. Such a task stays `pending` or `waiting` and is **blocked**: the
 scheduler skips it and reconsiders it whenever the registry changes (section
 5.4). Any built-in document touched by recovery migrates through its ordinary
 typed access path. Open does not scan or migrate other documents. No handler
@@ -540,7 +585,7 @@ no configured model produces a durable `no_model` generation failure.
 repeat open-time reconciliation, and it throws after close. Work that must happen
 before any task runs, such as registration or seeding, happens before
 `resume()`. Calls that ask for progress also enable scheduling, so they never
-wait on a paused Harness: `Conversation.submit()`, `Submission.wait()`,
+wait on a paused Harness: `Conversation.submit()`, `Conversation.compact()`, `Submission.wait()`,
 `Harness.waitForTask()`, `Harness.waitForIdle()`, and
 `Conversation.waitForIdle()`. Recovered work starts with them. A viewer that only
 reads never enables scheduling.
@@ -564,9 +609,9 @@ conversation setups (section 7.1) in the same commit, whether through the
 conveniences or through raw `tx.createConversation()` and `tx.forkConversation()`,
 for example inside a tool commit. The built-in `pi` setup runs first: an
 independent conversation gets the default configuration and a fork keeps its
-`asOf` copy, and both get an empty `pi.live`. Applications register setups for
-their own documents the same way. The conveniences add only `init` and its checks,
-which run after every setup. A conversation created by a plain Session has no
+`asOf` copy, and both get empty `pi.live`, `pi.inbox`, and `pi.usage`.
+Applications register setups for their own documents the same way. The
+conveniences add only `init` and its checks, which run after every setup. A conversation created by a plain Session has no
 built-in documents; its configuration reads as
 `ConversationConfig.definition.initial()` until something writes it.
 
@@ -590,6 +635,13 @@ fork. The getters return immutable committed values, falling back to
 returns `{}` and `getRetryPolicy()` returns the default policy
 `{ enabled: true, maxRetries: 3, baseDelayMs: 2000, maxAgentDelayMs: 60000 }`
 when the field is absent; `setRetryPolicy(undefined)` removes the field.
+`getToolExecution()` returns `parallel` when the field is absent;
+`setToolExecution(undefined)` removes it. `getSteeringMode()` and
+`getFollowUpMode()` return `one-at-a-time` when their field is absent; their
+setters remove the field for `undefined`. `getCompaction()` returns
+`DEFAULT_COMPACTION_POLICY`, `{ enabled: true, reserveTokens: 16384,
+keepRecentTokens: 20000, backgroundTokens: 32768 }`, when the field is absent;
+`setCompaction(undefined)` removes it.
 `streamOptions` are forwarded to every generation request of the conversation;
 `streamOptions.maxRetries` are provider retries inside one request, while `retry`
 governs durable generation attempts (section 8). Each setter performs
@@ -607,10 +659,10 @@ not registered. The create/fork conveniences check only one thing about `init`
 writes: names that `init` newly activates must be registered. Names that were
 already active are never revalidated, so stale unregistered names survive every
 edit. All other raw document writes are trusted and unchecked, so other writers,
-such as post-tools `addTools`, never fault because of registry movement. Readers tolerate what raw
+such as the generation's `addTools` handling, never fault because of registry movement. Readers tolerate what raw
 writes can produce: request preparation offers the first occurrence of a
-duplicated name, and post-tools `addTools` appends only names not already
-active.
+duplicated name, and the generation's `tools` phase appends only `addTools`
+names not already active.
 
 `init` runs after the conversation creation, which is a table write, so table
 reads inside it throw `ReadAfterWrite` (section 4). Document access remains
@@ -628,10 +680,18 @@ A missing tool implementation never fails a request. Request preparation offers
 only active names that are currently registered. If the replayed tool state still
 offers an unregistered name, the appended system delta lists it in
 `toolsRemoved`; when the name is registered again, a later delta adds its current
-declaration. When the model calls a tool that is not offered or whose
-implementation is unavailable at execution time, the tool task appends an error
-tool result with `details: { code: "tool_unavailable" }` stating that the tool is
-not available, and the run continues so the model can react.
+declaration. When the model calls a tool that its request did not offer, or whose
+implementation is unregistered when its tool task runs, an error tool result with
+an error diagnostic with code `tool_unavailable` (section 7.3) states that the tool is not available,
+and the run continues so the model can react (section 8.3).
+
+Configuration takes effect at turn boundaries. Generation preparation reads it
+once per request and fixes that turn's prompt, offered tools, model, and request
+options. A configuration change made while the turn runs, such as deactivating a
+tool the model already called, applies at the next preparation; the current
+turn's calls still execute. The retry policy is the exception: generation reads
+it when it classifies an attempt's result, because it governs the next attempt
+(section 8.3).
 
 A `Conversation.commit()` is a Session commit bound to that conversation.
 `tx.createTask()` defaults `TaskOptions.conversationId` to the bound conversation.
@@ -642,31 +702,35 @@ because `Harness extends Session`.
 
 `fork()` requires a concrete visible parent entry and explicit ownership, then
 applies section 3.7.
-`collapse()` returns the newly admitted background collapse task ID, not its
-future summary entry. `reset()` durably admits a passive self-head reset or
-handoff write and then resolves; while busy, placement follows section 6 and may
-occur later. Observe its placement through the conversation watch. An idle wait
-does not guarantee placement of queued passive writes.
-
-`abortTask()` commits `abortRequested` and the durable foreground-subtree
-cascade, then signals and joins the active run; the scheduler then starts the
-abort invocation. Marking without signalling is internal: the cascade marks
-owned tasks in the same commit. `Conversation.abort()` withdraws queued
+`compact()` admits a manual compaction task in one commit and returns its ID,
+not its future summary entry. The task is conversation-owned and not background,
+so `Conversation.abort()` cancels it and idle waits include it. It does not take
+run control, so it does not make the conversation busy: the conversation keeps
+working while it summarizes, and its summary is placed through a write
+submission, at once when idle, otherwise at the next boundary (section 8.7). `reset()` durably admits a write submission of a
+`pi.reset` entry (section 8.1) with `head: "self"`, carrying the handoff text as
+a user message when given, and then resolves; while busy, placement follows
+section 6 and may occur later. Observe its placement through the conversation
+watch. An idle wait does not guarantee placement of queued passive writes.
+
+`abortTask()` commits `abortRequested`, then signals and joins the active run;
+the scheduler then starts the abort invocation and marks the foreground-owned
+subtree in its next reconcile commit (section 5.4). `Conversation.abort()` withdraws queued
 input submissions, marks non-background tasks selected by ordinary ownership
 traversal, signals them, and resolves only after that scope is ordinarily idle.
 Passive writes and background subtrees survive. Conversation idle means no live
 non-background task selected from that conversation. Harness idle applies the
-same traversal from every ownerless conversation root. Pending dependency- or
-deadline-blocked work is still live and therefore not idle. Cancelling an idle
+same traversal from every ownerless conversation root. Waiting,
+deadline-blocked, and `completing` work is still live and therefore not idle. Cancelling an idle
 wait aborts only that waiter.
 
 Conversation handles are stateless; compare them by `id`. Hosts discover
-conversations through lookups and scans. An activity view that lists active
-conversations and reports conversations becoming active or idle is specified
-with run control (Package 17); there is no creation listener.
+conversations through lookups and scans. There is no creation listener and no
+activity view; `inspect()` and the idle waits report live work.
 
 `submit()` returns after durable admission, not settlement. An input submission
-creates a user message with the admission timestamp; `whenBusy` defaults to
+creates a user message with the Harness clock's timestamp at placement, which is
+admission when it is placed at once; `whenBusy` defaults to
 `followUp`. A write submission uses the ordered passive path in section 6 and
 never starts generation. `Submission.wait()` settles an input only after its
 answer or terminal failure; it settles a write when the entry is placed or the
@@ -676,20 +740,24 @@ withdrawal operation. `Harness.submission()` reacquires a submission after
 reopen; records remain queryable after settlement.
 
 `abortTask()` durably requests cancellation and returns `marked` after the mark
-is committed, any active run invocation has joined, and an abort invocation has
-been scheduled, or a blocked task has been settled as `orphaned` (section 5.4);
-it does not await terminal settlement. `waitForTask()` observes
+is committed and any active run invocation has joined, or after a blocked task
+without live ordinary owned work has been settled as `orphaned` (section 5.4).
+The abort invocation starts once the task's ordinary owned work is no longer
+live; a `completing` task is only marked, and its final record keeps its held
+outcome with `abortRequested: true` (section 5.5). It does not await terminal
+settlement. `waitForTask()` observes
 the terminal receipt. Aborting an already terminal task returns `terminal`; an
 unknown ID rejects. Explicit task abort includes a background task. Cancelling a
 task or idle wait does not abort work.
 
 `inspect()` returns live work at one point on the Session line, for recovery
 decisions after open, viewers, and diagnostics. It writes nothing, does not
-enable scheduling, and runs no task code. Each pending or running task carries
-its state under the current registry: `running` with an active invocation;
-`ready` when the next scheduling pass would reserve it, with `migrates` when its
-definition is newer and has `migrate`; `waiting` on unfinished dependencies; or
-`blocked` (section 5.4). A migration shows as failed only after the scheduler
+enable scheduling, and runs no task code. Each live task carries its state
+under the current registry: `running` with an active invocation; `completing`
+for a held outcome; `waiting` with the live tasks it still waits for, the live
+part of its `on`, or, when abort-marked, its live ordinary owned work (section
+5.5); `ready` when the next scheduling pass would reserve it, with `migrates`
+when its definition is newer and has `migrate`; or `blocked` (section 5.4). A migration shows as failed only after the scheduler
 tried it, or when the newer definition has no `migrate`; inspection never runs
 one to find out. Blocked reasons are derived, never stored. Queued and placed
 submissions and the registry's wrapper failures complete the view. Finished
@@ -965,10 +1033,14 @@ interface Tx {
     token: Entry<D>, conversationId: ConversationId, value: TypedEntryDraft<D>,
   ): Promise<TypedEntry<D>>;
   createTask<I, S extends { phase: string }, R, H extends object>(
-    task: Task<I, S, R, H>, input: I, options?: TaskOptions,
+    task: Task<I, S, R, H>, input: I, options: TaskOptions,
   ): Promise<TaskId<R>>;
   /** Settle a queued or placed submission; only a placed input can be answered. A settled one stays unchanged. */
   settleSubmission(id: SubmissionId, settlement: SubmissionSettlement): void;
+  /** Newest visible entry of the conversation that carries a `head`. */
+  latestHeadMarker(conversationId: ConversationId): Promise<(EntryRecord & { readonly head: EntryId }) | undefined>;
+  /** Record a queued submission's placement at `entry`: an input becomes `placed`, a write `done` (section 6). The caller appends the entry and edits `pi.inbox` and `pi.live`. */
+  placeSubmission(id: SubmissionId, entry: EntryId): void;
 
   doc<T extends JsonObject>(token: SessionDocToken<T>): Promise<Draft<T>>;
   doc<T extends JsonObject>(token: ConversationDocToken<T>, conversationId: ConversationId): Promise<Draft<T>>;
@@ -993,9 +1065,13 @@ For task ownership, the caller supplies only a typed task ID. The Session derive
 the persisted owner conversation from the task's final candidate record.
 
 An owner task may be committed or staged earlier in the same transaction. Before
-Storage admission, the Session rejects a missing, terminal, or abort-marked owner,
-including one made terminal or abort-marked later in that transaction. Existing
-owner edges remain valid when their owners terminalize afterward. Conversation
+Storage admission, the Session rejects a missing, `completing`, terminal, or
+abort-marked owner of a new task or conversation, judged on the owner's final
+candidate record in that transaction. A task therefore cannot create owned work
+in the commit that finishes it. A child task whose explicit `conversationId`
+differs from its owner's conversation, and a child task with `background: true`,
+reject the same way. Existing owner edges remain valid when their owners finish
+afterward. Conversation
 creation returns an inert record, never an operational handle.
 `forkConversation()` additionally validates one visible entry and applies section
 3.7. Only public typed `tx.doc()` is get-or-create. Internal fork copying may create
@@ -1108,10 +1184,10 @@ callback fails with no pending acquisition
 callback succeeds with no pending acquisition
   prepare every open change -> immutable next revision + self-contained Chord Op[]
   Session evaluates each required/ordinary document write exactly once
-  prepare every affected loaded conversation mount revision
   Storage.commit persists the atomic batch while the Session line remains held
 storage succeeds
   adopt every prepared change by pointer swap and enqueue immutable revision/ops publication
+  commit listeners, including conversation view mounts (section 9.3), capture it synchronously
   release the line; invoke listeners later
 storage fails
   abort every prepared change, poison Session, and publish nothing
@@ -1128,8 +1204,8 @@ strict JSON from Storage and enter the tracker without another copy. Chord's
 every root they receive must come from one of these sources. Migration callbacks
 never receive a live tracker revision.
 
-Preparation, validation, checkpoint, or mounted-view preparation failure occurs
-before Storage admission and rolls back normally. The Session performs no
+Preparation, validation, or checkpoint failure occurs before Storage admission
+and rolls back normally. The Session performs no
 strict-JSON walk of prepared operations or selected bases: roots are checked on
 entry and Chord checks every draft placement, so every revision, operation
 payload, and base is strict JSON by construction. Tracker branding and `baseRevision` enforce ownership and staleness; the
@@ -1321,7 +1397,7 @@ await session.commit(async tx => {
 
   await tx.appendEntry(conversationId, message);     // first table write
   delete live.message;                               // document mutation remains valid
-  await tx.createTask(Follow, { after: message.id }); // further table writes are fine
+  await tx.createTask(Follow, {}, { ownership: { kind: "conversation" } }); // further table writes are fine
 }, context);
 ```
 
@@ -1359,27 +1435,42 @@ type TaskOutcome<R> =
   | { readonly status: "orphaned"; readonly reason: string }
   | { readonly status: "faulted"; readonly error: TaskOutcomeError };
 
+type JoinPolicy = "failFast" | "allSettled";
+
 type TaskState<S, R> =
   | { readonly status: "pending"; readonly checkpoint: S }
   | { readonly status: "running"; readonly checkpoint: S }
+  /** Parked without an invocation until every task in `on` is terminal; then resumes at `checkpoint` (section 5.5). */
+  | {
+      readonly status: "waiting";
+      readonly checkpoint: S;
+      readonly on: readonly TaskId[];
+      readonly policy: JoinPolicy;
+    }
+  /** Outcome decided; terminal once no ordinary owned work below is live (section 5.5). Runs no more code. */
+  | { readonly status: "completing"; readonly outcome: TaskOutcome<R> }
   | { readonly status: "terminal"; readonly outcome: TaskOutcome<R> };
 
+/** Who owns a task: its conversation (a top-level task) or another task of the same conversation. */
+type TaskOwnership = { readonly kind: "conversation" } | { readonly kind: "task"; readonly taskId: TaskId };
+
 type TaskRecord<I, S, R> = {
   readonly id: TaskId<R>;
   readonly conversationId: ConversationId;
   readonly kind: string;
   readonly version: number;
   readonly input: I;
-  readonly after: readonly TaskId[];
+  /** Owning task; absent for a task its conversation owns. Immutable. */
+  readonly owner?: TaskId;
   readonly background: boolean;
   readonly abortRequested: boolean;
 } & (
   | {
-      readonly state: Extract<TaskState<S, R>, { status: "pending" | "running" }>;
+      readonly state: Extract<TaskState<S, R>, { status: "pending" | "running" | "waiting" }>;
       readonly memos?: Readonly<Record<string, JsonValue>>;
     }
   | {
-      readonly state: Extract<TaskState<S, R>, { status: "terminal" }>;
+      readonly state: Extract<TaskState<S, R>, { status: "completing" | "terminal" }>;
       readonly memos?: never;
     }
 );
@@ -1388,11 +1479,14 @@ type RunningTask<I, S, R> = TaskRecord<I, S, R> & {
   readonly state: Extract<TaskState<S, R>, { status: "running" }>;
 };
 
-/** State a task commits for itself: a replacement checkpoint or its terminal outcome. */
-type NextTaskState<S, R> = Extract<TaskState<S, R>, { status: "running" | "terminal" }>;
+/**
+ * State a task commits for itself: a replacement checkpoint, a wait, or its outcome. A returned `terminal` state
+ * becomes `completing` while ordinary owned work below is live (section 5.5).
+ */
+type NextTaskState<S, R> = Extract<TaskState<S, R>, { status: "running" | "waiting" | "terminal" }>;
 
 interface HookRunner<H extends object> {
-  each<K extends keyof H>(name: K, invoke: (handler: H[K]) => void | Promise<void>): Promise<void>;
+  each<K extends keyof H>(name: K, invoke: (handler: NonNullable<H[K]>) => void | Promise<void>): Promise<void>;
 }
 
 type PhaseHandler<I, P, S, R, H extends object> = (
@@ -1409,6 +1503,8 @@ interface TaskRuntime<I, S, R, H extends object> extends DocumentObserver, Docum
   readonly registry: RegistrySnapshot<ToolRegistration>;
   readonly models: Models;
   readonly hooks: HookRunner<H>;
+  /** `HarnessOptions.env`; the tool task passes it to tools as `api.env`. */
+  readonly env: ExecutionEnv | undefined;
 
   commit(
     change: (
@@ -1421,6 +1517,15 @@ interface TaskRuntime<I, S, R, H extends object> extends DocumentObserver, Docum
   memo<T extends JsonValue>(name: string, context: Context): Promise<T | undefined>;
   memo<T extends JsonValue>(name: string, candidate: T, context: Context): Promise<T>;
   conversation(id: ConversationId, context: Context): Promise<ConversationHandle | undefined>;
+  /** Committed task record. */
+  getTask<T>(id: TaskId<T>, context: Context): Promise<TaskRecord<JsonValue, JsonValue, T> | undefined>;
+  /** Terminal receipt; rejects when the invocation ends. */
+  waitForTask<T>(id: TaskId<T>, context: Context): Promise<SettledTask<T>>;
+  /** Outcomes of terminal tasks, in order; rejects when one is not terminal. Used after a wait (section 5.5). */
+  outcomes<T>(ids: readonly TaskId<T>[], context: Context): Promise<TaskOutcome<T>[]>;
+  /** Committed entry visible from the task's conversation. */
+  entry(id: EntryId, context: Context): Promise<EntryRecord | undefined>;
+  entry<D extends JsonValue>(token: Entry<D>, id: EntryId, context: Context): Promise<TypedEntry<D> | undefined>;
   /** Committed raw active transcript and model context, optionally cut off at `at`. */
   context(conversationId: ConversationId, context: Context, at?: EntryId): Promise<ContextView>;
   /** The Harness clock. */
@@ -1450,8 +1555,11 @@ interface Task<I, S extends { phase: string }, R, H extends object> {
 }
 
 type TaskOptions = {
+  /** Required: a task always names its owner (section 5.5). */
+  readonly ownership: TaskOwnership;
+  /** Default: the owner task's conversation, or the transaction's bound conversation. */
   readonly conversationId?: ConversationId;
-  readonly after?: readonly TaskId[];
+  /** Conversation-owned tasks only: excluded from conversation abort and idle, and from cascades. */
   readonly background?: boolean;
 };
 
@@ -1477,9 +1585,12 @@ entry it appends records the task as `byTaskId`. When the
 callback returns a state, the runtime replaces the task's state in the same
 commit, so the checkpoint or outcome is atomic with the callback's entries,
 documents, and child tasks and is type-checked against the task's checkpoint and
-result types. Returning nothing leaves the state unchanged. A terminal state
-drops the memos. `pending` is never returned; only reconciliation and handover
-write it.
+result types. Returning nothing leaves the state unchanged. A terminal or
+completing state drops the memos. A `waiting` state ends the invocation even
+when its checkpoint is unchanged; it rejects when `on` names a missing task, the
+task itself, or a task on its owner chain, which could never finish first, and
+an empty `on` resumes at the next scheduling pass. `pending` is never returned;
+only reconciliation and handover write it.
 
 `Tx` has no task replacement operation. A task changes only its own state,
 through its runtime. The scheduler owns reservation, reconciliation, handover,
@@ -1509,11 +1620,14 @@ record. `sleep(until)` compares against the Harness `now` clock and rejects when
 the invocation is signalled or its context is cancelled. Watches acquired through
 the runtime stop when the invocation ends. `snapshot()`/`snapshotAsOf()` read
 committed documents, for example to supply `PromptInput.read` (section 7.4).
+`getTask()` and `entry()` read committed records with one lookup each; `waitForTask()` waits for a terminal receipt,
+for example a child task created by a tool.
 `context()` captures its bounds on the Session line and derives the view from
 immutable entries off the line, like `Conversation.context()`. Like every runtime
 operation, these reject after the invocation ends.
 
-Reservation durably changes `pending` to `running`. One invocation runs phase
+Reservation durably changes `pending`, or `waiting` once it may resume, to
+`running`. One invocation runs phase
 handlers in sequence; checkpoint commits retain `running`. Before every phase,
 including the first, the scheduler runs one step callback on the Session line.
 It reads the committed task and synchronously applies the first matching rule
@@ -1525,10 +1639,11 @@ invocation queued earlier therefore either lands before the step and counts, or
 reaches the line after it and rejects. Before the first phase only rules 1–3
 apply:
 
-1. Terminal: stop.
+1. Terminal, `completing`, or `waiting`: stop.
 2. Session closing: stop; preserve the checkpoint and any abort mark for reopen.
-3. Run mode with a durable abort mark: end and join the run invocation, then
-   dispatch a fresh abort invocation.
+3. Run mode with a durable abort mark: end and join the run invocation; a fresh
+   abort invocation starts once the task's ordinary owned work is no longer
+   live (section 5.5).
 4. Uncaught error: write terminal `faulted`.
 5. Checkpoint changed, including progress within the same phase: refresh the
    registry snapshot and either hand over (section 5.4) or invoke the phase
@@ -1543,10 +1658,11 @@ invocation still ends; the task stays `running` and the next reservation runs it
 again.
 
 On open, running-task reconciliation changes surviving `running` tasks back to
-`pending`, preserving their checkpoint and abort mark. Task migration runs at
-reservation, atomically with `pending -> running`. One callback handles every
+`pending`, preserving their checkpoint and abort mark; `waiting` tasks stay
+waiting, and `completing` and `waiting` tasks are re-evaluated (section 5.5). Task migration runs at
+reservation, atomically with `pending` or `waiting` -> `running`. One callback handles every
 supported older version. A task whose definition is missing, older than the
-stored version, or fails migration stays `pending` and blocked until a fitting
+stored version, or fails migration stays `pending` or `waiting` and blocked until a fitting
 definition is registered or the task is aborted (section 5.4).
 `close()` marks the runtime closing, seals admission and reservation, signals
 invocations, and stops watches. Outside the Session line it settles admitted
@@ -1576,7 +1692,7 @@ envelope. Candidate insertion and reading the winner are one Session commit, so
 concurrent candidates return the same durable winner. Memos survive checkpoints
 and disappear in the terminal replacement. Bulk progress belongs in a document.
 
-### 5.3 Terminal tasks and dependencies
+### 5.3 Terminal tasks
 
 The terminal task record is the durable result receipt. Its result may directly
 contain a small value or reference an entry:
@@ -1592,10 +1708,14 @@ A terminal transition atomically:
 3. Retires all documents scoped to that task.
 4. Resolves any submissions settled by the task.
 
+A task whose ordinary owned work is live splits this at a `completing` hold
+(section 5.5, rule 4): a task-written outcome's own writes land at hold, and
+items 1 and 3 and its waiters follow in the final commit.
+
 The execution checkpoint and memos disappear from the terminal representation.
-Terminal records remain queryable for dependencies, waiters, inspection, and
-reopen. A normal run becomes eligible when every `after` task is terminal. An abort
-mark bypasses dependencies so pending work can always reach its abort handler,
+Terminal records remain queryable for waits, waiters, inspection, and reopen.
+There are no free-standing task dependencies: ordering comes from a task waiting
+on other tasks (section 5.5). An abort mark lets pending work reach its abort handler,
 or its `orphaned` settlement when its definition is unavailable.
 
 ### 5.4 Scheduler, abort, and ownership
@@ -1609,47 +1729,75 @@ Abort protocol:
 ```text
 commit abortRequested
 signal and join active run invocation
+wait until ordinary owned work is no longer live (section 5.5)
 start a fresh abort invocation
 abort handler commits terminal outcome
 ```
 
 A run invocation may not commit after its durable abort mark appears. Every
 runtime operation rejects after its owning invocation ends, even while the
-Session remains open. Returning from one phase handler does not end an invocation
+Session remains open, and the invocation's signal and handler context abort when
+it ends for any reason. An invocation ends only after its last handler returned,
+so this cancels only detached leftovers, such as an unawaited `waitForTask()` or
+a fetch started with the handler's context; they could no longer write anything. Returning from one phase handler does not end an invocation
 that continues into another phase. Invocation mode is volatile and derived from
 the durable mark on reopen. Cancelling one caller's `Context` only cancels
 that call or wait; it does not durably abort shared work unless the invoked API
 commits an abort mark.
 
-A task may create owned conversations. Conversations are durable scopes; tasks
-are the units of live work counted by idle and marked by abort. History parents
-are irrelevant to ownership traversal.
+A task may create owned conversations and owned tasks (section 5.5).
+Conversations are durable scopes; tasks are the units of live work counted by
+idle and marked by abort. History parents are irrelevant to ownership traversal.
 
 Ordinary traversal starts at an explicitly addressed conversation, visits its
-tasks, and follows conversations owned by each non-background task. It follows
-owner edges after the owner becomes terminal, but a background owner is a
-boundary: ordinary traversal skips that task and its complete owned subtree.
+conversation-owned tasks, follows the tasks each non-background task owns, and
+follows the conversations each non-background task owns. It follows owner edges after the
+owner becomes terminal, but a background task is a boundary: ordinary traversal
+skips that task and its complete owned subtree.
 Direct conversation operations start inside that conversation regardless of its
 owner. Directly aborting a live background task includes that task and follows
-its ordinary owned subtree; nested background owners remain boundaries. Full
-teardown crosses every boundary, marks every live task, and must seal new
-admission while it gathers the complete indexed ownership subtree.
+its ordinary owned subtree; nested background owners remain boundaries.
+`close()` stops every invocation, foreground and background, without writing an
+outcome, so the work resumes on reopen. A host that must durably cancel
+everything aborts each live task that `inspect()` lists.
 
 `Conversation.abort()` withdraws queued inputs and marks live non-background
-tasks selected by ordinary traversal. `Conversation.waitForIdle()` waits until
+tasks selected by ordinary traversal. With `{ background: true }` it crosses
+background boundaries: it marks every live task that traversal ignoring the
+background flag reaches when the operation is admitted and withdraws the queued
+inputs of every conversation it reaches. It then waits until every task it
+marked is terminal and the conversation is ordinarily idle; background work
+created afterwards is neither marked nor awaited. `Conversation.waitForIdle()` waits until
 that traversal contains no live non-background task. Harness idle performs the
 same traversal from every ownerless conversation root rather than globally
 counting tasks, so ordinary work below a background owner does not block it.
 Explicit `waitForTask()` waits for its referenced task regardless of the task's
 background flag.
 
-An abort mark atomically and idempotently cascades to foreground-owned work,
-including conversations, tasks, and submissions staged in the same transaction.
-Terminal outcomes `failed`, `faulted`, `orphaned`, and `aborted` record the same
-durable cancellation intent; `completed` does not. Conversation records and
-owner edges are never retired with the task. Active invocations are signalled
-after commit, and a terminal receipt guarantees durable cancellation intent,
-not descendant quiescence.
+An abort mark cascades idempotently to foreground-owned work. The durable
+cancellation intent is a live owner's own record: its abort mark, or a held
+`completing` outcome other than `completed` (section 5.5). A terminal owner never
+cascades: it became terminal only after its ordinary owned work drained, so its
+intent is already applied, and work later started in a conversation it owned,
+for example a user interrogating a finished subagent, runs normally and is
+reached by ordinary traversal from above. Queued inputs in its owned
+conversations stay queued, as after a failed run (section 6). The scheduler derives the marks in a
+later reconcile commit, and again at open, so a crash in between loses nothing;
+work already queued on the Session line may make one more commit first. Every
+live non-background task whose owner chain, walking up through owning tasks and
+owning conversations, reaches a cancelled live owner, without first crossing a
+background task that has no cancellation intent of its own, gets an abort mark, including work
+created there after the cascade. Deriving the marks in their own commit
+keeps them out of the owner's commit, which may already have written the tasks
+involved. Every conversation the cascade reaches is treated like
+`Conversation.abort()`: its queued input submissions become `unanswered` with
+reason `aborted` and leave its inbox, while queued writes stay. The cascade starts
+below the cancelled task, so that task's own conversation keeps its queue.
+Held outcomes `failed`, `faulted`, `orphaned`, and `aborted` record the same
+durable cancellation intent as an abort mark; `completed` does not. Conversation
+records and owner edges are never retired with the task. Active invocations are
+signalled after commit. A terminal receipt guarantees that the task's ordinary
+owned work drained; background work below it may continue.
 
 Every run invocation start resolves the task's definition by `TaskRecord.kind`
 from the scheduler's current registry snapshot:
@@ -1683,25 +1831,39 @@ missing or cannot take the task. The Harness therefore settles it as terminal
 ran and decided the outcome, while `orphaned` means no task code ran, so external
 effects the task started may remain uncleaned. The orphaned `reason` is the
 blocked reason (`missing_task`, `task_too_old`, or `migration_failed`). When
-`abortTask()` finds no active invocation and the current snapshot
-cannot take the task, the marking commit settles it directly; otherwise the
-scheduler settles it when it would reserve the abort invocation. Only an abort (direct, by
+`abortTask()` finds no active invocation, no live ordinary owned work, and a
+current snapshot that cannot take the task, the marking commit settles it
+directly; otherwise the scheduler settles it when it would reserve the abort
+invocation, which is after the owned work drained (section 5.5), so an orphaned
+outcome never holds. Only an abort (direct, by
 conversation, or by cascade) orphans a task; a missing definition alone never
 does. The orphaning commit performs the cleanup the task's code cannot: affected
 input submissions become unanswered with the reason, any matching active run
-control is cleared, and task-scoped documents retire. No transcript entry is
-written; the terminal task record and unanswered submissions carry the reason.
+control is cleared, and task-scoped documents retire. The terminal task record
+and unanswered submissions carry the reason; the only transcript entry written
+is the conversion of a committed generation partial (below).
 Faulting a run task performs the same control/submission cleanup with a
-`faulted` outcome.
+`faulted` outcome; a fault while ordinary owned work is live holds, and its
+cleanup runs in the final commit (section 5.5, rule 4).
 
 The scheduler knows nothing about runs or task kinds. The Harness, which owns
 submissions, run control, and the built-in tasks, gives it one hook that the
-scheduler calls in the same commit for every terminal outcome it writes itself
-(`faulted` and `orphaned`). The hook ignores tasks whose kind is not a built-in
-run kind, so it never creates `pi.live` elsewhere. It settles the run when
-`pi.live.run` names the task (section 8): its inputs become `unanswered` with reason `faulted`
-(detail: the error message) or the blocked reason, and `run` and `generation`
-are removed. Outcomes a task commits for itself do their own settlement.
+scheduler calls in the commit that makes an outcome it wrote itself (`faulted`
+and `orphaned`) terminal, which is the final commit after a hold. The hook ignores tasks whose kind is not a built-in
+run, tool, or compaction kind, so it never creates `pi.live` elsewhere. It settles the run when
+`pi.live.run` names the task (section 8): a committed generation partial becomes
+an aborted `pi.assistant` entry, exactly as the generation abort handler converts
+it, so the transcript keeps what the model produced and `pi.usage` counts its
+spend (the scheduler's commit has no task scope, so the entry has no
+`byTaskId`); its inputs become `unanswered` with reason `faulted` (detail: the error
+message) or the blocked reason; and `run`, `generation`, and `tools` are
+removed. Faults come from task bugs or malformed provider data, such as a
+non-JSON value in a response, or a commit the Storage rejected without effect
+(`StorageRejected`). An uncertain storage failure poisons the Session and writes
+no outcome. For a `pi.tool` task it marks the task's tool slot `done`
+without an entry; the run continues, and context derivation synthesizes the
+missing result (section 2.1). For a `pi.compaction` task it removes the task's
+compaction status (section 8.7). Outcomes a task commits for itself do their own settlement.
 
 At every normal phase boundary (section 5.1, rule 5), the step refreshes the
 invocation's registry snapshot. If the task definition resolved by name is a different object
@@ -1715,23 +1877,133 @@ definition, reports once through `onReport` per resolved definition, and
 reconsiders at its next boundary. A handler that
 never settles never hands over.
 
+### 5.5 Structured concurrency
+
+Tasks and conversations form one ownership tree. Every task names its owner at
+creation, `tx.createTask(task, input, { ownership })` with a required
+`TaskOwnership`: its conversation (`{ kind: "conversation" }`, a top-level task)
+or a task (`{ kind: "task", taskId }`, a child task). Every conversation is
+ownerless or owned by a task (section 2.2). A child task always lives in its
+owner's conversation; only owned conversations cross conversation boundaries.
+Owner edges are immutable.
+
+The **ordinary owned work** of a task `T` is every task that ordinary traversal
+reaches below `T`: the tasks `T` owns, the tasks in the conversations `T` owns,
+and, transitively, the same for each of those that is not background. A
+background task and everything below it are excluded. A conversation-owned task
+may be background; a child task may not.
+
+Two rules follow from the tree.
+
+**Abort flows down** (section 5.4). A live owner's cancellation intent (its abort
+mark, or a held non-`completed` outcome) marks its ordinary owned work. Background
+tasks are boundaries unless aborted directly or by `Conversation.abort(context,
+{ background: true })`.
+
+**Owned work does not outlive its owner's finish.** A task finishes only after
+its ordinary owned work drained:
+
+1. A terminal state a task commits, or a terminal outcome the scheduler writes
+   (`faulted`, `orphaned`), while the task's ordinary owned work is live is
+   stored as `{ status: "completing", outcome }` instead. The scheduler writes
+   the final `terminal` record in a later commit once no ordinary owned work is
+   live, evaluated after every commit, including work created after the hold.
+   Whether work is live is judged on the commit's candidate records, so work the
+   finishing commit itself creates, for example a task in a conversation the
+   task owns, holds it. At open it re-evaluates every `completing` task.
+2. A held outcome is final: no phase, runtime commit, or abort handler runs
+   again, no definition is needed, the task is never reserved or migrated, and
+   `abortTask()` on it only marks it and returns `marked`, which cancels the
+   work below. The final record keeps the held outcome and the mark.
+3. A held non-`completed` outcome is cancellation intent, so the work below is
+   aborted, drains, and then the task becomes terminal. A held `completed`
+   outcome waits for the work to finish normally.
+4. Writes split at the hold. A task-written terminal commit lands all of its
+   other writes, such as a tool's result entry and slot, at hold. Only the
+   record's terminal state, task-document retirement, and task waiters are
+   deferred to the final commit. A scheduler-written outcome writes only the
+   record at hold; its Harness cleanup (section 5.4) runs in the final commit,
+   so a faulted run task keeps `pi.live.run` until its tools drained.
+5. Waiters, idle waits, inspection, and ordinary traversal see a `completing`
+   task as live until its final commit.
+
+New owned work needs a live owner: `createTask` with task ownership and
+`createConversation` with task ownership reject an owner that is `completing`,
+`terminal`, or abort-marked in the commit's final candidate (section 3.3).
+Conversations stay usable after their owner finished: new runs
+started there, for example to interrogate a finished subagent, are ordinary work
+of that conversation, reached by traversal from above, and not part of any
+finish.
+
+**Waiting.** A phase may commit `{ status: "waiting", checkpoint, on, policy }`.
+The task stops without an invocation and resumes at `checkpoint` once every task
+in `on` is terminal. `on` may name any tasks, including already terminal ones;
+tasks the waiting task does not own, whose `owner` is not the waiting task,
+require `policy: "allSettled"`. `on` may not name a missing task, the task
+itself, or a task on its owner chain (section 5.1). With `failFast`, the first
+task in `on` that holds or ends with a non-`completed` outcome gives every other
+live task in `on` an abort mark, in the scheduler's next reconcile commit. The waiting task itself is not marked:
+it resumes once all of `on` is terminal and reads their outcomes with
+`runtime.outcomes()`. A task may create children and keep running phases before
+it waits, and may wait on any subset of its children in sequence.
+
+**Abort order is bottom-up.** An abort invocation of a task starts only once its
+ordinary owned work is no longer live, so an abort handler sees final outcomes
+below it. An abort mark on a waiting task lets it leave the wait early for its
+abort handler under this same rule; tasks in its `on` that it does not own are
+not awaited. Ordering is judged on committed records: code a child runs after
+its terminal commit is not ordered. An abort handler may not return `waiting`
+and cannot create owned children, because its task is abort-marked (section
+3.3): it compensates inline, or creates background conversation-owned tasks,
+which no cascade reaches, and waits for them with `runtime.waitForTask()`,
+which holds its invocation.
+
+The cascade of the example `Checkout` task, which waits `failFast` on four
+`Payment` children: an expired card fails its payment; the three live payments
+get abort marks and refund in their own abort handlers; once all four are
+terminal, `Checkout` resumes, reads `[aborted, failed, aborted, aborted]`
+through `outcomes()`, and decides its own outcome. `abortTask(Checkout)` instead
+marks `Checkout`, the cascade marks the live payments, their abort handlers run
+first, then `Checkout.abort` runs and sees their final outcomes.
+
 ## 6. Submissions and inbox
 
 Submission records back awaitable host objects. Admission is Harness-internal;
-run tasks settle the inputs they answer with `tx.settleSubmission()`. The inbox
-itself is an ordered conversation document containing tagged items:
+boundaries place queued submissions with `tx.placeSubmission()`, and run tasks
+settle the inputs they answer with `tx.settleSubmission()`. Queued submissions
+wait in the built-in inbox document, an ordered list of tagged items:
 
 ```ts
 type InboxItem =
-  | { readonly id: SubmissionId; readonly mode: "steer" | "followUp"; readonly message: Message }
-  | { readonly id: SubmissionId; readonly mode: "write"; readonly entry: EntryDraft };
+  | { readonly id: SubmissionId; readonly mode: "steer" | "followUp"; readonly content: UserInput }
+  /** `entry` is the write's `EntryDraft`, stored as plain JSON. */
+  | { readonly id: SubmissionId; readonly mode: "write"; readonly entry: JsonObject };
+
+type InboxState = { items: InboxItem[] };
 ```
 
+| field | value |
+|---|---|
+| kind | `pi.inbox` |
+| version | `1` |
+| scope/history/fork | conversation, `latest`, `initial` |
+| `initial()` | `{ items: [] }` |
+| checkpoint | complete base whenever `items` is empty |
+| view mount | `docs["pi.inbox"]` |
+| created | with every Harness conversation (section 2.2) |
+
+Items are in ID order. A queued input stores its content; its `pi.user` entry
+gets the Harness clock's timestamp at placement. Queued submissions belong to
+their conversation, so a fork starts with an empty inbox.
+
 Run control lives in the built-in live document `pi.live` (section 8). Its
 optional `run` value names the task currently responsible for the run and its
 placed input-submission IDs. `run !== undefined` defines `busy`; get-or-create
 of the idle document does not. The value remains while generation, tools, and
-post-tools hand work to one another. The ID list is mutable state because a
+tools hand work to one another: `taskId` names the generation that settles the
+inputs, including while its tool round runs, then the next
+generation. Tool tasks never own the run; the current round's tool tasks are
+listed in `pi.live.tools`. The ID list is mutable state because a
 boundary adds placed steering inputs to an active run; every terminal path
 settles exactly the listed inputs.
 
@@ -1739,43 +2011,85 @@ Admission and terminal transitions:
 
 | action | submission state | other writes |
 |---|---|---|
-| idle input submission | `placed`, with user entry | create run controller/generation |
-| busy input submission | `queued` | append steer/follow-up inbox item |
-| idle write submission | `done`, with entry | append entry; no run |
-| busy write submission | `queued` | append write inbox item |
-| boundary places user item | `placed`, with entry | add ID to current/successor run |
+| input, idle with empty inbox | `placed`, with user entry | create run and generation |
+| write, idle with empty inbox | `done`, with entry | append entry; no run |
+| input or write, busy or non-empty inbox | `queued` | append inbox item |
+| boundary places user item | `placed`, with entry | add ID to current or successor run |
 | boundary places write | `done`, with entry | append entry |
-| run answers | input `done`, with required answer entry | clear/hand off run controller |
-| run fails or aborts | input `unanswered`, with reason | clear/hand off run controller |
+| run answers | input `done`, with required answer entry | remove `run`, or hand it to a successor |
+| run fails or its task aborts | input `unanswered`, with reason | remove `run`; inbox unchanged |
 | withdraw queued item | `unanswered`, reason `aborted` | remove inbox item |
-| stale item | `unanswered`, reason `stale` | remove inbox item |
+| stale head write | `unanswered`, reason `stale` | remove inbox item |
 
 `requestId` deduplicates within one conversation before any write; reusing one
 for the other submission type rejects. A busy input with `whenBusy: "reject"`
-writes no record and reports `ConversationBusy`. Before an idle input places its
-own entry, it runs a final boundary to drain older eligible queued items. A
-`Submission` waits until `done` or `unanswered`; abort withdraws only a still-
+writes no record and reports `ConversationBusy`. An idle input queues with mode
+`steer` when `whenBusy` is `steer` and `followUp` otherwise.
+
+An idle conversation with a non-empty inbox, for example after a failed run,
+queues every new submission behind the waiting items and runs a final boundary
+in the same commit. Order is preserved: a follow-up queued before the failure is
+selected before the new input.
+
+A `Submission` waits until `done` or `unanswered`; abort withdraws only a still-
 queued submission, reports `already_placed` for a placed input, and reports
-`settled` for any terminal submission. Conversation abort withdraws queued steer/follow-up submissions but keeps writes
-for later placement.
+`settled` for any terminal submission. Conversation abort withdraws queued
+steer/follow-up submissions but keeps writes for later placement.
 
-Boundary selection is deterministic by item ID:
+Boundary selection is deterministic by item ID, with the conversation's
+configured `steeringMode` and `followUpMode` (section 2.2): `one-at-a-time`
+selects the first item of that mode, `all` every item of that mode.
 
 | boundary | write | steer | follow-up |
 |---|---|---|---|
 | `postTools` | all | first/all by mode | none |
 | `final` | all | first/all by mode | first/all by mode |
 
-A queued self-head write cuts older pending user items: those submissions become
-stale, the write is placed, and the current run terminates. Other head writes
-whose target predates the caller's newest known head are stale.
+A boundary places its selected writes first, in ID order, and then its selected
+user items, in ID order. A user item queued before a reset or compaction summary
+therefore lands after it and runs in the new context. Queued user items never
+become stale because of a head.
+
+A head write, queued or placed at once, whose target is older than the start of
+the active range, the newest head marker's `head`, is stale: placing it would bring back history that
+head cut. Heads placed earlier in the same boundary count: after a queued reset,
+a queued summary targeting an older entry is stale. A `head: "self"` write is
+never stale.
+
+Compaction summaries are head writes (section 8.7), so this rule alone orders
+compactions by cut position: a summary cutting before the active range start is
+stale, and one cutting at or after it is placed, whenever it was selected.
+Example: background compaction B selects at tail 100 and cuts at 70. While it
+summarizes, a blocking compaction A cuts at 150 and appends its summary. B's
+summary then settles `stale`, because 70 is older than 150. Had A cut at 60
+instead, B would be placed after it: B summarized the context at its selection,
+the then-newest summary plus the entries before 70, which covers everything A's
+summary covers. That holds while the only heads are compaction summaries and
+resets, which make older cuts stale; an application edit placed while a
+compaction summarizes is lost, and an application head can be undone (section
+12).
+
+A `postTools` boundary that selects a `head: "self"` write (a reset) behaves as
+`final`: it also selects follow-ups, and the current run ends with its inputs
+`unanswered` with reason `reset`, because its context was cut before an answer.
+A reset placed at a `final` boundary follows the answer, so the inputs are
+already `done`.
 
 At ordinary `postTools`, generation continues even with no queued trigger;
-selected steer IDs join that continuation. A terminating/handoff post-tools
-boundary uses final behavior instead. At `final`, the current run's placed
-input submissions settle first; selected user IDs start one successor generation. Writes
-never trigger generation by themselves. A final boundary without continuation
-or user triggers leaves the conversation idle.
+selected steer IDs join that continuation. A terminating or handoff tool round
+(section 8.5) uses final behavior instead. At `final`, the current run's placed
+input submissions settle first, unless an `onYield` continuation keeps them open
+(below); selected user IDs start one successor generation with those IDs as the
+new run's inputs. Writes never trigger generation by
+themselves. A final boundary without user triggers leaves the conversation idle,
+except for an `onYield` continuation (section 8.3), which applies only when the
+boundary selected no user item and no reset.
+
+Only successful run ends apply the final boundary: an answer, `terminate`, or
+`handoff`. Failure, a run task's abort handler, fault, and orphan settle the
+run's inputs `unanswered` and leave the inbox alone (`Conversation.abort()`
+separately withdraws queued user items); the queued items stay visible in
+`pi.inbox` until the next submission's boundary or their withdrawal.
 
 Selected and stale items are removed positionally while retained item order is
 preserved. Chord's Astra operation generator must express scattered removals
@@ -1957,7 +2271,7 @@ hooks read that snapshot and never take their own. At every normal phase boundar
 the scheduler takes a fresh one (section 5.4). A tool task keeps the composed tool
 it pinned until execution settles. Different phases may observe different
 registry states; nothing requires one run to see a single registry state across
-its generation, tool, and post-tools tasks. Host operations, such as the create
+its generation and tool tasks. Host operations, such as the create
 conveniences, take one snapshot inside their commit.
 
 ```ts
@@ -1997,14 +2311,91 @@ errors always propagate.
 | `beforeRequest` | replacement chain | report, continue |
 | `afterResponse` | all observers | report, continue |
 | `onYield` | first continuation wins | report, continue |
-| `beforeTool` | call replacement chain; first block wins | block tool with error text |
+| `beforeTool` | argument replacement chain; first block wins | block tool with error text |
 | `afterTool` | result replacement chain | report, continue |
 | `afterTools` | all observers | report, continue |
-| `beforeCollapse` | first decision wins | report, continue |
+| `beforeCompact` | first decision wins | report, continue |
 
 Hooks use task memos for durable first-writer-wins decisions. There is no public
 semantic event channel; current UI status is document state.
 
+```ts
+type HookResult<T> = T | undefined | Promise<T | undefined>;
+
+/** What a hook may use: committed reads and the asking task's memos. */
+interface HookApi extends DocumentReader {
+  readonly taskId: TaskId;
+  readonly conversationId: ConversationId;
+  memo<T extends JsonValue>(name: string, context: Context): Promise<T | undefined>;
+  memo<T extends JsonValue>(name: string, candidate: T, context: Context): Promise<T>;
+}
+
+interface GenerationHooks {
+  /** Before every request attempt, including recovery; the result is used for that request only. */
+  beforeRequest(
+    request: { readonly messages: readonly Message[] },
+    api: HookApi,
+    context: Context,
+  ): HookResult<{ readonly messages: readonly Message[] }>;
+  /** Every terminal provider message, before classification. */
+  afterResponse(message: AssistantMessage, api: HookApi, context: Context): void | Promise<void>;
+  /** A final answer; `continue` appends a user message and continues the run. */
+  onYield(answer: AssistantMessage, api: HookApi, context: Context): HookResult<{ readonly continue: UserInput }>;
+  /** After every tool of the round is terminal; `results` are the round's result entries in call order. */
+  afterTools(assistant: EntryId, results: readonly EntryId[], api: HookApi, context: Context): void | Promise<void>;
+}
+
+interface ToolHooks {
+  /** Before intent; replaces the arguments or blocks the call with error text. */
+  beforeTool(
+    call: ToolCall,
+    api: HookApi,
+    context: Context,
+  ): HookResult<{ readonly arguments?: JsonObject; readonly block?: string }>;
+  /** After execution, before the result entry; replaces the result. */
+  afterTool(
+    call: ToolCall,
+    result: ToolExecutionResult,
+    api: HookApi,
+    context: Context,
+  ): HookResult<ToolExecutionResult>;
+}
+
+interface CompactionHooks {
+  /**
+   * After range selection, before summarizing; the first decision wins. `entries` are the active entries the summary
+   * replaces, the head marker first, and `messages` their model context, the summarizer's source; `firstKept` is the
+   * first entry kept verbatim.
+   */
+  beforeCompact(
+    compaction: {
+      readonly reason: CompactionReason;
+      readonly entries: readonly EntryRecord[];
+      readonly messages: readonly Message[];
+      readonly firstKept: EntryId;
+      readonly instructions?: string;
+    },
+    api: HookApi,
+    context: Context,
+  ): HookResult<{ readonly decline: true } | { readonly summary: string }>;
+}
+```
+
+`GenerationTask`, `ToolTask`, and `CompactionTask` are the exported built-in task
+tokens whose `H` parameters are these interfaces. `runtime.hooks.each(name,
+invoke)` calls `invoke` with every handler registered under `name` whose
+registration matches the task's conversation, in registry order of the phase
+snapshot. A registration matches when it has no scope, when its scope names the
+task's conversation, or, with `subtree`, when the task's conversation is owned
+transitively through tasks of the scope's conversation. Owner edges never change,
+so the Harness may cache each conversation's owner chain. An ordinary throw from
+`invoke` is reported through `onReport` and `each` continues with the next
+handler; once the invocation is signalled, the error propagates. A task that
+composes differently, such as `beforeTool` turning a throw into a block, or stops
+after a first decision, does so inside its own `invoke`. Hooks receive the task's
+runtime as their `HookApi`; hook memos and the task's own memos share one
+namespace, so hook authors prefix their memo names.
+
 ### 7.3 Tools
 
 ```ts
@@ -2014,10 +2405,20 @@ type ToolControl = {
   readonly handoff?: string;
 };
 
+/** Remark about a call for the model and the UI; never part of the tool's data. */
+type ToolDiagnostic = {
+  readonly severity: "info" | "warn" | "error";
+  readonly message: string;
+  readonly code?: string;
+};
+
 type ToolExecutionResult = {
   readonly content?: ToolResultMessage["content"];
   readonly isError?: boolean;
   readonly details?: JsonValue;
+  readonly diagnostics?: readonly ToolDiagnostic[];
+  /** Spend of the execution itself, such as a model call; stored on the result and in `pi.usage.tools`. */
+  readonly usage?: Usage;
   readonly control?: ToolControl;
 };
 
@@ -2032,7 +2433,10 @@ interface ToolExecutionApi extends DocumentObserver, DocumentReader {
   readonly taskId: TaskId;
   readonly conversationId: ConversationId;
   readonly callId: string;
+  /** `HarnessOptions.env` unless a wrapper supplies another environment. */
+  readonly env: ExecutionEnv | undefined;
   output(chunk: string | Uint8Array): void;
+  diagnostic(diagnostic: ToolDiagnostic): void;
   details(value: JsonValue, context: Context): Promise<void>;
   commit<T>(change: (tx: Tx) => T | Promise<T>, context: Context): Promise<T>;
   memo<T extends JsonValue>(name: string, context: Context): Promise<T | undefined>;
@@ -2050,6 +2454,9 @@ interface ToolExecutionApi extends DocumentObserver, DocumentReader {
 
 type ToolRegistration = Tool & {
   readonly replay?: "safe" | "unsafe";
+  readonly executionMode?: ToolExecutionMode;
+  /** Pure repair of commonly malformed arguments; runs before validation and must not mutate `args`. */
+  prepareArguments?(args: JsonValue): JsonValue;
   readonly outputLimits?: {
     readonly maxBytes?: number;
     readonly maxLines?: number;
@@ -2064,14 +2471,41 @@ type ToolRegistration = Tool & {
 ```
 
 Omitted `replay` is `unsafe`. Omitted `outputLimits` are 50 KiB, 2,000 lines,
-and `retain: "head"`.
+and `retain: "head"`. Omitted `executionMode` follows the conversation's
+`toolExecution`; one `sequential` call makes its whole round sequential
+(section 8.3).
 
-A running tool reports two things to the UI, mirroring the two halves of its
-final result:
+Tools reach files and processes only through `api.env`, never through an
+environment captured at registration, so the environment is chosen per call. The
+Harness supplies `HarnessOptions.env`. A wrapper may supply another, for example
+a per-conversation working directory or sandbox:
+
+```ts
+registry.tools.wrap("bash", "workspace", (tool) => ({
+  ...tool,
+  execute: async (args, api, context) => {
+    const workspace = await api.snapshot(WorkspaceDoc, api.conversationId, context);
+    return tool.execute(args, { ...api, env: environmentFor(workspace) }, context);
+  },
+}));
+```
+
+A tool rerun after recovery must get the same environment. When the state a
+wrapper reads can change while a call runs, the wrapper memoizes its choice with
+`api.memo()`. `api` is a plain object so wrappers can spread
+it. A tool that needs an environment and receives none throws, which produces an
+ordinary error result.
+
+A running tool reports output and details to the UI, mirroring the two halves of
+its final result, plus diagnostics (below):
 
 - `output(chunk)` appends running text output, like stdout. If `execute()` omits
   `content`, the final retained output becomes one text content item; no output
-  becomes an empty content list.
+  becomes an empty content list. Retained output is an exact slice of whole lines
+  of the stream (the first lines for `head`, the last for `tail`), trailing
+  newline included; a single line longer than `maxBytes` is cut at the byte limit
+  on a character boundary. Control characters other than tab and newline are
+  removed from the retained text; accepting a chunk does no per-chunk sanitizing.
 - `details(value)` replaces the running details with a complete JSON value; it
   does not merge keys. If `execute()` omits `details`, the last value becomes the
   final `details`, so a renderer handles one details shape from the first
@@ -2080,19 +2514,56 @@ final result:
 Neither is sent to the model while the tool runs. `output()` synchronously
 accepts UTF-8 output into that invocation-owned bounded buffer and throws after
 invocation end. Throttled commits publish the retained output, dropped
-byte/line counts, and the current details in the tool presentation document. Explicit
+byte/line counts, and the current details and diagnostics in its `pi.live.tools`
+slot. The throttle is adaptive, like the environment's shell output capture: the
+first change after an idle period commits at once; each commit then delays the
+next by at least 100 ms and by its written size at 100 KiB/s, so a large
+rewrite buys a proportionally longer pause. Changes made during the delay
+coalesce into the next commit. The throttle is Harness policy, not part of
+`outputLimits`, which only bounds what is retained. Explicit
 text in explicit result content is bounded by the same limits before transcript
-persistence; non-text content is retained as declared by its pi-ai type.
+persistence; non-text content is retained as declared by its pi-ai type. When
+bounding drops text, the Harness adds a `warn` diagnostic with code `truncated`
+stating the dropped lines and bytes.
+
+Diagnostics are a channel, not text. Remarks about a call, such as truncated
+output, a spill path, a corrected path, a file changed on disk, or a capped
+search, go through `api.diagnostic()` or `ToolExecutionResult.diagnostics`,
+never into the content the model reads as the tool's data. The Harness adds the
+ones it owns, and a tool adds only what it alone knows. Every diagnostic is
+model-visible; information only for UIs belongs in `details`. `diagnostic()`
+synchronously records the diagnostic in the tool's slot with the next throttled
+commit and throws after invocation end. At settlement the result's diagnostics
+are those recorded through `api`, then those in the result, then the Harness's.
+When there are any, the result content ends with one text item:
+
+```text
+<harness>
+[warn] output truncated: 51,204 lines, 2,301,112 bytes dropped
+</harness>
+```
+
+with one `[severity] message` line per diagnostic, and the `pi.tool-result`
+entry stores the structured list, possibly empty, as `data: { diagnostics }`
+(section 8.1). The
+stored message is exactly what the model saw, while UIs and code read the list.
+A `warn` diagnostic does not set `isError`.
 
 `output()` never spills complete output to a file because spilling requires a
 filesystem, which may be remote or unavailable. A tool that must preserve
 complete output spills through the `ExecutionEnv` or `FileSystem` it was given,
-such as shell execution with spill capture, and reports the resulting path in its
-details.
+and reports the resulting path in a diagnostic, and in its details when a
+renderer needs it. The environment's shell streams raw output chunks and spills
+the complete output to a file once it crosses byte or line thresholds; it keeps
+no bounded view of its own, so `output()` is the one place output is bounded,
+sanitized, and throttled. The `bash` tool pipes those chunks into `output()`,
+reports the spill path as a diagnostic, and throws on a nonzero exit or timeout;
+the error result still carries the retained output and diagnostics.
 
 The `details()` promise resolves after the corresponding or coalesced document
-commit. During normal settlement, accepted output updates drain before
-the tool-result entry and terminal task record commit. Abort and close obey
+commit. During normal settlement the tool task stops its throttle and awaits the
+commit in flight; the terminal commit, which appends the result entry, is the
+final flush and settles any `details()` promise still pending. Abort and close obey
 invocation and Session admission gates: uncommitted buffered updates may be
 discarded, while admitted commits settle. Cancellation, callback, tracker
 preparation, and checkpoint failures occur before Storage admission and do not
@@ -2108,23 +2579,30 @@ not offered, and calls produce `tool_unavailable`) and is reported. A wrapper
 without a base contributes nothing. The composite supplies the declaration,
 argument validation, replay policy, and execution.
 
-A tool call is accepted only if it was offered in the request's effective
-system/tool history. A call to a tool that is not offered or has no registered
-implementation produces the `tool_unavailable` error result described in section
-2.2 instead of failing the run. The tool task resolves the composed tool once
-from its snapshot before argument validation and pins it until execution
-settles, even across later snapshot refreshes. Arguments must satisfy both the offered
-declaration and the pinned implementation's schema; they are validated before
-and after `beforeTool` hooks.
-
-After hooks and validation, the tool task durably records the final call and
+A tool call is accepted only if its request offered the tool. Generation checks
+this against the tool set replayed from the committed model context through the
+request's `cutoff`; `beforeRequest` replacements do not change it. It answers a
+call to a tool it did not offer with the `tool_unavailable` result described in
+section 2.2, without a tool task. A configuration change after preparation does
+not affect this check (section 2.2). The tool task resolves the composed tool
+once from its phase snapshot and uses that implementation until execution
+settles: one phase handler resolves, validates, runs `beforeTool`, records intent,
+executes, and commits the result, so no phase boundary separates resolution from
+settlement. An unregistered implementation produces `tool_unavailable`.
+The implementation's `prepareArguments`, if any, first repairs the call's
+arguments, for example `edits` sent as a JSON string; the stored call keeps what
+the model sent. Arguments are validated against the resolved implementation's
+schema before and after `beforeTool`; a failure, or a throwing repair, produces an
+`invalid_arguments` error result.
+
+After hooks and validation, the tool task durably records the final arguments and
 resolved replay policy before execution. Recovery does not rerun `beforeTool`
 and passes the same stored arguments to `execute()`. A replay-safe tool may
 reconstruct a submission from those arguments when that transformation is pure.
 Random values, timestamps, mutable document/configuration reads, or other derived
 inputs that must remain stable are first captured in a durable memo, checkpoint,
-or task input. A background supervisor receives the final submission draft in
-its own durable input so it can finish independently. Recovery does not let a
+or task input. A background reporter task receives the final message in its own
+durable input so it can finish independently. Recovery does not let a
 changed registry declaration alter the stored replay policy.
 
 A tool-acquired conversation handle accepts only input submissions; tools use
@@ -2132,7 +2610,7 @@ ordinary transaction writes for passive entries.
 
 A tool executes in a durable task. It may:
 
-- publish bounded running output and details to its presentation document;
+- publish bounded running output and details to its `pi.live.tools` slot;
 - commit memos;
 - create and wait for tasks;
 - atomically create or fork explicitly owned conversations through `commit()`;
@@ -2159,54 +2637,75 @@ the same way; the admitted submission remains durable after those methods reject
 Invocation-owned document watches stop when the invocation ends.
 
 A foreground subagent conversation is explicitly owned by its tool task. One
-transaction creates or forks the child and records its durable registry mapping;
-after settlement the tool reacquires the child, submits with the registered
-request ID, and waits for that submission's result. Aborting or abnormally
-terminalizing the tool task cascades through the owned scope.
-
-A background subagent is provisioned in one transaction. After deduplicating by
-its durable registry key, the tool stages a background supervisor task `B`, a
-child conversation `C` explicitly owned by `B`, and the registry mapping from the
-semantic name to `C` plus its stable request ID. `B` may be staged earlier in the
-same transaction and used immediately as `C`'s owner. Its durable input contains
-the exact submission draft and the registry location/key; it need not contain
-`C`'s not-yet-created ID. Once scheduled, `B` resolves `C` from the mapping,
-verifies the immutable owner edge, and performs normal `Conversation.submit()`.
-A crash before admission makes `B` retry; a crash after admission returns the
-existing request-ID-deduplicated `Submission`. The initiating tool may race the
-same submit for lower latency and wait only for the durable admission receipt.
-The supervisor may complete after setup: its terminal record retains
-`background`, so ancestor ordinary abort and idle traversal continue to stop at
-its owned scope.
-
-Applications may maintain a conversation document mapping semantic subagent
-names to durable conversation IDs and application-minted submission request IDs.
-Such a live registry uses `fork: "initial"` so children do not inherit the
-parent's agent list and its update is not a selected fork source. Conversation
-creation/forking, supervisor creation when applicable, and the registry mapping
-commit atomically. The supervisor input, tool's durable final arguments, or a
-durable checkpoint must retain enough information to reconstruct the exact
-submission draft; the registry itself need not duplicate that payload. Initial
-or later input then uses the registered stable request ID with the full
-`Conversation.submit()` state machine. A crash before admission leaves a durable
-request to submit; a crash after admission retries the same request and receives
-the existing `Submission`. A read-only lookup by conversation/request ID can
-report absence or return the durable queued/placed/done/unanswered receipt.
-Submission admission therefore needs no private transaction shortcut and does
-not move onto `Tx`. Kernel ownership indexes independently drive abort and idle
-traversal.
-
-A tool result may request `addTools`, `terminate`, or `handoff`. Post-tools
-applies added tool names to configured loadout, uses a final boundary for
-terminate/handoff, and writes a headed handoff entry when requested.
+transaction creates or forks the child; the owner edge is its durable record, so
+a replay-safe rerun finds the child with `scanConversations({ ownerTaskId })`
+before creating one. After settlement the tool reacquires the child, submits
+with a request ID derived from its task ID, which a rerun keeps, and waits for
+that submission's result. Provider call IDs are not unique across a Session and
+must not serve as request IDs. Aborting or abnormally
+terminalizing the tool task cascades through the owned scope. The tool reports
+the child in its running details, for example `api.details({ conversationId })`,
+so a UI that sees the call can attach to the child's view or events.
+
+A persistent background subagent outlives the parent's turns and can be
+messaged, steered, stopped, and listed later. One transaction, after
+deduplicating by the subagent's name in an application registry document,
+creates a background conversation-owned anchor task `A` in the parent, a child
+conversation `C` owned by `A`, and the registry mapping from the name to `C`.
+`A` completes at once; it holds `completing` while `C` has ordinary work
+(section 5.5) and then stays terminal. Its record keeps `background`, so the
+parent's ordinary abort and idle traversal stop at it, while
+`Conversation.abort(context, { background: true })` still reaches `C`'s work
+through it, and `Harness.waitForIdle()` does not wait for it. Later runs in `C`
+are ordinary work of `C`; a terminal owner never cascades.
+
+Each message to a subagent is delivered by a background conversation-owned
+reporter task in the parent, created in the tool's transaction and keyed there
+by the tool task ID so a rerun of the call does not create another. The
+reporter submits to `C` with a request ID derived from its own task ID, waits
+for that submission's settlement, and posts the answer to the parent as an
+input with `whenBusy: "followUp"`, under another request ID derived from its
+task ID. A crash before either admission retries it; a crash after returns the
+existing `Submission`, so the child gets the message once and the parent gets
+the answer once. Submission admission therefore needs no private transaction
+shortcut and does not move onto `Tx`. A registry of names uses `fork:
+"initial"` so forks of the parent do not inherit it. A UI lists subagents from
+the registry; a child is working while its `pi.live.run` is set. Owner edges
+alone drive abort and idle traversal.
+
+A tool result may request `addTools`, `terminate`, or `handoff`. The
+generation's `tools` phase (section 8.5) appends added tool names to the
+configured loadout; they take effect at the next preparation. The round
+terminates only when every result of the round requests `terminate`, as in the
+pi agent loop; the `tools` phase then uses a final boundary. Any
+`handoff` in the round, the last one in call order when several ask, ends the
+run the same way after appending a `pi.reset` entry with `head: "self"` and the
+handoff text as a user message (section 8.1), exactly what `reset(handoff)`
+writes.
+
+A result's `usage` is stored on the tool-result message and added to the
+conversation's `pi.usage.tools[toolName]` in the result commit (section 8.6). A
+tool that runs an owned conversation must not report that conversation's spend
+again: the child's own `pi.usage` already counts it (section 12).
 
 On reopen, a tool reruns only when both its stored intent policy and the current
 registered declaration say `safe`. A current `unsafe` declaration may veto a
 stored-safe replay; a current-safe declaration never upgrades stored unsafe. A
 tool with no current registration is treated as `unsafe`. Every other orphaned
 effect produces an interrupted result containing the
-durable partial output. Completed, failed, and aborted
-tool terminal outcomes retain their tool-result entry ID for post-tools.
+durable partial output. Completed, failed, and aborted tool terminal outcomes
+retain their tool-result entry ID for the generation's `tools` phase.
+
+Error results the Harness writes itself set `isError` and carry an `error`
+diagnostic with one of the codes `tool_unavailable`, `invalid_arguments`,
+`blocked`, `interrupted`, `aborted`, or `tool_error` (a throw from `execute()`)
+and the error text as its message. Their content is the durable partial output,
+if any, and `details` is the tool's last reported value, if any.
+
+`@earendil-works/pi-durable/tools` provides `read`, `bash`, `edit`, and `write`
+factories, ported from the agent harness tools. They use only `api.env` and are
+registered like any other tool; nothing registers them automatically. `read`
+does not return images yet.
 
 ### 7.4 System prompt and dynamic tools
 
@@ -2254,8 +2753,9 @@ Generation preparation takes these steps against its phase snapshot:
    append one positional `pi.system` entry when they differ.
 
 Preparation does not recheck the transcript before appending: only the Harness
-writes to a busy conversation, through submissions, run tasks, and boundaries,
-so the transcript it read is still current (section 12).
+writes to a busy conversation, through submissions, run tasks, boundaries, and a
+blocking compaction, which appends only while its generation waits for it
+(section 8.7), so the transcript it read is still current (section 12).
 
 Model and thinking level are request options, not prompt state.
 
@@ -2303,7 +2803,7 @@ A PR #9548 `SystemMessage` is always a patch, not a reset: it cannot remove
 previous `content` or restore section order merely by restating current values.
 Therefore, when a head removes the previous request-visible baseline, which is
 the case when the active context has a head marker and no `pi.system` entry
-follows that marker, the new
+was appended after that marker (has a higher ID), the new
 `pi.system` entry adds `ContextEdit` omissions for every earlier `pi.system`
 entry still retained after the cut. Its own message is then a complete baseline
 containing every desired section in order and every effective tool declaration.
@@ -2313,10 +2813,16 @@ values, so every later preparation finds a `pi.system` entry after the marker.
 Head rebaselining takes precedence over ordinary order/value patching.
 Without a head cut, an order mismatch uses the two-entry remove/re-add sequence
 above; only when order already matches does preparation emit the minimal changed
-values, `null` removals, and tool additions/removals. A changed tool declaration
-is removed and re-added in the same message. When the offered tool order differs
-from the desired order, the message removes every offered tool and re-adds the
-desired tools in order.
+values and `null` removals.
+
+Tool changes are planned separately and ride on the last planned entry, or on
+one entry of their own when sections are unchanged. Declarations are compared
+with pi-ai `declarationsEqual()` and written with `toToolDeclaration()`, so
+application metadata never enters the transcript. A changed declaration is
+removed and re-added in the same message. Replay keeps retained tools in place
+and appends additions; when that would not yield the desired order, the message
+removes every offered tool and re-adds the desired tools in order. A head
+rebaseline adds every desired tool.
 
 The rendered strings stored in historical `SystemMessage.sections` remain
 authoritative even if the current renderer changes. Pi-ai decides whether to
@@ -2359,8 +2865,7 @@ The initial implementation provides:
 |---|---|
 | `pi.generation` | prepare system/loadout, request or poll model, retry, classify response |
 | `pi.tool` | validate, hook, execute, persist output and details, append result |
-| `pi.post-tools` | wait for tools, apply controls, run boundary, continue generation |
-| `pi.collapse` | select a transcript range, summarize, append a headed summary |
+| `pi.compaction` | select a transcript range, summarize, place a headed summary |
 
 Generation uses `HarnessOptions.models` without a Pico-specific model adapter. It
 resolves `models.getModel(ref.provider, ref.modelId)`, builds a pi-ai `Context`
@@ -2376,23 +2881,29 @@ to normal interrupted/aborted transcript entries, clears presentation state,
 and then retries or terminates according to the task phase. Retry deadlines,
 attempts, compaction, and tool progress are current document state for late
 joiners; completed-attempt usage/accounting is an entry or terminal detail.
-Bounded output records whether content was truncated and any retained file path.
+Truncation and spill paths are tool diagnostics (section 7.3).
 
 Compaction changes model context by appending a summary entry with a head. It
 does not delete transcript history.
 
 ### 8.1 Built-in entries
 
-Built-in entry kinds carry no `data`; each is exported as an `Entry` token.
+Built-in entry kinds carry no `data`, except `pi.tool-result`, whose token is
+`Entry<{ diagnostics: ToolDiagnostic[] }>`; every tool result carries `data`,
+with an empty list when it has no diagnostics (section 7.3), and
+`pi.compaction`, whose token is `Entry<{ reason: CompactionReason }>`. Each kind
+is exported as an `Entry` token.
 
 | kind | `model` | written by |
 |---|---|---|
-| `pi.user` | `[UserMessage]`, timestamp from the Harness clock at admission or placement | submissions |
+| `pi.user` | `[UserMessage]`, timestamp from the Harness clock at admission or placement | submissions, `onYield` continuations |
 | `pi.assistant` | `[AssistantMessage]` with any stop reason | generation |
 | `pi.system` | `[SystemMessage]` with `content: ""` (section 7.4) | generation preparation |
-| `pi.tool-result` | `[ToolResultMessage]` | tool tasks |
+| `pi.tool-result` | `[ToolResultMessage]` | tool tasks; generation for calls to tools its request did not offer |
+| `pi.reset` | absent, or `[UserMessage]` with the handoff text; always `head: "self"` | `reset()`, generation `tools` phase for `handoff` |
+| `pi.compaction` | `[UserMessage]` with the wrapped summary; `head` is the first kept entry | compaction tasks (section 8.7) |
 
-Every provider result becomes a `pi.assistant` entry: answers, failed attempts
+Every generation response becomes a `pi.assistant` entry: answers, failed attempts
 with their error text and usage, and converted partials with stop reason
 `aborted`. Context derivation (section 2.1, rule 9) keeps failed and aborted
 messages out of later requests, so no separate usage or notice kind exists.
@@ -2413,6 +2924,39 @@ type LiveState = {
     /** Provider-side deferred response being polled. */
     deferred?: { pollAt: number };
   };
+  /** The current tool round in call order, from the tool-calling answer until the generation's `tools` phase ends it. */
+  tools?: {
+    callId: string;
+    name: string;
+    /**
+     * Absent for a call not started yet (sequential round, `pending`) and for a call its request did not offer,
+     * which starts `done` with the `entry` generation wrote.
+     */
+    taskId?: TaskId;
+    status: "pending" | "running" | "done";
+    /** Retained running output and what the bounds dropped. */
+    output?: string;
+    droppedBytes?: number;
+    droppedLines?: number;
+    /** Last `details()` value. */
+    details?: JsonValue;
+    /** Diagnostics recorded through `api.diagnostic()`. */
+    diagnostics?: ToolDiagnostic[];
+    /** Result entry once done; absent when the tool task faulted or was orphaned. */
+    entry?: EntryId;
+  }[];
+  /** Live compaction tasks in task ID order; absent when none (section 8.7). */
+  compactions?: CompactionStatus[];
+};
+
+type CompactionStatus = {
+  taskId: TaskId<CompactionResult>;
+  reason: CompactionReason;
+  /** Whether a generation waits for it: a compaction the generation owns. */
+  blocking: boolean;
+  attempt: number;
+  /** Durable backoff before the next summarization attempt. */
+  retry?: { at: number; error: string };
 };
 ```
 
@@ -2422,18 +2966,39 @@ type LiveState = {
 | version | `1` |
 | scope/history/fork | conversation, `latest`, `initial` |
 | `initial()` | `{}` |
-| checkpoint | complete base whenever `generation` is absent |
+| checkpoint | complete base whenever nothing runs: `generation` absent and no `running` tool slot |
 | view mount | `docs["pi.live"]` |
 | created | with every Harness conversation (section 2.2) |
 
-Nothing is in flight at every turn boundary and while idle, so the stored delta
-chain spans at most one generation, including its retries and deferred polls, or
-one tool round, and each base is small. Tool progress adds its own condition with the tool task.
-
-Tool progress and compaction status join this document with the tool and
-collapse tasks. Partials are normalized to strict JSON before assignment. Every
-terminal path of a run task removes `run` and `generation` in the commit that
-settles the run's inputs. `tx.settleSubmission()` stages each input's new status
+Nothing runs while idle, at a final boundary, in the commit where generation
+hands over to its tool round (every slot is still `pending` or `done`), between
+the tools of a sequential round, and whenever no tool of a parallel round is
+`running`. A slot holds output only while `running`, so every base is small, and
+the stored delta chain spans at most one generation, including its retries and
+deferred polls, or the overlapping execution of one round's tools. Retained head output grows by Chord string appends. A sliding tail
+usually becomes a front trim plus an append; when Chord's bounded overlap search
+finds no shared part, as with highly repetitive output or a window larger than
+its 64 KiB scan, the commit writes the retained window as one set. Either way
+each commit writes at most one window, and the throttle bounds the rate.
+
+Generation creates `tools` with one `pending` slot per call in the commit that
+appends the tool-calling answer; a call its request did not offer starts `done`
+with its result entry. A tool task sets its slot `running` in its intent commit,
+publishes throttled output and details into it, and in its terminal commit sets
+`done` and `entry` and removes `output`, `droppedBytes`, `droppedLines`,
+`details`, and `diagnostics`, which the result entry now carries (section 7.3).
+The generation's `tools` phase removes `tools`. Slot updates apply only while a slot with the task's
+`taskId` exists; without one, the durable partial output, details, and
+diagnostics are empty.
+
+A compaction's status is added in the commit that creates the task and removed
+in the commit that decides its outcome: the task's own outcome commit, even when
+that outcome holds as `completing` (section 5.5), or the scheduler's cleanup
+(section 5.4).
+It stays small: the summary text lives in the task's placement, never here. Partials are
+normalized to strict JSON before assignment. Every terminal path of a run task
+removes `run`, `generation`, and `tools` in the commit that settles the run's
+inputs. `tx.settleSubmission()` stages each input's new status
 and resolves the transaction's latest candidate submission record, falling back
 to committed state, during assembly, like task-document validation (section 3.3),
 so it is not a caller table read and works after the commit's first table write.
@@ -2443,18 +3008,44 @@ so it is not a caller table read and works after the commit's first table write.
 ```ts
 type GenerationInput = {};
 type GenerationCheckpoint =
-  | { phase: "prepare"; attempt: number }
+  | {
+      phase: "prepare";
+      attempt: number;
+      /** The blocking compaction this generation waited for; it starts no other compaction. */
+      compacted?: TaskId<CompactionResult>;
+      /** Error text of the overflow that started `compacted`; checked once when `prepare` resumes. */
+      overflow?: string;
+    }
   | {
       phase: "request";
       attempt: number;
+      compacted?: TaskId<CompactionResult>;
       model: ModelRef;
       thinkingLevel: ModelThinkingLevel;
       streamOptions: ConversationStreamOptions;
+      toolExecution: ToolExecutionMode;
       /** Newest entry included in the request. */
       cutoff: EntryId;
     }
-  | { phase: "retry"; attempt: number; until: number }
-  | { phase: "poll"; attempt: number; model: ModelRef; handle: DeferredHandle; pollAt: number };
+  | { phase: "retry"; attempt: number; compacted?: TaskId<CompactionResult>; until: number }
+  | {
+      phase: "poll";
+      attempt: number;
+      compacted?: TaskId<CompactionResult>;
+      model: ModelRef;
+      toolExecution: ToolExecutionMode;
+      cutoff: EntryId;
+      handle: DeferredHandle;
+      pollAt: number;
+    }
+  | {
+      /** Waiting on the round's tool tasks; `waiting` holds this checkpoint (section 8.5). */
+      phase: "tools";
+      assistant: EntryId;
+      tools: TaskId<ToolTaskResult>[];
+      /** Calls of a sequential round not started yet, in call order. */
+      pending: string[];
+    };
 type GenerationResult = { entryId: EntryId };
 ```
 
@@ -2463,9 +3054,35 @@ The run's inputs live in `pi.live.run`, not in the task input.
 
 - `prepare` runs section 7.4 against the committed configuration. When no model
   is configured or `models.getModel()` does not know it, the task fails with
-  `no_model`. Otherwise one commit appends the planned `pi.system` entries and
+  `no_model`. When it resumes with `overflow` and its compaction did not
+  complete with an `entryId`, the run fails with `model_error` and the overflow
+  text as detail. Otherwise one commit appends the planned `pi.system` entries and
   moves to `request` with the new tail as `cutoff` and the configuration's model,
-  thinking level, and stream options.
+  thinking level, stream options, and tool execution mode. These stay fixed for
+  this request attempt; a retry prepares again. `compacted` carries over to
+  `request`, `retry`, `poll`, and the next `prepare`.
+- Before that commit, `prepare` checks the compaction thresholds (section 8.7)
+  when the conversation's compaction policy is enabled, the model's
+  `contextWindow` is positive, and `compacted` is absent. The estimate starts at
+  the newest assistant message in the committed model context whose entry was
+  appended after the head marker (all qualify without one) and whose usage is
+  nonzero: pi-ai `calculateContextTokens()` of its usage, plus pi-ai
+  `estimateMessageTokens()` of every context message after it and of the planned
+  system messages. Its request included the marker, because a head is placed
+  only while no request is in flight. Without such a message, every message is
+  estimated. Both thresholds apply only when range selection finds a cut.
+  - Above `contextWindow - reserveTokens`, the blocking threshold: instead of
+    appending, one commit creates a compaction owned by the generation with reason
+    `threshold`, adds its status, and commits `waiting` on it with `allSettled`
+    and checkpoint `{ phase: "prepare", attempt, compacted }`. Whatever its
+    outcome, `prepare` then runs again and sends the request.
+  - Above `contextWindow - reserveTokens - backgroundTokens` with
+    `backgroundTokens > 0` and no compaction status in `pi.live`: the commit that
+    moves to `request` also creates a background compaction, owned by the
+    conversation, with reason `threshold`, and adds its status. The generation
+    does not wait for it. The retry policy is read when the
+  attempt's result is classified, because it governs the next attempt (section
+  2.2).
 - `request` and `poll` resolve the checkpoint's model through
   `models.getModel()`; an unknown model fails the task with `no_model`, like
   `prepare`. `request` converts a leftover partial (below) before it resolves
@@ -2474,15 +3091,37 @@ The run's inputs live in `pi.live.run`, not in the task input.
   interrupted attempt into an aborted `pi.assistant` entry. It then streams the
   model context through `cutoff` with the invocation signal, the thinking level
   as `reasoning` (omitted for `off`), and the pinned `streamOptions`,
-  committing throttled partials. Recovery resends the same messages with the
-  same pinned model, thinking level, and stream options.
+  committing throttled partials. Before streaming, the `beforeRequest` chain may
+  replace the messages for this request only. Recovery resends the same
+  committed messages with the same pinned model, thinking level, and stream
+  options, and reruns `beforeRequest`.
+- `afterResponse` observes every terminal message, from `request` or `poll`,
+  before classification; a still deferred result is not terminal.
 - Before classifying, the handler stops the partial throttle and awaits any
   partial commit in flight, so no stale partial lands after the outcome. The
   terminal message is classified in one commit that also clears the partial:
-  - `stop`/`length`: append the answer, settle the run's inputs `done`, remove
-    `run` and `generation`, and complete with `{ entryId }`. The same commit
-    applies the final boundary (section 6).
-  - `toolUse`: append the assistant entry and continue through the tool chain.
+  - `stop`/`length`: before the commit, the `onYield` chain runs; the first
+    `{ continue }` wins. The commit appends the answer and applies the final
+    boundary (section 6). With a continuation and no selected user item or
+    reset, it appends a `pi.user` entry with the continuation content, creates a
+    successor generation, and hands it `pi.live.run`, keeping the inputs open.
+    Otherwise it settles the run's inputs `done`, removes `run` and
+    `generation`, and starts a successor run for the selected user items, if
+    any; a dropped continuation is not retried. Both complete with
+    `{ entryId }`.
+  - `toolUse` with at least one tool call: the commit appends the assistant
+    entry and starts the tool round described below, moving to `waiting` in the
+    `tools` phase. A `toolUse` message without calls is classified like `stop`.
+  - `error` that pi-ai `isContextOverflow()` recognizes, while the compaction
+    policy is enabled, `compacted` is absent, and range selection finds a cut:
+    the commit appends the error entry, removes `generation`, creates a
+    compaction owned by the generation with reason `overflow`, adds its status,
+    and commits `waiting` on it with `allSettled` and checkpoint `{ phase:
+    "prepare", attempt, compacted, overflow }`; the recovery request does not
+    count against the retry policy. Any other overflow,
+    including a second one, is never retried and fails like the non-retryable
+    errors below. A `stop` or `length` response is never classified as overflow;
+    the next threshold check handles silent overflow.
   - `error` that `isRetryableAssistantError()` accepts while the conversation's
     retry policy allows another attempt (`enabled` and `attempt <= maxRetries`,
     so `maxRetries` counts retries after the first attempt): append the error entry and move to
@@ -2500,10 +3139,294 @@ The run's inputs live in `pi.live.run`, not in the task input.
   known (a failure is reported), converts a committed partial, settles the inputs `unanswered` with
   `aborted`, removes `run` and `generation`, and ends `aborted`.
 
+A tool round starts in the commit that appends the tool-calling answer:
+
+1. The offered tools are replayed with pi-ai `getCurrentTools()` from the
+   committed model context through `cutoff`: `request` already holds it, and
+   `poll` derives it again. A call to a tool not offered gets its
+   `tool_unavailable` result entry here, without a task.
+2. Every other call gets a `pi.tool` task owned by the generation, with input
+   `{ assistant, callId }`. The round is sequential when the pinned
+   `toolExecution` is `sequential` or any called tool's registration in the phase
+   snapshot has `executionMode: "sequential"`: then only the first call gets its
+   task now and the rest wait in `pending`. Otherwise every call gets its task at
+   once and they run in parallel. The checkpoint's `tools` lists the tasks
+   created so far and grows by one per started sequential call, while
+   `pending` shrinks.
+3. The generation commits `waiting` on its tool tasks with `allSettled` and the
+   `tools` checkpoint (section 8.5); `pi.live.run` stays with it.
+4. `pi.live.tools` receives the round's slots (section 8.2), and `generation` is
+   removed.
+
 Input submissions settle `unanswered` with one of these reasons: `no_model`,
 `model_error` (detail: provider error text), `aborted`, `faulted` (detail: error
 message), or an orphaning blocked reason (section 5.4). Fault and orphan
-settlement discard a committed partial without writing a transcript entry.
+settlement convert a committed partial into an aborted `pi.assistant` entry,
+like the abort handler.
+
+### 8.4 Tool
+
+```ts
+type ToolTaskInput = { assistant: EntryId; callId: string };
+type ToolTaskCheckpoint =
+  | { phase: "call" }
+  | { phase: "execute"; arguments: JsonObject; replay: "safe" | "unsafe" };
+type ToolTaskResult = { entryId: EntryId; control?: ToolControl };
+```
+
+`pi.tool` is version 1 and starts at `{ phase: "call" }`. The input stays small
+because the terminal record keeps it; the call is read from the assistant entry.
+
+- `call` reads the call with `runtime.entry()`, resolves the composed tool from
+  its phase snapshot, validates the arguments with pi-ai
+  `validateToolArguments()`, runs the `beforeTool` chain, and validates again
+  (section 7.3). One commit then records intent: it moves to `execute` with the
+  final arguments and the tool's replay policy and sets the slot `running`. The
+  same handler executes the tool, runs the `afterTool` chain, and commits the
+  result. An unregistered tool, invalid arguments, or a block commits the
+  corresponding error result instead, without intent.
+- `execute` is reached only by recovery. When both the stored and the currently
+  registered policy are `safe`, it executes again with the stored arguments,
+  without `beforeTool`, and settles like `call`. Otherwise it commits an
+  `interrupted` error result from the slot's durable partial output, details, and
+  diagnostics, and ends `failed` with `{ entryId }`.
+- The result commit bounds the content, appends the diagnostics block (section
+  7.3), appends one `pi.tool-result` entry with `model: [{ role: "toolResult",
+  toolCallId, toolName, content, details, isError, timestamp }]` and
+  `data: { diagnostics }`, marks the slot `done`, and
+  completes with `{ entryId, control }`. An `isError` result still completes.
+- A throw from `execute()` becomes a `tool_error` result and the task ends
+  `failed` with `{ entryId }`; once the invocation is signalled it propagates
+  instead. Ending `failed`, like `aborted`, records cancellation intent (section
+  5.4), so conversations the call owns, which nothing supervises any more, are
+  aborted. A returned `isError` result still completes, and its call's owned work
+  survives. Either way the run continues with the result entry. A tool task whose
+  owned conversations still have ordinary work when it commits its result holds
+  `completing` with the result entry already written (section 5.5); the
+  generation resumes only when the tool task is terminal.
+- The abort handler commits an `aborted` error result from the slot's durable
+  partial output, details, and diagnostics and ends `aborted` with `{ entryId }`.
+
+### 8.5 Tool rounds
+
+The generation resumes in its `tools` phase once every tool task it waits on is
+terminal. In a sequential round with calls left in `pending`, one commit creates
+the next call's owned tool task and waits on it again with the shorter `pending`.
+Otherwise it reads the tool records with `runtime.getTask()` and the round's
+result entries from the `pi.live.tools` slots, runs the `afterTools` observers,
+and then commits once:
+
+- It appends every `addTools` name not already active to the configured
+  loadout; the next preparation offers it.
+- When every result of the round requests `terminate`, or any requests
+  `handoff`, it appends the handoff's `pi.reset` entry, if any, settles the
+  run's inputs `done` with the tool-calling answer, removes `run` and `tools`,
+  and applies the final boundary.
+- Otherwise it removes `tools` and applies the `postTools` boundary. When that
+  boundary placed a reset, the run's inputs settle `unanswered` with `reset` and
+  selected user items start a successor run (section 6). Otherwise selected
+  steer IDs join `pi.live.run`, and it creates the next generation, owned by the
+  conversation, and hands it the run.
+
+It completes with `{ entryId }` of the tool-calling answer. Its abort handler
+runs only after its tool tasks are terminal (section 5.5). For every call still
+in `pending`, which never started, it appends an `aborted` error result; a
+started call whose task faulted or was orphaned keeps
+its `done` slot without an entry (section 8.2). It then settles the inputs
+`unanswered` with `aborted`, removes `run`, `generation`, and `tools`, and ends
+`aborted`. `abortTask()` on the generation therefore aborts its whole round.
+
+### 8.6 Usage
+
+```ts
+type UsageState = {
+  /** Assistant entries and compaction summarization attempts, keyed `provider/modelId`. */
+  models: Record<string, Usage>;
+  /** Tool results, keyed by tool name; their usage has no model identity. */
+  tools: Record<string, Usage>;
+};
+```
+
+| field | value |
+|---|---|
+| kind | `pi.usage` |
+| version | `1` |
+| scope/history/fork | conversation, `latest`, `initial` |
+| `initial()` | `{ models: {}, tools: {} }` |
+| checkpoint | complete base on every change |
+| view mount | `docs["pi.usage"]` |
+| created | with every Harness conversation (section 2.2) |
+
+`pi.usage` is the ledger of the conversation's own spend. Every built-in writer
+of a `pi.assistant` entry adds its message's `usage` to `models` under the
+message's own `provider/model`, and every writer of
+a `pi.tool-result` entry with `usage` adds it to `tools`, in the same commit.
+Every summarization attempt of a compaction task adds its response's `usage` to
+`models` in the commit that classifies it (section 8.7); that spend has no entry,
+whether the summary is placed, fails, or ends stale. Failed and aborted attempts
+count. A fork starts at zero, so no spend is counted
+twice. `Harness.usage()` sums every conversation's document into the Session
+total; other totals, such as an ownership subtree, are application sums over
+`scanConversations()`. Nothing stores a total across conversations.
+
+### 8.7 Compaction
+
+```ts
+type CompactionReason = "manual" | "threshold" | "overflow";
+type CompactionInput = { reason: CompactionReason; instructions?: string };
+/** The pinned summarization request. */
+type SummaryRequest = {
+  attempt: number;
+  model: ModelRef;
+  thinkingLevel: ModelThinkingLevel;
+  streamOptions: ConversationStreamOptions;
+  maxTokens: number;
+  /** Newest entry of the context the range was selected from. */
+  tail: EntryId;
+  /** First entry kept verbatim; the summary's `head`. */
+  firstKept: EntryId;
+};
+type CompactionCheckpoint =
+  | { phase: "select" }
+  | ({ phase: "summarize" } & SummaryRequest)
+  | ({ phase: "retry"; until: number } & SummaryRequest);
+/**
+ * `entryId` of a blocking compaction's summary, or the `submissionId` of a conversation-owned compaction's summary
+ * write; both absent when nothing was compacted.
+ */
+type CompactionResult = { entryId?: EntryId; submissionId?: SubmissionId };
+```
+
+`pi.compaction` is version 1 and starts at `{ phase: "select" }`. Compaction
+replaces an old prefix of the model context with a summary entry whose `head` is
+the first kept entry (section 2.1). Raw history stays in storage. There are three
+ways to start one; the task is the same, only ownership and placement differ:
+
+| started by | owner | background | generation waits | placement |
+|---|---|---|---|---|
+| `Conversation.compact()` | conversation | no | no | write submission |
+| generation above the background threshold | conversation | yes | no | write submission |
+| generation above the blocking threshold, or on overflow | the generation | no | yes | direct append |
+
+Only a blocking compaction runs while the conversation's run waits for it. The
+others never take run control: the conversation keeps working while they
+summarize, and their summary is placed like any passive write. Compactions do
+not coordinate with each other; several may run at once, and section 6 decides
+between their summaries.
+
+**Range selection** is a pure function of a `ContextView`, whose
+`contributions` give each active entry's model messages after every edit in the
+range (section 2.1, rules 4 and 9), including edits carried by older in-range
+markers, and `keepRecentTokens`.
+
+1. Cut candidates are the non-marker entries whose contribution begins with a
+   user or assistant message. Tool results and system entries are never
+   candidates, so a kept assistant message keeps its tool results. A user entry
+   is not a candidate either while a result for a call of the assistant before
+   it follows it, before the next assistant (section 2.1, rule 7).
+2. Walk the non-marker entries from newest to oldest, adding pi-ai
+   `estimateMessageTokens()` of each contribution. At the first entry where the
+   sum reaches `keepRecentTokens`, the cut is the first candidate at or after
+   that entry in transcript order, or the newest candidate when none follows.
+3. There is nothing to compact when the sum never reaches `keepRecentTokens`, or
+   when no non-marker entry before the cut contributes a model message.
+
+The summarized entries are the head marker, if any, followed by the non-marker
+entries before the cut. Their messages are their contributions, ordered as in
+section 2.1, rules 7 and 8, so an earlier summary is summarized again together
+with the history after it. Nothing is compacted while the context is smaller
+than `keepRecentTokens`, so with a window where `contextWindow - reserveTokens`
+is below it, overflow may come before any threshold compaction.
+
+```text
+1 user   2 assistant (read)   3 tool result, 30k tokens   4 assistant   5 user   6 assistant
+keepRecentTokens 20k: the walk from 6 reaches 20k at 3; the first candidate at or after 3 is 4.
+The summary covers 1-3; the model context becomes [summary, 4, 5, 6].
+```
+
+Phases:
+
+- `select` reads the committed configuration and captures the committed
+  context. When no model is configured or `models.getModel()` does not know it,
+  the task fails with `no_model`. With nothing to compact it completes with
+  `{}`. Otherwise the `beforeCompact` hooks (section 7.2) run with the
+  summarized entries and messages; the first decision wins. `{ decline: true }` completes
+  with `{}`, and `{ summary }` is placed as below in the same commit. Without a
+  decision, one commit moves to `summarize` with attempt 1, the configured model,
+  thinking level, and stream options, `maxTokens` = `min(floor(0.8 *
+  reserveTokens), model.maxTokens)` (the model's value only when positive), the
+  captured tail, and the cut as `firstKept`.
+- `summarize` derives the summarized messages again from the context at `tail`,
+  which is immutable, and serializes them to text: `[User]: ...`,
+  `[Assistant thinking]: ...`, `[Assistant]: ...`,
+  `[Assistant tool calls]: name(key=json, ...)`, and `[Tool result]: ...`
+  truncated to 2000 characters; system messages are omitted. The request has no
+  tools and two messages: a system message with the built-in summarization
+  system prompt, and a user message with the serialized text in
+  `<conversation>` tags followed by the built-in summarization prompt, and
+  `Additional focus: <instructions>` when the input has instructions. It uses the
+  pinned thinking level as `reasoning`, and the pinned stream options without
+  `deferred`, with `cacheRetention: "none"` and the pinned `maxTokens`.
+  Recovery resends the same request. The response is classified in one commit
+  that adds its usage to `pi.usage` (section 8.6):
+  - `stop` with non-empty text and no tool call: the text is the summary, placed
+    as below.
+  - `error` that `isRetryableAssistantError()` accepts while the conversation's
+    retry policy allows another attempt: move to `retry` with `until = now +
+    retryDelayMs(policy, attempt)`, and set the status's `attempt` and `retry`.
+  - anything else, including a `length` stop, which leaves the summary
+    incomplete: fail with `model_error`.
+- `retry` sleeps until `until`, then returns to `summarize` with the next attempt
+  and the same pinned request.
+
+The built-in prompts are the coding agent's structured checkpoint format. The
+prompt also asks the model to carry forward an earlier summary at the start of
+the conversation.
+
+**Placement.** The summary entry is
+
+```ts
+{
+  kind: "pi.compaction",
+  head: firstKept,
+  model: [{ role: "user", content: [{ type: "text", text: wrapped }], timestamp: now }],
+  data: { reason },
+}
+```
+
+where `wrapped` is `"The conversation history before this point was compacted
+into the following summary:\n\n<summary>\n"`, the summary, and
+`"\n</summary>"`. The commit that places it also removes the task's status and
+commits the task's `completed` outcome:
+
+- A blocking compaction appends the entry directly and completes with
+  `{ entryId }`. Its generation holds the run and waits, so nothing else writes
+  the conversation.
+- A conversation-owned compaction admits the entry as a write submission with
+  request ID `compaction:<taskId>`, following section 6 exactly: in an idle
+  conversation with an empty inbox it is appended at once or settles `stale`;
+  in an idle conversation with queued items it queues and a final boundary runs;
+  in a busy one it queues for the next boundary. It completes with
+  `{ submissionId }` and never waits for a queued placement;
+  `Harness.submission()` observes the placement.
+
+The next generation's preparation finds a head marker without a later
+`pi.system` entry and writes a complete system baseline (section 7.4).
+
+**Cancellation.** The abort handler removes the task's status and ends
+`aborted`; it writes no entry. An attempt cut short by abort or a crash has no
+committed response, so its usage is not counted. A manual compaction is
+ordinary work of its conversation: `Conversation.abort()` aborts it. A
+background compaction survives it and stops only through `abortTask()` or
+`Conversation.abort(context, { background: true })`. A blocking compaction is
+aborted with its generation, before the generation's abort handler runs
+(section 5.5). A summary that is already queued is a write submission:
+conversation abort keeps it, and `Submission.abort()` withdraws it.
+
+When a blocking compaction ends without an `entryId`, because it found nothing
+to compact, was declined, failed, faulted, or was aborted directly, a threshold
+generation sends its request anyway and an overflow generation fails with
+`model_error` (section 8.3).
 
 
 ## 9. Document observation and Chord
@@ -2662,75 +3585,196 @@ rejection is observed.
 
 ### 9.3 Conversation view
 
-The public view is a fixed structural mount of selected built-in documents:
+The public view is a fixed structural mount of the conversation's active
+transcript and its built-in documents:
 
 ```ts
 type ConversationView = {
   readonly conversation: ConversationRecord;
+  /** Raw active entries, as `ContextView.entries` (section 2.1): the head marker, then the non-head entries from its head. */
   readonly entries: readonly EntryRecord[];
+  /** `pi.conversation.config`, `pi.live`, `pi.inbox`, and `pi.usage`, keyed by kind; absent documents are absent. */
   readonly docs: Readonly<Record<string, JsonObject>>;
 };
 ```
 
-The concrete built-in document IDs and fields are public protocol once their
-implementation layer is approved. Third-party documents are initially exposed
-through their own Chord services, not automatically mounted.
+These kinds and their fields are public protocol. Third-party documents are
+exposed through their own Chord services, not mounted.
 
-The mount consumes one complete Session commit and publishes one Chord batch:
+The Harness keeps at most one mount per conversation. The first `viewState()`,
+`watch()`, or event attachment builds its revision on the Session line from the
+committed active transcript and documents; the mount is dropped when its last
+observer detaches. A mount derives each next revision from the Session's
+`subscribeCommits()` publications, like `watchDoc()`: every publication is
+already durable, so the view shows only committed state. One publication that
+touches the conversation yields one Chord batch:
 
 ```text
 document op ["s", ["generation", "message"], value]
 -> view op ["s", ["docs", "pi.live", "generation", "message"], value]
 ```
 
-Entry appends/head changes and every changed mounted document are included in
-the same publication. Before Storage admission, the Session derives the mounted
-operation batch and prepares each affected loaded mount's next immutable revision
-with the optimized immutable applier. Failure rolls back normally. After Storage
-success, finalization only installs the prepared mount pointers/cursors and
-enqueues publication. Mounted document revisions may be structurally shared
-because they obey the same trusted immutability contract. The mount performs no
-semantic projection and owns no second persistence authority. A Chord adapter
-assigns a contiguous in-memory delivery sequence per view source lifetime.
-
-`Conversation.viewState()` exposes the mount directly as a disposable read-only
-Chord state for facets and UI services. `Conversation.watch()` exposes the same
-mount through Package 12's serialized exact-frame watch with bounded pending
-frames and full-value overflow replacements. An empty mounted operation batch
-creates no revision; a redundant nonempty batch remains a real publication.
-Neither API adds another tracker, persistence authority, or semantic event
-envelope.
-
-### 9.4 Agent-mode notifications
-
-The Session kernel and Chord structural sources do not maintain a semantic event
-journal. Coding-agent JSON/RPC compatibility uses a thin agent-mode adapter
-derived from each uncoalesced committed publication before any per-watch
-overflow replacement. It owns no tracker or persistence and emits notifications only after
-the commit that makes them true.
-
-The adapter protocol covers run start/settlement, committed assistant progress,
-message entry settlement, tool intent/progress/result, submission queue/outcome,
-retry/deferred/compaction state, configuration changes, and faults. One commit
-may produce an ordered batch. Progress notifications represent Pico's throttled
-durable partials, not every raw provider frame. The exact legacy `AgentEvent`
-wire format is not preserved.
-
-Notifications have no hydration or replay contract. A consumer requiring a
-complete lifecycle subscribes before admitting the submission; a late or reconnecting
-consumer hydrates structural state and history instead. Product adapters apply
-these rules:
-
-- TUI hydrates and renders `ConversationView`, then applies structural updates;
-  notifications may drive transient animation but are not its authority.
-- Print awaits its input `Submission` and prints that submission's answer.
-- JSON/RPC expose correlated commands plus the ordered agent notification
-  protocol, with transport backpressure and disconnect policy owned by that
-  adapter.
-
-This adapter is allowed even though a public Session-kernel semantic stream is a
-non-goal. It must not derive notifications from a lossy, overflow-reset watch
-when complete subscribed lifecycle delivery is promised.
+An appended entry without a head is a splice at the end of `entries`. An
+appended head marker `H` makes the entries `H` followed by the current non-head
+entries at or after `H.head`: the kept entries stay, and splices remove the
+others and insert `H` at the front. Every kept entry is already mounted because
+Harness writers never target a head before the current range: resets and
+handoffs head themselves, compaction summaries target a kept entry of the
+current range, and head writes that reach further back are stale (section 6). A raw head write that targets further back shows only the
+mounted entries (section 12).
+Document creation and retirement set and delete the `docs` key. Parent entries
+through `parent.at` are immutable, so a child's mount follows only its own
+conversation. A publication that touches nothing mounted creates no revision; a
+redundant nonempty batch remains a real publication. Mounted document revisions
+are structurally shared under the trusted immutability contract. The mount
+performs no semantic projection and owns no persistence.
+
+`Conversation.viewState()` exposes the mount as a disposable read-only Chord
+state. `Conversation.watch()` exposes the same mount through the serialized
+exact-frame watch of section 9.2, with bounded pending frames and full-value
+overflow replacements.
+
+### 9.4 Agent events (experimental)
+
+`watchEvents(harness, conversationId, context): Promise<AgentEventStream>`,
+exported from the package root, is an experimental adapter that
+translates one conversation's committed publications into agent events shaped
+like the coding agent's `AgentSessionEvent`s. It owns no tracker or persistence,
+covers exactly one conversation (not its owned subtree), and emits an event only
+after the commit that makes it true. Its protocol may change without notice.
+
+```ts
+type AgentEvent =
+  | {
+      type: "snapshot";
+      entries: readonly EntryRecord[];
+      run?: { inputs: readonly SubmissionId[] };
+      /** Current generation attempt: its in-flight partial, retry backoff, or deferred poll. */
+      generation?: { attempt: number; message?: AssistantMessage; retry?: { at: number; error: string }; deferred?: { pollAt: number } };
+      tools: readonly ToolSlot[];
+      /** `pi.live.compactions` (section 8.2). */
+      compactions: readonly CompactionStatus[];
+      inbox: readonly { id: SubmissionId; mode: InboxItem["mode"] }[];
+      config: ConversationConfigState;
+      usage: UsageState;
+    }
+  | { type: "run_start"; inputs: readonly SubmissionId[] }
+  | { type: "run_end"; inputs: readonly SubmissionId[] }
+  | { type: "turn_start" }
+  | { type: "turn_end" }
+  | { type: "message_start"; message: Message }
+  | { type: "message_update"; usage: Usage; changes: readonly MessageChange[] }
+  | { type: "message_end"; entry: EntryRecord }
+  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: JsonObject }
+  | {
+      type: "tool_execution_update";
+      toolCallId: string;
+      toolName: string;
+      /** A front trim and then an append of the retained window, or its replacement. */
+      output?: { trimStart?: number; append?: string } | { set: string };
+      details?: JsonValue;
+      diagnostics?: readonly ToolDiagnostic[];
+    }
+  /** `entry` is absent when the tool task faulted or was orphaned. */
+  | { type: "tool_execution_end"; toolCallId: string; toolName: string; entry?: EntryRecord }
+  | { type: "inbox_update"; items: readonly { id: SubmissionId; mode: InboxItem["mode"] }[] }
+  | { type: "submission"; record: SubmissionRecord }
+  | { type: "auto_retry_start"; attempt: number; at: number; errorMessage: string }
+  | { type: "auto_retry_end"; attempt: number }
+  | { type: "deferred_poll"; pollAt: number }
+  | { type: "entry_appended"; entry: EntryRecord }
+  | { type: "config_changed"; config: ConversationConfigState }
+  | { type: "usage_changed"; usage: UsageState }
+  | { type: "task_failed"; taskId: TaskId; kind: string; message: string }
+  | { type: "compaction_start"; taskId: TaskId; reason: CompactionReason; blocking: boolean }
+  /** The task's receipt tells whether it produced a summary; the summary entry has its own events. */
+  | { type: "compaction_end"; taskId: TaskId; reason: CompactionReason };
+
+/** One change to the in-flight assistant message, relative to that message. */
+type MessageChange =
+  | { type: "text_start" | "thinking_start" | "toolcall_start"; contentIndex: number; block: AssistantMessage["content"][number] }
+  | { type: "text_delta" | "thinking_delta"; contentIndex: number; delta: string }
+  | { type: "toolcall_delta"; contentIndex: number; path: readonly (string | number)[]; delta: string }
+  | { type: "block"; contentIndex: number; block: AssistantMessage["content"][number] }
+  | { type: "message"; message: AssistantMessage };
+
+interface AgentEventStream {
+  /** The `snapshot` event at attachment. */
+  readonly snapshot: Extract<AgentEvent, { type: "snapshot" }>;
+  start(listener: (events: readonly AgentEvent[], context: Context) => Promise<void>): void;
+  stop(): Promise<WatchEnd>;
+  readonly closed: Promise<WatchEnd>;
+}
+```
+
+Every event is relative to the `snapshot` and the events before it, never to
+Pico's document layout. `snapshot` replaces everything a consumer holds; every
+other event applies on top of it. Attachment captures the snapshot and
+registers for later publications atomically on the Session line.
+
+Events derive from committed changes:
+
+- `run_start`/`run_end`: `pi.live.run` appears, is removed, or is replaced by a
+  successor run whose first input differs. Steers joining the current run and
+  handovers between its tasks are not run events. The inputs' outcomes are
+  `submission` events.
+- `turn_start`: a `pi.generation` task is created. `turn_end`: a generation's
+  outcome is committed, when it holds `completing` or becomes terminal,
+  whichever comes first, so a successor created at hold starts after it.
+- `message_start`: the first committed partial of an attempt, or, for a message
+  entry without a committed partial, the entry itself; `message_end` follows for
+  every entry with `model` messages. Generation commits a partial only once it has
+  content, and every built-in path that clears one appends its entry, so each
+  started message ends with its entry. Entries without messages are
+  `entry_appended`.
+- `message_update`: the Chord operations on the committed partial, translated:
+  an insertion into `content` starts blocks, an append to a block's `text` or
+  `thinking` is a delta, an append to a string inside a tool call's `arguments`
+  is a `toolcall_delta` with the path relative to `arguments`, any other change
+  inside a block sends that `block`, which already holds the batch's later
+  changes to it, and any other change to `content` sends the whole `message`.
+  Each update carries the partial's current `usage`, as the coding agent's JSON
+  mode does; a change of only `usage` sends no changes. Only deltas travel, so throttled
+  partials cause no write amplification on the wire.
+- `tool_execution_start`: a slot becomes `running`; `args` come from the tool
+  task's intent checkpoint in the same commit. A slot that becomes `done`
+  without running (a call not offered, invalid arguments, a block, a fault
+  before intent) gets only `tool_execution_end`. `tool_execution_update`: output
+  appends, front trims, and replacements of the slot's retained window, and the
+  slot's current `details` and `diagnostics` when they change; removed ones, as
+  when a safe replay restarts the tool, send `null` and `[]`.
+  `tool_execution_end`: the slot becomes `done`, with its `pi.tool-result`
+  entry, which carries the diagnostics, or without one after a fault or
+  orphan. An unfinished slot that disappears because its run ended ends with the
+  result entry appended in the same commit, as for the unstarted calls of an
+  aborted round, directly before its `message_start`, or without an entry.
+- `inbox_update`, `config_changed`, `usage_changed`: the document changed; a
+  retired one reads as its initial value, as in a snapshot.
+- `auto_retry_start`/`auto_retry_end`, `deferred_poll`: `pi.live.generation`
+  gains or drops `retry`, or gains `deferred` or moves its `pollAt`.
+- `task_failed`: a task of the conversation settles `faulted` or `orphaned`.
+- `compaction_start`/`compaction_end`: a status appears in or disappears from
+  `pi.live.compactions`. A retry backoff shows only in the snapshot's
+  `compactions`. A queued summary is placed later with its own
+  `message_start`/`message_end` and `submission` events.
+
+One commit produces one batch, in this order: `tool_execution_start`,
+`message_start` of a first partial, `message_update`, `tool_execution_update`,
+and retry/deferred events; then entries in append order with their
+`message_start`/`message_end` or `entry_appended`, where a tool result's
+`tool_execution_end` directly precedes its `message_start`, as in the coding
+agent; then the `tool_execution_end` of tools ending without an entry;
+then `compaction_end`, `task_failed`, `turn_end`, `run_end`; then `submission`
+events in ID order; then `inbox_update`, `config_changed`, and `usage_changed`;
+and last `compaction_start`, `run_start`, and `turn_start`. A stream buffers at most 100 undelivered
+batches; adding another replaces every undelivered batch with one `snapshot` of
+the newest committed state. The stream therefore converges but does not promise
+every transition; `Submission.wait()` reports exact outcomes. A reconnecting
+consumer attaches again and starts from its `snapshot`; nothing is replayed.
+Transport backpressure and disconnect policy belong to the consumer.
+
+Print mode awaits its own input `Submission` and prints its answer. A TUI
+renders `ConversationView`; events may drive transient animation.
 
 ## 10. Storage contract
 
@@ -2758,7 +3802,7 @@ type EntryQuery = {
 type TaskQuery = {
   readonly conversationId?: ConversationId;
   readonly kind?: string;
-  readonly status?: "pending" | "running" | "terminal";
+  readonly status?: "pending" | "running" | "waiting" | "completing" | "terminal";
   readonly abortRequested?: boolean;
   readonly background?: boolean;
 };
@@ -3008,6 +4052,52 @@ These are contracts, not invitations to add defensive machinery:
   with an active run. Raw entries appended by `Harness.commit()` or a custom
   task while a generation prepares its request can misplace its system prompt entries;
   use a write submission.
+- **Queued items after a failed run:** failure and task abort leave the inbox alone.
+  Queued follow-ups wait in `pi.inbox`, and their `wait()` does not settle, until
+  the next submission's boundary places them or the host withdraws them. A
+  compaction summary is such a submission: when a manual or background
+  compaction finishes in that idle conversation, its final boundary places the
+  waiting follow-ups and starts a run.
+- **Compaction spend:** every manual and background compaction pays for one
+  summarization request per attempt, also when its summary ends stale because a
+  later compaction cut further.
+- **Heads and edits during compaction:** a summary reflects the context when its
+  compaction selected the range. An application edit placed while it
+  summarizes, such as a write replacing entry 20, is lost when the summary cuts
+  past its target: the summary still describes the old entry 20, and the edit's
+  target leaves the range. An application head placed meanwhile, for example
+  one cutting at 85 to forget entries 10-84, is undone by a summary cutting at 90:
+  that summary still describes 10-84. Place such writes before compacting.
+- **Summary timestamps:** a queued summary's user message carries the time its
+  compaction finished, not its placement. Code that judges usage staleness by
+  message timestamps, such as pi-ai `estimateContextTokens()` over view
+  messages, can misjudge; the Harness estimate uses entry order (section 8.3).
+- **Raw head writes into the past:** a head written directly with `tx.appendEntry()`
+  that targets an entry before the conversation's active range changes model
+  context, but a mounted view keeps only the entries it already holds until the
+  mount is rebuilt. Use a write submission, whose stale check rejects it.
+- **Double-counted subagent spend:** a tool that runs an owned conversation must
+  not report that conversation's usage in its result; the child's `pi.usage`
+  already counts it, and subtree sums would count it twice.
+- **Owned work holds its owner:** a task that owns live ordinary work stays
+  `completing` until that work ends (section 5.5). Foreground work an extension
+  starts in a subagent's conversation holds the calling tool, and with it the
+  run; interrogating a subagent while its tool is completing extends the hold.
+  Esc or a host timeout ends it; work that should not hold its owner is created
+  conversation-owned and `background`.
+- **Work created by hooks:** hooks run inside the asking task's invocation, so
+  work they create owned by that task holds it. Work that must delay a task's
+  finish has to be created before the task commits its outcome; a listener
+  reacting to published events afterwards cannot extend it. A run task's owned
+  work must not write the transcript after the run was released.
+- **Compensation in abort handlers:** an abort handler cannot create owned
+  children, because its task is abort-marked. Compensate at the level
+  that did the effect, in that task's own abort handler, or inline, or through
+  background conversation-owned tasks awaited with `waitForTask()`; a
+  non-background one would be aborted by any cascade that reaches its
+  conversation.
+- **Hook memo names:** hooks share the asking task's memo namespace with the
+  task and other hooks. Prefix memo names.
 - **Long transactions:** an async commit callback holds the Session mutation
   line. Never await models, tools, processes, network calls, humans, a nested
   Session commit, or a Session waiter inside it. Use methods on the current `Tx`.