pi-mono/packages/agent/docs/pico/v3/plugins.md

Pico3 plugins

Status: proposal for how the hardened V3 (pico3) harness is extended, and how those extensions are packaged as Chord facets in the coding agent. Companion of view-and-events.md. Written against harness-v3.zip, pico-handoff-v2.md (§8–§12, §16) and packages/agent/docs/plugins.md (the coding-agent facet architecture), read in full.

Read order: §1–§5 are the harness alone (no Chord); §6 is the Chord layer; §7 tests.

1. Principles

1. There is no plugin object. The harness exposes registration capabilities; whoever composes the process (a Chord facet, a test, a script) calls them. The coding agent's "plugin" is a package of host-specific Chord facets that call these capabilities (§6); the harness never sees the package.
2. One durability story. Everything durable is one of four primitives (§2): entry, task checkpoint, task slot, namespace slice. Tools, hooks and custom task kinds use the same four; none has a private mechanism.
3. Nothing durable belongs to a facet. Chord service instances and replicated state are live process state; a reload replaces code, never state.
4. Core authority stays core. Extensions cannot append entries mid-turn, touch turn/inbox, resolve inputs, create core tasks, or write outside their namespace or their own task's slot. Enforced at runtime on every method, by type at the surface.
5. An extension's presentation is only what it projects. The view shows a namespace's declared view projection (nothing by default), a kind's describe() output, the core-rendered tool slot fields, and entries. Raw namespace state (caches, keys, secrets) and slot working state (memos, idempotency evidence) never appear in the view.

Here, “durable” means recoverable according to the selected storage mode. JSONL with fsync: false covers process termination while the OS/filesystem remain alive, but acknowledged tail commits may disappear after power, kernel, VM-host, or storage-cache failure. fsync: true strengthens file-data durability; see hardening-handoff.md §10 for the exact boundary and worst cases. Neither mode makes an external effect exactly once without an external idempotency key.

2. Durable primitives

primitive	lives in	lifetime	written by	forks / history	in the view
entry	transcript	forever, immutable	anyone via c.write (boundary-safe); core via appendEntry	inherited up to the fork point; rewind = at	entries
task checkpoint	task record	the task	its kind, whole replacement	no	via describe() → turn.generation, compaction, tasks[id].status
task slot	sticky document, tasks[id] (turn tasks: turn.tools[i])	the task; retired atomically with its terminal record	its kind; tools running in it; hooks running in it	no	tasks[id], turn.tools[i]
namespace slice	plugins[ns] in the session, rewindable or sticky document	the conversation / session	holders of the namespace token	rewindable slices are inherited and rewindable; sticky/session are present-only	plugins[ns]

Rules:

• Checkpoint is the kind's recovery program counter, nothing else. It is not a place for working state (that is the slot) or long-lived state (namespace).
• Slot is working state that should die with the task: progress, streamed output, and memos. memoOnce(slot, key, candidate) is one operation inside one commit: if Object.hasOwn(slot.memos, key) return the stored value, else store candidate and return it (??= is wrong: null is a valid value). It returns the durable winner to every caller. A memo is durable coordination and evidence; it is not exactly-once execution by itself. For an external effect, persist the idempotency key before the effect and replay the effect with the same key, relying on the external side to dedupe or to answer a result lookup; persist a result after an effect only when a duplicate is otherwise harmless. Slot contents are never in the view.
• Namespace slice defaults are declared at registration, per document, and seeded lazily (plugins[ns] ??= defaults on first access). Choose the document by semantics: rewindable when a fork should see the value as it was (plan mode, chosen model overrides), sticky for the present (UI preferences, caches), session for session-wide.
• Entries are the only primitive the model can see (when they carry model); everything else is invisible to the model by construction.
• Protected: turn, inbox, core config keys and other tasks' slots reject writes from extensions.

What is deliberately not durable: Chord keyed service instances (an open approval dialog), hook handler registrations, tool and section registrations. All are re-established by code at startup or reload.

3. Registration surface

const h = await Harness.open(storage, { models, processHost?, onReport? }, ctx);
// nothing runs yet; register, then:
h.resume();

All registration methods return an unregister function and may be called while the harness is open (§5 for what happens then).

