pi-daddy 0.28.0 → 0.32.0

package/src/effect-profile.ts

@@ -1,129 +0,0 @@
-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 });
-  } }]);
-}

package/src/execution-retention.ts

@@ -1,230 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { mkdir, writeFile, rename } from "node:fs/promises";
-import { isAbsolute, join } from "node:path";
-import { buildExecutionRetentionManifest } from "./retention-contract.ts";
-import { missingNativeSession, readNativeSession, type NativeSessionObservation, type NativeSessionManager, type NativeSessionCapture } from "./native-session.ts";
-export { buildExecutionRetentionManifest, parseExecutionRetentionManifest, RETENTION_SCHEMA } from "./retention-contract.ts";
-export { ENV_NATIVE_SESSION_ROOT, readNativeSession, parseNativeSessionBytes, type NativeSessionObservation, type NativeSessionManager } from "./native-session.ts";
-
-/** Operator-owned archive boundary; never a model-facing parameter or an authority source. */
-export const ENV_EXECUTION_ARCHIVE = "PI_GRANTS_EXECUTION_ARCHIVE";
-export const RETENTION_VERSION = "2.0";
-const LIMIT = 1024 * 1024;
-const MAX_ACTIVE = 32;
-let active = 0;
-const digest = (bytes: Uint8Array | string) => createHash("sha256").update(bytes).digest("hex");
-export interface RetentionIdentity {
-  executionId: string;
-  parentExecutionId: string | null;
-  childId: string;
-  toolCallId: string | null;
-  executor: "process" | "herdr" | "check";
-  taskDigest: string | null;
-  definitionDigest: string | null;
-  configurationDigest: string;
-  workspaceId: string | null;
-}
-export interface RetainedContent {
-  status: "retained" | "missing";
-  path: string | null;
-  sha256: string | null;
-  bytes: number | null;
-}
-export interface ExecutionRetentionManifest {
-  version: "2.0";
-  archiveId: string;
-  identity: RetentionIdentity;
-  native: { pid: number | null; paneId: string | null; agentName: string | null; tabId: string | null;
-    sessionId: string | null; sessionPath: string | null; branchLeafId: string | null };
-  nativeSession: NativeSessionObservation;
-  state: "running" | "terminal";
-  outcome: { code: number | null; signal: string | null; timedOut: boolean; aborted: boolean;
-    truncated: boolean; failed: boolean } | null;
-  content: Record<"stdout" | "stderr" | "paneSnapshot" | "checkReceipt" | "result" | "session", RetainedContent>;
-  coverage: { complete: false; losses: string[] };
-  /** Retention is observation, never a work-v4 acceptance decision. */
-  acceptance: "not-assessed";
-}
-export interface RetentionStatus { manifestPath: string | null; status: "disabled" | "pending" | "retained" | "lost" }
-const drains = new WeakMap<RetentionStatus, () => Promise<RetentionStatus>>();
-/** Original live status only; drains admitted observations, not producer completeness or fsync. */
-export function drainExecutionRetention(status: RetentionStatus): Promise<RetentionStatus> {
-  const drain = drains.get(status);
-  if (!drain) return Promise.reject(new TypeError("original live retention status required"));
-  return drain();
-}
-const missing = (): RetainedContent => ({ status: "missing", path: null, sha256: null, bytes: null });
-
-/** Hash only an explicitly selected configuration. Callers must not pass environment/auth objects. */
-export const retentionConfigurationDigest = (configuration: unknown): string => digest(JSON.stringify(configuration));
-
-/**
- * A bounded, coalescing observation queue. No worker-control path awaits publication. A failed or stalled
- * archive never changes required ledger/lease semantics. `flush` is exclusively for external archival at
- * quiescence; it is NOT called by the spawner. Missing terminal publication means incomplete observation.
- */
-export function beginExecutionRetention(identity: RetentionIdentity, directory = process.env[ENV_EXECUTION_ARCHIVE]) {
-  const archiveId = randomUUID();
-  const valid = Boolean(directory && isAbsolute(directory) && !directory.split(/[\\/]/).includes(".pi"));
-  const admitted = valid && active < MAX_ACTIVE;
-  const root = admitted ? join(directory!, archiveId) : null;
-  const manifestPath = root ? join(root, "manifest.json") : null;
-  let status: RetentionStatus["status"] = !directory ? "disabled" : admitted ? "pending" : "lost";
-  const manifest: ExecutionRetentionManifest = {
-    version: RETENTION_VERSION, archiveId, identity: {
-      executionId: identity.executionId, parentExecutionId: identity.parentExecutionId, childId: identity.childId,
-      toolCallId: identity.toolCallId, executor: identity.executor, taskDigest: identity.taskDigest,
-      definitionDigest: identity.definitionDigest, configurationDigest: identity.configurationDigest, workspaceId: identity.workspaceId,
-    },
-    native: { pid: null, paneId: null, agentName: null, tabId: null, sessionId: null, sessionPath: null, branchLeafId: null },
-    nativeSession: missingNativeSession(),
-    state: "running", outcome: null,
-    content: { stdout: missing(), stderr: missing(), paneSnapshot: missing(), checkReceipt: missing(), result: missing(), session: missing() },
-    coverage: { complete: false, losses: ["native-session-content-unavailable", "active-branch-unknown"] },
-    acceptance: "not-assessed",
-  };
-  const buffers = new Map<keyof typeof manifest.content, Buffer>();
-  const written = new Set<string>();
-  let total = 0;
-  let dirty = false;
-  let running: Promise<void> | undefined;
-  let finished = false;
-  let released = false;
-  let nativeTask: Promise<void> | undefined;
-  let nextNative: { source: "herdr-id" | "herdr-path" | "pi-session-file" | "pi-session-manager"; value: string; manager?: NativeSessionManager } | undefined;
-  let pinnedSessionId: string | undefined;
-  let pinnedFile: NativeSessionCapture["fileIdentity"];
-  const loss = (reason: string) => { if (!manifest.coverage.losses.includes(reason)) manifest.coverage.losses.push(reason); };
-  const release = () => { if (admitted && !released) { active--; released = true; } };
-  if (admitted) active++;
-  else if (directory) loss("archive-unavailable-or-capacity-exceeded");
-  const publish = async () => {
-    try {
-      await mkdir(root!, { recursive: true, mode: 0o700 });
-      while (dirty) {
-        dirty = false;
-        // Detached checkpoint: asynchronous I/O cannot mix later outcome/content into this generation.
-        const checkpoint: ExecutionRetentionManifest = JSON.parse(JSON.stringify(manifest));
-        const contents = [...buffers];
-        for (const [kind, bytes] of contents) {
-          const sha256 = digest(bytes);
-          const name = `${kind}-${sha256}.bin`;
-          if (!written.has(name)) {
-            await writeFile(join(root!, name), bytes, { flag: "wx", mode: 0o600 });
-            written.add(name);
-          }
-          checkpoint.content[kind] = { status: "retained", path: name, sha256, bytes: bytes.length };
-        }
-        await writeFile(join(root!, "manifest.pending"), JSON.stringify(buildExecutionRetentionManifest(checkpoint)) + "\n", { mode: 0o600 });
-        await rename(join(root!, "manifest.pending"), manifestPath!);
-        status = "retained";
-      }
-    } catch {
-      status = "lost";
-      loss("archive-write-failed");
-      buffers.clear();
-      release();
-    } finally {
-      running = undefined;
-      if (finished && !nativeTask) { buffers.clear(); release(); }
-    }
-  };
-  const schedule = () => {
-    if (!admitted || status === "lost" || released) return;
-    dirty = true;
-    status = "pending";
-    if (!running) running = Promise.resolve().then(publish);
-  };
-  const observeSession = (reference: NonNullable<typeof nextNative>) => {
-    if (finished || !admitted || released || status === "lost") return;
-    if (nextNative && (nextNative.source !== reference.source || nextNative.value !== reference.value)) loss("native-session-reference-coalesced");
-    nextNative = { source: reference.source, value: reference.value, ...(reference.manager ? { manager: reference.manager } : {}) };
-    if (nativeTask) return;
-    nativeTask = Promise.resolve().then(async () => {
-      while (nextNative) {
-        const current = nextNative; nextNative = undefined;
-        const captured: NativeSessionCapture = current.source === "herdr-id"
-          ? { observation: { ...missingNativeSession(), source: current.source, status: "missing" as const,
-              sessionId: current.value, reason: "native-session-path-unavailable" } }
-          : await readNativeSession({ path: current.value, source: current.source, manager: current.manager, expectedSessionId: pinnedSessionId, expectedFile: pinnedFile });
-        if (captured.observation.sessionId && captured.fileIdentity) pinnedFile ??= captured.fileIdentity;
-        let observation = captured.observation;
-        if (pinnedSessionId && observation.sessionId && pinnedSessionId !== observation.sessionId) {
-          observation = { ...missingNativeSession(), source: current.source, status: "changed", reason: "native-session-id-changed" };
-        }
-        if (observation.sessionId) pinnedSessionId ??= observation.sessionId;
-        manifest.nativeSession = { ...observation };
-        manifest.native.sessionId = observation.sessionId;
-        manifest.native.sessionPath = observation.sessionPath;
-        manifest.native.branchLeafId = observation.branchLeafId;
-        buffers.delete("session");
-        if (captured.bytes && observation === captured.observation) buffers.set("session", captured.bytes);
-        if (observation.reason) loss(observation.reason);
-        schedule();
-      }
-    }).catch(() => { loss("native-session-observation-failed"); }).finally(() => { nativeTask = undefined; schedule(); });
-  };
-  const drain = async (): Promise<RetentionStatus> => {
-    while (nativeTask || running) { if (nativeTask) await nativeTask; if (running) await running; }
-    return { manifestPath, status };
-  };
-  schedule();
-  return {
-    /** Read-only native API reference; never derive IDs from the locator or a displayed name. */
-    observeSession,
-    observeSessionManager(manager: NativeSessionManager) {
-      try {
-        const value = manager.getSessionFile();
-        if (value) observeSession({ source: "pi-session-manager", value, manager });
-        else { loss("native-session-not-persisted"); schedule(); }
-      } catch { loss("native-session-manager-unavailable"); schedule(); }
-    },
-    status: (): RetentionStatus => { const value = { manifestPath, status }; drains.set(value, drain); return value; },
-    native(value: Partial<Pick<ExecutionRetentionManifest["native"], "pid" | "paneId" | "agentName" | "tabId">>) {
-      if (finished) return;
-      for (const key of ["pid", "paneId", "agentName", "tabId"] as const) {
-        const item = value[key];
-        if (key === "pid") { if (typeof item === "number" && Number.isSafeInteger(item) && item > 0) manifest.native.pid = item; }
-        else if (typeof item === "string" && item.length <= 4096) manifest.native[key] = item;
-      }
-      schedule();
-    },
-    capture(kind: "stdout" | "stderr" | "paneSnapshot" | "checkReceipt" | "result", bytes: Uint8Array, replace = false) {
-      if (finished || !admitted || status === "lost") return;
-      const indivisible = kind === "checkReceipt" || kind === "result";
-      if (indivisible) replace = true;
-      const old = buffers.get(kind) ?? Buffer.alloc(0);
-      const available = indivisible ? LIMIT : LIMIT - total + (replace ? old.length : 0);
-      // Receipts and assembled results each have reserved capacity and are never partially published.
-      if (indivisible && bytes.length > available) { loss(`${kind === "checkReceipt" ? "check-receipt" : kind}-not-retained-capacity`); schedule(); return; }
-      const kept = Buffer.from(bytes.subarray(0, Math.max(0, available)));
-      if (kept.length !== bytes.length) loss(`${kind}-observation-dropped`);
-      if (kind === "paneSnapshot") loss("pane-snapshot-not-full-transcript");
-      const next = replace ? kept : Buffer.concat([old, kept]);
-      if (!indivisible) total += next.length - old.length;
-      buffers.set(kind, next);
-      schedule();
-    },
-    finish(outcome: NonNullable<ExecutionRetentionManifest["outcome"]>) {
-      if (finished) return;
-      manifest.outcome = { code: outcome.code, signal: outcome.signal, timedOut: outcome.timedOut,
-        aborted: outcome.aborted, truncated: outcome.truncated, failed: outcome.failed };
-      manifest.state = "terminal";
-      if (outcome.truncated) loss("executor-output-truncated");
-      if (outcome.aborted || outcome.timedOut) loss("execution-interrupted");
-      finished = true;
-      schedule();
-    },
-    /** Observation-only diagnostic; never establishes successful execution or accepted work. */
-    coverage: () => ({ complete: false as const, losses: [...manifest.coverage.losses] }),
-    flush: drain,
-  };
-}
-export type ExecutionRetention = ReturnType<typeof beginExecutionRetention>;
-
-/** Public consumer check: neither a reference nor a wire status supplies the missing bytes. */
-export function verifyRetainedBytes(reference: RetainedContent, bytes?: Uint8Array): "retained" | "missing" | "mismatch" {
-  if (reference.status !== "retained" || bytes === undefined) return "missing";
-  if (reference.bytes !== bytes.byteLength || reference.sha256 !== digest(bytes)) return "mismatch";
-  return "retained";
-}

