pi-daddy 0.22.0 → 0.23.0

package/src/debrief.ts

@@ -0,0 +1,198 @@
+import { reviewPage, reviewRequest, matchingHistory, validatedHistory, blindView, blindChoice, byteDigest, dataDigest, dataKey, detached, freeze,
+  sha, closed, type SignalSelection, type ReviewPort, type ReviewItem, type ReviewRequest, type BlindPort, type BlindView, type BlindChoice } from "./debrief-contract.ts";
+export interface DebriefCheckpoint {
+  version: "debrief-checkpoint-v1" | "debrief-checkpoint-v2"; bindingDigest?: string; scope: string; offset: number; operatorIdentity: string | null; caseIds: string[]; blindDigest: string | null;
+  requests: ReviewRequest[]; choice: BlindChoice | null; revealRequested: boolean;
+}
+/** Host-owned attention/transport checkpoint, NOT a dashboard decision ledger. CAS must be durable/atomic. */
+export interface DebriefPersistence {
+  durability: "host-owned" | "fixture-memory";
+  load(): unknown | Promise<unknown>;
+  compareAndSwap(expectedDigest: string | null, next: DebriefCheckpoint): void | Promise<void>;
+}
+export interface DebriefHost {
+  scope: string; offset?: number; operatorIdentity?: string; reviewer: ReviewPort; blind?: BlindPort; persistence?: DebriefPersistence;
+  fixture?: boolean;
+  signals?: SignalSelection;
+  blindBinding?: { comparisonId: string; author: string };
+}
+export interface DebriefFrame {
+  version: "debrief-view-v1"; mode: "manual"; state: string; persistence: "host-checkpoint" | "session-only";
+  total: number; unexposed: number; budgetSpent: number | null; remainingBudget: number | null; cards: ({ kind: "case"; slot: number; caseManifestId: string; priorDecisionId: string | null;
+    summary: string; disposition: string; resolution: "unresolved" | "label-recorded"; actionEnabled: boolean } |
+    { kind: "blind"; slot: number; variants: { label: string; text: string[] }[]; choice: BlindChoice | null; choiceConfirmed: boolean;
+      actionEnabled: boolean; revealed: unknown | null })[];
+  observation?: { batchId: string; id: string; issues: string[] };
+  fixture: boolean; acceptance: "not-assessed"; automatic: "unqualified"; freshness: "snapshot-unknown";
+}
+const presenters = new WeakSet<object>();
+export const isDebriefPresenter = (p: unknown): p is DebriefPresenter => typeof p === "object" && p !== null && presenters.has(p);
+export type DebriefPresenter = ReturnType<typeof createDebriefPresenter>;
+const reasons: Record<string, string> = { repeat_without_progress: "Repeated attempts without recorded progress", economical_exemplar: "Candidate economical exemplar", coverage_gap: "Missing evidence coverage", overdue_checkpoint: "Declared checkpoint overdue", reopened_acceptance: "Previously accepted binding reopened", intent_conflict: "Declared objective intent conflict" };
+function checkpoint(value: unknown, scope: string, offset: number, operatorIdentity: string | null, bindingDigest: string | null): DebriefCheckpoint | null {
+  if (value === null) return null;
+  const c = detached(value) as DebriefCheckpoint;
+  if (!c || Object.keys(c).sort().join() !== (bindingDigest ? "bindingDigest," : "") + "blindDigest,caseIds,choice,offset,operatorIdentity,requests,revealRequested,scope,version" || c.version !== (bindingDigest ? "debrief-checkpoint-v2" : "debrief-checkpoint-v1") || (bindingDigest !== null && c.bindingDigest !== bindingDigest) || c.scope !== scope || c.offset !== offset || c.operatorIdentity !== operatorIdentity || !Array.isArray(c.caseIds) ||
+    new Set(c.caseIds).size !== c.caseIds.length || c.caseIds.length + (c.blindDigest ? 1 : 0) > 5 || c.caseIds.some(id => !/^[a-f0-9]{64}$/.test(id)) ||
+    !(c.blindDigest === null || /^[a-f0-9]{64}$/.test(c.blindDigest)) || !Array.isArray(c.requests) || c.requests.length > c.caseIds.length || typeof c.revealRequested !== "boolean" ||
+    new Set(c.requests.map(r => r.caseManifestId)).size !== c.requests.length || c.requests.some(r => !c.caseIds.includes(reviewRequest(r).caseManifestId)) ||
+    (!c.blindDigest && (c.choice !== null || c.revealRequested)) || (c.revealRequested && !c.choice)) throw new Error("invalid host presentation checkpoint");
+  return c;
+}
+/** Manual host path only. Neither events nor caller-shaped idle/pause claims qualify automatic exposure. */
+export function createDebriefPresenter(host: DebriefHost) {
+  if (typeof host.scope !== "string" || !host.scope || host.scope.length > 256) throw new Error("explicit host presentation scope required");
+  const scope = host.scope, fixture = host.fixture === true, offset = host.offset ?? 0, operatorIdentity = host.operatorIdentity ?? null;
+  if (operatorIdentity !== null && (typeof operatorIdentity !== "string" || !operatorIdentity || operatorIdentity.length > 512 || /[\u0000-\u001f\u007f]/.test(operatorIdentity))) throw new Error("invalid independent operator identity");
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > 4096) throw new Error("invalid independently selected queue offset");
+  const signals = host.signals ? freeze(detached(host.signals)) : undefined, blindBinding = host.blindBinding ? freeze(detached(host.blindBinding)) : undefined;
+  if (signals) { closed(signals, ["batchId", "observationId"]); if (!sha(signals.batchId) || !sha(signals.observationId)) throw new Error("exact signal selection required"); }
+  if (blindBinding) { closed(blindBinding, ["comparisonId", "author"]); if (!sha(blindBinding.comparisonId) || blindBinding.author !== operatorIdentity || !host.blind?.quality) throw new Error("independent durable blind binding/quality reader required"); }
+  const bindingDigest = signals || blindBinding ? dataDigest({ signals: signals ?? null, blind: blindBinding ?? null }) : null;
+  const reviewer: ReviewPort = Object.freeze({ list: host.reviewer.list.bind(host.reviewer), history: host.reviewer.history.bind(host.reviewer),
+    ...(host.reviewer.decide ? { decide: host.reviewer.decide.bind(host.reviewer) } : {}) });
+  const blind: BlindPort | undefined = host.blind ? Object.freeze({ view: host.blind.view.bind(host.blind), readArtifact: host.blind.readArtifact.bind(host.blind),
+    choose: host.blind.choose.bind(host.blind), reveal: host.blind.reveal.bind(host.blind), ...(host.blind.quality ? { quality: host.blind.quality.bind(host.blind) } : {}) }) : undefined;
+  const persistence: DebriefPersistence | undefined = host.persistence ? Object.freeze({ durability: host.persistence.durability,
+    load: host.persistence.load.bind(host.persistence), compareAndSwap: host.persistence.compareAndSwap.bind(host.persistence) }) : undefined;
+  let saved: DebriefCheckpoint | null = null, items: ReviewItem[] = [], publicBlind: BlindView | null = null;
+  let checkpointKnown = !persistence;
+  let issues: string[] = [];
+  let total = 0, state = "closed", busy = false, poisoned = false, choiceConfirmed = false, revealed: unknown | null = null;
+  let variants: { label: string; text: string[] }[] = [];
+  const outcomes = new Map<string, { disposition: string; prior: string | null; resolution: "unresolved" | "label-recorded" }>();
+  const enabled = () => Boolean(operatorIdentity && persistence && (persistence.durability === "host-owned" || fixture) && reviewer.decide && !poisoned);
+  const persist = async (next: DebriefCheckpoint) => {
+    if (persistence) {
+      await persistence.compareAndSwap(saved ? dataDigest(saved) : null, detached(next));
+      const observed = checkpoint(await persistence.load(), scope, offset, operatorIdentity, bindingDigest);
+      if (!observed || dataDigest(observed) !== dataDigest(next)) throw new Error("checkpoint acknowledgement has no exact readback");
+    }
+    saved = freeze(detached(next));
+  };
+  const exclusive = async <T>(run: () => Promise<T>): Promise<T> => {
+    if (busy || poisoned) throw new Error("debrief busy or persistence unknown"); busy = true;
+    try { return await run(); } finally { busy = false; }
+  };
+  const reconcileItem = async (item: ReviewItem, request: ReviewRequest) => {
+    try {
+      const id = matchingHistory(await reviewer.history(item.caseManifestId), item, request, operatorIdentity ?? "");
+      outcomes.set(item.caseManifestId, { disposition: id ? request.disposition : "unresolved", prior: id ?? item.priorDecisionId,
+        resolution: id && !["skip", "uncertain"].includes(request.disposition) ? "label-recorded" : "unresolved" });
+      return id ? "recorded" : "stale-or-unknown";
+    } catch { outcomes.set(item.caseManifestId, { disposition: "unresolved", prior: item.priorDecisionId, resolution: "unresolved" }); return "unknown"; }
+  };
+  const api = {
+    async open(input: { mode: "manual" | "automatic"; userPresent: boolean; boundary?: string }) {
+      return exclusive(async () => {
+        if (input.mode !== "manual" || !input.userPresent || input.boundary === "busy") { state = "deferred: automatic/absent/busy boundary unqualified"; return api.view(); }
+        try {
+          if (persistence) {
+            const loaded = checkpoint(await persistence.load(), scope, offset, operatorIdentity, bindingDigest);
+            if (saved && (!loaded || dataKey(saved.caseIds) !== dataKey(loaded.caseIds) || saved.blindDigest !== loaded.blindDigest ||
+              saved.choice && dataKey(saved.choice) !== dataKey(loaded.choice) || saved.requests.some(r => !loaded.requests.some(n => dataKey(n) === dataKey(r))) || saved.revealRequested && !loaded.revealRequested)) throw new Error("checkpoint rollback/change; no new allowance");
+            saved = loaded; checkpointKnown = true;
+          }
+          publicBlind = blind ? blindView(await blind.view()) : null;
+          const page = reviewPage(await reviewer.list(offset, publicBlind ? 4 : 5), publicBlind ? 4 : 5, offset, signals); total = page.total; issues = page.issues ?? [];
+          if (!saved) await persist({ version: bindingDigest ? "debrief-checkpoint-v2" : "debrief-checkpoint-v1", ...(bindingDigest ? { bindingDigest } : {}), scope, offset, operatorIdentity, caseIds: page.items.map(i => i.caseManifestId), blindDigest: publicBlind ? dataDigest(publicBlind) : null, requests: [], choice: null, revealRequested: false });
+          if (saved!.blindDigest !== (publicBlind ? dataDigest(publicBlind) : null) || saved!.caseIds.some(id => !page.items.some(i => i.caseManifestId === id))) throw new Error("changed batch/blind identity; no fresh allowance");
+          items = saved!.caseIds.map(id => page.items.find(i => i.caseManifestId === id)!);
+          if (saved!.choice && publicBlind) blindChoice(saved!.choice, publicBlind);
+          for (const item of items) {
+            const latest = validatedHistory(await reviewer.history(item.caseManifestId), item);
+            const consistent = (latest?.id ?? null) === item.priorDecisionId && (latest?.disposition ?? "unresolved") === item.disposition;
+            outcomes.set(item.caseManifestId, { disposition: consistent ? item.disposition : "unresolved", prior: item.priorDecisionId, resolution: !consistent || ["unresolved", "skip", "uncertain"].includes(item.disposition) ? "unresolved" : "label-recorded" });
+            const request = saved!.requests.find(r => r.caseManifestId === item.caseManifestId); if (request) await reconcileItem(item, request);
+          }
+          variants = [];
+          for (const c of publicBlind?.cards ?? []) {
+            const text: string[] = [];
+            for (const digest of c.artifactDigests) {
+              const bytes = await blind!.readArtifact(c.label, digest);
+              if (!(bytes instanceof Uint8Array) || bytes.byteLength > 65536 || byteDigest(bytes) !== digest) throw new Error("blind artifact unavailable/mismatched");
+              let preview = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+              if (fixture) preview = preview.replace(/Synthetic Layout [AB]/g, "Synthetic layout (fixture caption removed)");
+              text.push(preview.slice(0, 320) + (preview.length > 320 ? " [preview truncated]" : ""));
+            }
+            variants.push({ label: c.label, text });
+          }
+          if (blindBinding) {
+            choiceConfirmed = false; revealed = null;
+            const value = await blind!.quality!();
+            if (value !== null) {
+              const quality = blindChoice(value as BlindChoice, publicBlind!);
+              if (saved!.choice && dataKey(saved!.choice) !== dataKey(quality)) throw new Error("durable quality changed");
+              if (!saved!.choice) await persist({ ...saved!, choice: quality });
+              choiceConfirmed = true;
+            }
+          }
+          state = "open"; return api.view();
+        } catch { state = "unavailable: host data/persistence unknown"; poisoned = true; return api.view(); }
+      });
+    },
+    close() { state = "closed"; return api.view(); },
+    view(): Readonly<DebriefFrame> {
+      const cards: DebriefFrame["cards"] = state === "open" ? items.map((item, i) => ({ kind: "case", slot: i + 1, caseManifestId: item.caseManifestId,
+        priorDecisionId: outcomes.get(item.caseManifestId)?.prior ?? item.priorDecisionId, summary: reasons[item.candidate.reason] ?? "Unresolved case",
+        disposition: outcomes.get(item.caseManifestId)?.disposition ?? "unresolved", resolution: outcomes.get(item.caseManifestId)?.resolution ?? "unresolved",
+        actionEnabled: enabled() && !saved?.requests.some(r => r.caseManifestId === item.caseManifestId) })) : [];
+      if (state === "open" && publicBlind) cards.push({ kind: "blind", slot: cards.length + 1, variants, choice: saved?.choice ?? null, choiceConfirmed,
+        actionEnabled: Boolean(blind && (fixture || operatorIdentity) && persistence && (persistence.durability === "host-owned" || fixture) && !poisoned), revealed });
+      return freeze(detached({ version: "debrief-view-v1", mode: "manual", state, persistence: persistence?.durability === "host-owned" ? "host-checkpoint" : "session-only", total,
+        unexposed: Math.max(0, total - items.length), budgetSpent: saved ? saved.caseIds.length + (saved.blindDigest ? 1 : 0) : poisoned || !checkpointKnown ? null : 0,
+        ...(signals ? { observation: { batchId: signals.batchId, id: signals.observationId, issues } } : {}),
+        remainingBudget: !checkpointKnown || poisoned && !saved ? null : 5 - (saved ? saved.caseIds.length + (saved.blindDigest ? 1 : 0) : 0), cards, fixture, acceptance: "not-assessed", automatic: "unqualified", freshness: "snapshot-unknown" }));
+    },
+    async label(input: ReviewRequest) {
+      const request = reviewRequest(input);
+      return exclusive(async () => {
+        if (state !== "open" || !enabled()) throw new Error("genuine host writer/persistence unavailable");
+        const item = items.find(i => i.caseManifestId === request.caseManifestId); if (!item) throw new Error("case not exposed in this budget");
+        const prior = saved!.requests.find(r => r.caseManifestId === item.caseManifestId);
+        if (prior) { if (dataKey(prior) !== dataKey(request)) throw new Error("one immutable label request per card/pause"); return reconcileItem(item, request); }
+        if (request.priorDecisionId !== item.priorDecisionId) throw new Error("stale displayed label request");
+        try { await persist({ ...saved!, requests: [...saved!.requests, request] }); }
+        catch { poisoned = true; throw new Error("label request persistence unknown; no writer call"); }
+        outcomes.set(item.caseManifestId, { disposition: "unresolved", prior: item.priorDecisionId, resolution: "unresolved" });
+        try { await reviewer.decide!(request); } catch { return "unknown"; }
+        return reconcileItem(item, request);
+      });
+    },
+    async reconcile(caseManifestId: string) {
+      return exclusive(async () => {
+        const item = items.find(i => i.caseManifestId === caseManifestId), request = saved?.requests.find(r => r.caseManifestId === caseManifestId);
+        if (!item || !request) throw new Error("no exact pending request"); return reconcileItem(item, request);
+      });
+    },
+    async choose(input: BlindChoice) {
+      return exclusive(async () => {
+        if (state !== "open" || !blind || !publicBlind || !persistence || !fixture && !operatorIdentity || persistence.durability !== "host-owned" && !fixture) throw new Error("quality persistence/host unavailable");
+        const choice = blindChoice(input, publicBlind);
+        if (saved!.choice && dataKey(saved!.choice) !== dataKey(choice)) throw new Error("quality choice is locked");
+        try { if (!saved!.choice) await persist({ ...saved!, choice }); }
+        catch { poisoned = true; throw new Error("quality persistence unknown; no reveal"); }
+        const chosen = blindChoice(await blind.choose(choice) as BlindChoice, publicBlind);
+        if (dataKey(chosen) !== dataKey(choice)) throw new Error("quality acknowledgement mismatch");
+        if (blindBinding && dataKey(blindChoice(await blind.quality!() as BlindChoice, publicBlind)) !== dataKey(choice)) throw new Error("durable quality readback mismatch");
+        choiceConfirmed = true; return api.view();
+      });
+    },
+    async reveal() {
+      return exclusive(async () => {
+        if (state !== "open" || !blind || !saved?.choice || !choiceConfirmed || !persistence || !fixture && !operatorIdentity) throw new Error("confirmed quality choice required before reveal");
+        try { if (!saved.revealRequested) await persist({ ...saved, revealRequested: true }); }
+        catch { poisoned = true; throw new Error("reveal persistence unknown; no exposure"); }
+        if (blindBinding && dataKey(blindChoice(await blind.quality!() as BlindChoice, publicBlind!)) !== dataKey(saved.choice)) throw new Error("durable quality unavailable/changed");
+        const result = detached(await blind.reveal()) as Record<string, any>;
+        if (!result || Object.keys(result).sort().join() !== "arms,choice,manifestId,routingDefault" || result.routingDefault !== null || !Array.isArray(result.arms) || result.arms.length !== publicBlind!.cards.length || new Set(result.arms.map(a => a.label)).size !== result.arms.length || dataKey(blindChoice(result.choice, publicBlind!)) !== dataKey(saved.choice)) throw new Error("invalid reveal acknowledgement");
+        revealed = { arms: result.arms.map(a => {
+          if (Object.keys(a).sort().join() !== "armId,configuration,cost,costUnit,label" || !publicBlind!.cards.some(c => c.label === a.label) || !["wall_ms", "tool_calls", "usd"].includes(a.costUnit) || !(a.cost === null || typeof a.cost === "number" && Number.isFinite(a.cost) && a.cost >= 0) || typeof a.configuration !== "object" || a.configuration === null || Object.keys(a.configuration).sort().join() !== "configuration,effort,model,prompt,skill" || Object.values(a.configuration).some(v => typeof v !== "string")) throw new Error("invalid reveal arm");
+          return { label: a.label, configuration: a.configuration, cost: a.cost, costUnit: a.costUnit };
+        }), routingDefault: null, adoptionAuthorized: false };
+        return api.view();
+      });
+    },
+  };
+  presenters.add(api); return Object.freeze(api);
+}