h.registerTool(declaration: ToolDeclaration): () => void
h.registerSection(section: SystemSection): () => void
h.registerTaskKind(kind: Kind): () => void                     // ordinary kinds only; config keys checked for collisions
h.namespace<T extends NamespaceShape>(ns: string, defaults: T, opts?: { view?: (slice: T) => JsonValue }): Namespace<T>
                                                               // token with idempotent `unregister()`; unique, not `pi.*`; no `view` ⇒ nothing in the view
h.hooks(ns: Namespace, kind, handlers: Partial<HooksOf<typeof kind>>, opts?): () => void   // harness-wide; bound to the namespace (§4.2)
c.hooks(ns, kind, handlers, { subtree? }): () => void                             // one conversation (+ owned)
defineEntry<E>(kind: string): EntryKind<E>                                      // stateless; throws on `pi.*` (§4.4)
h.conversation(id, ctx): Promise<ConversationHandle | undefined>
h.quiescent(): boolean;  h.hold(): () => void;  h.suspend(ctx): Promise<void>    // §5

Token identity: the object passed to tx.plugins(ns), tx.emit(ns, …), tx.createTask(kind, …), h.hooks(ns, kind, …) must be the currently registered one; a redeclared or unregistered token rejects with StaleDefinition. The namespace string is what persists (memo keys, state slices); the token is only current runtime authority. This is what makes reload safe: code from a retired generation cannot keep writing, and a replacement registration of the same string finds the same state and memos.

Before resume(): task kinds whose tasks may exist in storage, and hook handlers that recovery reruns (beforeTool, systemInstructions, beforeRequest, beforeCollapse). A task whose kind is unregistered at resume() is orphaned (open-time reconciliation, pico-handoff-v2.md §13). A kind registered later only affects tasks created later. Tools, sections, namespaces and observer hooks may be registered at any time.

Inside a commit, extensions get:

tx.plugins(ns): T                                   // typed slice in the declared document(s), tracked proxy
tx.emit(ns, name: string, data: JsonValue): void    // -> { type: `plugin.${ns}.${name}`, data } in this commit's envelope
tx.slot(task): Slot                                 // own task only (kinds); tools/hooks use the api variants
memoOnce(tx.slot(task), key, candidate)             // first writer wins; hasOwn semantics (§2)
tx.write(conversationId, entryKind, input): Promise<Id>
tx.createTask(kind, input, opts): TaskRef<K>        // ordinary kinds

4. Extension points

Each with what it may do, where its durable state lives, and a worked example against the raw harness. The three examples are the ones §6 turns into Chord facets.

4.1 Tools

ToolDeclaration as in the sketch (name, description, parameters TypeBox, replay, output bounds, execute(args: Static<P>, api, ctx)), plus the tool-facing API:

interface ToolApi {
  readonly taskId: Id; readonly conversationId: Id; readonly callId: string;
  stream(chunk: string | Uint8Array): void;                          // kernel-bounded; becomes the result content if none returned
  progress(update: (slot: ToolSlot) => void, ctx): Promise<void>;    // own slot: progress, details, continuedBy
  memo<T extends JsonValue>(name: string, candidate: T, ctx): Promise<T>;   // memoOnce on the own slot
  memo<T extends JsonValue>(name: string, ctx): Promise<T | undefined>;     // read
  task<K>(kind: K, input: InputOf<K>, opts, ctx): Promise<TaskRef<K>>;
  conversation(spec, ctx): Promise<OwnedConversation>;
  waitForTask(ref, ctx): Promise<TaskOf<K>>;
  slot<T>(ref, ctx): Promise<T | undefined>;                         // another task's slot, read-only snapshot
}

Durability: the tool's slot (turn.tools[i]) for streamed output, progress and memos; entries through its result. A tool has no checkpoint; it runs inside pi.tool, whose started{call} checkpoint is the effect evidence.

How memos and replay interact: beforeTool and the started checkpoint happen before execute; a crash after started re-invokes only replay: "safe" tools. A safe tool that performs a keyed external effect records the idempotency key as a memo before the effect and reuses it on re-invocation; the external side dedupes or answers a result lookup for that key. Recording a result after the effect (as the question tool does) is only correct when a repeated effect is harmless, which asking a human again is. Memos are scoped to the tool task's slot and retired with it, so they cannot leak into a later call with the same id.

Example: a question tool that waits for a human. ask is whatever the host wires in (§6.2 wires a Chord dialog service; a test wires a promise).