package/src/executor.ts

@@ -1,123 +0,0 @@
-/**
- * Which executor runs a governed child — ADR-0031.
- *
- * `PI_GRANTS_HERDR` is three-state, and **absent means probe**. That reverses ADR-0016 point 6's opt-in, and
- * the reversal is narrower than it sounds: nothing is detected from `herdr` being on `PATH` (option C, rejected
- * by name), only from a server that *answered*. The grant, the depth bound, the gate and `--tools` enforcement
- * are identical either way — `planSpawn` produces one plan and both executors enforce it.
- *
- * **Pure on purpose.** The probe is I/O and lives in `herdr-cli.ts`; the DECISION is a table, and a table that
- * fits on one screen is the only reason a reversal like this is reviewable at all.
- *
- * The disclosure string is part of the return value rather than composed at the call site, because ADR-0031's
- * defence against "this relocates silently" is that every outcome says what it chose AND what to set instead.
- * Two call sites composing that separately is how one of them comes to omit it (R-28).
- */
-
-import type { HerdrProbe } from "./herdr-cli.ts";
-
-export const ENV_HERDR = "PI_GRANTS_HERDR";
-
-export const EXECUTOR_KINDS = ["process", "herdr"] as const;
-export type ExecutorKind = typeof EXECUTOR_KINDS[number];
-
-export interface ExecutorChoice {
-  kind: ExecutorKind;
-  /** The operator named it: `PI_GRANTS_HERDR` was exactly `0` or `1`. */
-  forced: boolean;
-  /** Whether a probe was needed at all — false only for `0`. */
-  probed: boolean;
-  /**
-   * Set ONLY when herdr was demanded and is unreachable. Every delegation must refuse with this.
-   *
-   * Note that `kind` stays `"herdr"` in that case, deliberately: nothing downstream may mistake a refusing
-   * session for a working process-executor one.
-   */
-  refusal?: string;
-  /** One line for the session banner and `/grants`. Always present. */
-  disclosure: string;
-}
-
-/** `0` is the one value that needs no probe: the operator ruled herdr out, so asking is pure cost. */
-export function needsProbe(raw: string | undefined): boolean {
-  return raw === undefined || raw === "1";
-}
-
-export function chooseExecutor(raw: string | undefined, probe: HerdrProbe | null): ExecutorChoice {
-  if (raw === "0") {
-    return {
-      kind: "process",
-      forced: true,
-      probed: false,
-      disclosure: "captured subprocess (PI_GRANTS_HERDR=0) — children have no terminal",
-    };
-  }
-
-  if (raw === "1") {
-    if (probe?.ok) {
-      return { kind: "herdr", forced: true, probed: true, disclosure: "herdr panes (PI_GRANTS_HERDR=1)" };
-    }
-    // Refusal, not fallback — the operator's decision of 2026-08-17, against the alternative of falling back
-    // loudly. A fallback nobody reads is R-25's shape; refusing keeps the ledger unable to name a child that
-    // ran somewhere nobody chose. A `null` probe lands here too: if the probe failed so badly it produced no
-    // result, herdr was still demanded, and failing closed means refusing.
-    const why = probe?.error ?? "the herdr probe did not succeed";
-    return {
-      kind: "herdr",
-      forced: true,
-      probed: true,
-      refusal:
-        `PI_GRANTS_HERDR=1 demands the herdr executor and herdr is not answering (${why}). ` +
-        `Delegation is refused rather than quietly relocated to a captured subprocess, so this session's ` +
-        `ledger can never contain a child that ran somewhere nobody chose. Start herdr, or unset ` +
-        `PI_GRANTS_HERDR to let this session probe, or set PI_GRANTS_HERDR=0 to choose subprocesses.`,
-      disclosure: `herdr panes DEMANDED but unreachable (${why}) — every delegation will refuse`,
-    };
-  }
-
-  if (raw !== undefined) {
-    // Rule 8: fail closed and be loud. An unrecognised value must not relocate a run, and must not break
-    // delegation either — the operator meant *something*, and the dependency-free executor is the safe read.
-    // The empty string lands here rather than with `undefined`, which keeps absent-versus-empty
-    // distinguishable exactly as `PI_GRANTS_GATED` does.
-    return {
-      kind: "process",
-      forced: false,
-      probed: probe !== null,
-      disclosure:
-        `captured subprocess — PI_GRANTS_HERDR is set to an unrecognised value and was ignored. ` +
-        `Use 1 (demand herdr panes), 0 (demand subprocesses), or unset it to probe.`,
-    };
-  }
-
-  if (probe?.ok) {
-    return { kind: "herdr", forced: false, probed: true, disclosure: "herdr panes (probed — herdr is answering)" };
-  }
-  if (probe === null) {
-    // **The pre-probe seed, and it must not claim a probe happened.** `createGrantsSession` builds a choice
-    // synchronously with `probe: null` because S-5 forces the factory to run before any hook; `resolveExecutor`
-    // replaces it during `session_start`. This branch previously fell through to the one below and reported
-    // `probed: true` with the word "(probed)" in its disclosure — a fabricated observation, indistinguishable
-    // from a real negative probe.
-    //
-    // Unreachable in practice today (pi awaits the `session_start` emit before the first prompt, verified by a
-    // reviewer against real pi), which is exactly why it is worth making honest rather than leaving to be
-    // discovered: if a throw ever strands a session on this reading, the disclosure should say so.
-    return {
-      kind: "process",
-      forced: false,
-      probed: false,
-      disclosure: "not yet probed — settling at session start",
-    };
-  }
-  return {
-    kind: "process",
-    forced: false,
-    probed: true,
-    // Names the remedy on the same line as the state. The gap that produced ADR-0031 was not that the
-    // operator could not see which executor ran — it was that seeing it would not have told them what to do.
-    disclosure:
-      `captured subprocess (probed — no herdr answering${probe?.error ? `: ${probe.error}` : ""}). ` +
-      `Set PI_GRANTS_HERDR=1 to demand panes.`,
-  };
-}

