pi-daddy 0.32.0 → 0.34.0

package/extensions/context-staging.ts

@@ -0,0 +1,200 @@
+/**
+ * Stage what a granted handoff hands over (ADR-0078).
+ *
+ * The kernel decides WHETHER context crosses and in which mode; this decides what the bytes are, because building
+ * them means reading files and the parent's own session and the kernel does no I/O. It is called only after the
+ * mode has survived the ceiling, the parent's grant and the gate, so a refused handoff reads nothing.
+ *
+ * **What authorises the read.** `context:files` is the authorisation, not `tool:read`: an operator who grants a
+ * definition the right to receive file contents has said so explicitly, in the grant, where a reviewer sees it.
+ * Paths are still confined to the session's working directory, because they are MODEL-supplied and the fence must
+ * not become a way to read `/etc` without holding a tool that can. That confinement is a bound on the parameter,
+ * not a claim of containment: the parent process can already read whatever its own grant allows.
+ *
+ * **What is not staged.** A mode whose input cannot be read — a missing file, an unreadable session — yields a
+ * section saying so rather than silence. A handoff that quietly carried less than it promised would be R-03's
+ * shape, a missing result indistinguishable from an empty one, and the child would have no way to know.
+ */
+import { randomUUID } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readSync, realpathSync, rmSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import {
+  fenceContext,
+  selectPrunedTurns,
+  type ContextRequest,
+  type ContextSection,
+  type PrunableTurn,
+} from "../src/kernel/context-handoff.ts";
+
+/** The parent's session, as much of it as staging needs. Satisfied by pi's `ReadonlySessionManager`. */
+export interface ParentSession {
+  getSessionFile(): string | undefined;
+  getEntries(): Array<{ id: string; type: string }>;
+}
+
+export interface StagingInput {
+  cwd: string;
+  /** Where a forked session is written. One directory per fork, private to this uid. */
+  forkRoot: string;
+  parentSession?: ParentSession;
+}
+
+export interface StagedHandoff {
+  contextPrompt?: string;
+  forkFrom?: { sessionPath: string; sessionDir: string; sessionId: string };
+  /**
+   * Why nothing could be staged. Returned rather than thrown: `planDelegation` is pure and no caller expects it to
+   * throw, so a throw here escaped as a raw error with no ledger record, or as `APPROVAL_FLOW_FAILED` after the
+   * human had already said yes — measured in review.
+   */
+  refusal?: string;
+  /** Remove anything this staging created. A fork writes a copy of the parent's session and must not outlive it. */
+  dispose?: () => void;
+  /** For the ledger: what actually crossed, never what was asked for. Absent when nothing was staged. */
+  record?: {
+    mode: string;
+    sections: number;
+    bytes: number;
+    truncatedBytes: number;
+    keptTurns?: number;
+    droppedTurns?: number;
+    rule?: string;
+  };
+}
+
+/** 64 KiB per file before the fence's own budget sees it, so one large file cannot starve the others. */
+const MAX_FILE_BYTES = 64 * 1024;
+
+export function createHandoffStager(input: StagingInput) {
+  return (granted: ContextRequest): StagedHandoff => {
+    if (granted.mode === "fork") return stageFork(input);
+    const sections: ContextSection[] = [];
+    let keptTurns: number | undefined;
+    let droppedTurns: number | undefined;
+    let rule: string | undefined;
+
+    if (granted.mode === "summary")
+      sections.push({ label: "what your parent says you need to know", body: granted.summary ?? "" });
+    if (granted.mode === "files" || granted.mode === "pruned")
+      for (const path of granted.files ?? []) sections.push(readSection(input.cwd, path));
+    if (granted.mode === "pruned") {
+      const selection = selectPrunedTurns(parentTurns(input.parentSession), {
+        ...(granted.turns !== undefined ? { turns: granted.turns } : {}),
+        ...(granted.files !== undefined ? { files: granted.files } : {}),
+      });
+      keptTurns = selection.kept.length;
+      droppedTurns = selection.droppedCount;
+      rule = selection.rule;
+      for (const turn of selection.kept) sections.push({ label: `parent turn ${turn.id}`, body: turn.text });
+      if (selection.kept.length === 0)
+        sections.push({ label: "parent turns", body: "(no turn of your parent's session matched the selection)" });
+    }
+
+    const fenced = fenceContext(sections);
+    return {
+      contextPrompt: fenced.text,
+      record: {
+        mode: granted.mode,
+        sections: sections.length,
+        bytes: Buffer.byteLength(fenced.text),
+        truncatedBytes: fenced.truncatedBytes,
+        ...(keptTurns !== undefined ? { keptTurns, droppedTurns, rule } : {}),
+      },
+    };
+  };
+}
+
+/**
+ * A fork replaces the session file the inactivity deadline would otherwise watch, because pi refuses `--fork`
+ * beside `--session`. The directory is ours and holds exactly one session, so the activity probe watches the
+ * directory instead of a fixed path — pi names the file `<timestamp>_<id>.jsonl` and only the id half is ours.
+ */
+function stageFork(input: StagingInput): StagedHandoff {
+  const sessionPath = input.parentSession?.getSessionFile();
+  if (!sessionPath)
+    // Not a silent downgrade to `none`: the parent asked for its whole session to cross and it has none to give.
+    return { refusal: "context: fork needs the parent's session file, and this session is not persisted" };
+  const sessionId = randomUUID();
+  const sessionDir = resolve(input.forkRoot, `fork-${sessionId}`);
+  try {
+    mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+  } catch (error) {
+    return { refusal: `context: fork could not allocate ${sessionDir} (${String(error)})` };
+  }
+  // The ledger records the SIZE of what crossed, because a fork is the largest handoff there is and recording it
+  // as zero bytes would make the audit trail understate exactly the mode that deserves the most scrutiny.
+  let bytes = 0;
+  let entries = 0;
+  try {
+    bytes = statSync(sessionPath).size;
+    entries = input.parentSession?.getEntries().length ?? 0;
+  } catch {
+    /* an unreadable parent session is still a fork pi will attempt; the record says 0 rather than guessing */
+  }
+  return {
+    forkFrom: { sessionPath, sessionDir, sessionId },
+    dispose: () => rmSync(sessionDir, { recursive: true, force: true }),
+    record: { mode: "fork", sections: 1, bytes, truncatedBytes: 0, keptTurns: entries, droppedTurns: 0 },
+  };
+}
+
+/** Read one named file, confined to the working directory, saying so in the fence when it cannot be read. */
+function readSection(cwd: string, path: string): ContextSection {
+  const refuse = (why: string) => ({ label: path, body: `(refused: ${why})` });
+  if (isAbsolute(path)) return refuse("an absolute path");
+  let absolute: string;
+  let root: string;
+  try {
+    // `realpath`, not `resolve`: `resolve`/`relative` are LEXICAL, so a symlink inside the working directory
+    // pointing anywhere at all passed the check — measured in review with `cwd/link.txt -> /tmp/outside.txt`,
+    // whose contents duly appeared inside the fence. A repository full of `node_modules/.bin` symlinks makes that
+    // the ordinary case rather than a contrived one.
+    root = realpathSync(resolve(cwd));
+    absolute = realpathSync(resolve(cwd, path));
+  } catch (error) {
+    return { label: path, body: `(could not be read: ${error instanceof Error ? error.message : String(error)})` };
+  }
+  const within = relative(root, absolute);
+  if (within.startsWith("..") || within === "" || isAbsolute(within))
+    return refuse("outside this session's working directory");
+  try {
+    const stats = statSync(absolute);
+    // A FIFO satisfies `statSync` and then never returns from a read, which would block the whole pi session with
+    // no watchdog — and the path is model-supplied, so it is reachable rather than theoretical.
+    if (!stats.isFile()) return refuse("not a regular file");
+    const note = stats.size > MAX_FILE_BYTES ? ` (first ${MAX_FILE_BYTES} of ${stats.size} bytes)` : "";
+    return { label: `${path}${note}`, body: readBounded(absolute, MAX_FILE_BYTES) };
+  } catch (error) {
+    return { label: path, body: `(could not be read: ${error instanceof Error ? error.message : String(error)})` };
+  }
+}
+
+/**
+ * Read at most `budget` BYTES, without pulling the rest of the file into the parent first.
+ *
+ * `readFileSync(...).slice(budget)` reads the whole file and then slices by UTF-16 code units, so a large file in
+ * the repository stalled the parent and the "(first N of M bytes)" label was wrong for any multi-byte content.
+ */
+function readBounded(path: string, budget: number): string {
+  const handle = openSync(path, "r");
+  try {
+    const buffer = Buffer.alloc(budget);
+    const read = readSync(handle, buffer, 0, budget, 0);
+    return new TextDecoder("utf-8", { fatal: false }).decode(buffer.subarray(0, read)).replace(/\uFFFD+$/, "");
+  } finally {
+    closeSync(handle);
+  }
+}
+
+/** The parent's message turns, reduced to what the selection rule needs. Never pi's own types past this point. */
+function parentTurns(session?: ParentSession): PrunableTurn[] {
+  if (!session) return [];
+  try {
+    return session
+      .getEntries()
+      .filter((entry) => entry.type === "message")
+      .map((entry) => ({ id: entry.id, text: JSON.stringify((entry as { message?: unknown }).message ?? entry) }));
+  } catch {
+    return [];
+  }
+}