export function questionTool(ask: (req: QuestionRequest, api: ToolApi, ctx: Context) => Promise<QuestionResponse>): ToolDeclaration {
  return {
    name: "question", description: "Ask the user a question and wait for the answer.",
    parameters: QuestionParamsSchema, replay: "safe",
    async execute(params, api, ctx) {
      let response = await api.memo<QuestionResponse>("answer", ctx);        // answered before a crash?
      if (response === undefined) {
        const candidate = await ask(params, api, ctx);                        // may wait for a long time; abort unwinds through ctx
        response = await api.memo("answer", candidate, ctx);                  // first writer wins
      }
      return response.outcome === "cancelled"
        ? { content: [{ type: "text", text: "User cancelled" }], isError: true }
        : { content: [{ type: "text", text: `User answered: ${response.answer}` }], details: { ...params, answer: response.answer } };
    },
  };
}

Crash before the memo: pi.tool recovers started (safe), re-invokes, no memo, asks again. Crash after: re-invokes, memo present, returns without asking. Two answers racing: both call api.memo("answer", …), both receive the winner.

4.2 Hooks

Declared per kind, typed (GenerationHooks, ToolHooks, PostToolsHooks, CollapseHooks, plus any custom kind's H). Handlers receive (…payload, api, ctx). HookApi is identity only; each point's runner passes a point-specific info object with exactly the capabilities that point can use:

interface HookApi { readonly kind: string; readonly taskId: Id; readonly conversationId: Id }

interface BeforeToolApi extends HookApi {
  readonly callId: string;
  waiting(ctx: Context): Promise<void>;              // commits turn.tools[i].waitingOn = <this handler's namespace>; idempotent
  memo<T extends JsonValue>(name: string, candidate: T, ctx: Context): Promise<T>;   // memoOnce on the tool task's slot, keyed (task, namespace, name)
  memo<T extends JsonValue>(name: string, ctx: Context): Promise<T | undefined>;
  emit(name: string, data: JsonValue, ctx: Context): Promise<void>;                   // plugin.<namespace>.<name>
}
// Hooks are registered with their namespace token (`h.hooks(ns, kind, handlers)`), so `waiting`, `memo` and
// `emit` need no namespace argument and two plugins cannot collide on a memo name. `waitingOn` is cleared by the
// kernel atomically with `started` (handler allowed), with the synthetic result (handler blocked or threw), or in
// its own commit when the handler unwinds on abort or suspend.

interface ToolHooks {
  beforeTool(call: ToolCall, api: BeforeToolApi, ctx: Context): { call?: ToolCall; block?: string } | void | Promise<…>;
  afterTool(call: ToolCall, result: ToolResult, api: HookApi & { readonly callId: string }, ctx: Context): ToolResult | void | Promise<…>;
}
// generation points: HookApi & { cutoff } / { attempt } as today; collapse: HookApi. A `memo` on another
// point's hosting-task slot is added to that point's info type when a real case needs it, not by default.

Durability: a hook has no task of its own. State tied to the invocation it is running in goes in the hosting task's slot via the point's api.memo, keyed by (hosting task, namespace string, name) so it survives recovery and re-registration and cannot collide with another plugin's memo (retired with that task, no cleanup code); state that outlives tasks goes in a namespace. There is no hook invocation id: nothing durable identifies "the same handler invocation" across a crash or a reload, and the rerun must find the earlier decision. Hooks commit through h.conversation(api.conversationId, ctx) handles (never from inside a transaction builder: use the builder's own ctx there, see hardening-handoff.md §7) and may wait as long as they like; beforeTool handlers rerun after a crash or a suspend/reopen (they run before started), which is why their decision must be a memo.

Example: tool approval.