package/src/experiment-contract.ts

@@ -1,66 +0,0 @@
-import type { WorkFrozen } from "./work-ledger-types.ts";
-import { createHash } from "node:crypto";
-import { intentKey, type WorkIntentBinding } from "./intent-control.ts";
-import { workIntentBinding } from "./intent-application.ts";
-import { freezeWork, parseWorkJson } from "./work-ledger-json.ts";
-import { orderSchedule, type OrderSchedule } from "./order-schedule.ts";
-import { DIGEST_PROFILE } from "./effect-profile.ts";
-export const experimentHash = (value: unknown) => createHash("sha256").update(intentKey(value)).digest("hex");
-export const byteHash = (bytes: Uint8Array | string) => createHash("sha256").update(bytes).digest("hex");
-export const cloneExperiment = <T>(value: T): T => JSON.parse(intentKey(value));
-export function closed(value: unknown, keys: string[]): asserts value is Record<string, unknown> {
-  if (!value || typeof value !== "object" || Object.keys(value).sort().join() !== keys.sort().join()) throw new TypeError("closed experiment data required");
-}
-const id = (x: unknown) => typeof x === "string" && /^[a-zA-Z0-9:_-]{1,128}$/.test(x);
-const hex = (x: unknown) => typeof x === "string" && /^[a-f0-9]{64}$/.test(x);
-export interface ExperimentVariant {
-  variantId: string; executionId: string; kind: "primary" | "shadow" | "retry";
-  parentExecutionId: string | null; suffixBase64: string; operation: "digest" | "hold";
-  configuration: { model: null; effort: null; skills: null };
-}
-export interface ExperimentCharter {
-  version: "fixed-experiment-v1" | "fixed-experiment-v2"; order?: OrderSchedule; experimentId: string; orderId: string; budgetDigest: string;
-  profile: typeof DIGEST_PROFILE; common: { sha256: string; bytes: number; work: WorkFrozen<WorkIntentBinding> | null; workTextDigest: string | null };
-  mode: "bounded-waves" | "concurrent-shadow"; deadlineMs: number; variants: readonly ExperimentVariant[];
-}
-export function experimentCharter(input: ExperimentCharter): ExperimentCharter {
-  const c = cloneExperiment(input); closed(c, ["version", "experimentId", "orderId", "budgetDigest", "profile", "common", "mode", "deadlineMs", "variants", ...(c.version === "fixed-experiment-v2" ? ["order"] : [])]);
-  if (!["fixed-experiment-v1", "fixed-experiment-v2"].includes(c.version) || !id(c.experimentId) || !id(c.orderId) || !hex(c.budgetDigest) || c.profile !== DIGEST_PROFILE || !["bounded-waves", "concurrent-shadow"].includes(c.mode) || !Number.isSafeInteger(c.deadlineMs) || c.deadlineMs < 1000 || c.deadlineMs > 30000 || Buffer.byteLength(intentKey(c)) > 48000) throw new TypeError("unsupported experiment charter/profile");
-  closed(c.common, ["sha256", "bytes", "work", "workTextDigest"]);
-  if (!hex(c.common.sha256) || !Number.isSafeInteger(c.common.bytes) || c.common.bytes < 0 || c.common.bytes > 16384) throw new TypeError("bounded common input required");
-  if (c.common.work !== null) { c.common.work = workIntentBinding(JSON.parse(intentKey(c.common.work))); if (!hex(c.common.workTextDigest)) throw new TypeError("exact work bytes required"); }
-  else if (c.common.workTextDigest !== null) throw new TypeError("unexpected work digest");
-  if (!Array.isArray(c.variants) || c.variants.length < (c.version === "fixed-experiment-v2" ? 1 : 2) || c.variants.length > 32) throw new TypeError("2..32 explicit attempts required");
-  const ids = new Set<string>(), variants = new Set<string>();
-  for (const [i, v] of (c.variants as readonly ExperimentVariant[]).entries()) {
-    closed(v, ["variantId", "executionId", "kind", "parentExecutionId", "suffixBase64", "operation", "configuration"]);
-    closed(v.configuration, ["model", "effort", "skills"]);
-    if (!id(v.variantId) || !id(v.executionId) || ids.has(v.executionId) || variants.has(v.variantId) || !["digest", "hold"].includes(v.operation) || Object.values(v.configuration).some(x => x !== null)) throw new TypeError("unknown/general configuration cannot execute");
-    if (c.version === "fixed-experiment-v2" ? !["primary", "retry"].includes(v.kind) || (v.kind === "primary" ? v.parentExecutionId !== null : !ids.has(v.parentExecutionId!)) : i === 0 ? v.kind !== "primary" || v.parentExecutionId !== null || v.operation !== "digest" : !["shadow", "retry"].includes(v.kind) || !ids.has(v.parentExecutionId!)) throw new TypeError("explicit ordered parent/primary required");
-    if (typeof v.suffixBase64 !== "string" || v.suffixBase64.length > 22000 || Buffer.from(v.suffixBase64, "base64").toString("base64") !== v.suffixBase64 || c.common.bytes + Buffer.from(v.suffixBase64, "base64").length > 16384) throw new TypeError("invalid bounded byte difference");
-    ids.add(v.executionId); variants.add(v.variantId);
-  }
-  if (c.mode === "concurrent-shadow" && (c.variants.length !== 2 || c.variants[1].kind !== "shadow")) throw new TypeError("concurrent shadow requires exactly primary and shadow");
-  if (c.version === "fixed-experiment-v2") {
-    if (c.mode !== "bounded-waves" || !c.common.work) throw new Error("orders require pinned work and bounded scheduling");
-    c.order = orderSchedule(c.order!, c.variants.map(v => v.executionId));
-    for (const n of c.order.nodes) for (const [i,id] of n.executions.entries()) { const v=c.variants.find(v=>v.executionId===id)!; if(i ? v.kind!=="retry"||v.parentExecutionId!==n.executions[i-1] : v.kind!=="primary") throw new Error("node recovery lineage mismatch"); }
-  }
-  return freezeWork(c) as ExperimentCharter;
-}
-export const parseExperimentCharter = (text: string) => experimentCharter(parseWorkJson(text) as unknown as ExperimentCharter);
-export const experimentCharterDigest = (c: ExperimentCharter) => experimentHash(experimentCharter(c));
-export interface ExperimentAuthority { authorityDigest: string; charterDigests: readonly string[]; cancellationDigests: readonly string[] }
-export function experimentAuthority(value: ExperimentAuthority | null): ExperimentAuthority | null {
-  if (value === null) return null;
-  const a = cloneExperiment(value); closed(a, ["authorityDigest", "charterDigests", "cancellationDigests"]);
-  if (!hex(a.authorityDigest) || [a.charterDigests, a.cancellationDigests].some(xs => !Array.isArray(xs) || xs.length > 128 || xs.some(x => !hex(x)))) throw new TypeError("independent bounded host approvals required");
-  return freezeWork(a);
-}
-export interface ExperimentCancellation { version: "experiment-cancel-v1"; requestId: string; bindingDigest: string; executionId: string }
-export function experimentCancellation(value: ExperimentCancellation): ExperimentCancellation {
-  const c = cloneExperiment(value); closed(c, ["version", "requestId", "bindingDigest", "executionId"]);
-  if (c.version !== "experiment-cancel-v1" || !id(c.requestId) || !hex(c.bindingDigest) || !id(c.executionId)) throw new TypeError("exact cancellation required");
-  return freezeWork(c);
-}
-export const experimentCancellationDigest = (c: ExperimentCancellation) => experimentHash(experimentCancellation(c));

