@arnilo/prism 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,3 +1,44 @@
+## [0.3.2] - 2026-08-29 (plan 050)
+
+### Added
+- **OKF adoption (`@arnilo/prism-wiki`)**: wiki-init/refresh/lint emit and validate
+  OKF v0.2 bundles (Karpathy prompt retained). See `docs/wiki.md`.
+- **DOCS-1 (Clay integration findings)**: three integrator contracts, in place on
+  the pages that own them — resume-aware workflow nodes (`ctx.resume` or silent
+  re-suspend) in `docs/workflows.md`; supervisor child factories return `Agent`
+  not `AgentSession` (`SupervisorError: child "<id>" factory must return an
+  Agent, got <type>`) plus durable-store nested approvals in `docs/supervisors.md`;
+  task-boundary `session.compact()` fails closed during an active run in
+  `docs/compaction-and-retry.md`. Each block links `examples/autonomous-coding-loop.ts`.
+- **FEATURE-2 (Clay integration findings)**: documented bounded iterate-until-done
+  host-loop pattern in `docs/workflows.md` — one `runWorkflow` per iteration,
+  iteration state in workflow inputs, explicit termination predicate and budgets,
+  typed `BudgetExhaustedError` (fail-closed, never a hang), `replayWorkflow` per
+  iteration run id. Seeded by `examples/autonomous-coding-loop.ts`. Plan 045 `loop`
+  node remains the future in-graph primitive; this intake ships the docs+example
+  minimum only.
+- **FEATURE-6 (Clay integration findings)**: composite `examples/autonomous-coding-loop.ts`
+  conformance reference — goal → roadmap → per-task supervisor children (per-child
+  models) → `runCodingGoalVerify`-style validation → observational-memory attach +
+  task-boundary compact + recall → human gate with simulated restart → host-side
+  bounded iterate-until-done with deterministic budget exhaustion. Mock providers
+  only; no credentials or network.
+- **FEATURE-3 (Clay integration findings)**: host-opt-in command driver hooks.
+  `CommandExecutionContext` gains an optional `drivers?: CommandDrivers`
+  (`startRun` / `startWorkflow` / `steer` — typed minimal handles returning
+  `AgentRunResult`-shaped results / workflow run id + status) so a contributed
+  command can act through host-injected capabilities instead of being
+  re-implemented host-side. The RPC session factory accepts `drivers` and
+  forwards them at the single command-execution site; absent drivers leave
+  the context shape unchanged (no key, no allocation). Drivers are
+  host-injected capabilities, never package-supplied.
+### Fixed
+- **FEATURE-1 (Clay integration findings)**: `resolveAgentDefinition` no longer
+  throws `Agent "<name>" has no model` when the declarative definition omits
+  `model` but `context.overrides.model` supplies one — the fallback is a
+  single `??` at `buildBaseConfig`, the `create()` path is unchanged, and a
+  definition with neither source still fails closed.
+
 ## [0.3.1] - 2026-08-29
 
 > Root + 28 changed packages move to 0.3.1 in the plan 039 changed-package cut; `@arnilo/prism-rag` moves 0.3.1 → 0.3.2; `@arnilo/prism-obscura` publishes new at 0.3.0. Distinct from the 2026-08-26 rag/memory/otel 0.3.1 patch below (independent Decision B tags).

package/dist/agent-definitions.js