package/src/delegate-types.ts

@@ -82,6 +82,8 @@ export interface DelegationContext {
    * non-interactive plan, because a governed child should not sit waiting for a human by accident.
    */
   interactive?: boolean;
+  /** Explicit host-owned pi persistence target; never model-facing and never enabled by archive observation. */
+  sessionFile?: string;
   /**
    * Total descendants this session may still create (`src/fanout.ts`). Split among children by the caller.
    *

package/src/delegate.ts

@@ -266,6 +266,7 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
     skillPaths: ctx.skillPaths,
     contextFiles: ctx.contextFiles,
     systemPrompt,
+    sessionFile: ctx.sessionFile,
     print: ctx.interactive ? false : undefined,
   });
 

package/src/dispatch-control.ts

@@ -0,0 +1,81 @@
+import { createHash } from "node:crypto";
+import { canonicalWorkJson, copyWorkJson, parseWorkJson } from "./work-ledger-json.ts";
+
+export interface DispatchRequest {
+  version: "1.0"; requestId: string; bindingDigest: string; expectedRevision: number;
+  action: "pause-dispatch" | "resume-dispatch" | "cancel-execution" | "revise-scope" | "reprioritize" | "select-alternative";
+  targetExecutionId: string | null;
+}
+/** Independent trusted host declarations, NOT a wire request field or a file loaded by the controller. */
+export interface DispatchAuthority { authorityDigest: string; requestDigests: readonly string[] }
+export interface DispatchRecord {
+  request: Readonly<DispatchRequest>; digest: string;
+  decision: "approved" | "authority-unavailable" | "unsupported" | "stale" | "busy";
+  application: "pending" | "applied" | "not-applied";
+  outcome: "boundary-pending" | "paused" | "enabled" | "refused";
+}
+export interface DispatchState { revision: number; paused: boolean; records: DispatchRecord[] }
+export interface DispatchSnapshot {
+  version: "dispatch-control-snapshot-v1"; bindingDigest: string; freshness: "snapshot-unknown"; revision: number; paused: boolean;
+  admission: "blocked-pending" | "paused" | "enabled"; acceptance: "not-assessed";
+  records: readonly Readonly<DispatchRecord>[];
+}
+const hex = (x: unknown): x is string => typeof x === "string" && /^[a-f0-9]{64}$/.test(x);
+const id = (x: unknown): x is string => typeof x === "string" && /^[a-zA-Z0-9:_-]{1,128}$/.test(x);
+export function controlShape(value: unknown, keys: string[]): asserts value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || ![Object.prototype, null].includes(Object.getPrototypeOf(value)) ||
+    Reflect.ownKeys(value).length !== keys.length || keys.some(k => { const d = Object.getOwnPropertyDescriptor(value, k); return !d?.enumerable || !Object.hasOwn(d, "value"); })) throw new TypeError("closed dispatch control data required");
+}
+export function dispatchRequest(input: DispatchRequest): Readonly<DispatchRequest> {
+  controlShape(input, ["version", "requestId", "bindingDigest", "expectedRevision", "action", "targetExecutionId"]);
+  if (input.version !== "1.0" || !id(input.requestId) || !hex(input.bindingDigest) || !Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0 || input.expectedRevision > 128 ||
+    !["pause-dispatch", "resume-dispatch", "cancel-execution", "revise-scope", "reprioritize", "select-alternative"].includes(input.action) ||
+    !(input.targetExecutionId === null || id(input.targetExecutionId)) || (input.action === "cancel-execution" ? input.targetExecutionId === null : input.targetExecutionId !== null)) throw new TypeError("invalid dispatch request");
+  return Object.freeze({ version: input.version, requestId: input.requestId, bindingDigest: input.bindingDigest,
+    expectedRevision: input.expectedRevision, action: input.action, targetExecutionId: input.targetExecutionId });
+}
+export function parseDispatchRequest(text: string): Readonly<DispatchRequest> {
+  if (typeof text !== "string" || Buffer.byteLength(text) > 4096) throw new TypeError("bounded dispatch JSON required");
+  return dispatchRequest(parseWorkJson(text) as unknown as DispatchRequest);
+}
+export function dispatchRequestDigest(input: DispatchRequest): string {
+  return createHash("sha256").update(canonicalWorkJson(copyWorkJson(dispatchRequest(input)))).digest("hex");
+}
+export function dispatchAuthority(input: DispatchAuthority | null): Readonly<DispatchAuthority> | null {
+  if (input === null) return null;
+  controlShape(input, ["authorityDigest", "requestDigests"]);
+  const copy = copyWorkJson(input.requestDigests);
+  if (!hex(input.authorityDigest) || !Array.isArray(copy) || copy.length > 128 || !copy.every(hex) || new Set(copy).size !== copy.length) throw new TypeError("invalid independent dispatch authority");
+  return Object.freeze({ authorityDigest: input.authorityDigest, requestDigests: Object.freeze([...copy] as string[]) });
+}
+export function dispatchDecision(state: DispatchState, request: DispatchRequest, authorized: boolean, otherPending = false): DispatchRecord["decision"] {
+  if (!authorized) return "authority-unavailable";
+  if (!["pause-dispatch", "resume-dispatch"].includes(request.action)) return "unsupported";
+  if (request.expectedRevision !== state.revision) return "stale";
+  if (otherPending || state.records.some(r => r.application === "pending")) return "busy";
+  return "approved";
+}
+/** Replay operational controls only; no work-intent or acceptance projection is maintained here. */
+export function replayDispatch(state: DispatchState, event: Record<string, unknown>, bindingDigest: string, active: number, otherPending = false): void {
+  if (event.type === "control-request") {
+    controlShape(event, ["type", "request", "decision"]);
+    const request = dispatchRequest(event.request as DispatchRequest), decision = event.decision as DispatchRecord["decision"];
+    if (state.records.length >= 128 || request.bindingDigest !== bindingDigest || state.records.some(r => r.request.requestId === request.requestId) ||
+      !["approved", "authority-unavailable", "unsupported", "stale", "busy"].includes(decision) ||
+      dispatchDecision(state, request, decision !== "authority-unavailable", otherPending) !== decision) throw new Error("invalid dispatch decision sequence");
+    state.records.push({ request, digest: dispatchRequestDigest(request), decision,
+      application: decision === "approved" ? "pending" : "not-applied", outcome: decision === "approved" ? "boundary-pending" : "refused" });
+    if (decision === "approved") state.revision++;
+  } else {
+    controlShape(event, ["type", "requestId"]);
+    const record = state.records.find(r => r.request.requestId === event.requestId);
+    if (event.type !== "control-apply" || !record || record.application !== "pending" || active !== 0) throw new Error("unverified dispatch application boundary");
+    state.paused = record.request.action === "pause-dispatch";
+    record.application = "applied"; record.outcome = state.paused ? "paused" : "enabled";
+  }
+}
+export function freezeDispatch(state: DispatchState, bindingDigest: string, otherPending = false): Readonly<DispatchSnapshot> {
+  return Object.freeze({ version: "dispatch-control-snapshot-v1", bindingDigest, freshness: "snapshot-unknown", revision: state.revision, paused: state.paused,
+    admission: otherPending || state.records.some(r => r.application === "pending") ? "blocked-pending" : state.paused ? "paused" : "enabled",
+    acceptance: "not-assessed", records: Object.freeze(state.records.map(r => Object.freeze({ ...r }))) });
+}