package/src/experiment-state.ts

@@ -1,44 +0,0 @@
-import { closed, experimentCancellation, type ExperimentCancellation, type ExperimentCharter, type ExperimentVariant } from "./experiment-contract.ts";
-import { factoryDecision, type FactoryDecision } from "./order-schedule.ts";
-export type VariantState = "unstarted" | "queued" | "dispatching" | "running" | "completed" | "failed" | "cancelled" | "timed-out" | "unknown";
-export interface VariantRecord extends Pick<ExperimentVariant, "variantId" | "kind" | "operation"> { executionId: string; state: VariantState; artifactDigest: string | null; spawned: boolean }
-export function replayExperiment(c: ExperimentCharter, events: Record<string, unknown>[]) {
-  let claim: { owner: string; deadlineAt: number } | null = null, admitted = false;
-  const variants: VariantRecord[] = c.variants.map(v => ({ variantId: v.variantId, kind: v.kind, operation: v.operation, executionId: v.executionId, state: "unstarted", artifactDigest: null, spawned: false }));
-  const cancellations: ExperimentCancellation[] = [], decisions: FactoryDecision[] = [];
-  let superseded = false, controllerFailed = false;
-  for (const e of events) {
-    if (e.type === "order-decision") {
-      closed(e,["type","request"]);const d=factoryDecision(e.request as FactoryDecision);
-      if(!c.order || !c.order.nodes.some(n=>n.nodeId===d.nodeId&&n.decision?.authorityId===d.authorityId)||decisions.some(r=>r.nodeId===d.nodeId||r.requestId===d.requestId))throw new Error("invalid order decision sequence");decisions.push(d);
-    } else if(e.type === "order-migrated") {
-      closed(e,["type","requestId","successorDigest"]);if(!c.order||claim||superseded||typeof e.requestId!=="string"||typeof e.successorDigest!=="string"||!/^[a-f0-9]{64}$/.test(e.successorDigest))throw new Error("migration requires unstarted order");superseded=true;
-    } else if (e.type === "claim") {
-      closed(e, ["type", "owner", "deadlineAt"]);
-      if (superseded || claim || typeof e.owner !== "string" || !/^[a-f0-9-]{36}$/.test(e.owner) || !Number.isSafeInteger(e.deadlineAt)) throw new Error("invalid experiment claim");
-      claim = { owner: e.owner, deadlineAt: e.deadlineAt as number }; variants.forEach(v => v.state = "queued");
-    } else if (e.type === "admitted") {
-      closed(e, ["type"]); if (!claim || admitted) throw new Error("invalid experiment admission"); admitted = true;
-    } else if (e.type === "cancel") {
-      closed(e, ["type", "request"]); const request = experimentCancellation(e.request as ExperimentCancellation);
-      if (!variants.some(v => v.executionId === request.executionId) || cancellations.some(r => r.requestId === request.requestId) || cancellations.length >= 64) throw new Error("invalid cancellation sequence");
-      cancellations.push(request);
-    } else if (e.type === "controller-unknown") {
-      closed(e, ["type"]); if (!claim) throw new Error("missing claim"); controllerFailed = true;
-      variants.filter(v => v.artifactDigest === null).forEach(v => v.state = "unknown");
-    } else {
-      const v = variants.find(v => v.executionId === e.executionId);
-      if (!claim || !admitted || !v || v.artifactDigest !== null) throw new Error("invalid variant sequence");
-      if (e.type === "dispatch") {
-        closed(e, ["type", "executionId"]); if (v.state !== "queued") throw new Error("duplicate dispatch"); v.state = "dispatching";
-      } else if (e.type === "spawn") {
-        closed(e, ["type", "executionId"]); if (v.state !== "dispatching") throw new Error("invalid spawn observation"); v.state = "running"; v.spawned = true;
-      } else if (e.type === "result") {
-        closed(e, ["type", "executionId", "state", "artifactDigest"]);
-        if (!["dispatching", "running"].includes(v.state) || !["completed", "failed", "cancelled", "timed-out"].includes(String(e.state)) || typeof e.artifactDigest !== "string" || !/^[a-f0-9]{64}$/.test(e.artifactDigest)) throw new Error("invalid result observation");
-        v.state = e.state as VariantState; v.artifactDigest = e.artifactDigest;
-      } else throw new Error("unknown experiment event");
-    }
-  }
-  return { claim, admitted, variants, cancellations, decisions, superseded, controllerFailed };
-}