@@ -20,7 +20,10 @@ export function resolveAgentDefinition(def, context) {
     return createAgent(applyConfigOverrides(baseConfig, context.overrides));
 }
 function buildBaseConfig(def, context) {
-    const model = resolveModel(def.name, def.model, context);
+    // Model precedence: explicit def.model wins; a definition without a model
+    // falls back to context.overrides.model (host-injected selection). Neither
+    // present still fails closed in resolveModel.
+    const model = resolveModel(def.name, def.model ?? context.overrides?.model, context);
     const tools = resolveTools(def.tools, context);
     const skills = resolveSkills(def.skills, tools, context);
     return {

package/dist/contracts-core/agent.d.ts

@@ -1,7 +1,7 @@
 /** Contracts-core agent family (0.2.5 plan 025 Task 1 split).
  * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
-import type { InputAssemblyLayout, RunLedger, ToolDefinition, ToolEffectStore, ToolRegistry } from "../contracts-protocol.js";
-import type { AgentRunStateOptions, AgentSession } from "../contracts-run-state.js";
+import type { InputAssemblyLayout, RunLedger, RunOptions, ToolDefinition, ToolEffectStore, ToolRegistry } from "../contracts-protocol.js";
+import type { AgentRunResult, AgentRunStateOptions, AgentSession } from "../contracts-run-state.js";
 import type { ContributionRegistries } from "../contributions.js";
 import type { MiddlewareRegistry } from "../middleware.js";
 import type { SecretRedactor } from "../redaction.js";
@@ -147,6 +147,27 @@ export interface CommandExecutionContext {
     readonly runId?: string;
     readonly signal?: AbortSignal;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Host-injected driver capabilities (host-opt-in; never package-supplied).
+     *  Absent in hosts that don't supply them — commands stay inert data there. */
+    readonly drivers?: CommandDrivers;
+}
+/** Minimal run reference returned by {@link CommandDrivers.startWorkflow}. */
+export interface CommandWorkflowRun {
+    readonly runId: string;
+    readonly status: string;
+}
+/** Host-injected capabilities a contributed command may act through when the
+ *  host opts in. Drivers are supplied by the host at context construction
+ *  (e.g. the RPC session factory), never by packages; core only types and
+ *  forwards them. `metadata.trust` labeling is unaffected. */
+export interface CommandDrivers {
+    /** Start a session run. */
+    startRun(input: string, options?: RunOptions): Promise<AgentRunResult> | AgentRunResult;
+    /** Start a run on a host-understood orchestration definition. Returns at
+     *  minimum the run id and status; richer host shapes pass through as-is. */
+    startWorkflow(definition: object, input: unknown, options?: Readonly<Record<string, unknown>>): Promise<CommandWorkflowRun>;
+    /** Steer an active run with additional input. */
+    steer(runId: string, input: string): Promise<void> | void;
 }
 export interface CommandResult {
     readonly name: string;

package/dist/index.d.ts

@@ -115,5 +115,5 @@ export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.3.1";
+export declare const version = "0.3.2";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -64,6 +64,6 @@ export { createToolParameterValidator, createToolRegistry, dispatchToolCall, fil
 export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.3.1";
+export const version = "0.3.2";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/rpc.d.ts

@@ -1,5 +1,5 @@
 import type { Readable, Writable } from "node:stream";
-import type { AgentSession, CommandDefinition, InstructionInjector } from "./contracts.js";
+import type { AgentSession, CommandDefinition, CommandDrivers, InstructionInjector } from "./contracts.js";
 import type { ContributionRegistry } from "./contributions.js";
 export type RpcCommandName = "prompt" | "steer" | "followUp" | "abort" | "state" | "messages" | "setModel" | "compact" | "switchSession" | "forkSession" | "cloneSession" | "checkout" | "command";
 export interface RpcRequest {
@@ -10,6 +10,9 @@ export interface RpcRequest {
 export interface RpcSessionFactory {
     createSession(id?: string): AgentSession;
     readonly commands?: readonly CommandDefinition[];
+    /** Host-opt-in driver capabilities forwarded to contributed commands on the
+     *  `command` execution context. Absent ⇒ context shape unchanged. */
+    readonly drivers?: CommandDrivers;
     /** Optional registry for resolving `instructionInjectors` names in `prompt`/`followUp`
      *  params (Phase 30). Names resolve fail-closed. */
     readonly instructionInjectors?: ContributionRegistry<InstructionInjector>;

package/dist/rpc.js

@@ -9,6 +9,7 @@ export async function runRpcServer(options) {
         sessions: new Map([[first.id, first]]),
         commands: new Map((options.commands ?? []).map((command) => [command.name, command])),
         createSession: options.createSession,
+        ...(options.drivers ? { drivers: options.drivers } : {}),
         ...(options.instructionInjectors ? { instructionInjectors: options.instructionInjectors } : {}),
     };
     const activeRuns = new Map();
@@ -181,7 +182,10 @@ async function handleRequest(request, state, stdout, activeRuns) {
             if (!command)
                 throw new Error(`Unknown command: ${name}`);
             const args = objectParam(request.params, "args") ?? {};
-            const result = await command.execute(args, { sessionId: state.current.id });
+            const result = await command.execute(args, 
+            // FEATURE-3 (plan 050 Task 5): host-opt-in drivers forwarded verbatim; the
+            // context carries no `drivers` key when the host supplied none.
+            state.drivers ? { sessionId: state.current.id, drivers: state.drivers } : { sessionId: state.current.id });
             write(stdout, { id: request.id, ok: true, result });
             break;
         }

package/docs/0.1.0-readiness.md

@@ -20,7 +20,7 @@ Historical release lines (0.0.16 floor → 0.0.27 Phase 10 ACP interop → 0.1.0
 keep their per-phase evidence in the pages above; this page records the 0.2.6
 snapshot (plan 026) with the 0.1.x tables below as the historical record.
 
-## Current line (0.3.1)
+## Current line (0.3.2)
 
 | Item | Status |
 |---|---|

package/docs/agent-definitions.md

@@ -27,7 +27,7 @@ Do not use the bundle loader to discover providers — provider/model packages s
 | --- | --- |
 | `name` | Required agent name. |
 | `description?` | Optional description. |
-| `model?` | `ModelConfig` object, or a `"<provider>/<model>"` string resolved through `registries.models`. |
+| `model?` | `ModelConfig` object, or a `"<provider>/<model>"` string resolved through `registries.models`. Optional at authoring time: when omitted, resolution falls back to `context.overrides.model` (host-injected selection); an explicit definition `model` drives registry resolution, and neither present fails closed with `Agent "<name>" has no model`. |
 | `tools?` | Tool names to activate from the active tool registry / `registries.tools`. Omitted means no active tools unless `activateAllCapabilities: true` is passed for migration. |
 | `skills?` | Skill names resolved via `resolveActiveSkills()`; omitted means no active skills unless `activateAllCapabilities: true` is passed for migration. `toolNames` enforcement applies at activation. |
 | `context?` | Context provider names from `registries.contextProviders`. |

package/docs/coding-agent-tools.md

@@ -417,6 +417,12 @@ Opt-in `ask_user_decision` for ambiguous, high-impact direction choices. Model m
 | Agent durable adapter | `validateAskUserDecisionAgentResume({ request, answer })` — same validation; **no** new `AgentRunInterruption` kinds in 0.0.11 |
 
 Custom-text caps match question defaults (2 KiB / hard 8 KiB). Options default max 6 (hard 16).
+`allowCustom` defaults to `false` on **both** paths when omitted — the tool
+path (`parseAllowCustom`) and the workflow suspend path
+(`toAskUserDecisionSuspendData`) normalize at accept time, so the persisted
+suspension always carries a boolean and survives JSON checkpoint round-trips;
+a non-boolean value throws `allowCustom must be a boolean` at accept time,
+never at resume time.
 
 ```ts
 import { createToolRegistry } from "@arnilo/prism";
@@ -440,7 +446,7 @@ return suspendAskUserDecision({
   question: "Ship sqlite or postgres?",
   options: [/* ≥2 with 3 pros + 3 cons each */],
   selectionMode: "single",
-  allowCustom: false,
+  // allowCustom optional — defaults to false (tool-path parity)
 });
 // resumeWorkflow(..., { validateResume: createAskUserDecisionResumeValidator() })
 ```

package/docs/compaction-and-retry.md

@@ -93,6 +93,8 @@ createDefaultRetryPolicy(options?: DefaultRetryPolicyOptions): RetryPolicy
 
 `session.compact(options?)` emits `compaction_started`, runs the strategy on the current branch, runs `middleware.run("compaction", { context, result })` when middleware is configured, appends one standard `kind: "compaction"` entry under the current leaf, emits `compaction_finished`, and returns the appended result. Manual compaction rejects while a run is active.
 
+> **Contract — compact at the task boundary.** `session.compact()` throws `Error("Agent session already has an active run")` while `run()`/`stream()` is in flight. Intended model: one `run()` per task, then compact. Do not design mid-run compaction. Auto-compaction (when `thresholdEntries` is set) already runs **before** provider input, not during the turn. Live demo: [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) (`compact` node after execute/validate/gate).
+
 Auto-compaction checks at most once per `run()`, after input/model-change entries are appended and before provider input assembly. It runs only when `AgentConfig.compaction` or `RunOptions.compaction` supplies `thresholdEntries`, and it is skipped by `RunOptions.compaction: false`.
 
 `rebuildSessionContext()` detects the latest compaction entry on a branch. Its returned `entries` still contains the raw full branch, while `messages` contains only messages after the compaction boundary plus `keepEntryIds`, and `summaries` contains the compaction summary plus later summary entries.
@@ -170,6 +172,7 @@ The default strategy does not call a provider. Hosts that need model-generated s
 - [Session stores and branching](session-stores-and-branching.md): branch entries, compaction entries, and `rebuildSessionContext()` behavior.
 - [Input and prompt assembly](input-and-prompt-assembly.md): compacted summaries become default summary messages for provider input.
 - [Agent/session runtime](agent-session-runtime.md): `session.compact()`, opt-in auto-compaction, `RunOptions.retry`, and `retry_scheduled` runtime behavior.
+- Example: [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) — task-boundary compact after each iteration.
 - [Middleware hooks](middleware-hooks.md): `compaction` and `retry` middleware payload timing.
 - [Contribution registries](contribution-registries.md): compaction strategy and retry policy contributions.
 - [Configuration and manifests](configuration-and-manifests.md): `compactionStrategy` and `retryPolicy` manifest contribution kinds.

package/docs/compaction-observational-memory.md

@@ -166,6 +166,52 @@ The runtime requires host-supplied `session`, an `appendEntry` callback bound to
 
 `createObservationalMemoryExtension()` registers only inert contributions. It does not start workers, compact sessions, read settings, resolve credentials, call providers, or execute tools/commands during setup.
 
+## Cross-session / delegation-tree recall (opt-in pattern)
+
+Default is per-session: `attach()` + `appendEntry` bind one store/branch, and `recallObservationalMemory(entries, id)` / `createRecallMemoryTool({ getEntries })` see only the entries the host passes for that session. Supervisor children therefore produce observations the parent cannot recall. That is acceptable for v1 — the parent transcript already contains `delegate()` results, so parent OM covers milestones. There is no package primitive for a shared workspace scope (a namespaced multi-tenant store key is out of scope).
+
+Hosts that need parent recall of child *source* work compose it themselves: wrap the shared `SessionStore.append` so eligible child messages (`isEligibleObservationSourceEntry`) are copied onto a workspace (or parent) session with a **new entry id** and that session's `sessionId`/`parentId`. Parent OM then observes those copies and mints **new** observation ids. Child OM, if attached, stays on the child session with its own ids.
+
+```ts
+import { createId, type SessionStore } from "@arnilo/prism";
+import { isEligibleObservationSourceEntry } from "@arnilo/prism-compaction-observational-memory";
+
+function funnelChildMessagesToWorkspace(store: SessionStore, workspaceSessionId: string): SessionStore {
+  return {
+    async append(entry, options) {
+      await store.append(entry, options);
+      if (entry.sessionId === workspaceSessionId) return;
+      if (!isEligibleObservationSourceEntry(entry)) return;
+      const leaf = (await store.list(workspaceSessionId)).at(-1);
+      await store.append({
+        ...entry,
+        id: createId("entry"),
+        sessionId: workspaceSessionId,
+        parentId: leaf?.id,
+      });
+    },
+    list: (sessionId) => store.list(sessionId),
+    get: (id) => store.get?.(id) ?? Promise.resolve(undefined),
+    searchSessions: (query) => store.searchSessions?.(query) ?? Promise.reject(new Error("searchSessions unsupported")),
+    readBranchPath: store.readBranchPath?.bind(store),
+  };
+}
+```
+
+Wire the wrapped store into both the parent session and each supervisor child factory (`createAgent({ store })`). Parent `attach({ appendEntry: (entry, options) => store.append(entry, options) })` and `createRecallMemoryTool({ getEntries: () => parentSession.entries() })` then see funneled child messages plus parent-minted observations. Recreate the parent session with the store `leafId` after a restart so the workspace branch is the one that received the copies. [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) shows parent OM attach/compact/recall in the supervisor loop; it records child outcomes on the parent session (same recall, no extra store wrap).
+
+Rules that keep exact-id recall unambiguous:
+
+- Recall always takes **one** branch (`session.entries()` / `getEntries(sessionId)`). Never concatenate parent + child lists into one `recallObservationalMemory()` call.
+- Copies mint a new `entry.id`. `createMemorySessionStore` rejects duplicate ids globally; JSONL/DB adapters do too.
+- Do **not** rewrite the child's OM `appendEntry` onto the workspace session. After each memory append the runtime checks the entry is visible at the **child** leaf and fails closed on a session/store mismatch. Funnel messages; let parent OM observe them.
+- Do **not** copy `om.*` custom entries across. Their `sourceEntryIds` point at the origin session and would dangle on the workspace branch.
+- Serialize funnel copies if concurrent children share the workspace tip (the sketch's `list().at(-1)` is not a lock).
+
+Cost: the workspace branch grows with every funneled child message; parent `compactAfterTokens` / observation-pool caps still apply but fire sooner. Keep the per-session default unless parent recall of child sources is required.
+
+Ownership: funnel only within the `OwnershipScope` already on the parent agent/store. Child factories receive that ownership from the supervisor; do not share a store across tenants or identities. Observations never leave the store the host scoped.
+
 ## Security and performance notes
 
 - Recall is exact-id only; there is no semantic search, vector store, or transcript browser.
@@ -187,6 +233,7 @@ The runtime requires host-supplied `session`, an `appendEntry` callback bound to
 - [Compaction and retry policies](compaction-and-retry.md): replaceable compaction strategy boundary.
 - [LLM compaction package](compaction-llm.md): existing optional compaction-package pattern.
 - [Session stores and branching](session-stores-and-branching.md): branch entries that observational memory reads and appends to.
+- [Supervisor delegation](supervisors.md): child sessions whose messages this page's opt-in funnel can copy onto a workspace branch.
 - [Extensions](extensions.md): inert registration pattern for optional package contributions.
 - [Tools](tools.md): host activation and dispatch for optional recall tool contributions.
 - [CLI/RPC](cli-rpc.md): command contributions through explicitly wired RPC hosts.

package/docs/extension-authoring.md

@@ -168,6 +168,48 @@ await agent.createSession().run("Use the Acme extension.", { activeSkills: ["acm
 - Middleware from `api.use()` runs only when the host passes `kernel.middleware` into runtime configuration.
 - Provider packages, provider request policies, system prompt contributions, instruction injectors, builders, strategies, commands, store factories, resource loaders, settings providers, and credential resolvers are all inert until host code selects or invokes them.
 
+### Host driver hooks (opt-in)
+
+A contributed command can act — start a session run, start a workflow, steer
+an active run — only when the **host** injects driver capabilities into the
+execution context. Drivers are never package-supplied: a command that wants
+them guards on `context.drivers` and degrades gracefully when the host
+supplies none. Commands stay inert data in hosts without drivers, and the
+context shape is unchanged (no `drivers` key at all).
+
+```ts
+// Host opt-in (e.g. RPC session factory):
+await runRpcServer({
+  stdin,
+  stdout,
+  createSession,
+  commands,
+  drivers: {
+    startRun: (input, options) => session.run(input, options),
+    startWorkflow: (workflow, input, options) => runWorkflow(workflow, input, options),
+    steer: (runId, input) => session.steer(runId, input),
+  },
+});
+
+// Contributed command (host-opt-in capability use):
+registerCommand({
+  name: "acme.start",
+  async execute(args, context) {
+    if (!context.drivers?.startWorkflow) {
+      return { name: "acme.start", error: { message: "host did not supply workflow drivers" } };
+    }
+    const run = await context.drivers.startWorkflow(workflowFor(args), args.input);
+    return { name: "acme.start", value: { runId: run.runId, status: run.status } };
+  },
+});
+```
+
+`CommandDrivers` is typed (`startRun` / `startWorkflow` / `steer`) and exported
+from the core contracts surface. Driver errors surface through the command's
+normal error path — commands map failures to `CommandResult.error`
+(`ErrorInfo`) or let the host error envelope carry them. Driver presence does
+not affect command `metadata.trust` labeling.
+
 ## Security and performance notes
 
 - Prism does not sandbox extension code. Hosts should load only trusted packages or run untrusted packages in their own sandbox/process before calling Prism APIs.

package/docs/index.md

@@ -34,9 +34,9 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Structured output](structured-output.md): the `Artifact*` seam plus provider-native `StructuredOutputOptions` / `structuredOutputMode` for capable models.
 
 ## Compaction/session memory
-- [Compaction and retry policies](compaction-and-retry.md): summarize branch history and retry transient provider failures with host-replaceable policies.
+- [Compaction and retry policies](compaction-and-retry.md): summarize branch history and retry transient provider failures with host-replaceable policies. Task-boundary `session.compact()` fails closed during an active run (`Error("Agent session already has an active run")`).
 - [LLM compaction package](compaction-llm.md): optional provider-backed strategy with finite summary/reserve/error caps, bounded redacted streaming retention, mandatory finite post-policy `model.parameters.maxTokens`, and `createCodingCompactionStrategy()` for coding handoff focus.
-- [Observational memory compaction package](compaction-observational-memory.md): optional source-backed memory with explicit `attach()` lifecycle — **Recent exact messages**, **Observation log**, **Reflections**, **Raw-source retrieval** (exact-id recall + cursor paging); dual coverage, **nested-only settings** (pre-0.0.19 flat keys and top-level `workerProvider`/`workerModel` aliases removed in 0.1.5; removed keys fail closed naming the nested replacement), branch-isolated `appendEntry`, secrets redaction, and inert import/extension.
+- [Observational memory compaction package](compaction-observational-memory.md): optional source-backed memory with explicit `attach()` lifecycle — **Recent exact messages**, **Observation log**, **Reflections**, **Raw-source retrieval** (exact-id recall + cursor paging); dual coverage, **nested-only settings** (pre-0.0.19 flat keys and top-level `workerProvider`/`workerModel` aliases removed in 0.1.5; removed keys fail closed naming the nested replacement), branch-isolated `appendEntry`, secrets redaction, inert import/extension, and an opt-in cross-session recall pattern (host-composed store funnel; default remains per-session).
 - [Working and semantic memory](working-and-semantic-memory.md): optional `@arnilo/prism-memory` working-memory store, semantic recall, finite Embedder/VectorStore contracts (incl. embedder identity + generation pointers), PostgreSQL/pgvector path (`createPostgresVectorStore` standalone, HNSW/fts DDL on the host knowledge database), consent lifecycle, identity-bound redacted export, and resumable bounded rebuild.
 - [Session stores](session-stores.md): `SessionStore` contract, `SessionAppendOptions`, `SessionAppendConflictError`, branch handles, `readBranchPath`, optional bounded `searchSessions` / `SessionIndex` (memory linear|unsupported), and dev-vs-production branch reads — start here for session persistence.
 - [Conversations](conversations.md): durable user-scoped conversation threads (create/list/continue/branch/archive/export/delete) on session + event-ledger seams, thread-bound reconnectable replay, frozen caps, atomic metadata via version/CAS (`metadata_conflict` on stale writes), and legal-hold-aware deletion.
@@ -71,7 +71,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [System prompts](system-prompts.md): compose explicit user/package/app/run system prompt layers, auto-load the standard `AGENTS.md` (workspace) / `SYSTEM.md` prompt files via the Node `loadSystemPromptFiles` loader (trust-gated for `AGENTS.md`), and append `SYSTEM.md` → per-agent `AGENT.md` body → repo `AGENTS.md` layers from a discovered agent bundle via `resolveAgentBundle`.
 - [Instruction injection](instruction-injection.md): register package injectors that layer redacted instructions/context blocks without granting tools, permissions, or resource escapes.
 - [Context and skills](context-and-skills.md): resolve ordered context providers; progressive skill catalog (`skillsDisclosure`, default catalog-only), `load_skill` on-demand bodies, fail-closed registry activation (`activateAllSkills` migration opt-in), `toolNames` fail closed before provider turns, priority-aware budget demotion, and optional `toolResultFold`.
-- [LLM Wiki](wiki.md): optional `@arnilo/prism-wiki` automated Karpathy-style knowledge compiler, incremental Merkle change tracking, on-device `qmd` hybrid search, and Context7-style clickable line navigation for codebases and PKM.
+- [LLM Wiki](wiki.md): optional `@arnilo/prism-wiki` automated Karpathy-style knowledge compiler that emits OKF v0.2 bundles (GoogleCloudPlatform/open-knowledge-format), incremental Merkle change tracking, on-device `qmd` hybrid search, and Context7-style clickable line navigation for codebases and PKM.
 - [Retrieval-augmented generation](rag.md): optional bounded source lifecycle, document adapters, ATX heading-stack chunk metadata, hybrid vector+lexical retrieval with RRF fusion, multi-scope retrieve (one embed / one RRF / one rerank), embedder-identity drift guards, content-hash skip, generation visibility, host reranking, ingestion status (plus an in-cluster TEI adapter), attributable citations, telemetry seam, and inert context injection.
 
 ## Tools
@@ -111,7 +111,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 
 ## Multi-agent and interoperability
 - [Antigravity delegated agent](antigravity-agent.md): optional `@arnilo/prism-antigravity-agent` adapter over the official host-owned Google Antigravity CLI (`agy`) — per-run ephemeral HTTP MCP server with Bearer auth, ephemeral workspace `.agents/` config backup/restore, NDJSON stream parsing, secret redaction, AG-UI timeline projection, multi-turn conversation continuation, and optional `createAntigravityDelegationTool` for supervisor delegation.
-- [Supervisor delegation](supervisors.md): optional explicit child allow-list, derived memory scopes, narrowing-only permissions, lifecycle hooks, nested delegation, cancellation, finite budgets, host-projected delegation telemetry, and separate A2A durable adapter boundary.
+- [Supervisor delegation](supervisors.md): optional explicit child allow-list, derived memory scopes, narrowing-only permissions, lifecycle hooks, nested delegation, cancellation, finite budgets, host-projected delegation telemetry, opt-in child event passthrough (`childEvents`), and separate A2A durable adapter boundary. Child factories return `Agent`, not `AgentSession` (`SupervisorError: child "<id>" factory must return an Agent, got <type>`); nested approvals need a stable config plus a durable store.
 - [A2A interoperability](a2a.md): A2A 1.0 JSON-RPC/HTTPS cards plus host-owned durable task get/list/cancel/subscribe, shared `AgentEventSource` task adapter, bounded rich parts/replay, principal-scoped push configs, exact-origin verified client, rich stream seam for explicit AG-UI fronting, and server-side `createAgUiA2AServer` exposure of a local AG-UI agent (0.0.26).
 - [Frontend interoperability (AG-UI and ACP)](ag-ui.md): optional `@arnilo/prism-ag-ui` full AG-UI 0.0.57 input/event/capability mapper, authorized Web handler/distributed source follow, opt-in A2UI painting middleware, explicit hardened MCP/MCP Apps/remote A2A adapters, a framework-free reference renderer subpath (`@arnilo/prism-ag-ui/renderer`, 0.0.26), and stable ACP sibling over shared redacted event and durable-approval seams; 0.0.14 adds reconnectable co-work events.
 - [ACP coding-host interop](acp.md): stable ACP v1 `createPrismAcpAgent()`/`createAcpEventMapper()` over `@agentclientprotocol/sdk@1.3.0` — capability advertisement is a pure function of host seams (sessions load/list/delete/resume/dirs, close always, prompt media/embedded, MCP http/sse), client fs/terminal adapters, modes and config options as host overlays, `CodingLifecycleEvent` mapping, four-outcome approvals with elicitation, and frozen caps (0.0.27); 0.1.1 adds ownership-scoped persistence guidance for host-persisted modes/config (plan 013 Task 5 — the agent never persists them); 0.1.6 adds the optional host-owned `AcpSessionStore` durability seam — live registry (modes/config/cwd/ownership) survives agent restart, restore is ownership-scoped and fail-closed (plan 018 Task 2). 0.2.6 adds durable run recovery (plan 026 Task 5): bounded `activeRun` refs on persisted sessions, restart re-resolution against `AgentRunLifecycle` (suspended → pending approval ids, terminal → terminal, unprovable in-flight → unknown, never a restarted prompt), and durable ownership/version/fence-checked cancellation that never replays tools; docs/migration.md records the additive-field decision and the 0.2.5 → 0.2.6 downgrade rules. 0.2.8 (plan 028) adds `session/load`/`session/resume` transcript replay (bounded, redacted chunks from the `sessions.transcript` seam), truthful `usage_update`, per-type `set_config_option` gates, explicit tool `kind` metadata, run-level error mapping, permission wire alignment, `agent_thought_chunk`, and the spawnable entrypoint; UNSTABLE-gated `plan_update`/`plan_removed` from coding plan lifecycle events (F5, client must advertise `ClientCapabilities.plan`); host-owned `session_info_update` titles and title pass-through in `session/list` (F6, `sessions.title` seam); opt-in `createCodingToolProjection()` for first-party edit/write diffs+locations (F7, deny-by-default unchanged); projected `toolResult` images as ACP content/image blocks (F8, `acpImageBytes` cap); host-owned slash commands as `available_commands_update` (F9, `acpCommandsPerUpdate` cap).
@@ -120,7 +120,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 
 ## CLI/RPC
 - [CLI/RPC](cli-rpc.md): Run print/json modes and LF-delimited RPC over the public AgentSession runtime, including mid-run `steer`, branch-handle results, fixed `forkSession`, and `checkout`. `prism init` scaffolds a tiny TypeScript project with one selected provider and an offline mock test; `prism providers add <name>` scaffolds an OpenAI-compatible provider package (manifest, provider, models, cache helpers, conformance test, docs stub).
-- [Workflows](workflows.md): optional `@arnilo/prism-workflows` typed bounded DAG orchestration plus linear durable sagas — explicit recursive definition revisions, exact-owner cancellation/active identity, finite hard limits, durable human suspend/resume, schedules/background execution, revocable proactive schedule capability tokens, nested workflows, replay, coordination, events, saga compensation/reconciliation, and optional RPC/Web bindings. Compose coding plans/checkpoints via workspace Markdown + `state.coding` without a second runtime. Active-run registry is non-durable, in-process only, with bounded sweep/cap cleanup. Interactive TUI (C-012) deferred.
+- [Workflows](workflows.md): optional `@arnilo/prism-workflows` typed bounded DAG orchestration plus linear durable sagas — explicit recursive definition revisions, exact-owner cancellation/active identity, finite hard limits, durable human suspend/resume (resume-aware nodes: branch on `ctx.resume` or the node re-suspends silently), schedules/background execution, revocable proactive schedule capability tokens, nested workflows, replay, coordination, events, saga compensation/reconciliation, documented bounded iterate-until-done host-loop pattern, and optional RPC/Web bindings. Compose coding plans/checkpoints via workspace Markdown + `state.coding` without a second runtime. Active-run registry is non-durable, in-process only, with bounded sweep/cap cleanup. Interactive TUI (C-012) deferred.
 - [Workflow orchestration primitives](workflow-orchestration-primitives.md): architecture inventory — workflow adapters consume core `CheckpointStore`, `LeaseStore`, and bounded `EventMultiplexer`; run control and optional RPC commands stay package-local.
 - [Workflow/TUI scope](workflow-tui-primitives.md): records why 0.0.5 ships workflow APIs/RPC control but no interactive terminal UI.
 
@@ -138,7 +138,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Compaction conformance](compaction-conformance.md): assert any `CompactionStrategy` returns a non-empty redacted summary and observes abort from `@arnilo/prism/testing/compaction-conformance`.
 - [Tool conformance](tool-conformance.md): assert the tool-dispatch blocked-reason matrix (unknown/denied/invalid/permission/validator) and success path from `@arnilo/prism/testing/tool-conformance`.
 - [Extension conformance](extension-conformance.md): assert an `Extension` setup runs, contributions stay inert, and setup errors are redacted or rethrown from `@arnilo/prism/testing/extension-conformance`.
-- `examples/`: compile-checked typed examples and runnable mock demos (SDK basics, provider registration, auth, tools, [`examples/ag-ui-server.ts`](../examples/ag-ui-server.ts), [`examples/ag-ui-a2ui.ts`](../examples/ag-ui-a2ui.ts), [`examples/ag-ui-mcp-apps.ts`](../examples/ag-ui-mcp-apps.ts), [`examples/enterprise-identity.ts`](../examples/enterprise-identity.ts), [`examples/enterprise-policy-audit.ts`](../examples/enterprise-policy-audit.ts), [`examples/enterprise-work-connectors.ts`](../examples/enterprise-work-connectors.ts), [`examples/enterprise-postgres-state.ts`](../examples/enterprise-postgres-state.ts), [`examples/conversation-durable-replay.ts`](../examples/conversation-durable-replay.ts), [`examples/artifact-review-delivery.ts`](../examples/artifact-review-delivery.ts), [`examples/server-deployment-seams.ts`](../examples/server-deployment-seams.ts), cache-aware prompt assembly, NeuralWatt agent run ([`examples/neuralwatt-agent-run.ts`](../examples/neuralwatt-agent-run.ts)), [`examples/provider-deepseek.ts`](../examples/provider-deepseek.ts), [`examples/provider-xai.ts`](../examples/provider-xai.ts), [`examples/provider-xai-oauth.ts`](../examples/provider-xai-oauth.ts), [`examples/provider-clinepass.ts`](../examples/provider-clinepass.ts), [`examples/impeccable.ts`](../examples/impeccable.ts), [`examples/coding-compaction.ts`](../examples/coding-compaction.ts), [`examples/acp-coding-host.ts`](../examples/acp-coding-host.ts), [`examples/caveman-ponytail.ts`](../examples/caveman-ponytail.ts), [`examples/graft-extension.ts`](../examples/graft-extension.ts), stores/branching, structured-output/artifact-loop, CLI, RPC, workflow orchestration).
+- `examples/`: compile-checked typed examples and runnable mock demos (SDK basics, provider registration, auth, tools, [`examples/ag-ui-server.ts`](../examples/ag-ui-server.ts), [`examples/ag-ui-a2ui.ts`](../examples/ag-ui-a2ui.ts), [`examples/ag-ui-mcp-apps.ts`](../examples/ag-ui-mcp-apps.ts), [`examples/enterprise-identity.ts`](../examples/enterprise-identity.ts), [`examples/enterprise-policy-audit.ts`](../examples/enterprise-policy-audit.ts), [`examples/enterprise-work-connectors.ts`](../examples/enterprise-work-connectors.ts), [`examples/enterprise-postgres-state.ts`](../examples/enterprise-postgres-state.ts), [`examples/conversation-durable-replay.ts`](../examples/conversation-durable-replay.ts), [`examples/artifact-review-delivery.ts`](../examples/artifact-review-delivery.ts), [`examples/server-deployment-seams.ts`](../examples/server-deployment-seams.ts), cache-aware prompt assembly, NeuralWatt agent run ([`examples/neuralwatt-agent-run.ts`](../examples/neuralwatt-agent-run.ts)), [`examples/provider-deepseek.ts`](../examples/provider-deepseek.ts), [`examples/provider-xai.ts`](../examples/provider-xai.ts), [`examples/provider-xai-oauth.ts`](../examples/provider-xai-oauth.ts), [`examples/provider-clinepass.ts`](../examples/provider-clinepass.ts), [`examples/impeccable.ts`](../examples/impeccable.ts), [`examples/coding-compaction.ts`](../examples/coding-compaction.ts), [`examples/acp-coding-host.ts`](../examples/acp-coding-host.ts), [`examples/caveman-ponytail.ts`](../examples/caveman-ponytail.ts), [`examples/graft-extension.ts`](../examples/graft-extension.ts), [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts), stores/branching, structured-output/artifact-loop, CLI, RPC, workflow orchestration).
 
 ## Third-party integrations
 - [Caveman behavior integration](caveman.md): optional `@arnilo/prism-caveman` — upstream Caveman skills/commands, `caveman-mode` injector, session `caveman-level` persistence, progressive catalog + `load_skill`; requires host `upstreamPath` and session attach callbacks; inert until `kernel.load`.
@@ -147,7 +147,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Impeccable behavior integration](impeccable.md): optional `@arnilo/prism-impeccable` — host `upstreamPath` to compiled Impeccable `SKILL.md`, skill + `/impeccable` → `load_skill`; no detector CLI, no live browser, not in code/sdk/all.
 
 ## Release and install
-- [Release and install](release-and-install.md): current **0.3.1** 60-package graph (root + 59 workspace packages) — plan 030 last-lockstep cut and independent `^0.3.0` publication; plan 029 **0.2.9** provider adoption (DeepSeek, xAI SuperGrok OAuth, ClinePass), `@arnilo/prism-impeccable`, Ponytail 4.9.0, Caveman v2.1 extras; then plan 028 **0.2.8** ACP adoption fixes; then plan 026 the fully-featured coding-agent-readiness cut: **host-selected PTY** (`pty: true` delegates only to the host `ptyBackend`, fails closed as unsupported when absent, bounded resize/TERM/attach caps), **indexed code search** (host-owned incremental index seam with explicit `indexed_literal`/`semantic` modes, literal remains the default, stale/failed/untrusted indexes fail closed `ERR_PRISM_INDEX_*`, results labeled `untrusted_index`), **coding workspaces** (`createCodingWorkspaceLifecycle`: durable CheckpointStore CAS records + LeaseStore fencing, locked worktrees, credential-free fingerprints, cleanup refusal matrix), **durable recovery** (process intent/ACP `activeRun` refs over Postgres/SQLite stores with attach-if-attested `recover()` and durable fence-checked cancellation, never fabricated exits), **patch review and diagnostics** (`createCodingPatchReviewManifest` + `assertCodingPatchAccepted` with pending/accepted/rejected/superseded bound to digest + revision + identity, opt-in LSP `syncDocument`/`diagnosticDelta`), and the **protected real coding journey** (packed consumer through real provider/Docker/Postgres/GitHub/Playwright/PTY services with retained evidence report; forge breadth GitLab/Bitbucket stays demand-gated); then plan 025 the maintainability-and-bounded-performance cut: **god-module splits** (the six remaining implementation monoliths — `src/contracts-core.ts` 1,719 L, `src/agent-session.ts` 2,049 L, `workflows/src/run.ts` 1,227 L, `server/src/handler.ts` 1,005 L, `coding-agent/src/repository.ts` 974 L, `ag-ui/src/acp/agent.ts` 836 L — split into cohesive family files behind preserved barrels, compat-preserving with zero breaking deltas, no `exports`-map subpath, `RuntimeAgentSession` kept as one class with a recorded reason), **persistence-mechanics dedup** (21 pure ownership/cursor/checkpoint/lifecycle/search helpers moved into the dependency-free `session-store-codecs`; postgres/sqlite adapters shrank 273 lines; SQL dialect stays per-adapter; no schema/shape change; cross-store conformance green), **bounded accumulation removed** (per-push `Buffer.concat` in language framing + tar parsing → chunk-array readers; framing ~100–200× faster at 4,000 chunks, tar linear at 8 MiB, caps fail-closed byte-identical; CLI `collectOutput` audited already linear), **dead-code cleanup internal-only** (62 candidates triaged: 2 internal removals + 60 allow-listed in `docs/_evidence/phase25-dead-exports-triage.md`), and **coverage close** (76 behavior-backed regressions; core 90.53/84.20/90.54 → 91.43/84.80/91.60); additive-only compat (105 helper exports), no migration; then plan 024 the package-documentation-and-compatibility-truth cut: **umbrella wording matches manifests** (`@arnilo/prism-providers` installs 11 of 14 provider adapters — Azure/Bedrock/Vertex are added separately by `prism-all`; `prism-all` installs 20 direct / 43 transitive packages and omits document-reader, OpenAPI tools, NATS, Caveman, Ponytail; membership unchanged in 0.2.x), **manifest-derived package truth** (`scripts/package-truth.mjs` → `scripts/package-truth.json` is the single source for counts, provider membership, and closures; docs literals regenerate from it and drift fails the gates), **peer-version policy Decision A** (exact `@arnilo/prism: 0.2.4` pins, atomic-upgrade rule, ERESOLVE refusal for partial upgrades, `^1.0.0` widening at 1.x), and **current-line truth** (`docs/0.1.0-readiness.md` at the 0.2.x line with 0.1.7 as the terminal 0.1.x baseline); no runtime contract delta (compat gate at 0.2.4: version literal only), no migration; then plan 023 the build-coverage-and-release-evidence-integrity cut: **build serialization** (dependency-free `scripts/with-build-lock.mjs` — one O_EXCL lockfile at `node_modules/.prism-build.lock` serializing every emit/test leaf so concurrent compilers can never expose a partial live `dist/`, stale-PID reclaim, env-overridable `PRISM_BUILD_LOCK_TIMEOUT_MS`, fail-closed; documented direct-`tsc` caveat), **corrected workspace coverage denominators** (package-local `--test-coverage-include=dist/**` so imported core `dist` no longer pollutes workspace rows — `mcp` 45.47→90.25, `rag` 19.70→94.82; evidence-based per-package thresholds in `scripts/coverage-thresholds.json` with `protectedException` for durable-leg packages shown separately, machine-readable `scripts/coverage-summary.json`), **machine-auditable release skip manifest** (`scripts/release-skip-manifest.mjs` → `scripts/release-evidence.json`: every surface recorded `pass`/`skip`/`blocked`/`protected` with reason and required env; the 33 protected/live skips named; a required surface without evidence records `blocked` and fails the release gate fail-closed — missing credentials/services can never convert into a green release), and **stabilized quality gates** (Biome 2.x `preset` config migration with zero lint diagnostics, the racy 150ms MCP bridge timing assert replaced by a deterministic barrier, load-sensitive guards carry documented `ponytail:` ceilings, machine-readable `lint-report.sarif` + `unused-report.json` retained by CI); no runtime contract delta (compat gate at 0.2.3: version literal only), no migration; then plan 022 the concurrent-state-and-durability-integrity cut: atomic model-budget reservation (`ModelRouterStateStore.reserveBudget`/`commitBudget`/`releaseBudget` with fencing tokens, `reservationTtlMs` expiry and unknown-usage reconciliation, rate/budget key-map caps with LRU eviction that never drops a held reservation), atomic conversation metadata (`SessionRecord.version` + `appendSession` `expectedVersion` CAS across Postgres/SQLite — create-only `0`, exact-version `N>0`, legacy last-write-wins when omitted; `SessionMetadataConflictError` `metadata_conflict` with versions only, HTTP 409; concurrent create/branch/archive single-statement with branch caps inside the CAS, archive wins, deleted rows never resurrect), single-consumer `EventMultiplexer` (`EventMultiplexerError` `ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER` instead of silent queue sharing), restart-stable NATS durable consumer identity (`prism_<hmac16>` with no random suffix — crash-resumed subscribe continues from the last ack, orphaned 0.2.1 consumers reclaimed on clean stop), and bounded non-durable active-run registries (sweep + fail-closed 512 cap `ERR_PRISM_WORKFLOW_RUN_REGISTRY_OVERFLOW`); new regression surface `scripts/phase22-security.test.mjs` (4 blockers + gate accounting over built public entrypoints) + packed plain-JS `security22.mjs` consumer + the `@arnilo/prism/testing/state-concurrency-conformance` harness (7 probes across memory/Postgres/SQLite/NATS legs, no timing-only sleeps) + the `scripts/phase22-conformance.test.mjs` gate; additive-only compat (new exports only, no removals); forward-only migrations 008 (`prism_sessions.version`) and 003 (`prism_model_router_budgets.reservations`); migration `0.2.1 → 0.2.2`; then plan 021 the provider-completion-and-outbound-trust-boundaries cut: strict stream completion is the shared OpenAI-compatible default (truncated streams fail `incomplete_delta`, explicit `strictCompletion: false` opt-out), bounded success bodies via `readBoundedResponseJson` on all discovery/quota/embeddings/upload/OAuth JSON endpoints (65,536-byte ceiling, depth/property/shape caps), DNS-pinned OIDC JWKS/OPA/content fetches through the core `pinnedFetch` primitive with 3xx redirects rejected outright (private/metadata answers fail closed `ssrf_denied`), shared bounded OAuth device/token polling (`pollDeviceCodeToken`) across provider-openai and credentials-node, and the four edge fixes (Azure/Vertex credential-once, Bedrock duplicate-case/repeated-query SigV4 canonicalization, OpenAI upload failed-DELETE retention, cache `__overflow__` tokens-only); public-entrypoint threat-suite `scripts/phase21-security.test.mjs` + packed plain-JS consumer; additive-only compat (MCP transport helpers re-exported from core, no removals); migration `0.2.0 → 0.2.1`; then plan 020 the fail-closed runtime-and-sandbox-security cut on the 0.2.x review-remediation line: durable-resume decision validation in core (`assertValidAgentRunResume` — unknown decisions/malformed batches fail closed with `ERR_PRISM_DECISION_*` before any state claim, checkpoint write, or tool execution; server parser remains defense in depth), isolated work-tool subprocess environments (`@arnilo/prism-work-tools` — fixed base allow-list + explicit env + forced HOME/telemetry + late-bound per-identity tokens, 64-name/64-KiB caps, absolute binary/configDir, linear output capture), and explicit sandbox capabilities (`@arnilo/prism-coding-security` — `SandboxAdapter.capabilities` with omission-is-false fail-closed resolution, `SandboxCodingComposition.capabilities` from verified wiring, `containmentClaim` deprecated as the conservative projection; Docker reports only verified controls, native reports filesystem/process/privilege `false`); public-entrypoint security conformance (`scripts/phase20-security.test.mjs`, wired into `security:threat-suites`), packed plain-JS consumer regressions, and the sandbox-browser workflow's fail-loud Docker/native capability evidence gate — 0.2.0 never ships while a blocker is skipped; migration and rollback notes in `docs/migration.md` `0.1.7 → 0.2.0`, store-compatible with 0.1.7 in both directions; 0.1.7 was the performance-and-DX patch — dependency-free `createCacheTelemetry()` per-provider/model cache hit/miss aggregator (bounded cardinality with `__overflow__`, token counters/rates only, host-activated), host-configurable `ModelRouterSelectionPolicy` on `createModelRouter` with the reference `createCostLatencySelection` (ModelCost rank then in-memory latency EMA, default ordered behavior byte-identical), `prism providers add <name>` OpenAI-compatible provider scaffold (manifest/provider/models/cache/conformance test/docs stub, npm-name + traversal + symlink-escape validation, placeholders only), and the async `AgUiProjection` verification closeout (plan 009 Task 15 evidence recorded, no new code); plan 017 the documented breaking cut — deprecated-option removal with `docs/migration.md` `0.1.4 → 0.1.5` section and reviewed compat-baseline regeneration via `--allow-break` then `--update-baseline`: the inert provider request knobs, `RunOptions.maxToolRounds`, observational-memory flat settings keys + top-level worker aliases, `ReadToolOptions.autoResizeImages`, `INIT_PROVIDERS`; all removals fail closed naming their replacement; plan 016 internal god-module split — `agents.ts`/`contracts.ts` reorganized behind barrel re-exports with a byte-identical public entry surface, measured tree-shaking improvement in `scripts/phase16-baseline.json`, and additive `@arnilo/prism-browser` Chrome DevTools Protocol capabilities — `browser_evaluate`/`browser_observe` and `block_urls`/`unblock_urls`/`throttle`/`emulate` act actions; plan 015 dead-code and deprecation hygiene on the frozen 0.1.x line — parameterized benchmark runner `scripts/benchmark.mjs` absorbing the per-version runners, archived review-coverage evidence in `docs/_evidence/`, non-blocking unused-code sweep `npm run sweep:unused`, opt-in checkpoint persistence for loaded-skill names and read-path sets; plan 014 Alibaba provider enrichment — embeddings, video input, verified compatible-mode surface decision table; plan 013 post-release hardening — build single-flight, MCP SSE relay test, combined coverage summary, canonical manifest-count narrative, ACP modes/config persistence guidance; Phase 12 release-candidate hardening; plan 012 — freeze manifest, compatibility matrix, upgrade matrix, packed-install e2e journeys, restart-recovery evidence, capacity envelopes, security policy), exact-peer/install/tarball rules, deterministic resumable publication and publish dry-run, frozen 0.1.x compatibility and support matrix (Node/PostgreSQL/platform/provider/protocol pins and unsupported combinations, machine-checked against `scripts/phase12-freeze-manifest.json`), protected PostgreSQL gate, pinned supply-chain gates, offline tests, the 0.0.15 provider/AI-SDK/RAG/memory protected live-canary matrix, and sandbox-browser Docker/Playwright gates. 0.2.6 (plan 026 Task 7) adds the protected coding journey: `scripts/phase26-coding-journey.test.mjs` runs a packed consumer through real provider calls, a digest-pinned Docker sandbox, the durable Postgres worktree lifecycle, provider-driven ACP edits with policy approval, named checks with `diagnosticDelta`, patch review over the server ArtifactService, cross-replica process recovery, durable cancellation, real GitHub PR push/reconcile/cleanup, host Playwright inspection, and the host PTY adapter (frozen profile) — the retained `scripts/phase26-coding-journey-report.json` gates release evidence (pass/blocked/protected, never a passing skip).
+- [Release and install](release-and-install.md): current **0.3.2** 60-package graph (root + 59 workspace packages) — plan 050 changed-package cut (clay-integration-findings fixes + OKF v0.2 wiki bundles) and independent `^0.3.0` publication; plan 030 last-lockstep cut and independent `^0.3.0` publication; plan 029 **0.2.9** provider adoption (DeepSeek, xAI SuperGrok OAuth, ClinePass), `@arnilo/prism-impeccable`, Ponytail 4.9.0, Caveman v2.1 extras; then plan 028 **0.2.8** ACP adoption fixes; then plan 026 the fully-featured coding-agent-readiness cut: **host-selected PTY** (`pty: true` delegates only to the host `ptyBackend`, fails closed as unsupported when absent, bounded resize/TERM/attach caps), **indexed code search** (host-owned incremental index seam with explicit `indexed_literal`/`semantic` modes, literal remains the default, stale/failed/untrusted indexes fail closed `ERR_PRISM_INDEX_*`, results labeled `untrusted_index`), **coding workspaces** (`createCodingWorkspaceLifecycle`: durable CheckpointStore CAS records + LeaseStore fencing, locked worktrees, credential-free fingerprints, cleanup refusal matrix), **durable recovery** (process intent/ACP `activeRun` refs over Postgres/SQLite stores with attach-if-attested `recover()` and durable fence-checked cancellation, never fabricated exits), **patch review and diagnostics** (`createCodingPatchReviewManifest` + `assertCodingPatchAccepted` with pending/accepted/rejected/superseded bound to digest + revision + identity, opt-in LSP `syncDocument`/`diagnosticDelta`), and the **protected real coding journey** (packed consumer through real provider/Docker/Postgres/GitHub/Playwright/PTY services with retained evidence report; forge breadth GitLab/Bitbucket stays demand-gated); then plan 025 the maintainability-and-bounded-performance cut: **god-module splits** (the six remaining implementation monoliths — `src/contracts-core.ts` 1,719 L, `src/agent-session.ts` 2,049 L, `workflows/src/run.ts` 1,227 L, `server/src/handler.ts` 1,005 L, `coding-agent/src/repository.ts` 974 L, `ag-ui/src/acp/agent.ts` 836 L — split into cohesive family files behind preserved barrels, compat-preserving with zero breaking deltas, no `exports`-map subpath, `RuntimeAgentSession` kept as one class with a recorded reason), **persistence-mechanics dedup** (21 pure ownership/cursor/checkpoint/lifecycle/search helpers moved into the dependency-free `session-store-codecs`; postgres/sqlite adapters shrank 273 lines; SQL dialect stays per-adapter; no schema/shape change; cross-store conformance green), **bounded accumulation removed** (per-push `Buffer.concat` in language framing + tar parsing → chunk-array readers; framing ~100–200× faster at 4,000 chunks, tar linear at 8 MiB, caps fail-closed byte-identical; CLI `collectOutput` audited already linear), **dead-code cleanup internal-only** (62 candidates triaged: 2 internal removals + 60 allow-listed in `docs/_evidence/phase25-dead-exports-triage.md`), and **coverage close** (76 behavior-backed regressions; core 90.53/84.20/90.54 → 91.43/84.80/91.60); additive-only compat (105 helper exports), no migration; then plan 024 the package-documentation-and-compatibility-truth cut: **umbrella wording matches manifests** (`@arnilo/prism-providers` installs 11 of 14 provider adapters — Azure/Bedrock/Vertex are added separately by `prism-all`; `prism-all` installs 20 direct / 43 transitive packages and omits document-reader, OpenAPI tools, NATS, Caveman, Ponytail; membership unchanged in 0.2.x), **manifest-derived package truth** (`scripts/package-truth.mjs` → `scripts/package-truth.json` is the single source for counts, provider membership, and closures; docs literals regenerate from it and drift fails the gates), **peer-version policy Decision A** (exact `@arnilo/prism: 0.2.4` pins, atomic-upgrade rule, ERESOLVE refusal for partial upgrades, `^1.0.0` widening at 1.x), and **current-line truth** (`docs/0.1.0-readiness.md` at the 0.2.x line with 0.1.7 as the terminal 0.1.x baseline); no runtime contract delta (compat gate at 0.2.4: version literal only), no migration; then plan 023 the build-coverage-and-release-evidence-integrity cut: **build serialization** (dependency-free `scripts/with-build-lock.mjs` — one O_EXCL lockfile at `node_modules/.prism-build.lock` serializing every emit/test leaf so concurrent compilers can never expose a partial live `dist/`, stale-PID reclaim, env-overridable `PRISM_BUILD_LOCK_TIMEOUT_MS`, fail-closed; documented direct-`tsc` caveat), **corrected workspace coverage denominators** (package-local `--test-coverage-include=dist/**` so imported core `dist` no longer pollutes workspace rows — `mcp` 45.47→90.25, `rag` 19.70→94.82; evidence-based per-package thresholds in `scripts/coverage-thresholds.json` with `protectedException` for durable-leg packages shown separately, machine-readable `scripts/coverage-summary.json`), **machine-auditable release skip manifest** (`scripts/release-skip-manifest.mjs` → `scripts/release-evidence.json`: every surface recorded `pass`/`skip`/`blocked`/`protected` with reason and required env; the 33 protected/live skips named; a required surface without evidence records `blocked` and fails the release gate fail-closed — missing credentials/services can never convert into a green release), and **stabilized quality gates** (Biome 2.x `preset` config migration with zero lint diagnostics, the racy 150ms MCP bridge timing assert replaced by a deterministic barrier, load-sensitive guards carry documented `ponytail:` ceilings, machine-readable `lint-report.sarif` + `unused-report.json` retained by CI); no runtime contract delta (compat gate at 0.2.3: version literal only), no migration; then plan 022 the concurrent-state-and-durability-integrity cut: atomic model-budget reservation (`ModelRouterStateStore.reserveBudget`/`commitBudget`/`releaseBudget` with fencing tokens, `reservationTtlMs` expiry and unknown-usage reconciliation, rate/budget key-map caps with LRU eviction that never drops a held reservation), atomic conversation metadata (`SessionRecord.version` + `appendSession` `expectedVersion` CAS across Postgres/SQLite — create-only `0`, exact-version `N>0`, legacy last-write-wins when omitted; `SessionMetadataConflictError` `metadata_conflict` with versions only, HTTP 409; concurrent create/branch/archive single-statement with branch caps inside the CAS, archive wins, deleted rows never resurrect), single-consumer `EventMultiplexer` (`EventMultiplexerError` `ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER` instead of silent queue sharing), restart-stable NATS durable consumer identity (`prism_<hmac16>` with no random suffix — crash-resumed subscribe continues from the last ack, orphaned 0.2.1 consumers reclaimed on clean stop), and bounded non-durable active-run registries (sweep + fail-closed 512 cap `ERR_PRISM_WORKFLOW_RUN_REGISTRY_OVERFLOW`); new regression surface `scripts/phase22-security.test.mjs` (4 blockers + gate accounting over built public entrypoints) + packed plain-JS `security22.mjs` consumer + the `@arnilo/prism/testing/state-concurrency-conformance` harness (7 probes across memory/Postgres/SQLite/NATS legs, no timing-only sleeps) + the `scripts/phase22-conformance.test.mjs` gate; additive-only compat (new exports only, no removals); forward-only migrations 008 (`prism_sessions.version`) and 003 (`prism_model_router_budgets.reservations`); migration `0.2.1 → 0.2.2`; then plan 021 the provider-completion-and-outbound-trust-boundaries cut: strict stream completion is the shared OpenAI-compatible default (truncated streams fail `incomplete_delta`, explicit `strictCompletion: false` opt-out), bounded success bodies via `readBoundedResponseJson` on all discovery/quota/embeddings/upload/OAuth JSON endpoints (65,536-byte ceiling, depth/property/shape caps), DNS-pinned OIDC JWKS/OPA/content fetches through the core `pinnedFetch` primitive with 3xx redirects rejected outright (private/metadata answers fail closed `ssrf_denied`), shared bounded OAuth device/token polling (`pollDeviceCodeToken`) across provider-openai and credentials-node, and the four edge fixes (Azure/Vertex credential-once, Bedrock duplicate-case/repeated-query SigV4 canonicalization, OpenAI upload failed-DELETE retention, cache `__overflow__` tokens-only); public-entrypoint threat-suite `scripts/phase21-security.test.mjs` + packed plain-JS consumer; additive-only compat (MCP transport helpers re-exported from core, no removals); migration `0.2.0 → 0.2.1`; then plan 020 the fail-closed runtime-and-sandbox-security cut on the 0.2.x review-remediation line: durable-resume decision validation in core (`assertValidAgentRunResume` — unknown decisions/malformed batches fail closed with `ERR_PRISM_DECISION_*` before any state claim, checkpoint write, or tool execution; server parser remains defense in depth), isolated work-tool subprocess environments (`@arnilo/prism-work-tools` — fixed base allow-list + explicit env + forced HOME/telemetry + late-bound per-identity tokens, 64-name/64-KiB caps, absolute binary/configDir, linear output capture), and explicit sandbox capabilities (`@arnilo/prism-coding-security` — `SandboxAdapter.capabilities` with omission-is-false fail-closed resolution, `SandboxCodingComposition.capabilities` from verified wiring, `containmentClaim` deprecated as the conservative projection; Docker reports only verified controls, native reports filesystem/process/privilege `false`); public-entrypoint security conformance (`scripts/phase20-security.test.mjs`, wired into `security:threat-suites`), packed plain-JS consumer regressions, and the sandbox-browser workflow's fail-loud Docker/native capability evidence gate — 0.2.0 never ships while a blocker is skipped; migration and rollback notes in `docs/migration.md` `0.1.7 → 0.2.0`, store-compatible with 0.1.7 in both directions; 0.1.7 was the performance-and-DX patch — dependency-free `createCacheTelemetry()` per-provider/model cache hit/miss aggregator (bounded cardinality with `__overflow__`, token counters/rates only, host-activated), host-configurable `ModelRouterSelectionPolicy` on `createModelRouter` with the reference `createCostLatencySelection` (ModelCost rank then in-memory latency EMA, default ordered behavior byte-identical), `prism providers add <name>` OpenAI-compatible provider scaffold (manifest/provider/models/cache/conformance test/docs stub, npm-name + traversal + symlink-escape validation, placeholders only), and the async `AgUiProjection` verification closeout (plan 009 Task 15 evidence recorded, no new code); plan 017 the documented breaking cut — deprecated-option removal with `docs/migration.md` `0.1.4 → 0.1.5` section and reviewed compat-baseline regeneration via `--allow-break` then `--update-baseline`: the inert provider request knobs, `RunOptions.maxToolRounds`, observational-memory flat settings keys + top-level worker aliases, `ReadToolOptions.autoResizeImages`, `INIT_PROVIDERS`; all removals fail closed naming their replacement; plan 016 internal god-module split — `agents.ts`/`contracts.ts` reorganized behind barrel re-exports with a byte-identical public entry surface, measured tree-shaking improvement in `scripts/phase16-baseline.json`, and additive `@arnilo/prism-browser` Chrome DevTools Protocol capabilities — `browser_evaluate`/`browser_observe` and `block_urls`/`unblock_urls`/`throttle`/`emulate` act actions; plan 015 dead-code and deprecation hygiene on the frozen 0.1.x line — parameterized benchmark runner `scripts/benchmark.mjs` absorbing the per-version runners, archived review-coverage evidence in `docs/_evidence/`, non-blocking unused-code sweep `npm run sweep:unused`, opt-in checkpoint persistence for loaded-skill names and read-path sets; plan 014 Alibaba provider enrichment — embeddings, video input, verified compatible-mode surface decision table; plan 013 post-release hardening — build single-flight, MCP SSE relay test, combined coverage summary, canonical manifest-count narrative, ACP modes/config persistence guidance; Phase 12 release-candidate hardening; plan 012 — freeze manifest, compatibility matrix, upgrade matrix, packed-install e2e journeys, restart-recovery evidence, capacity envelopes, security policy), exact-peer/install/tarball rules, deterministic resumable publication and publish dry-run, frozen 0.1.x compatibility and support matrix (Node/PostgreSQL/platform/provider/protocol pins and unsupported combinations, machine-checked against `scripts/phase12-freeze-manifest.json`), protected PostgreSQL gate, pinned supply-chain gates, offline tests, the 0.0.15 provider/AI-SDK/RAG/memory protected live-canary matrix, and sandbox-browser Docker/Playwright gates. 0.2.6 (plan 026 Task 7) adds the protected coding journey: `scripts/phase26-coding-journey.test.mjs` runs a packed consumer through real provider calls, a digest-pinned Docker sandbox, the durable Postgres worktree lifecycle, provider-driven ACP edits with policy approval, named checks with `diagnosticDelta`, patch review over the server ArtifactService, cross-replica process recovery, durable cancellation, real GitHub PR push/reconcile/cleanup, host Playwright inspection, and the host PTY adapter (frozen profile) — the retained `scripts/phase26-coding-journey-report.json` gates release evidence (pass/blocked/protected, never a passing skip).
 - [0.1.0 / 1.0 readiness gates](0.1.0-readiness.md): command-per-gate 1.0 readiness table — frozen API surface + compat gate, migration/docs tripwires, budget table, live-suite matrix, security matrix, current-line status (**0.2.5** current line; 0.1.7 terminal 0.1.x baseline), signed-publication/live-canary prerequisites for 1.0, and Phase 12 demand-evidence entry criteria.
 - [Review coverage archive](_evidence/): per-phase evidence freezes (plans 067–079, releases 0.0.4–0.0.16, 0.2.7 ERP evidence) — traceability matrices, provider validation, capability/primitive/limit matrices, benchmark budgets, and artifact-diet findings; tarball-excluded, kept in-repo for audit.
 

package/docs/public-contracts.md

@@ -10,7 +10,7 @@ Current contract groups:
 - Content/messages: `ContentBlock`, `TextContent`, `ImageContent`, `ThinkingContent`, `ToolCallDeltaContent`, `ToolCallContent`, `ToolResultContent`, `Message`
 - Providers/models/auth: `ModelConfig`, `ModelCapabilities`, `ModelLimits`, `ModelCost`, `ModelCacheCapabilities`, `PromptCacheKind`, `Usage`, `CacheRetention`, `PromptCacheMode`, `PromptCacheBreakpoint`, `PromptCacheHints`, `ProviderRequestOptions`, `ProviderRequest`, `ProviderEvent`, `AIProvider`, `ProviderPackage`, `ProviderPackageAPI`, `ProviderPackageDocs`, `AuthMethod`, `ApiKeyAuthMethod`, `OAuthAuthMethod`, `CustomAuthMethod`, `OAuthLoginCallbacks`, `OAuthCredentials`, `OAuthProvider`, `CredentialResolverSource`, `OAuthCredentialStore`, `ProviderRequestPolicy`, `ProviderRequestPolicyContext`, `ProviderRequestPolicyResult`, `SystemPromptContribution`, `SystemPromptMode`, `SystemPromptSource`, `SystemPromptConfig`
 - Agents/sessions: `AgentConfig`, `AgentDefinition`, `Agent`, `AgentSessionConfig`, `AgentSessionForkOptions`, `AgentSessionCloneOptions`, `AgentSession`, `SubscribeOptions`, `SubscriberOverflowPolicy`, `RunOptions`, `AgentEvent`
-- Tools/commands: `ToolDefinition`, `ToolRegistry`, `ToolExecutionContext`, `ToolResult`, `CommandDefinition`, `CommandExecutionContext`, `CommandResult`
+- Tools/commands: `ToolDefinition`, `ToolRegistry`, `ToolExecutionContext`, `ToolResult`, `CommandDefinition`, `CommandExecutionContext`, `CommandDrivers`, `CommandWorkflowRun`, `CommandResult`
 - Input/prompt/context/skills: `InputBuilder`, `InputBuildContext`, `AgentInput`, `DefaultInputBuilder`, `DefaultInputBuildContext`, `InputAttachment`, `PromptInstruction`, `PromptBuilder`, `PromptBuildRequest`, `ContextBlock`, `ContextProvider`, `ContextResolutionContext`, `Skill`, `SkillRegistry`
 - Extensions/middleware: `ExtensionLifecycleEventName`, `ExtensionEvent`, `Extension`, `ExtensionAPI`, `MiddlewareHookName`, `Middleware`, `MiddlewareNext`, `MiddlewareRegistry`
 - Configuration/manifests: `ConfigProvider`, `ConfigLayer`, `ConfigLoadContext`, `PrismManifest`, `ManifestContributionDeclaration`, `ManifestResourceDeclaration`, `ManifestContributionKind`

package/docs/release-and-install.md

@@ -2,9 +2,9 @@
 
 ## What it does
 
-Prism's current **0.3.1** line has **60 publishable manifests**: the root `@arnilo/prism` core package plus **59 workspace packages** — 17 provider adapters, 10 `prism-*` family/profile packages, and 32 capability packages. (Generated by `node scripts/package-truth.mjs` → `scripts/package-truth.json` — the manifest-derived single source for counts, provider membership, umbrella closures, and profile closures.) The last lockstep cut was 0.3.0; Decision B now publishes changed packages independently inside `^0.3.0` — the plan 039 changed-package cut moved root `@arnilo/prism` and every plan-035+ changed package to **0.3.1** (obscura joined at its reviewed initial 0.3.0), and independent publication continues inside `^0.3.0` ranges (which satisfy 0.3.1). This page describes how they are packed, what each tarball contains, how to install them, the required `@arnilo/prism` peer range, the release workflow, and the offline test budget. The measurable 1.0 readiness gates (command-per-gate) live in [`0.1.0-readiness.md`](./0.1.0-readiness.md).
+Prism's current **0.3.2** line has **60 publishable manifests**: the root `@arnilo/prism` core package plus **59 workspace packages** — 17 provider adapters, 10 `prism-*` family/profile packages, and 32 capability packages. (Generated by `node scripts/package-truth.mjs` → `scripts/package-truth.json` — the manifest-derived single source for counts, provider membership, umbrella closures, and profile closures.) The last lockstep cut was 0.3.0; Decision B now publishes changed packages independently inside `^0.3.0` — the plan 039 changed-package cut moved root `@arnilo/prism` and every plan-035+ changed package to **0.3.1** (obscura joined at its reviewed initial 0.3.0), and the plan 050 changed-package cut moved root plus four changed packages to **0.3.2**; independent publication continues inside `^0.3.0` ranges (which satisfy 0.3.1 and 0.3.2). This page describes how they are packed, what each tarball contains, how to install them, the required `@arnilo/prism` peer range, the release workflow, and the offline test budget. The measurable 1.0 readiness gates (command-per-gate) live in [`0.1.0-readiness.md`](./0.1.0-readiness.md).
 
-Core `@arnilo/prism` ships runtime, CLI, templates, and docs. Every code package has a required `@arnilo/prism` peer inside the Decision B window — packages republishing in the plan 039 cut carry `^0.3.1`; unchanged packages keep their `^0.3.0` peer (both satisfy `@arnilo/prism@0.3.1`); profiles are pure manifests. The plan 039 republished set declares the required `@arnilo/prism@^0.3.1` peer; unchanged packages keep `^0.3.0`. Installation activates no provider, listener, database, browser, credential, or tool capability.
+Core `@arnilo/prism` ships runtime, CLI, templates, and docs. Every code package has a required `@arnilo/prism` peer inside the Decision B window — packages republishing in the plan 050 cut carry `^0.3.2`; the plan 039 set keeps `^0.3.1`; unchanged packages keep their `^0.3.0` peer (all satisfy `@arnilo/prism@0.3.2`); profiles are pure manifests. The plan 050 republished set declares the required `@arnilo/prism@^0.3.2` peer; unchanged packages keep their prior window. Installation activates no provider, listener, database, browser, credential, or tool capability.
 
 Current **58** publishable manifests (root + 57 workspace packages):
 
@@ -94,7 +94,7 @@ A packed tarball contains only public compiled output and release files:
 - Code packages ship `README.md`, `LICENSE`, and `CHANGELOG.md`; family/profile packages ship `README.md` and `CHANGELOG.md`.
 - The core tarball additionally ships the full `docs/` directory (the docs hub) and `templates/init/` used by `prism init`.
 - `dist/cli.js` and the `bin` link in core.
-- **Tarball filenames.** npm strips the `@scope/` prefix, so the core package `@arnilo/prism` produces a tarball named `arnilo-prism-0.3.1.tgz`; first-party packages produce `arnilo-prism-provider-<name>-0.3.1.tgz` / `arnilo-prism-compaction-<name>-0.3.1.tgz` / `arnilo-prism-coding-agent-0.3.1.tgz`; family/profile packages produce `arnilo-prism-{providers,compaction,base,code,sdk,all}-0.3.1.tgz`; independent Decision B tags (e.g. `@arnilo/prism-obscura@0.3.0`, the 0.3.1 RAG engine patch) carry their own package version. Later independent package tags carry their own package version. The CLI bin name `prism` is unaffected by the package name (`npx prism` still works; npm allows the bin field to differ from the package name).
+- **Tarball filenames.** npm strips the `@scope/` prefix, so the core package `@arnilo/prism` produces a tarball named `arnilo-prism-0.3.2.tgz`; first-party packages produce `arnilo-prism-provider-<name>-0.3.1.tgz` / `arnilo-prism-compaction-<name>-0.3.1.tgz` / `arnilo-prism-coding-agent-0.3.2.tgz`; family/profile packages produce `arnilo-prism-{providers,compaction,base,code,sdk,all}-0.3.1.tgz`; independent Decision B tags (e.g. `@arnilo/prism-obscura@0.3.0`, the 0.3.1 RAG engine patch) carry their own package version. Later independent package tags carry their own package version. The CLI bin name `prism` is unaffected by the package name (`npx prism` still works; npm allows the bin field to differ from the package name).
 
 Excluded from every tarball by `files` negation:
 
@@ -402,6 +402,24 @@ node scripts/release.mjs publish --independent --baseline c600eaa18f65b56764ec2f
 
 **Compat.** Baselines regenerated (`--update-baseline`): version literal, obscura `connectObscuraCdp`/`createObscuraWebTools` types, plan 036/037 additive exports. **Rollback:** restore the pre-cut manifests/tags. Publication remains the operator handoff — this task does not publish.
 
+### 0.3.2 changed-package cut (plan 050 Task 12)
+
+**Decision: GO when the operator prerequisites below are recorded.** The plan 050 cut covers the clay-integration-findings remediation and the OKF wiki adoption: baseline `edb4fcf` (the parent of the plan 050 implementation work); five packages publish in dependency order — root `@arnilo/prism` (FEATURE-1 agent-definition model override fallback, FEATURE-3 command driver hooks, FEATURE-2/6 docs+example, DOCS-1 contracts), `@arnilo/prism-coding-agent` (BUG-1 `allowCustom` default + optional `toolCallId`), `@arnilo/prism-supervisor` (BUG-2 child-factory `Agent` guard, FEATURE-4 opt-in child event passthrough), `@arnilo/prism-wiki` (OKF v0.2 bundle emission, 0.0.2 → 0.0.3), and `@arnilo/prism-acp-agent` (sqlite `:memory:` pass-through fix, 0.0.x-style patch 0.3.1 → 0.3.2). Every unchanged package stays byte-identical; docs-only packages (`@arnilo/prism-workflows`, `@arnilo/prism-compaction-observational-memory`) do not bump. Republished packages carry `^0.3.2` root peers; unchanged packages keep their window peers. Docs-only change on the root: none of the deltas are breaking (additive fields and fail-closed guards), compat additive-only, no migration.
+
+```bash
+node scripts/release.mjs changed --baseline edb4fcf   # 5 packages
+# per-package: node scripts/release.mjs bump --package <name> --type patch (regenerates the lockfile)
+npm run sdk:ready   # blocked only by the protected PRISM_TEST_POSTGRES_URL row (pre-existing)
+node scripts/release.mjs check --independent --baseline edb4fcf --allow-dirty --allow-untagged
+node scripts/release.mjs publish --independent --baseline edb4fcf --dry-run
+# publish tags (operator handoff; not this task): push the 5 annotated
+# `<name>@<version>` package tags (e.g. @arnilo/prism@0.3.2,
+# @arnilo/prism-wiki@0.0.3) — release.yml's publish job runs deterministic
+# release:publish in dependency order with OIDC provenance.
+```
+
+**Rollback:** restore the pre-cut manifests/tags. No persisted shape changed (BUG-1/BUG-2 guards and the acp-agent `:memory:` fix are fail-closed tightenings). Publication remains the operator handoff — this task does not publish.
+
 ### 0.2.9 publish handoff (plan 029 Task 10)
 
 **Decision: GO when the operator prerequisites below are recorded.** Release **0.2.9** (plan 029) is the provider-adoption and behavior-packages cut on the 0.2.x review-remediation line. API surface **additive-only** (plain reviewed compat gate at 0.2.9: expected deltas are the version literal plus the new provider/OAuth/impeccable exports and the form-urlencoded `pollDeviceCodeToken` options; zero removals; baselines regenerated with `--update-baseline`, no `--allow-break`). Ships `@arnilo/prism-provider-deepseek`, `@arnilo/prism-provider-xai` (API key + SuperGrok RFC 8628), `@arnilo/prism-provider-clinepass`, and `@arnilo/prism-impeccable`. Ponytail peer `^4.9.0` (bare `/ponytail` reports status). Caveman registers extra `SKILL.md`. SuperGrok is host-invoked; Cline WorkOS, DeepSeek `/anthropic`, grok-cli file scan, harness/Cordis/Muse, Caveman 2 engine, and Impeccable live detector stay out. Release graph is **55** publishable manifests at exact **0.2.9** (root + 54 workspace). Store compatibility with 0.2.8: **compatible, no migration**.
@@ -913,7 +931,7 @@ Audit fixes, dependency updates, and security patches land only for the supporte
 
 ## Extension and configuration notes
 
-- **Required `@arnilo/prism` peer.** Every first-party code package declares a non-optional **caret** `@arnilo/prism@^0.3.1` peer (plan 039 republished set; unchanged packages keep the prior `^0.3.0` window peer — both satisfy the root) (`peerDependenciesMeta` must not mark `@arnilo/prism` optional; other peers such as `playwright-core` may be optional). **Peer-version policy (plan 030, Decision B — independent packages):** internal ranges stay inside the 0.x `^0.3.0` window, so a package may patch independently while consumers remain on a compatible 0.3.x line. A package outside that window (for example `0.4.0`) is refused by the release gate until the next coordinated peer bump. Inside the workspace each package also declares `"@arnilo/prism": "file:../.."` in `devDependencies` so `npm install` resolves the peer locally; that devDependency is stripped from consumer installs and is not a runtime dependency.
+- **Required `@arnilo/prism` peer.** Every first-party code package declares a non-optional **caret** `@arnilo/prism@^0.3.2` peer (plan 050 republished set; the plan 039 set keeps `^0.3.1` and unchanged packages keep the prior `^0.3.0` window peer — all satisfy the root) (`peerDependenciesMeta` must not mark `@arnilo/prism` optional; other peers such as `playwright-core` may be optional). **Peer-version policy (plan 030, Decision B — independent packages):** internal ranges stay inside the 0.x `^0.3.0` window, so a package may patch independently while consumers remain on a compatible 0.3.x line. A package outside that window (for example `0.4.0`) is refused by the release gate until the next coordinated peer bump. Inside the workspace each package also declares `"@arnilo/prism": "file:../.."` in `devDependencies` so `npm install` resolves the peer locally; that devDependency is stripped from consumer installs and is not a runtime dependency.
 - **Public access.** All 56 manifests (root + 55 workspace packages: 49 code packages + 6 pure-manifest family/profile packages — the 10 `prism-*` family/profile set is the 6 pure-manifest profiles plus the 4 code packages `prism-caveman`, `prism-impeccable`, `prism-openapi-tools`, `prism-ponytail`) declare `"publishConfig": { "access": "public" }`; the publisher also passes `--access public` explicitly because scoped packages otherwise default to restricted on first publish.
 - **Shipped vs repository docs.** The npm tarball ships `docs/` pages linked from `docs/index.md` (public API, security, migration, providers, install). It excludes `docs/_evidence/` (per-phase evidence freezes, including `release-0.2.7-evidence.md`), `docs/release-*-evidence.md`, and `docs/api-page-template.md`. Those files remain in git for audit. `dist/__tests__` and `*.map` stay excluded.
 - **Map retention knob.** Source maps are emitted locally but stripped from tarballs by `!dist/**/*.map`. Removing that `files` negation ships maps in releases (larger tarballs, better consumer stack traces).

package/docs/supervisors.md

@@ -17,12 +17,16 @@ Use a supervisor when a host or agent must choose a child dynamically. Use `@arn
 | `delegate({ childId, input, threadId?, limits?, signal? })` | Invokes one allow-listed child. Input is text and byte-bounded. |
 | `hooks.before` | May reject, modify redacted input, or narrow limits/policy. |
 | `hooks.after` | Observes redacted terminal summary; failures cannot alter settled result. |
-| `limits` | Depth 4/16, active children 4/32, input 64 KiB/1 MiB, steps 8/64, tools 32/256, tokens 20k/1m, timeout 60s/30m, event queue 128/4096 default/hard. Over-cap `delegate()` throws `SupervisorLimitError` before incrementing `activeChildren`. Hook rejection and timeout decrement the count exactly once (no leaked timers). |
+| `limits` | Depth 4/16, active children 4/32, input 64 KiB/1 MiB, steps 8/64, tools 32/256, tokens 20k/1m, timeout 60s/30m, event queue 128/4096, child events/delegation 256/4096, child-event bytes 32 KiB/256 KiB default/hard. Over-cap `delegate()` throws `SupervisorLimitError` before incrementing `activeChildren`. Hook rejection and timeout decrement the count exactly once (no leaked timers). |
 
 ## Outputs / response / events
 
 `delegate()` returns the child's `AgentRunResult` or throws its `AgentRunError`/a supervisor denial or limit error. `subscribe()` emits bounded `delegation_started`, `delegation_finished`, `delegation_rejected`, and `delegation_error` metadata events. Graceful close drains already-queued terminal events before the iterator completes (same core multiplexer contract). Hosts may project those events through observability `handleDelegation()` using the parent Prism run ID; no OpenTelemetry dependency enters this package.
 
+### Child event passthrough (opt-in)
+
+`createSupervisor({ childEvents: true })` projects a redacted, size-capped **milestone** subset of child `AgentEvent`s onto the same stream as `delegation_child_event` (tagged `childId`, `delegationId`, `depth`). v1 covers run start/finish/`suspended`/`denied` and tool-execution started/finished/error/blocked — not per-token `message_delta`. Default off: the stream is byte-identical to today (no subscribe, no allocation). Caps: `limits.maxChildEventsPerDelegation` (256/4096) and `limits.maxChildEventBytes` (32 KiB/256 KiB); exceeding either drops further child events and emits one `delegation_child_events_capped` marker (never throws). Events pass through the supervisor `redactor` before emission. Children never receive supervisor internals or store/subscription access. Resume-path rebuilds (`resumeNestedRun`) do not currently project child events — live passthrough is the initial `delegate()` session only.
+
 ## Request/response example
 
 ```json
@@ -50,6 +54,8 @@ const supervisor = createSupervisor({
 const result = await supervisor.delegate({ childId: "research", input: "Check sources" });
 ```
 
+> **Contract — child factories return `Agent`.** `createAgent` must return an `Agent`, not an `AgentSession` (or a plain object). Wrong type throws `SupervisorError: child "<id>" factory must return an Agent, got <type>` on both initial `delegate()` and nested resume. Nested approvals also need a **stable config** plus a **durable (or rebuild-stable) store** — calling `createSession()` inside the factory and returning that session loses the child's checkpointed leaf. Live demo: [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) (`childAgent` returns `createAgent(...)`).
+
 ## Durable child approvals
 
 With `checkpoints` + `definitionRevision`, every child run is durable with `interruptBeforeTool: true`. A child that suspends on pending decisions throws `AgentDelegationSuspendedError` out of `delegate()`; when the delegation runs inside a root agent's tool, core converts it into a root suspension whose `interruption.pendingDecisions` carry hashed root-visible approval ids (`sub_<sha256(runId:childApprovalId)>`) and `attribution.path` (redacted child ids, root first, at most 8 deep). Root decisions route back through the same CAS rules: pass `supervisor.resumeNestedRun` as `resumeNestedRun` in the root run's `runState` and in every `resumeAgentRun` options object. The supervisor rebuilds the child from a bounded delegation mapping stored in the same checkpoint store (child id, delegation/thread ids, redacted input, version), re-runs the `before` hook so its narrowing applies to the resumed run (hooks must be idempotent), and re-attributes re-suspensions recursively, so grandchild decisions surface with the full path. A delegating child's own `interruptBeforeTool` also gates its delegate tool, so hosts approve delegation and the child's own side effects as separate stages. Root `*_for_run` stickies record the attribution path and only match the same delegation path; child stickies live on the child run and expire with it. A root approval never widens the child: the child's narrowed permission re-runs at dispatch. Unknown or foreign nested run ids fail closed with one non-enumerating error. Child factories must return stable configs and a durable (or rebuild-stable) session store for resume to work.
@@ -75,6 +81,7 @@ Supervisors propagate parent `identity` and `effectStore` to every child agent/r
 - [Agent identity](agent-identity.md): host-verified identity and narrow delegation.
 - [A2A interoperability](a2a.md): separate remote protocol boundary. `A2ATaskLifecycle` adapts host durable agent/workflow state directly; it does not route A2A execution through local supervisor child planning.
 - [Workflows](workflows.md): preferred deterministic orchestration.
+- Example: [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) — per-child models, factory returns `Agent`.
 - [Working and semantic memory](working-and-semantic-memory.md): child scope construction.
 - [Host security](host-security.md): permission and credential boundaries.
 - [Obscura browser engine](obscura.md): optional binary-backed generic tools for child agents.

package/docs/wiki.md

@@ -19,7 +19,7 @@ The Karpathy LLM Wiki pattern is structured into 3 distinct tiers:
 
 1. **Raw Sources (Immutable)**: Source code files, design docs, transcripts, journals, and Markdown notes. Raw sources are strictly read-only and never mutated.
 2. **Compiled Wiki (`.wiki/`)**: Persistent, cross-linked Markdown documents containing synthesized architecture models, entity descriptions, decision records, and line-anchored claims.
-3. **Schema & Protocols (`SCHEMA.md`)**: Operational guidelines governing entity categorization, link formatting (`[[wikilink]]`), citation rules (`file:///path#Lxx-Lyy`), catalog indexing (`index.md`), and chronological change logging (`log.md`).
+3. **Schema & Protocols (`SCHEMA.md`)**: Operational guidelines governing OKF v0.2 emission, entity categorization, citation rules (`file:///path#Lxx-Lyy`), catalog indexing (`index.md`), and chronological change logging (`log.md`).
 
 ## Inputs / request
 
@@ -44,7 +44,7 @@ The Karpathy LLM Wiki pattern is structured into 3 distinct tiers:
 
 - `/wiki-init`: Scaffolds `.wiki/`, instantiates `SCHEMA.md`, `index.md`, and `log.md`, deploys skills, and adds the `qmd` collection.
 - `/wiki-refresh`: Detects modified source files via SHA-256 Merkle diffing, compiles updates to affected entity pages, reconciles contradictions in `log.md`, and runs `qmd update`.
-- `/wiki-lint`: Checks for broken `[[wikilinks]]`, dead line anchors, orphan pages, and unindexed symbols.
+- `/wiki-lint`: Checks OKF frontmatter (`type`, ISO `generated.at`), leftover `[[wikilinks]]`, unresolved relative markdown links, dead line anchors, and orphan pages.
 
 ### Standalone CLI Commands
 
@@ -81,7 +81,7 @@ npx prism-wiki search "How does authentication work?" --mode query
 ### Response Content:
 ```markdown
 ### Match 1: Authentication Architecture > Token Verification
-- **Wiki Page:** [[entities/authentication.md]]
+- **Wiki Page:** `entities/authentication.md`
 - **Category:** Core Module
 - **Freshness:** Current (Source hash matches manifest)
 
@@ -91,7 +91,7 @@ The authentication layer uses asymmetric Ed25519 JWT verification in middleware,
 **Code & Source Anchors (Clickable):**
 - Token verification: `verifyToken()` (`file:///src/auth/jwt.ts#L45-L89`)
 - Revocation check: `assertNotRevoked()` (`file:///src/auth/session-store.ts#L112-L138`)
-- Architecture Decision: [[decisions/ADR-004-ed25519-migration.md]]
+- Architecture Decision: `decisions/ADR-004-ed25519-migration.md`
 ```
 
 ## Implementation example
@@ -119,6 +119,20 @@ await kernel.load([wiki]);
 
 When initialized (`wiki-init` or `createWikiExtension`), these skills are automatically deployed to the host workspace's `.agents/skills/` folder so any compatible agent can leverage them immediately.
 
+## OKF v0.2 bundle format
+
+Emitted `.wiki/` trees are [OKF v0.2](https://github.com/GoogleCloudPlatform/open-knowledge-format) bundles. Karpathy compilation (synthesize, don't copy; precise `file:///` anchors; contradiction reconciliation; synchronized catalog/ledger) is unchanged.
+
+| Artifact | OKF rule |
+| --- | --- |
+| Root `index.md` | Only `okf_version: "0.2"` frontmatter; sectioned bullet listings per OKF §8 |
+| `entities/index.md`, `decisions/index.md`, `concepts/index.md` | No frontmatter (progressive disclosure) |
+| Concept pages | `type` required (Module / Concept / Decision Record / Entity / Person / Tool), plus `title`, `description`, `tags`, `sources[].resource`, `generated: { by: prism-wiki/<version>, at: <ISO 8601 UTC> }` |
+| `log.md` | `# Directory Update Log`, `## YYYY-MM-DD` newest first, `* **Verb**: …` |
+| Links | Standard relative markdown. `[[wikilinks]]` are lint errors |
+
+`.manifest.json` remains the compilation ledger (`id`, `category`, `rawSources`, `lastCompiledAt`). Those keys are not copied into page frontmatter. Trust families (`verified`, `status`) are omitted in v1 (unverified). `wiki-refresh` upgrades pages it touches; leftover legacy pages can be re-scaffolded — the format is regenerable from raw sources.
+
 ## Extension and configuration notes
 
 - `@arnilo/prism-wiki` registers tools (`wiki_search`, `wiki_read_page`, `wiki_record_insight`), commands (`wiki-init`, `wiki-refresh`, `wiki-lint`), skills (`wiki-maintainer`, `wiki-searcher`), and instruction injectors (`wiki-guidance`) into Prism registries.

package/docs/workflows.md

@@ -76,6 +76,16 @@ All workflow limits and runtime `concurrency` reject non-safe integers, zero, ne
 
 A function node returns `suspend({ reason, data?, resumeSchema? })` to persist `status: "suspended"`. Its next invocation receives `ctx.resume` only after an approved resume. `resumeWorkflow(workflow, { runId }, options)` validates schema/version/ownership/`definitionHash`, claims the checkpoint before node execution, and continues the suspended node. Denial persists terminal `denied` status without invoking it. Existing failed/aborted checkpoint resume remains available without a human decision.
 
+> **Contract — resume-aware nodes.** After an approved resume, the **same** node's `execute` is re-invoked with `ctx.resume`. Returning `suspend(...)` unconditionally re-suspends silently; downstream nodes never run. Branch on `ctx.resume`:
+>
+> ```ts
+> execute: async (ctx) => ctx.resume
+>   ? handle(ctx.resume)
+>   : suspendAskUserDecision({ ... }),
+> ```
+>
+> Live demo: [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) (`gate` node).
+
 Coding-agent ask-user glue (opt-in, no Goal DB): `suspendAskUserDecision(request)` wraps `suspend` with durable question/options/`selectionMode`/`allowCustom` data + resume schema; resume with `createAskUserDecisionResumeValidator()` or `validateAskUserDecisionResume`. Goal→verify: `runCodingGoalVerify` / `createCodingGoalVerifyWorkflow` compose plan Markdown → named checks → approve suspend → bounded handoff over the same primitives (`examples/coding-goal-verify.ts`). When a workflow node wraps a durable agent run, that run's shared pending-decision batch (Task 2) is the approval authority — workflow `suspend`/`resume` stay workflow-scoped and do not mint a parallel decision store.
 
 Every node receives bounded `ctx.state`, `ctx.stateVersion`, and async `ctx.updateState(patch, { mode: "merge" | "replace" })`. Updates serialize, validate, redact, and snapshot before checkpoint save. A rejected state or checkpoint write stays rejected (nothing committed) and recovers the per-run chain so a later valid write can run. `workflowNode({ workflow })` runs its child with the same ownership, agent/tool registries, execution policy, redactor, signal, checkpoints, and event bus; child state replaces parent state after success.
@@ -300,6 +310,29 @@ runRpcServer({
 });
 ```
 
+## Bounded iterate-until-done (host-loop pattern)
+
+Workflows stay acyclic. "Loop until the goal passes" is a **host** `for`/`while` over `runWorkflow`, not a graph cycle. One run per iteration; iteration state in workflow **inputs**; the host owns the termination predicate and budgets. No extra runtime. Runnable proof: [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) (N iterations, mid-loop human gate with simulated restart, typed budget exhaustion).
+
+1. Keep the DAG acyclic (roadmap → execute → validate → gate → compact).
+2. Pass `{ goal, iteration }` as `runWorkflow` input — never a back-edge.
+3. Bound the host loop (`MAX_ITERATIONS`). Per-child tool/token caps stay on `supervisor.delegate` / `RunOptions`.
+4. Explicit predicate (`passed(outputs)`). Exhaustion throws a typed error — fail-closed, never hang.
+5. Human gate is ordinary `suspend` / `resumeWorkflow` (CAS `expectedVersion`). Restart = new runtime, same checkpoint store.
+6. Audit **each iteration** with `replayWorkflow({ sourceRunId, fromNodeId })`. The host loop is N run ids — `listWorkflowRuns` lists them; `replayWorkflow` does not replay the `for`.
+
+```ts
+for (let i = 0; i < MAX_ITERATIONS; i++) {
+  const run = await runWorkflow(phase, { goal, iteration: i }, { checkpoints, ownership });
+  if (run.status === "suspended") break; // resumeWorkflow later with expectedVersion
+  if (run.status !== "succeeded") throw new Error(run.status);
+  if (passed(run.outputs)) break;
+}
+if (!passed(last.outputs)) throw new BudgetExhaustedError(MAX_ITERATIONS);
+```
+
+Budgets are the host's job until [plan 045](../plans/045-Bounded-Loop-Workflow-Node.md) ships an in-graph `loop` node (`until` + hard `maxIterations`, still finite). Do not wait on that primitive for this pattern.
+
 ## Extension and configuration notes
 
 - Workflow semantics stay in this optional package; generic checkpoint persistence and bounded event fan-in live in core.
@@ -337,7 +370,7 @@ Use workflows for known, durable, replayable graphs. Use optional supervisor del
 
 ## Related APIs
 
-- Examples: `examples/workflow-research-and-review.ts`, `examples/workflow-parallel-research.ts`, `examples/workflow-tool-approval.ts`, `examples/workflow-multimodal-document.ts`, `examples/workflow-sqlite-resume.ts`, `examples/workflow-postgres-resume.ts`, `examples/workflow-event-sink.ts`, `examples/workflow-rpc-cancel.ts`, `examples/workflow-distributed-coordinator.ts` — offline runnable demos; PostgreSQL safely skips unless `PRISM_TEST_POSTGRES_URL` is set.
+- Examples: `examples/workflow-research-and-review.ts`, `examples/workflow-parallel-research.ts`, `examples/workflow-tool-approval.ts`, `examples/workflow-multimodal-document.ts`, `examples/workflow-sqlite-resume.ts`, `examples/workflow-postgres-resume.ts`, `examples/workflow-event-sink.ts`, `examples/workflow-rpc-cancel.ts`, `examples/workflow-distributed-coordinator.ts`, `examples/autonomous-coding-loop.ts` (host-loop iterate-until-done) — offline runnable demos; PostgreSQL safely skips unless `PRISM_TEST_POSTGRES_URL` is set.
 - [Workflow orchestration primitives](workflow-orchestration-primitives.md): Task 0–1 inventory and locked adapter contracts
 - [Agent/session runtime](agent-session-runtime.md): `AgentSession.run()`/`stream()`, abort, subscribe
 - [Guardrails](guardrails.md): `RunWorkflowOptions.guardrails` routes tool nodes through core dispatch before policy and side effects.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",