package/src/effect-profile-runtime.ts

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+
+export const DIGEST_PROFILE = "linux-bwrap-digest-v1" as const;
+export const DIGEST_WORKER = `const b=Buffer.from(process.argv[1],'base64');if(b.length>16384)process.exit(90);process.stdout.write(JSON.stringify({bytes:b.length,sha256:require('node:crypto').createHash('sha256').update(b).digest('hex')})+'\\n');`;
+export interface DigestRuntime { node: string; fingerprints: Readonly<Record<string, string>> }
+function executableDetails(path: string, st: { isFile(): boolean; mode: number; size: number }) {
+  return { path, regular: st.isFile(), mode: (st.mode & 0o7777).toString(8), size: st.size,
+    predicates: { notRegular: !st.isFile(), writable: (st.mode & 0o022) !== 0, oversize: st.size > 256 * 1024 * 1024 } };
+}
+/** Read-only independent observations; no installation, admission or namespace qualification. */
+export async function inspectDigestPrerequisites() {
+  const observations = [];
+  for (const requested of [process.execPath, "/usr/bin/bwrap", "/usr/bin/prlimit"]) {
+    try { const path = requested === process.execPath ? await realpath(requested) : requested;
+      const details = executableDetails(path, await lstat(path)); observations.push({ requested, ...details, conforms: !Object.values(details.predicates).some(Boolean) });
+    } catch (error) { observations.push({ requested, conforms: false, error: { code: (error as NodeJS.ErrnoException).code ?? null, message: String(error) } }); }
+  }
+  return { version: "digest-prerequisites-v1", platform: process.platform, nodeVersion: process.version, execPath: process.execPath,
+    conforms: process.platform === "linux" && observations.every(o => o.conforms), observations, qualification: "not-assessed" };
+}
+export async function digestRuntime(): Promise<DigestRuntime> {
+  if (process.platform !== "linux") throw new Error("Linux user/mount/PID/network namespaces required");
+  const node = await realpath(process.execPath), fingerprints: Record<string, string> = {};
+  for (const path of [node, "/usr/bin/bwrap", "/usr/bin/prlimit"]) {
+    const st = await lstat(path);
+    if (!st.isFile() || (st.mode & 0o022) !== 0 || st.size > 256 * 1024 * 1024) {
+      const details = executableDetails(path, st), code = details.predicates.notRegular ? "RUNTIME_NOT_REGULAR" : details.predicates.writable ? "RUNTIME_WRITABLE" : "RUNTIME_TOO_LARGE";
+      throw Object.assign(new Error("unsupported mutable runtime executable"), { code, path, details });
+    }
+    fingerprints[path] = createHash("sha256").update(await readFile(path)).digest("hex");
+  }
+  return Object.freeze({ node, fingerprints: Object.freeze(fingerprints) });
+}
+/** Internal fixed boundary builder. No user command/environment/workspace/destination interface. */
+export function digestNamespaceArgs(runtime: DigestRuntime, code: string, args: string[], fixture?: string): string[] {
+  return ["--unshare-all", "--die-with-parent", "--new-session", "--cap-drop", "ALL",
+    "--ro-bind", "/usr", "/usr", "--ro-bind", "/lib", "/lib", "--ro-bind", "/lib64", "/lib64",
+    "--dir", "/runtime", "--ro-bind", runtime.node, "/runtime/node",
+    ...(fixture ? ["--ro-bind", fixture, "/input"] : []),
+    "--proc", "/proc", "--dev", "/dev", "--clearenv", "--chdir", "/", "--",
+    "/usr/bin/prlimit", "--cpu=2:2", "--nofile=64:64", "--", "/runtime/node",
+    // No arbitrary code enters the production worker. Permission flags are additional tripwires,
+    // not a claim that Node's permission model is a hostile-JavaScript sandbox.
+    ...(fixture ? [] : ["--permission"]), "--max-old-space-size=32", "-e", code, ...args];
+}