export function installApproval(h: Harness, ask: (req: ApprovalRequest, ctx: Context) => Promise<ApprovalDecision>): () => void {
  const ns = h.namespace<{ autoAllow: string[] }>("approval", { sticky: { autoAllow: [] } });   // long-lived: which tools skip approval; no `view` ⇒ private

  return h.hooks(ns, kinds.tool, {
    async beforeTool(call, api, ctx) {
      const c = await h.conversation(api.conversationId, ctx);
      const auto = await c.commit((tx) => tx.plugins(ns).autoAllow.includes(call.name), ctx);
      if (auto) return;
      let d = await api.memo<ApprovalDecision>("decision", ctx);             // decided before a crash / reload? key = (task, "approval", "decision")
      if (d === undefined) {
        await api.waiting(ctx);                                               // view: turn.tools[i].waitingOn = "approval"; event tool.waiting
        const candidate = await ask({ conversationId: c.id, callId: call.id, taskId: api.taskId, name: call.name, args: call.arguments }, ctx);
        d = await api.memo("decision", candidate, ctx);                       // first writer wins
      }
      return d.decision === "deny" ? { block: `denied${d.by ? ` by ${d.by}` : ""}` } : undefined;
    },
  });
}

No afterTool cleanup: the memo lives in the tool task's slot and is retired with it. Late joiners see waitingOn in the snapshot. Two clients deciding at once both get the memo winner. Abort or suspend unwinds ask through ctx; the kernel clears waitingOn when the handler returns for any reason. Asking a human twice after a crash between waiting and the memo is harmless, which is why a post-effect memo is acceptable here.

4.3 Custom task kinds

Shape as in the sketch and the hardening handoff: defineTask({ name, config?, hooks?, initial, phases, abort, describe? }), exhaustive phase map, in-flight phases written before an effect and entered only after reopen, next builders that may checkpoint, terminalize or "retry".

Durability:

need	primitive
where to resume after a crash	checkpoint (tx.checkpoint(next) / returned next)
progress, partial output, per-run memos	slot (tx.slot(current), memoOnce) — shown as tasks[id].status after describe()
state that outlives the task, per conversation or session	namespace
facts for the transcript / model	entries via tx.write (placed at a boundary when busy)

describe(task): JsonValue turns checkpoint + slot into the rendering-shaped status the view publishes; if omitted, the view shows { phase }.

Example: a background repository indexer, resumable and observable.

type IndexInput = { root: string };
type IndexCheckpoint = { phase: "scanning"; cursor: string | null } | { phase: "writing"; batchKey: string };
type IndexSlot = { files: number; lastFile?: string; memos?: Record<string, JsonValue> };

export const indexer = defineTask<IndexInput, IndexCheckpoint, { files: number }, { reason: string }, null>({
  name: "repo.indexer",
  config: { rewindable: { indexIgnore: [] as string[] } },
  describe: (task) => ({ stage: task.checkpoint?.phase ?? "starting", files: task.slot?.files ?? 0 }),

  async initial(task, rt, ctx) {
    await rt.commit((tx) => { tx.slot(task).files = 0; tx.checkpoint({ phase: "scanning", cursor: null }); }, ctx);
    return scan(task, null, rt, ctx);
  },
  phases: {
    scanning: (task, rt, ctx) => scan(task, task.checkpoint.cursor, rt, ctx),
    // in-flight: only entered after a crash. The batch key was persisted before the effect; the write is
    // repeated with the same key and is safe only because writeBatch(key) is idempotent on the receiving side.
    async writing(task, rt, ctx) {
      await writeBatch(task.checkpoint.batchKey, ctx);
      return { next: { phase: "scanning", cursor: task.checkpoint.batchKey } };
    },
  },
  async abort() { return () => null; },
});

async function scan(task, cursor, rt, ctx) {
  const ignore = (await rt.rewindable(task.conversationId, ctx)).indexIgnore;
  const batch = await nextBatch(task.input.root, cursor, ignore, ctx);
  if (batch === undefined) {
    return { done: async (tx, current) => {
      await tx.write(current.conversationId, entries.notice, { model: [{ role: "user", content: `Indexed ${tx.slot(current).files} files.`, timestamp: rt.now() }] });
      return { status: "completed", result: { files: tx.slot(current).files } };
    } };
  }
  await rt.commit((tx) => tx.checkpoint({ phase: "writing", batchKey: batch.key }), ctx);   // idempotency key before the effect
  await writeBatch(batch.key, ctx);
  return { next: (tx, current) => {
    const s = tx.slot(current); s.files += batch.files.length; s.lastFile = batch.files.at(-1);
    return { phase: "scanning", cursor: batch.key };
  } };
}

Registered with h.registerTaskKind(indexer) before resume(); started with c.commit((tx) => tx.createTask(indexer, { root }, { background: true }), ctx) or from a tool via api.task(indexer, …). The view shows tasks[id] = { kind: "repo.indexer", background: true, status: { stage, files } }; a UI renders it from that alone.