package/extensions/delegate-chain.ts

@@ -41,6 +41,7 @@ import { GovernanceRefusal, refusal, type StructuredRefusal } from "../src/kerne
 import { chainApprovalFacts, newChainApprovalAudit, rememberChainApproval } from "./chain-approval-facts.ts";
 import { newExecutionId } from "../src/kernel/execution-id.ts";
 import { planChain, type GateRequest } from "./chain-plan.ts";
+import { contextShape } from "./context-shape.ts";
 import { preflightModel } from "../src/kernel/model-preflight.ts";
 import { assertDelegationAuthority } from "./delegation-authority.ts";
 
@@ -83,6 +84,7 @@ export function registerChainTool(pi: ExtensionAPI, session: GrantsSession): voi
         { description: "Requested Pi thinking level; unsupported model/level combinations fail in the child." },
       ),
     ),
+    context: Type.Optional(contextShape()),
     correlation: Type.Optional(correlationShape()),
     workspace: Type.Optional(
       Type.Object({

package/extensions/delegation-ledger.ts

@@ -39,6 +39,8 @@ export async function recordDelegationDecision(input: {
       taskFrom: input.taskFrom,
       taskFromExecutionId: input.taskFromExecutionId,
       requested: plan.requested,
+      // ADR-0078: what crossed, recorded as a fact about this child rather than as the parent's request.
+      ...(plan.handoffRecord ? { handoff: plan.handoffRecord } : {}),
       parentGrant: session.ownGrant,
       result: plan.result,
       blocked: !plan.ok,

package/extensions/delegation.ts

@@ -36,6 +36,7 @@ import { type GrantsSession } from "./session.ts";
 import { newDelegationOccurrence } from "./execution-occurrence.ts";
 import { correlationShape as buildCorrelationShape } from "./correlation-shape.ts";
 import { assertDelegationAuthority } from "./delegation-authority.ts";
+import { contextShape } from "./context-shape.ts";
 
 /**
  * Wire a set of children to pi's partial-result channel — ADR-0032.
@@ -189,6 +190,7 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
     tools: Type.Optional(Type.Array(Type.String(), { description: "Capabilities, when no 'agent' fits." })),
     model: Type.Optional(Type.String({ description: "Model as provider/id. Defaults to this session's." })),
     thinking: thinkingShape,
+    context: Type.Optional(contextShape()),
     correlation: Type.Optional(correlationShape),
     workspace: Type.Optional(workspaceShape),
   });
@@ -221,6 +223,7 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
       }),
     ),
     thinking: thinkingShape,
+    context: Type.Optional(contextShape()),
     correlation: Type.Optional(correlationShape),
     workspace: Type.Optional(workspaceShape),
   });
@@ -247,6 +250,7 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
           tools: params.tools,
           model: params.model,
           thinking: params.thinking,
+          context: params.context,
           correlation: params.correlation,
           workspace: params.workspace,
         },

package/extensions/execute-child.ts

@@ -148,6 +148,14 @@ export async function executePlannedChild(input: {
     return await executeWithActivitySession();
   } finally {
     if (!keepPaneRequested) await activitySession.dispose();
+    // ADR-0078: a fork wrote a COPY of the parent's whole session to disk. PR 3e deletes its own temp session on
+    // every path and this must too, or every forked child leaves a full transcript behind for good.
+    if (!keepPaneRequested)
+      try {
+        plan.disposeHandoff?.();
+      } catch {
+        /* teardown must not replace the child's outcome */
+      }
   }
 
   async function executeWithActivitySession(): Promise<DelegationOutcome> {
@@ -352,7 +360,7 @@ export async function executePlannedChild(input: {
               // NOT strict, and this line is the whole point of R-99. The child has already run: failing
               // closed here prevents nothing and used to discard a completed child's entire output while
               // blaming "ledger" — under `delegate_all` it discarded every sibling's work too. The docstring
-              // above, `docs/SPEC.md` and the ADR-0034 amendment all promised this; only the comment changed.
+              // above, the README and the ADR-0034 amendment all promised this; only the comment changed.
               // `capability_decision`, which PROVISIONS, still fails closed.
               strict: false,
               onFailure: (cause) => teardownFailures.push(`child lifecycle record failed: ${String(cause)}`),

package/extensions/grants-command.ts

@@ -137,7 +137,7 @@ export const grantsCommand = {
       ];
       for (const bad of report.corrupt.slice(0, 5)) lines.push(`    line ${bad.line}: ${bad.reason}`);
       // ADR-0031, and R-51's lesson applied on the day the field was added rather than a release later: a field
-      // the writer sets and no diagnostic reads is one that needs `jq`, and `docs/SPEC.md` claims the executor is
+      // the writer sets and no diagnostic reads is one that needs `jq`, and the README claims the executor is
       // announced "per child in the ledger". `unknown` is shown only when present, because on a fresh ledger it
       // is always zero and a permanent zero is noise; on an upgraded one it is the count of pre-0.16 lines, which
       // is worth seeing.

package/extensions/grants.ts

@@ -79,6 +79,11 @@ export default function (pi: ExtensionAPI) {
     const reload = bindReloadLifecycle(owner, session.reloadLifecycle);
     session.reconcileEnvironment(reload.environment, reload.lifecycle);
     session.ownerBound = true;
+    // ADR-0078: the parent's own session, for a granted `pruned` or `fork` handoff. Read-only, and only ever
+    // read after the mode has survived the gate.
+    const manager = owner as Partial<import("./context-staging.ts").ParentSession>;
+    if (typeof manager.getSessionFile === "function" && typeof manager.getEntries === "function")
+      session.parentSession = manager as import("./context-staging.ts").ParentSession;
     delegation.refreshSpawnable = registerDelegationTools(pi, session).refreshSpawnable;
     reconcileActiveDelegationTools(pi, session);
     session.cwd = ctx.cwd;

package/extensions/run-delegation.ts

@@ -45,6 +45,8 @@ interface ChildSpec {
   tools?: string[];
   model?: string;
   thinking?: string;
+  /** ADR-0078: what of the parent's session crosses. Validated in the kernel, never here. */
+  context?: unknown;
   correlation?: CorrelationMetadata;
   workspace?: DelegationWorkspaceSpec;
 }
@@ -248,6 +250,7 @@ export async function runOneDelegation(
     tools: spec.tools,
     model: spec.model ?? defaultModel,
     thinking: spec.thinking,
+    context: spec.context,
     correlation: spec.workspace
       ? { ...(spec.correlation ?? {}), workspace_id: spec.workspace.workspace_id }
       : spec.correlation,

package/extensions/session-report.ts

@@ -127,7 +127,7 @@ export async function reportSessionStart(session: GrantsSession, ctx: SessionRep
   // `agent:*` grants no tools, but it authorises every definition in BOTH skill roots — including
   // `~/.pi/agent/skills/`, which other software installs into, so ADR-0017's "an operator-authored
   // file" is not true of everything it covers. Paired with a shell that is every body on disk running
-  // with `bash`. `docs/SPEC.md` calls the combination poor and nothing detected it, which is R-47's
+  // with `bash`. The README calls the combination poor and nothing detected it, which is R-47's
   // shape in a control shipped one day later.
   if (
     session.ownGrant.includes(AGENT_WILDCARD) &&

package/extensions/session.ts

@@ -48,6 +48,9 @@ import type { GrantStoreRefusalReason } from "../src/governance/grant-store.ts";
 import { republishable } from "./approvals.ts";
 import { storedGrantSessionState } from "./stored-grant-session.ts";
 import { nativeSessionRootFromEnv, type NativeSessionHost } from "../src/executors/native-session-target.ts";
+import { createHandoffStager, type ParentSession } from "./context-staging.ts";
+import { join } from "node:path";
+import { agentDir } from "../src/kernel/project-paths.ts";
 import { ENV_ALLOW_UNRESOLVED_MODELS } from "../src/kernel/model-preflight.ts";
 import { beginExtensionLifecycle, rememberChildPublication, type ReloadLifecycle } from "./reload-environment.ts";
 import { reconcileSessionEnvironment } from "./session-environment.ts";
@@ -149,6 +152,11 @@ export interface GrantsSession extends NativeSessionHost {
   /** Stable root identity plus current turn, used only to join local activity facts. */
   activityRootId: string;
   activity?: { rootId: string; path: string; taskId?: string };
+  /**
+   * The parent's own session, once `session_start` supplies it. Read-only and used only to stage a granted
+   * context handoff (ADR-0078): its file path for `fork`, its message turns for `pruned`.
+   */
+  parentSession?: ParentSession;
   /** Root identity keyed to ctx.sessionManager once session_start supplies it. */
   reloadLifecycle: ReloadLifecycle;
   /** Approval keys approved for this session. In memory only — this dies with the process. */
@@ -352,6 +360,13 @@ export function createGrantsSession(
       extensionPath: session.extensionPath,
       observerExtensionPath: session.observerExtensionPath,
       childEnv: activityChildEnv(session.activity),
+      // ADR-0078: composition reads, the kernel decides. Called only for a mode that survived the gate.
+      stageHandoff: (granted) =>
+        createHandoffStager({
+          cwd: session.cwd,
+          forkRoot: join(agentDir(), "context-forks"),
+          ...(session.parentSession ? { parentSession: session.parentSession } : {}),
+        })(granted),
       catalog: await session.catalogReady,
       // R-32: where each granted skill lives, so `planSpawn` can pass `--skill` for those and only those.
       // Derived from the catalog's own `source`, so it cannot drift from what was discovered.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
   "keywords": [
     "pi-package",

package/src/advisors/advisor.ts

@@ -0,0 +1,123 @@
+/**
+ * The wrapper that makes "every use is recorded" structural rather than a rule (ADR-0077).
+ *
+ * A caller cannot reach a `Decider` directly through this layer's public surface: it asks an `Advisor`, and asking
+ * always produces an `advice` record — including when the answer was "no advice", which is the case a reviewer most
+ * needs to see, because an advisor that silently stops answering would otherwise look exactly like one nobody used.
+ *
+ * **What is recorded, and what is not.** The record names the purpose, the decider, the question keys, the answers
+ * and how long it took. It does NOT contain the state. A caller composes that state from its own context, which can
+ * include task text, file contents and a repository's private material; the ledger has never stored a task
+ * (ADR-0021) and an advisor must not become the way it starts. The question keys are the caller's own constants,
+ * so they name the decision without describing the situation.
+ */
+import type { Advice, AdviceRequest, Decider } from "./decider.ts";
+
+/** Two seconds. An advisor is on the path of a decision a human is waiting for; it is not worth more than that. */
+export const DEFAULT_ADVICE_TIMEOUT_MS = 2000;
+
+export interface AdviceRecord {
+  /** Which decision this advice was for, from the caller's own closed list. */
+  purpose: string;
+  decider: string;
+  /** Question keys only — never the state, and never a question's free text. */
+  questions: string[];
+  answered: boolean;
+  durationMs: number;
+  /** Present only when advice came back. */
+  answers?: Readonly<Record<string, { value: string | number | boolean; confidence?: number }>>;
+  model?: string;
+  /**
+   * Why there is no advice. `declined` means the advisor answered with nothing; `error` means it could not be
+   * reached or its response was unrecognised; `cancelled` means the CALLER went away, which is not the advisor's
+   * failure and must not read as one.
+   */
+  outcome: "answered" | "disabled" | "timeout" | "error" | "declined" | "cancelled";
+}
+
+export interface Advisor {
+  ask(purpose: string, request: AdviceRequest, signal?: AbortSignal): Promise<Advice | null>;
+}
+
+export function createAdvisor(input: {
+  decider: Decider;
+  /** Where the record goes. Injected so this layer does no I/O and governance does not import it. */
+  record: (entry: AdviceRecord) => void | Promise<void>;
+  timeoutMs?: number;
+  /** Absent or false means the null decider is used whatever `decider` says. */
+  enabled?: boolean;
+}): Advisor {
+  const timeoutMs = input.timeoutMs ?? DEFAULT_ADVICE_TIMEOUT_MS;
+  return {
+    async ask(purpose, request, signal) {
+      const started = Date.now();
+      const base = { purpose, decider: input.decider.name, questions: Object.keys(request.questions) };
+      const write = async (entry: AdviceRecord) => {
+        try {
+          await input.record(entry);
+        } catch {
+          // Recording is an observation of a decision that has already been taken. Failing to write it must not
+          // change what the caller does, for `execute-child`'s reason: an audit failure that discards the work is
+          // worse than one that is merely missing.
+        }
+      };
+      if (input.enabled !== true) {
+        await write({ ...base, decider: "none", answered: false, durationMs: 0, outcome: "disabled" });
+        return null;
+      }
+      const timer = new AbortController();
+      const cancel = setTimeout(() => timer.abort(), timeoutMs);
+      const linked = signal ? AbortSignal.any([signal, timer.signal]) : timer.signal;
+      try {
+        // RACED, not merely signalled. A decider that ignores its signal would otherwise run as long as it liked
+        // and then be recorded as a timeout — measured at fifty times the configured bound. The `Decider` contract
+        // cannot make an implementation honour an abort, so the bound is enforced on this side of it.
+        const advice = await Promise.race([
+          input.decider.decide(request, linked),
+          new Promise<null>((settle) => linked.addEventListener("abort", () => settle(null), { once: true })),
+        ]);
+        const durationMs = Date.now() - started;
+        if (!advice) {
+          await write({ ...base, answered: false, durationMs, outcome: outcomeFor(timer.signal, signal, "declined") });
+          return null;
+        }
+        await write({
+          ...base,
+          answered: true,
+          durationMs,
+          outcome: "answered",
+          answers: Object.fromEntries(
+            Object.entries(advice.answers).map(([key, answer]) => [
+              key,
+              { value: answer.value, ...(answer.confidence === undefined ? {} : { confidence: answer.confidence }) },
+            ]),
+          ),
+          ...(advice.model ? { model: advice.model } : {}),
+        });
+        return advice;
+      } catch {
+        // Including an abort. A caller asked for advice and is getting none; it proceeds exactly as it would have.
+        await write({
+          ...base,
+          answered: false,
+          durationMs: Date.now() - started,
+          outcome: outcomeFor(timer.signal, signal, "error"),
+        });
+        return null;
+      } finally {
+        clearTimeout(cancel);
+      }
+    },
+  };
+}
+
+/** The bound fired, the caller went away, or neither — three different facts a reviewer needs to tell apart. */
+function outcomeFor(
+  timer: AbortSignal,
+  caller: AbortSignal | undefined,
+  otherwise: "declined" | "error",
+): AdviceRecord["outcome"] {
+  if (timer.aborted && !caller?.aborted) return "timeout";
+  if (caller?.aborted) return "cancelled";
+  return otherwise;
+}

package/src/advisors/decider.ts

@@ -0,0 +1,64 @@
+/**
+ * An advisor is a thing that answers a typed question. It is never a thing that decides (ADR-0077).
+ *
+ * The boundary is the whole design, and it is structural rather than remembered: **no type in this layer names a
+ * `Capability` or a refusal code**, and no function in `kernel/` or `governance/` accepts an advisor's result. An
+ * advisor may select among options the caller already had, rank them, annotate them, or propose one. It can never
+ * widen an `effective` set, satisfy a gate, or stand in for a human's answer — not because it is asked not to, but
+ * because nothing on those paths can receive what it returns. `test/advisors.test.ts` forces that.
+ *
+ * Non-generative on purpose. The first advisor is a classifier that returns a typed answer with a probability, not
+ * prose, which is what makes an advisor auditable: "it chose `b` at 0.91" is a fact a reviewer can disagree with,
+ * where a paragraph of reasoning is not.
+ *
+ * Degradation is "no advice", never a guess. Every path that cannot produce an answer — disabled, missing key,
+ * timeout, transport error, a response shape we do not recognise — returns `null`, and the caller does what it
+ * would have done without an advisor at all. That is why a caller must be written to work with `nullDecider`
+ * first, and why `nullDecider` is the default.
+ */
+
+/** A question, in the three shapes the first advisor understands. */
+export type Question =
+  | { kind: "noul"; instructions: string; whenTrue: string; whenFalse: string }
+  | { kind: "choice"; instructions: string; options: Readonly<Record<string, string>> }
+  | { kind: "score"; instructions: string; levels: readonly string[] };
+
+/** One typed answer. `confidence` is absent when the transport did not report one; it is never invented. */
+export type Answer =
+  | { kind: "noul"; value: boolean; confidence?: number }
+  | { kind: "choice"; value: string; confidence?: number }
+  // `level` is the string the value indexes, so a caller never has to know which end the scale starts at.
+  | { kind: "score"; value: number; level: string; confidence?: number };
+
+export interface AdviceRequest {
+  /**
+   * What the advisor is told about the situation. **Caller-composed and deliberately not the raw task**: the task
+   * is never stored (ADR-0021) and must not be shipped to a third party either, so a caller passes the facts it
+   * chose, and the record below names them by key without their values.
+   */
+  state: Readonly<Record<string, unknown>>;
+  questions: Readonly<Record<string, Question>>;
+}
+
+export interface Advice {
+  answers: Readonly<Record<string, Answer>>;
+  /** What actually answered, as the transport reported it — a dated model id, not the one we asked for. */
+  model?: string;
+}
+
+export interface Decider {
+  /** Recorded in the ledger so a reviewer can tell which advisor a decision was taken beside. */
+  readonly name: string;
+  decide(request: AdviceRequest, signal?: AbortSignal): Promise<Advice | null>;
+}
+
+/**
+ * The default, and the one every caller must work correctly with.
+ *
+ * Not a placeholder: it is how advisors stay optional. A caller that behaves differently under `nullDecider` than
+ * under no advisor at all has made advice load-bearing, which is the one thing ADR-0077 forbids.
+ */
+export const nullDecider: Decider = {
+  name: "none",
+  decide: async () => null,
+};