package/src/effect-profile.ts

@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto";
+import { mkdtemp, mkdir, readlink, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { runChild, type ChildRunResult } from "./run-child.ts";
+import { runWithFinalizers } from "./finalization.ts";
+import { beginExecutionRetention, retentionConfigurationDigest } from "./execution-retention.ts";
+import { openResourceBudget, resourceBindingDigest, type AttemptDemand, type ResourcePermit, type GovernedBudgetBinding } from "./resource-budget.ts";
+import { intentKey, type IntentAdmission } from "./intent-control.ts";
+import { DIGEST_PROFILE, DIGEST_WORKER, digestNamespaceArgs, digestRuntime, type DigestRuntime } from "./effect-profile-runtime.ts";
+export { DIGEST_PROFILE } from "./effect-profile-runtime.ts";
+
+export interface DigestProfile { readonly profile: typeof DIGEST_PROFILE; readonly bindingDigest: string; readonly runtimeDigest: string }
+export class EffectProfileUnavailableError extends Error {
+  constructor(message: string) { super(message); this.name = "EffectProfileUnavailableError"; }
+}
+const profiles = new WeakMap<DigestProfile, { runtime: DigestRuntime; budget: ReturnType<typeof openResourceBudget> }>();
+export const isDigestProfile = (value: unknown): value is DigestProfile => typeof value === "object" && value !== null && profiles.has(value as DigestProfile);
+const hash = (bytes: Uint8Array | string) => createHash("sha256").update(bytes).digest("hex");
+function requireClean(result: ChildRunResult): void {
+  if (result.code !== 0 || result.spawnError || result.aborted || result.timedOut || result.truncated) throw new EffectProfileUnavailableError(`fixed native profile failed: ${result.spawnError ?? result.text ?? result.code}`);
+}
+const child = (runtime: DigestRuntime, code: string, args: string[], fixture?: string, signal?: AbortSignal) => runChild({
+  command: "/usr/bin/bwrap", args: digestNamespaceArgs(runtime, code, args, fixture), cwd: "/", env: {},
+  timeoutMs: 3000, killGraceMs: 50, hardDeadlineAt: Date.now() + 3500, maxOutputBytes: 4096, signal,
+});
+
+/** Actual bounded native probes, not an executable-presence flag. Trusted fixture code only. */
+export async function prepareDigestProfile(binding: GovernedBudgetBinding): Promise<Readonly<DigestProfile>> {
+  const budget = openResourceBudget(binding);
+  await budget.inspect(); // Required admission state failures remain failures, not an unavailable fallback.
+  const runtime = await digestRuntime();
+  const root = await mkdtemp(join(budget.binding.directory, "profile-probe-")), input = join(root, "input");
+  return runWithFinalizers(async () => {
+    await mkdir(input, { mode: 0o700 }); await writeFile(join(input, "allowed"), "owned-readable", { mode: 0o600 });
+    await writeFile(join(root, "outside"), "owned-outside", { mode: 0o600 });
+    const net = await readlink("/proc/self/ns/net");
+    const code = `const fs=require('node:fs');let failures=0;for(const fn of [()=>fs.readFileSync(${JSON.stringify(join(root, "outside"))}),()=>fs.writeFileSync('/input/denied','bad')]){try{fn()}catch(e){if(['ENOENT','EROFS'].includes(e.code))failures++}}if(failures!==2||fs.readFileSync('/input/allowed','utf8')!=='owned-readable'||fs.readlinkSync('/proc/self/ns/net')===${JSON.stringify(net)})process.exit(91);console.log('boundary-ok');`;
+    const boundary = await child(runtime, code, [], input); requireClean(boundary);
+    if (boundary.text.trim() !== "boundary-ok") throw new EffectProfileUnavailableError("native boundary probe did not establish its expected observations");
+    const permission = await child(runtime, `try{require('node:child_process').spawnSync('/runtime/node',['-e','process.exit(92)']);process.exit(93)}catch(e){if(e.code!=='ERR_ACCESS_DENIED')process.exit(94);console.log('descendant-denied')}`, []);
+    requireClean(permission);
+    if (permission.text.trim() !== "descendant-denied") throw new EffectProfileUnavailableError("descendant tripwire unavailable");
+    const sample = await child(runtime, DIGEST_WORKER, [Buffer.from("fixture").toString("base64")]); requireClean(sample);
+    if (sample.text !== JSON.stringify({ bytes: 7, sha256: hash("fixture") }) + "\n") throw new EffectProfileUnavailableError("fixed worker probe mismatch");
+    const result = Object.freeze({ profile: DIGEST_PROFILE, bindingDigest: resourceBindingDigest(budget.binding), runtimeDigest: retentionConfigurationDigest(runtime) });
+    profiles.set(result, { runtime, budget });
+    return result;
+  }, [{ label: "profile probe cleanup failed", run: () => rm(root, { recursive: true, force: true }) }]);
+}
+
+export interface DigestAttempt { attempt: Omit<AttemptDemand, "inputBytes" | "inputDigest">; bytes: Uint8Array; intent?: IntentAdmission }
+/** A fixed, useful non-shell operation: hash at most 16 KiB. No writable destinations or provider calls.
+ * The opaque profile is bound to one budget. A claimed profile name/receipt cannot authorize a launch. */
+export async function runDigestProfile(profile: DigestProfile, request: DigestAttempt, signal?: AbortSignal): Promise<Readonly<{
+  attemptId: string; output: ChildRunResult; digest: string | null;
+}>> {
+  const prepared = profiles.get(profile);
+  if (!prepared || profile.profile !== DIGEST_PROFILE) throw new EffectProfileUnavailableError("unsupported or unprobed effect profile; no launch");
+  const requestKeys = ["attempt", "bytes", ...(request && Object.hasOwn(request, "intent") ? ["intent"] : [])];
+  if (!request || typeof request !== "object" || Reflect.ownKeys(request).length !== requestKeys.length ||
+    !requestKeys.every(k => { const d = Object.getOwnPropertyDescriptor(request, k); return d && d.enumerable && Object.hasOwn(d, "value"); }) ||
+    !(request.bytes instanceof Uint8Array) || request.bytes.byteLength > 16384) throw new TypeError("bounded byte-only request required; no destination, code, money or workspace override");
+  const bytes = Buffer.from(request.bytes), inputDigest = hash(bytes);
+  const selectedIntent: IntentAdmission | undefined = Object.hasOwn(request, "intent") ? JSON.parse(intentKey(request.intent)) : undefined;
+  const descriptors = Object.getOwnPropertyDescriptors(request.attempt);
+  const keys = ["attemptId", "orderId", "experimentId", "kind", "parentAttemptId"];
+  if (Reflect.ownKeys(request.attempt).length !== keys.length || keys.some(k => !descriptors[k]?.enumerable || !Object.hasOwn(descriptors[k], "value"))) throw new TypeError("closed attempt identity required");
+  const attempt = Object.fromEntries(keys.map(k => [k, descriptors[k].value])) as DigestAttempt["attempt"];
+  if (signal?.aborted) throw new EffectProfileUnavailableError("cancelled before reservation/launch");
+  if (retentionConfigurationDigest(await digestRuntime()) !== profile.runtimeDigest) throw new EffectProfileUnavailableError("runtime changed since the native profile probe");
+  const permit = await prepared.budget.reserve({ ...attempt, inputBytes: bytes.length, inputDigest }, selectedIntent);
+  return executeReserved(profile, prepared.runtime, attempt, bytes, permit, "digest", signal);
+}
+
+export type FixedDigestOperation = "digest" | "hold";
+export interface ReservedDigestRun { readonly started: Promise<"spawned" | "settled-without-spawn">; run(signal?: AbortSignal): ReturnType<typeof runDigestProfile> }
+/** Atomic all-attempt admission; only minted closures hold the original permits. No caller-supplied permit. */
+export async function reserveDigestProfileBatch(profile: DigestProfile, requests: readonly { attempt: DigestAttempt["attempt"]; bytes: Uint8Array; operation: FixedDigestOperation }[]): Promise<readonly ReservedDigestRun[]> {
+  const prepared = profiles.get(profile);
+  if (!prepared || !Array.isArray(requests) || !requests.length || requests.length > 32 || Reflect.ownKeys(requests).length !== requests.length + 1 || Array.from({ length: requests.length }, (_, i) => Object.getOwnPropertyDescriptor(requests, String(i))).some(d => !d?.enumerable || !Object.hasOwn(d, "value"))) throw new EffectProfileUnavailableError("probed profile and bounded batch required");
+  const detached = requests.map(r => {
+    const descriptors = r && Object.getOwnPropertyDescriptors(r);
+    if (!descriptors || Reflect.ownKeys(r).length !== 3 || ["attempt", "bytes", "operation"].some(k => !descriptors[k]?.enumerable || !Object.hasOwn(descriptors[k], "value"))) throw new TypeError("closed data variant required");
+    if (!r || !["digest", "hold"].includes(r.operation) || !(r.bytes instanceof Uint8Array) || r.bytes.length > 16384 || Object.keys(r).sort().join() !== "attempt,bytes,operation") throw new TypeError("fixed byte-only variant required");
+    return { attempt: JSON.parse(intentKey(r.attempt)) as DigestAttempt["attempt"], bytes: Buffer.from(r.bytes), operation: r.operation };
+  });
+  if (retentionConfigurationDigest(await digestRuntime()) !== profile.runtimeDigest) throw new EffectProfileUnavailableError("runtime changed before batch");
+  const permits = await prepared.budget.reserveBatch(detached.map(r => ({ ...r.attempt, inputBytes: r.bytes.length, inputDigest: hash(r.bytes) })));
+  return Object.freeze(detached.map((r, i) => {
+    let used = false, resolveStarted!: (value: "spawned" | "settled-without-spawn") => void;
+    const started = { promise: new Promise<"spawned" | "settled-without-spawn">(resolve => { resolveStarted = resolve; }), resolve: (value: "spawned" | "settled-without-spawn") => resolveStarted(value) };
+    return Object.freeze({ started: started.promise, async run(signal?: AbortSignal) {
+      if (used) throw new Error("reserved execution already consumed; no replay"); used = true;
+      try { return await executeReserved(profile, prepared.runtime, r.attempt, r.bytes, permits[i], r.operation, signal, () => started.resolve("spawned")); }
+      finally { started.resolve("settled-without-spawn"); } // Settled-without-spawn also unblocks waiters; never a spawn/identity claim.
+    } });
+  }));
+}
+
+async function executeReserved(profile: DigestProfile, runtime: DigestRuntime, attempt: DigestAttempt["attempt"], bytes: Buffer, permit: ResourcePermit, operation: FixedDigestOperation, signal?: AbortSignal, started?: () => void) {
+  const inputDigest = hash(bytes), code = operation === "digest" ? DIGEST_WORKER : "setInterval(()=>{},1000);";
+  // From this point every outcome costs the full reservation. No posthoc result refunds resources.
+  const retention = beginExecutionRetention({ executionId: attempt.attemptId, parentExecutionId: attempt.parentAttemptId,
+    childId: "digest", toolCallId: null, executor: "process", taskDigest: inputDigest, definitionDigest: hash(code),
+    configurationDigest: retentionConfigurationDigest({ profile: profile.profile, binding: profile.bindingDigest, runtime: profile.runtimeDigest }), workspaceId: null });
+  let output: ChildRunResult | undefined;
+  let outcome: "completed" | "failed" | "cancelled" = "failed";
+  let accountingFailed = false, spawned = false, exitObserved = false;
+  return runWithFinalizers(async () => {
+    if (!signal?.aborted && retentionConfigurationDigest(await digestRuntime()) !== profile.runtimeDigest) throw new EffectProfileUnavailableError("runtime changed after admission");
+    output = await runChild({ command: "/usr/bin/bwrap", args: digestNamespaceArgs(runtime, code, [bytes.toString("base64")]),
+      cwd: "/", env: {}, signal, timeoutMs: 3000, killGraceMs: 50, hardDeadlineAt: Date.now() + 3500, maxOutputBytes: 4096,
+      onSpawn: pid => { spawned = true; retention.native({ pid }); started?.(); }, onObservation: (stream, data) => retention.capture(stream, data) });
+    exitObserved = output.code !== null || Boolean(output.signal);
+    if (spawned && !exitObserved) throw new Error("owned executor exit unknown; reservation retained");
+    const completed = output.code === 0 && !output.aborted && !output.spawnError && !output.timedOut && !output.truncated;
+    if (completed && output.text !== JSON.stringify({ bytes: bytes.length, sha256: inputDigest }) + "\n") throw new Error("fixed worker result mismatch");
+    outcome = output.aborted && (!spawned || Boolean(output.signal)) ? "cancelled" : completed ? "completed" : "failed";
+    retention.capture("result", Buffer.from(output.text), true);
+    return Object.freeze({ attemptId: attempt.attemptId, output, digest: completed ? inputDigest : null });
+  }, [{ label: "required resource settlement failed", run: async () => {
+    // Only this live controller, after executor settlement, releases a slot. Cleanup failure still rejects.
+    // Crashes/lost controllers keep their slots; reopening has no expiry, receipt-credit or reclaim API.
+    try { if (spawned && !exitObserved) throw new Error("owned executor exit unknown; no settlement credit"); await permit.settle(outcome); } catch (error) { accountingFailed = true; throw error; }
+  } }, { label: "retention observation failed", run: () => {
+    retention.finish({ code: output?.code ?? null, signal: output?.signal ?? null, timedOut: output?.timedOut ?? false,
+      aborted: output?.aborted ?? Boolean(signal?.aborted), truncated: output?.truncated ?? false, failed: outcome !== "completed" || accountingFailed });
+  } }]);
+}