4.4 Custom entries

interface CiEntry extends Entry { kind: "ci.result"; data: { run: number; ok: boolean }; model: [UserMessage] }
const ci = defineEntry<CiEntry>("ci.result");

await c.write(ci, { data: { run: 812, ok: false }, model: [{ role: "user", content: "CI run 812 failed.", timestamp: now }] }, ctx);
const last = await c.commit((tx) => tx.newestEntry(c.id, ci), ctx);     // CiEntry | undefined
for (const e of view.entries) if (ci.is(e)) render(e.data.run);

Omit model for bookkeeping the model must not see. head and edits are core-only. defineEntry throws on a pi.* name and c.write/tx.write reject pi.* at runtime for non-core callers even after a cast, with one allow-listed exception: pi.notice (one user message, optional data, no head/edits), which hosts, jobs and tools use for notices. No entry registry or schema is required. Placement is boundary-safe: immediately when idle, otherwise at the next boundary (view-and-events.md §6.1).

4.5 Namespaces

const ns = h.namespace<{ planMode: { enabled: boolean }; cache: Record<string, string> }>(
  "plan",
  { rewindable: { planMode: { enabled: false } }, sticky: { cache: {} } },
  { view: (s) => ({ planMode: s.planMode }) },                 // only this projection reaches the view; `cache` never does
);
await c.commit((tx) => { tx.plugins(ns).planMode.enabled = true; tx.emit(ns, "toggled", { enabled: true }); }, ctx);
// view: plugins.plan.planMode; envelope: ["s", ["plugins","plan","planMode","enabled"], true] + { type: "plugin.plan.toggled", data }
env.own(ns.unregister);                                        // idempotent; state stays, token goes stale

Defaults are per document; a slice may span documents ({ rewindable: …, sticky: … }) and tx.plugins(ns) returns the merged typed object with each key routed to its document (same mechanism as core config). view is a pure projection the kernel re-evaluates when the slice changes; without it the namespace has no presence in the view. Re-registering the same string with changed defaults adds new keys lazily and leaves removed keys as inert stored data.

4.6 Owned conversations and jobs

Subagents (api.conversation) and processes (pi.job via api.task(kinds.job, …)) are core features with their own durability; extensions use them, they do not extend them. See pico-handoff-v2.md §8, §10.5 and the hardening handoff §15.

5. Unregister, re-register, reload

Every registration can be undone and redone while the harness is open.

contribution	on unregister	on re-register
namespace (ns.unregister(), idempotent)	token stale; tx.plugins/tx.emit/h.hooks(ns, …) with it reject	new token for the same string; stored state and memos untouched; new defaults seeded lazily
hooks	removed from future chains; a handler already running continues to completion (it is cancelled only by abort or suspend)	joins the chain
task kind	pending tasks of the kind are not dispatched (not orphaned; orphaning is open-time only); running invocations keep the kind object they captured	pending tasks dispatch with the new implementation; config keys re-checked
tool / section	revision bump; in-flight invocations keep their captured declaration; preparation snapshots retry	same
entry kind	nothing	nothing

Reload replaces code, never durable state. Two modes, chosen by the host:

• Quiescent reload. h.quiescent() is true when the scheduler holds no invocation, running or sleeping: no phase handler, no retrying/deferred sleep, no job poll, no waiting beforeTool. Live task records may exist (pending, or between invocations). Then: release = h.hold() (defers new dispatch and new hook chains; commits and reads continue) → deactivate old facets (their disposals unregister) → activate new ones (re-register) → release().
• Suspend and reopen when not quiescent (the first safe version for active work). h.suspend(ctx): stop dispatch, cancel every in-process invocation context, await unwind, close storage; task records stay live and nothing is terminalized. Reopen with the new registrations and let ordinary recovery run: pre-effect phases rerun, started tools replay if safe and still safe, unsafe ones become interrupted results, other phases recover per their kind. Memos make reruns cheap (an approval already decided is not asked again). The injected ProcessHost must outlive the harness instance so running jobs reconcile through status(key) instead of becoming unknown.

Cancelling live calls of a tool or kind that the new generation no longer registers is not a transparent migration: it durably aborts them, cannot undo external effects, and post-tools observes aborted results. It is an explicit host policy (suspend({ abortRemoved: true })), never the default. Generation leases (old registrations kept alive until captured invocations drain while new work uses replacements) are a possible later refinement; they are not required for v1.

Registration belongs in onActivate, not setup: during a shape-preserving reload the replacement's setup runs before the old facet is deactivated, and two live registrations of one namespace string would collide.

6. The Chord layer

The coding agent composes the harness and its extensions as Chord facets (packages/agent/docs/plugins.md). Nothing in §1–§5 changes; this section only says which facet calls what.

6.1 Built-in facets (plumbing)

Provided once by the coding agent, consumed by every feature:

// session worker
export const Harness = defineService<HarnessHandle>("pi.harness", { local: true });   // the in-process handle from §3; never remote
export const ConversationService = defineService<{                                  // keyed by conversation id; remote
  view: ReplicatedState<ConversationView>;                                            // view-and-events.md; one publish per commit, on the line
  send(input: SendInput, ctx): Promise<Id>;  write(entry: NewEntry, ctx): Promise<Id>;
  inputAbort(id: Id, ctx): Promise<"aborted" | "already_placed" | "not_found">;
  configSet(patch: Partial<Config>, ctx): Promise<void>;
  abort(ctx): Promise<void>;  reset(handoff: string | undefined, ctx): Promise<void>;  collapse(instructions: string | undefined, ctx): Promise<Id>;
  fork(at: Id | "start", spec: ForkSpec, ctx): Promise<Id>;  entries(scan: EntryScan, ctx): Promise<Entry[]>;
}>("pi.conversation");

export const harnessSessionFacet = defineFacet({
  id: "@pi/harness",
  setup(env) {
    const conversations = env.provideMany(ConversationService);
    const handle = createHarnessHandle();                       // wraps Harness.open/resume/hold and the registration surface
    env.provide(Harness, handle);
    env.onActivate(async () => {
      await handle.open(storage, { models, processHost }, ctx);
      handle.onConversation((c) => {                            // existing at open, and every fork/subagent created later
        const view = env.replicatedState(c.snapshot());         // built on the line
        c.attachView(view);                                     // bounded ordered adapter: raw envelopes → one view.change(), off the line (below)
        env.own(conversations.spawn(String(c.id), { view, send: (i, cx) => c.send(i, cx).then((r) => r.id), /* … */ }));
      });
    });
    // resume() is called by the session worker after the facet host reports activation complete (all registrations done)
  },
});

ConversationView gains commit: { events } so events ride inside the replicated member; a subscriber reads value.commit.events after each delivery. No revision or storage sequence is placed in the view: Chord's ReplicatedStateDelivery.sequence is contiguous per member and plays that role.

Publication must not happen on the Session line. Chord's change() invokes source and subscriber listeners synchronously and a subscriber may throw or be slow. The bridge is a bounded ordered adapter: the kernel enqueues raw envelopes from its own view tracker; the adapter, off the line, applies one envelope's ops and sets commit.events inside one view.change(ctx, callback) transaction. One raw envelope = one change = one Chord sequence. If the queue overflows or change throws, close that keyed instance and respawn it with a fresh snapshot; a persisted Pico commit is never turned into a failure. Chord's subscription snapshot then gives late joiners the member at its current sequence, so §9 of view-and-events.md is implemented by Chord, not by us.

6.2 A feature: contract + session facet + presentation facet

The rule from plugins.md: one shared contract module, one facet per host, connected by service IDs. The session facet calls §3; the presentation facet observes services and the view. Facets keep no durable state: everything durable is in the harness through §2, and keyed service instances are channels.

Approval (hook + dialog service):

// contract.ts
export interface ApprovalRequest { conversationId: Id; callId: string; taskId: Id; name: string; args: JsonValue }
export type ApprovalDecision = { decision: "allow" | "deny"; by?: string };
export interface ApprovalDialog { readonly request: ReplicatedState<ApprovalRequest>; decide(d: ApprovalDecision, ctx: Context): Promise<void> }
export const ApprovalDialogs = defineService<ApprovalDialog>("pi.approval-dialog");   // keyed `${conversationId}:${callId}`

// session.ts
export const approvalSessionFacet = defineFacet({
  id: "@pi/approval",
  setup(env) {
    const harness = env.use(Harness);
    const dialogs = env.provideMany(ApprovalDialogs);
    env.onActivate(() => {
      env.own(installApproval(harness, (req, ctx) => {                       // §4.2, unchanged
        const completion = Promise.withResolvers<ApprovalDecision>();
        const close = dialogs.spawn(`${req.conversationId}:${req.callId}`, {
          request: env.replicatedState(req),
          async decide(d, _ctx) { completion.resolve(d); },
        });
        return awaitAbortable(completion.promise, ctx.abortSignal).finally(close);
      }));
    });
  },
});

// tui.ts
export const approvalTuiFacet = defineFacet({
  id: "@pi/approval",
  setup(env) {
    const tui = env.use(Tui);
    env.observe(ApprovalDialogs, async (dialog, ctx) => {                    // one task per open instance, incl. hydrated ones
      const r = dialog.request.value!;
      const modal = await tui.acquireModal(ctx.abortSignal);
      try { await dialog.decide({ decision: (await modal.confirm(`Allow ${r.name}?`, pretty(r.args))) ? "allow" : "deny", by: "tui" }, ctx); }
      finally { modal.close(); }
    });
  },
});

The decision memo (api.memo("approval", …)) is written by the hook in the session worker, so decide only resolves the local promise; the first-writer rule is applied where the durability is. A second client's decide resolves an already-resolved promise: harmless.

Question tool (tool + dialog service): identical shape with questionTool from §4.1 as the session contribution (harness.registerTool(questionTool(ask))) and ToolApi.memo instead of BeforeToolApi.memo. This is the packages/agent/docs/plugins.md question example with memoOnce replaced by the slot memo.

Indexer (custom kind, no service of its own):

// session.ts
export const indexerSessionFacet = defineFacet({
  id: "@pi/indexer",
  setup(env) {
    const harness = env.use(Harness);
    env.onActivate(() => { env.own(harness.registerTaskKind(indexer)); });   // before resume(): tasks may exist in storage
  },
});
// tui.ts: nothing to provide; render view.tasks[id].status for kind "repo.indexer" from ConversationService.view,
// and offer a /index slash command that calls conversation.commit-equivalent RPC (or a tiny IndexerService.start method).

6.3 What the session worker does at reload

if (harness.quiescent()) {
  release = harness.hold()
  FacetHost.reload(candidates)    // old facets' env.own() disposals unregister; new onActivate re-registers
  release()
} else {
  await harness.suspend(ctx)      // cancel invocations, close storage; task records stay live
  FacetHost.reload(candidates)
  await harness.reopen(ctx)       // recovery runs against the new registrations
}

Durable state, task records and open conversations are untouched either way (§5).

7. Tests the hardening must include

• Memo: two concurrent api.memo writers receive the same winner; null is a stored value (hasOwn, not ??=); a crash after the memo skips ask, before it re-asks; the memo is gone after the tool task terminalizes; two namespaces using the same memo name on one task do not collide.
• Hooks: await api.waiting(ctx) sets waitingOn in its own commit and it is cleared atomically with started, with the synthetic result on block/throw, and in its own commit on abort/suspend; the decision memo survives a crash between waiting and started; memos never appear in the view.
• Custom kind: crash in the in-flight phase re-enters it and repeats the keyed effect (test with a fake idempotent sink and a crash between effect and the next checkpoint); describe() output appears in tasks[id].status; unregistered kind leaves pending tasks pending and orphans only at open.
• Namespaces: writes outside plugins[ns] reject; stale token rejects; unregister is idempotent; re-register keeps values and memos and seeds new defaults; only the view projection appears in the view; rewindable slice is inherited by a fork and readable at an entry.
• Entries: defineEntry("pi.x") throws; write of any pi.* except pi.notice rejects at runtime after a cast; pi.notice with head/edits rejects.
• Reload: quiescent() is false while any invocation exists (including a waiting beforeTool and a polling job); hold() defers dispatch and hook chains but not commits; suspend/reopen with the approval facet lets a pending call be approved through the new generation without asking twice when a memo exists; ProcessHost survives suspend/reopen and a running job reconciles.
• Chord: loopback facet tests for approval and question (session + presentation fixtures), late-joiner hydration of an open dialog instance, and ConversationService.view sequence equals commit sequence.