pi-daddy 0.28.0 → 0.32.0

package/src/native-session.ts

@@ -1,139 +0,0 @@
-import { constants } from "node:fs";
-import { open, lstat, realpath } from "node:fs/promises";
-import { isAbsolute, relative, sep } from "node:path";
-import { createHash } from "node:crypto";
-import { parseRetentionJson } from "./retention-json.ts";
-
-export const ENV_NATIVE_SESSION_ROOT = "PI_GRANTS_NATIVE_SESSION_ROOT";
-export const MAX_NATIVE_SESSION_BYTES = 1024 * 1024;
-export type NativeSessionSource = "herdr-id" | "herdr-path" | "pi-session-file" | "pi-session-manager";
-export interface NativeSessionObservation {
-  source: NativeSessionSource | null;
-  status: "missing" | "verified" | "invalid" | "changed" | "truncated" | "unsupported";
-  sessionId: string | null;
-  sessionPath: string | null;
-  parentSessionPath: string | null;
-  branchLeafId: string | null;
-  branchState: "unknown" | "observed";
-  lastPersistedEntryId: string | null;
-  sha256: string | null;
-  reason: string | null;
-}
-export interface NativeSessionCapture { observation: NativeSessionObservation; bytes?: Buffer; fileIdentity?: { device: string; inode: string } }
-/** Read-only methods of pi 0.84.2's public SessionManager; no runtime/session creation or model work. */
-export interface NativeSessionManager {
-  getSessionFile(): string | undefined;
-  getSessionId(): string;
-  getLeafId(): string | null;
-}
-export const missingNativeSession = (): NativeSessionObservation => ({ source: null, status: "missing", sessionId: null,
-  sessionPath: null, parentSessionPath: null, branchLeafId: null, branchState: "unknown", lastPersistedEntryId: null,
-  sha256: null, reason: "native-session-unavailable" });
-const id = (x: unknown): x is string => typeof x === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(x);
-const uuid = (x: unknown): x is string => typeof x === "string" && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(x);
-const obj = (x: unknown): x is Record<string, unknown> => x !== null && typeof x === "object" && !Array.isArray(x);
-const filePath = (x: unknown): x is string => typeof x === "string" && x.length <= 4096 && isAbsolute(x) && !x.includes("\0");
-
-/** Parse the retained native v3 bytes, never load/migrate/rewrite a session via SessionManager.open(). */
-export function parseNativeSessionBytes(bytes: Uint8Array, input: {
-  source: NativeSessionSource; path: string; expectedSessionId?: string; truncated?: boolean;
-  liveLeaf?: { sessionId: string; leafId: string | null };
-}): NativeSessionCapture {
-  const observation = { ...missingNativeSession(), source: input.source, sessionPath: input.path };
-  const result: NativeSessionCapture = { observation };
-  const fail = (status: NativeSessionObservation["status"], reason: string) => {
-    observation.status = status; observation.reason = reason; observation.branchLeafId = null; observation.branchState = "unknown";
-    return result;
-  };
-  if (bytes.length > MAX_NATIVE_SESSION_BYTES) return fail("truncated", "native-session-size-limit");
-  const raw = Buffer.from(bytes), newline = raw.indexOf(10);
-  let header: unknown;
-  try { header = parseRetentionJson(new TextDecoder("utf-8", { fatal: true }).decode(raw.subarray(0, newline < 0 ? raw.length : newline)), MAX_NATIVE_SESSION_BYTES); }
-  catch { return fail("invalid", "native-session-header-invalid"); }
-  if (!obj(header) || header.type !== "session" || header.version !== 3 || !uuid(header.id) ||
-    !filePath(header.cwd) || typeof header.timestamp !== "string" || !Number.isFinite(Date.parse(header.timestamp)) ||
-    (header.parentSession !== undefined && !filePath(header.parentSession))) return fail("invalid", "native-session-header-invalid");
-  if (input.expectedSessionId !== undefined && header.id !== input.expectedSessionId) return fail("changed", "native-session-id-changed");
-  // Only validated session headers admit transcript bytes; arbitrary files are never archived here.
-  result.bytes = Buffer.from(bytes);
-  observation.sessionId = header.id;
-  observation.parentSessionPath = header.parentSession as string | undefined ?? null;
-  observation.sha256 = createHash("sha256").update(bytes).digest("hex");
-  if (input.truncated || raw.at(-1) !== 10) return fail("truncated", "native-session-incomplete-bytes");
-  let text: string;
-  try { text = new TextDecoder("utf-8", { fatal: true }).decode(raw); }
-  catch { return fail("invalid", "native-session-utf8-invalid"); }
-  const lines = text.split("\n");
-  const ids = new Set<string>();
-  if (lines.length > 10002) return fail("invalid", "native-session-entry-limit");
-  for (const line of lines.slice(1, -1)) {
-    let entry: unknown;
-    try { entry = parseRetentionJson(line, MAX_NATIVE_SESSION_BYTES); } catch { return fail("invalid", "native-session-entry-invalid"); }
-    if (!obj(entry) || typeof entry.type !== "string" || entry.type === "session" || !id(entry.id) || ids.has(entry.id) ||
-      !(entry.parentId === null || (id(entry.parentId) && ids.has(entry.parentId))) || typeof entry.timestamp !== "string" ||
-      !Number.isFinite(Date.parse(entry.timestamp))) return fail("invalid", "native-session-parent-link-invalid");
-    ids.add(entry.id); observation.lastPersistedEntryId = entry.id;
-  }
-  if (input.liveLeaf) {
-    if (input.liveLeaf.sessionId !== header.id || (input.liveLeaf.leafId !== null && !ids.has(input.liveLeaf.leafId))) {
-      return fail("changed", "native-session-live-leaf-mismatch");
-    }
-    observation.branchLeafId = input.liveLeaf.leafId; observation.branchState = "observed";
-  }
-  observation.status = "verified"; observation.reason = observation.branchState === "unknown" ? "active-branch-unknown" : null;
-  return result;
-}
-
-/** Private allowlisted files only, bounded non-following descriptor reads, no scan of session/auth dirs. */
-export async function readNativeSession(input: {
-  path: string; source: NativeSessionSource; expectedSessionId?: string; allowedRoot?: string;
-  manager?: NativeSessionManager;
-  expectedFile?: { device: string; inode: string };
-}): Promise<NativeSessionCapture> {
-  const gap = (status: NativeSessionObservation["status"], reason: string): NativeSessionCapture => ({ observation: {
-    ...missingNativeSession(), source: input.source, status, reason, sessionPath: filePath(input.path) ? input.path : null,
-  } });
-  const root = input.allowedRoot ?? process.env[ENV_NATIVE_SESSION_ROOT];
-  if (!filePath(input.path) || !input.path.endsWith(".jsonl") || !root || !filePath(root)) return gap("unsupported", "native-session-private-root-required");
-  const within = (base: string, candidate: string) => { const p = relative(base, candidate); return p !== "" && p !== ".." && !p.startsWith(`..${sep}`) && !isAbsolute(p); };
-  if (!within(root, input.path)) return gap("unsupported", "native-session-outside-private-root");
-  let handle: Awaited<ReturnType<typeof open>> | undefined;
-  try {
-    const canonicalRoot = await realpath(root), canonicalFile = await realpath(input.path);
-    const rootStat = await lstat(canonicalRoot);
-    if (!rootStat.isDirectory() || (rootStat.mode & 0o077) !== 0 || (typeof process.getuid === "function" && rootStat.uid !== process.getuid())) return gap("unsupported", "native-session-root-not-private");
-    if (!within(canonicalRoot, canonicalFile) || (await lstat(input.path)).isSymbolicLink()) return gap("unsupported", "native-session-path-alias");
-    handle = await open(input.path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-    const before = await handle.stat();
-    if (!before.isFile() || before.nlink !== 1 || (typeof process.getuid === "function" && before.uid !== process.getuid())) {
-      return gap("unsupported", "native-session-not-private-regular-file");
-    }
-    const fileIdentity = { device: String(before.dev), inode: String(before.ino) };
-    if (input.expectedFile && (input.expectedFile.device !== fileIdentity.device || input.expectedFile.inode !== fileIdentity.inode)) return gap("changed", "native-session-file-replaced");
-    const live = input.manager ? { sessionId: input.manager.getSessionId(), leafId: input.manager.getLeafId(), path: input.manager.getSessionFile() } : undefined;
-    if (live && live.path !== input.path) return gap("changed", "native-session-manager-path-changed");
-    const bytes = Buffer.alloc(Math.min(before.size, MAX_NATIVE_SESSION_BYTES));
-    let offset = 0;
-    while (offset < bytes.length) { const read = await handle.read(bytes, offset, bytes.length - offset, offset); if (!read.bytesRead) break; offset += read.bytesRead; }
-    const after = await handle.stat(), location = await lstat(input.path);
-    if (before.dev !== location.dev || before.ino !== location.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs ||
-      before.ctimeMs !== after.ctimeMs || location.isSymbolicLink() || after.size !== location.size) return gap("changed", "native-session-file-changed");
-    if (live && (input.manager!.getSessionId() !== live.sessionId || input.manager!.getLeafId() !== live.leafId || input.manager!.getSessionFile() !== live.path)) {
-      return gap("changed", "native-session-live-state-changed");
-    }
-    return { ...parseNativeSessionBytes(bytes.subarray(0, offset), { ...input, liveLeaf: live,
-      truncated: before.size > MAX_NATIVE_SESSION_BYTES || offset !== before.size }), fileIdentity };
-  } catch (error) {
-    return gap((error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "invalid", "native-session-read-failed");
-  } finally { await handle?.close().catch(() => undefined); }
-}
-
-/** Herdr 0.8.2 protocol 20 AgentInfo.agent_session; never scrape terminal text, PID or names. */
-export function herdrSessionReference(value: unknown, expectedPane: string): { source: "herdr-id" | "herdr-path"; value: string } | null {
-  if (!obj(value) || value.pane_id !== expectedPane || value.agent !== "pi" || !obj(value.agent_session)) return null;
-  const s = value.agent_session;
-  if (s.agent !== "pi" || typeof s.source !== "string" || s.source.length > 128) return null;
-  if (s.kind === "id" && uuid(s.value)) return { source: "herdr-id", value: s.value };
-  if (s.kind === "path" && filePath(s.value)) return { source: "herdr-path", value: s.value };
-  return null;
-}

package/src/order-schedule.ts

@@ -1,42 +0,0 @@
-import { closed, cloneExperiment, experimentHash } from "./experiment-contract.ts";
-import type { VariantRecord } from "./experiment-state.ts";
-export interface OrderNode { nodeId: string; dependencies: readonly string[]; executions: readonly string[]; expectedDigest: string; decision: { decisionId: string; authorityId: string } | null }
-export interface OrderSchedule { version: "order-schedule-v1"; policyDigest: string; nodes: readonly OrderNode[] }
-export interface FactoryDecision { version: "factory-decision-v1"; requestId: string; bindingDigest: string; nodeId: string; evidenceDigest: string; authorityId: string; choice: "approve" | "reject" }
-export const factoryDecisionDigest = (d: FactoryDecision) => experimentHash(factoryDecision(d));
-export function factoryDecision(value: FactoryDecision): FactoryDecision {
-  const d = cloneExperiment(value); closed(d,["version","requestId","bindingDigest","nodeId","evidenceDigest","authorityId","choice"]);
-  if(d.version!=="factory-decision-v1" || ![d.requestId,d.nodeId,d.authorityId].every(x=>typeof x==="string"&&/^[a-zA-Z0-9:_-]{1,128}$/.test(x)) || ![d.bindingDigest,d.evidenceDigest].every(x=>typeof x==="string"&&/^[a-f0-9]{64}$/.test(x)) || !["approve","reject"].includes(d.choice))throw new Error("invalid reserved decision");return d;
-}
-export function orderSchedule(input: OrderSchedule, executions: readonly string[]): OrderSchedule {
-  const s=cloneExperiment(input);closed(s,["version","policyDigest","nodes"]);
-  if(s.version!=="order-schedule-v1"|| !/^[a-f0-9]{64}$/.test(s.policyDigest)||!Array.isArray(s.nodes)||!s.nodes.length||s.nodes.length>16)throw new Error("bounded order schedule required");
-  const ids=new Set<string>(),all:string[]=[];
-  for(const n of s.nodes as readonly OrderNode[]){closed(n,["nodeId","dependencies","executions","expectedDigest","decision"]);
-    if(!/^[a-zA-Z0-9:_-]{1,128}$/.test(n.nodeId)||ids.has(n.nodeId)||!Array.isArray(n.dependencies)||n.dependencies.length>16||new Set(n.dependencies).size!==n.dependencies.length||!Array.isArray(n.executions)||n.executions.length<1||n.executions.length>3||!/^[a-f0-9]{64}$/.test(n.expectedDigest))throw new Error("invalid node/dependency/recovery policy");
-    if(n.decision!==null){closed(n.decision,["decisionId","authorityId"]);if(![n.decision.decisionId,n.decision.authorityId].every(x=>/^[a-zA-Z0-9:_-]{1,128}$/.test(x)))throw new Error("invalid decision owner");}
-    ids.add(n.nodeId);all.push(...n.executions);
-  }
-  if(new Set(all).size!==all.length||all.length!==executions.length||all.some(x=>!executions.includes(x)))throw new Error("schedule must own every reserved execution exactly once");
-  const visiting=new Set<string>(),done=new Set<string>();
-  const visit=(id:string)=>{if(done.has(id))return;if(visiting.has(id))throw new Error("dependency cycle");const n=s.nodes.find(n=>n.nodeId===id);if(!n)throw new Error("missing dependency");visiting.add(id);n.dependencies.forEach(visit);visiting.delete(id);done.add(id);};s.nodes.forEach(n=>visit(n.nodeId));return s;
-}
-export interface OrderNodeView {nodeId:string;state:"eligible"|"running"|"unknown"|"exhausted"|"decision-required"|"decision-rejected"|"dependency-blocked"|"satisfied";action:"dispatch"|"decide"|"wait"|"stakeholder"|"none";executionId:string|null;evidenceDigest:string|null}
-export function evaluateOrder(s:OrderSchedule,variants:readonly VariantRecord[],digests:ReadonlyMap<string,string|null>,decisions:readonly FactoryDecision[]):OrderNodeView[]{
-  const rows=new Map<string,OrderNodeView>();
-  function evaluate(n:OrderNode):OrderNodeView{
-    if(rows.has(n.nodeId))return rows.get(n.nodeId)!;
-    const row:OrderNodeView={nodeId:n.nodeId,state:"exhausted",action:"stakeholder",executionId:null,evidenceDigest:null};
-    if(n.dependencies.some(id=>evaluate(s.nodes.find(n=>n.nodeId===id)!).state!=="satisfied")){row.state="dependency-blocked";row.action="wait";rows.set(n.nodeId,row);return row;}
-    for(const id of n.executions){const v=variants.find(v=>v.executionId===id)!;row.executionId=id;
-      if(v.state==="unknown"){row.state="unknown";row.action="stakeholder";break;}
-      if(v.state==="completed"&&digests.get(id)===n.expectedDigest){row.evidenceDigest=experimentHash({nodeId:n.nodeId,policyDigest:s.policyDigest,executionId:id,artifactDigest:v.artifactDigest,expectedDigest:n.expectedDigest});
-        const d=decisions.find(d=>d.nodeId===n.nodeId&&d.evidenceDigest===row.evidenceDigest);
-        row.state=n.decision?d?d.choice==="approve"?"satisfied":"decision-rejected":"decision-required":"satisfied";row.action=row.state==="decision-required"?"decide":row.state==="decision-rejected"?"stakeholder":"none";break;}
-      if(["unstarted","queued"].includes(v.state)){row.state="eligible";row.action="dispatch";break;}
-      if(["dispatching","running"].includes(v.state)){row.state="running";row.action="wait";break;}
-    }
-    rows.set(n.nodeId,row);return row;
-  }
-  return s.nodes.map(evaluate);
-}

package/src/ordinary-children.ts

@@ -1,59 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { isExecutionId } from "./execution-id.ts";
-import { dataDigest, detached, freeze, sha } from "./debrief-contract.ts";
-import { controlShape } from "./dispatch-control.ts";
-export interface OrdinaryTarget { executionId:string; parentExecutionId:string|null; toolCallId:string|null }
-export interface OrdinaryCancellation { version:"ordinary-cancel-v1"; requestId:string; bindingDigest:string; expectedRevision:number; target:OrdinaryTarget }
-export interface OrdinaryAuthority { bindingDigest:string; requestDigests:readonly string[] }
-type ControlState="not-assessed"|"failed"|"unknown";
-interface Row { target:OrdinaryTarget; state:"active"|"settled"|"unknown"; abortRequested:boolean; control:ControlState; boundary:ControlState; outcome:unknown }
-interface State { holds:Set<string>; enabled:boolean; coverageGap:boolean; bindingDigest:string; revision:number; rows:Map<string,Row>; handles:Map<string,AbortController>; requests:Map<string,{digest:string;result:unknown}> }
-const sessions=new WeakMap<object,OrdinaryChildren>(),ports=new WeakMap<object,State>();
-const id=(v:unknown)=>typeof v==="string"&&/^[a-zA-Z0-9:_-]{1,128}$/.test(v);
-function target(value:OrdinaryTarget){const t=detached(value);controlShape(t,["executionId","parentExecutionId","toolCallId"]);if(!isExecutionId(t.executionId)||!(t.parentExecutionId===null||isExecutionId(t.parentExecutionId))||!(t.toolCallId===null||typeof t.toolCallId==="string"&&t.toolCallId.length>0&&t.toolCallId.length<=256))throw Error("exact original occurrence identity required");return t;}
-export function ordinaryCancellation(input:OrdinaryCancellation){const r=detached(input);controlShape(r,["version","requestId","bindingDigest","expectedRevision","target"]);if(r.version!=="ordinary-cancel-v1"||!id(r.requestId)||!sha(r.bindingDigest)||!Number.isSafeInteger(r.expectedRevision)||r.expectedRevision<0)throw Error("invalid ordinary cancellation");return freeze({...r,target:target(r.target)});}
-export const ordinaryCancellationDigest=(r:OrdinaryCancellation)=>dataDigest(ordinaryCancellation(r));
-export interface OrdinaryChildren { readonly bindingDigest:string; inspect():unknown; quiescent():boolean; cancel(request:OrdinaryCancellation,authority:OrdinaryAuthority|null):unknown }
-export const isOrdinaryChildren=(p:unknown):p is OrdinaryChildren=>typeof p==="object"&&p!==null&&ports.has(p);
-/** Extension-internal constructor. No disk discovery/recovery and no identity inferred from labels. */
-function initializeOrdinaryChildren(session:object):void {
-  if(sessions.has(session))throw Error("original session already registered");
-  const s:State={holds:new Set(),enabled:false,coverageGap:false,bindingDigest:dataDigest({occurrence:randomUUID()}),revision:0,rows:new Map(),handles:new Map(),requests:new Map()};
-  const port:OrdinaryChildren=Object.freeze({bindingDigest:s.bindingDigest,
-    quiescent:()=>!s.coverageGap&&[...s.rows.values()].every(r=>r.state==="settled"&&r.boundary==="not-assessed"),
-    inspect:()=>freeze(detached({bindingDigest:s.bindingDigest,revision:s.revision,children:[...s.rows.values()],admission:s.holds.size?"held-by-original-owner":"open",coverage:s.coverageGap?"unretained-before-opt-in":"original-registered-lifetimes-only",freshness:"snapshot-unknown",recovery:"unavailable",acceptance:"not-assessed"})),
-    cancel(input:OrdinaryCancellation,authority:OrdinaryAuthority|null){
-      const r=ordinaryCancellation(input),digest=ordinaryCancellationDigest(input),old=s.requests.get(r.requestId);
-      if(old){if(old.digest!==digest)throw Error("immutable ordinary cancellation ID");return freeze(detached(old.result));}
-      if(r.bindingDigest!==s.bindingDigest||r.expectedRevision!==s.revision)throw Error("stale original ordinary controller CAS");
-      if(!authority||authority.bindingDigest!==s.bindingDigest||!authority.requestDigests.includes(digest))throw Error("independent exact ordinary cancellation authority required");
-      const row=s.rows.get(r.target.executionId),handle=s.handles.get(r.target.executionId);
-      if(!row||dataDigest(row.target)!==dataDigest(r.target)||row.state!=="active"||!handle)throw Error("original live child handle unavailable; no recovery");
-      if(s.requests.size>=1024)throw Error("ordinary cancellation capacity exhausted");
-      // Synchronous original-handle operation: CAS cannot yield between checking and requesting abort.
-      const result={state:"abort-requested",target:r.target,revision:++s.revision,completion:"pending-original-caller",durability:"process-local"};
-      s.requests.set(r.requestId,{digest,result});row.abortRequested=true;handle.abort();return freeze(detached(result));
-    }});
-  sessions.set(session,port);ports.set(port,s);
-}
-/** Only the original session object can retrieve its retained port; spreading/copying cannot. */
-export function ordinaryChildrenFor(session:object):OrdinaryChildren {const p=sessions.get(session);if(!p)throw Error("original grants session required");ports.get(p)!.enabled=true;return p;}
-/** Associate the actual extension API object at factory creation, never a label or path. */
-export function associateOrdinaryHost(host:object,session:object){initializeOrdinaryChildren(session);const p=sessions.get(session);if(!p||sessions.has(host))throw Error("original unbound extension host required");sessions.set(host,p);}
-export function retainSessionChild(session:object,input:OrdinaryTarget,caller?:AbortSignal){const p=sessions.get(session);if(!p)return undefined;const s=ports.get(p)!;if(!s.enabled){s.coverageGap=true;return undefined;}return retainOrdinaryChild(p,input,caller);}
-/** Internal host control seam, not a model tool or recovered capability. Reads never call it. */
-export function holdOrdinaryDispatch(port:OrdinaryChildren,key:string){
- const s=ports.get(port);if(!s||!sha(key))throw Error("original ordinary boundary required");
- if(s.coverageGap||[...s.rows.values()].some(r=>r.state!=="active"&&r.boundary!=="not-assessed"))throw Error("ordinary boundary unavailable; no recovery");
- if(!s.holds.has(key)){if(s.holds.size>=32)throw Error("ordinary boundary capacity exhausted");s.holds.add(key);s.revision++;}
- return Object.freeze({ready:()=>port.quiescent(),release:()=>{if(s.holds.delete(key))s.revision++;}});
-}
-/** Extension executor seam; never exported through the package root or model tools. */
-export function retainOrdinaryChild(port:OrdinaryChildren,input:OrdinaryTarget,caller?:AbortSignal){
-  const s=ports.get(port);if(!s)throw Error("original ordinary controller required");const t=target(input);
-  if(s.holds.size)throw Error("ordinary dispatch held at original control boundary");
-  if(s.rows.has(t.executionId)||s.rows.size>=1024)throw Error("ordinary occurrence reused or capacity exhausted");
-  const abort=new AbortController(),row:Row={target:t,state:"active",abortRequested:false,control:"not-assessed",boundary:"not-assessed",outcome:null};s.rows.set(t.executionId,row);s.handles.set(t.executionId,abort);s.revision++;
-  let done=false;return {signal:caller?AbortSignal.any([caller,abort.signal]):abort.signal,
-    settle(outcome:unknown,control:ControlState,boundary:ControlState=control){if(done)throw Error("original child already settled");done=true;row.outcome=detached(outcome);row.control=control;row.boundary=boundary;row.state=boundary==="unknown"?"unknown":"settled";s.handles.delete(t.executionId);s.revision++;}};
-}

package/src/pane-reaper.ts

@@ -1,270 +0,0 @@
-/**
- * Close herdr panes this process opened but never got to close.
- *
- * **As of ADR-0032 a pane belongs to the AGENT RUN, not to the tool call.** `runHerdrPane` closes a tab only for
- * a child that did *not* settle — closing the tab is the only kill herdr offers, so a child still working must
- * lose its pane. A child that answered keeps its pane so a human can read it, and this module reaps those: at
- * `agent_settled` (async) and at process `exit` (sync backstop).
- *
- * The gap that remains is the one this module was created for. A pi session **killed outright** runs no `exit`
- * handler, so it leaves one pane per tracked child, and `docs/probes/g16-herdr` records that an orphaned pane is
- * not trivially closable afterwards. R-62 was re-rated L×L → M×L when ADR-0031 made panes the default path.
- *
- * **Registered on `exit` only, deliberately — not on SIGINT or SIGTERM.** That is the part worth reading,
- * because the obvious fix is the dangerous one. Adding a signal listener *suppresses Node's default
- * termination*, so a library that adds one takes over an application-level decision it has no standing to
- * make: pi uses SIGINT to interrupt a turn, and a listener here that re-raised would turn "cancel this
- * delegation" into "exit pi". A governance package quietly changing the host's interrupt semantics is a
- * worse defect than the leak it fixes, and it would land on **every** session rather than the opt-in ones.
- *
- * So the coverage is exact and stated rather than implied:
- *
- *  - **Covered:** normal exit, `process.exit()`, an uncaught exception that unwinds to the default handler.
- *  - **NOT covered:** SIGKILL, and SIGTERM/SIGINT where nothing else in the process has installed a
- *    listener. Node terminates without running `exit` handlers in those cases, by design. A pane can still
- *    be orphaned there, and `herdr tab close <id>` is the manual remedy.
- *
- * Everything here is **synchronous**, because an `exit` handler is: a promise scheduled there never runs.
- */
-
-import { execFileSync } from "node:child_process";
-import { rmSync } from "node:fs";
-import { rm } from "node:fs/promises";
-import { MAX_CHILDREN_PER_CALL } from "./fanout.ts";
-import { defaultExec, parseReply, type HerdrExec } from "./herdr-cli.ts";
-
-/**
- * How many panes may be open at once — ADR-0032.
- *
- * **Derived from `MAX_CHILDREN_PER_CALL` rather than declared, so the two cannot drift.** The bound is not
- * decoration: `delegate_all` is capped per call and the fan-out budget bounds a subtree, but a plain blocking
- * `delegate` spends **nothing** from that budget by design — so thirty sequential `delegate` calls in one agent
- * run would otherwise hold thirty panes open until it settled.
- */
-export const MAX_OPEN_PANES = MAX_CHILDREN_PER_CALL;
-
-export interface OpenPane {
-  /** herdr tab id — what `tab close` takes. */
-  tab: string;
-  /** herdr agent name, for diagnostics. There is no `agent stop`, so nothing acts on it — see `closePane`. */
-  name: string;
-  /** Staged system-prompt directory, removed with the pane it belonged to. */
-  promptDir?: string;
-  /**
-   * True once the child has answered and stopped working.
-   *
-   * **The trim may only close a pane with this set**, and that is a correctness rule rather than politeness. pi
-   * executes tool calls in **parallel** by default, and a plain `delegate` spends nothing from the fan-out
-   * budget — so one assistant message can hold `delegate_all(8)` *and* a `delegate`, and the ninth pane's trim
-   * used to close the oldest **live sibling**. Measured: two `delegate_all(8)` in one message killed **8 of 16
-   * children mid-work**, each reported as "could not be started" with its partial output discarded, while the
-   * ledger recorded all sixteen as provisioned. ADR-0032 argued the cap from *sequential* delegates only.
-   */
-  settled?: boolean;
-  /**
-   * The operator asked to keep this tab (`PI_GRANTS_HERDR_KEEP_PANE=1`), so no sweep may close it.
-   *
-   * It is registered anyway, and only for its `promptDir`: that temp dir was otherwise unreachable by either
-   * sweep and leaked one directory per kept pane, forever. So `exit` removes the staged prompt and leaves the
-   * tab, which is exactly what the flag promises.
-   */
-  keepTab?: boolean;
-}
-
-/** A run has finished with its pane: the trim may now reclaim it. */
-export function markPaneSettled(tab: string): void {
-  const pane = open.get(tab);
-  if (pane) pane.settled = true;
-}
-
-/**
- * Panes opened by THIS process and not yet closed. Keyed by tab id, so a double close is impossible.
- *
- * **That keying rests on tab ids being unique, which was measured rather than assumed** (herdr 0.7.5): ids
- * are `w<workspace>:t<counter>`, allocated by the single server, and **not recycled** — creating a tab,
- * closing it, and creating again yields the next counter value, never the freed one. If that ever changed,
- * concurrent panes would collapse into one entry and an early finisher's `untrackPane` would drop a live
- * sibling. Recorded because the hazard is invisible in the code and the precondition lives in another
- * project.
- */
-const open = new Map<string, OpenPane>();
-let hookInstalled = false;
-
-/** A run has opened a pane. Idempotent per tab, and installs the exit hook on first use only. */
-export function trackPane(pane: OpenPane): void {
-  open.set(pane.tab, pane);
-  if (hookInstalled) return;
-  hookInstalled = true;
-  // `once`, and only ever one, so a fan-out of eight children does not install eight handlers and trip
-  // Node's MaxListenersExceededWarning — which would be this package printing a warning about itself.
-  process.once("exit", () => void reapOpenPanes());
-}
-
-/** A run closed its own pane the normal way. */
-export function untrackPane(tab: string): void {
-  open.delete(tab);
-}
-
-/** How many panes are currently outstanding — for tests and for `/grants`. */
-export function openPaneCount(): number {
-  return open.size;
-}
-
-/** Per-command wall clock. `SIGKILL` because `timeout` alone is not a bound — see `TOTAL_BUDGET_MS`. */
-const PER_CALL_MS = 2000;
-
-/**
- * Total wall clock the whole sweep may add to process exit.
- *
- * **Measured, and the reason this exists.** With eight panes and a hung herdr, a per-call timeout of 5s
- * across two calls per pane is **80 seconds of silent hang at shutdown** — `stdio: "ignore"`, so the process
- * looks wedged with no output. Worse, `timeout` is not a hard bound at all: `spawnSync` sends `SIGTERM` and
- * then waits for the child to actually die, so a process ignoring `SIGTERM` runs to its own completion
- * (measured: a 3s timeout took 59.8s against `trap '' TERM; sleep 60`). Hence `killSignal: "SIGKILL"` **and**
- * a budget across the whole sweep rather than per call.
- *
- * A pane left open because the budget ran out is the failure this whole module downgrades to, and it is the
- * right one: `herdr tab close <id>` is a five-second manual fix, whereas a shell that will not exit is not.
- */
-const TOTAL_BUDGET_MS = 6000;
-
-/** Run one herdr command synchronously, swallowing everything: at exit there is nowhere to report. */
-const defaultSyncExec = (args: string[]): void => {
-  execFileSync("herdr", args, { stdio: "ignore", timeout: PER_CALL_MS, killSignal: "SIGKILL" });
-};
-
-/**
- * Close every outstanding pane and return the tab ids closed.
- *
- * Exported and parameterised so it can be tested without herdr installed: the exit hook is unreachable from
- * a test (registering a real `exit` handler would run during the test runner's own shutdown), so the hook is
- * one line and *this* is where the behaviour lives.
- *
- * Failures are swallowed per pane rather than per call — one pane herdr will not close must not strand the
- * other seven, and nothing at exit has anywhere to report to anyway.
- */
-export function reapOpenPanes(syncExec: (args: string[]) => void = defaultSyncExec, now = Date.now): string[] {
-  const closed: string[] = [];
-  const deadline = now() + TOTAL_BUDGET_MS;
-  for (const pane of [...open.values()]) {
-    // Checked BEFORE each pane rather than after, so the budget bounds what we start, not what we finish.
-    // Panes left behind stay in the map; there is no later sweep, and saying so is the honest position —
-    // `openPaneCount()` is non-zero afterwards precisely so a caller could report it if it ever wanted to.
-    if (now() >= deadline) break;
-    // No `agent stop`: it is not a herdr command (see `closePane`). Closing the tab is the kill.
-    //
-    // A `keepTab` pane is registered only for its staged prompt: remove that and leave the tab alone, which is
-    // the whole of what `PI_GRANTS_HERDR_KEEP_PANE=1` promises.
-    let closedThisPane = pane.keepTab === true;
-    if (pane.keepTab) {
-      if (pane.promptDir) {
-        try {
-          rmSync(pane.promptDir, { recursive: true, force: true });
-        } catch {
-          /* /tmp litter, not correctness */
-        }
-      }
-      open.delete(pane.tab);
-      continue;
-    }
-    try {
-      syncExec(["tab", "close", pane.tab]);
-      closed.push(pane.tab);
-      closedThisPane = true;
-    } catch {
-      /* an orphan we could not close: `herdr tab close` is the manual remedy, as documented above */
-    }
-    // **The staged prompt is deleted only when the tab is provably gone.** It used to be removed
-    // unconditionally, so a pane herdr refused to close lost its `--append-system-prompt` file — and pi treats a
-    // missing path there as **literal text, with no warning** (`resource-loader.js`: `existsSync` fails, the
-    // input is returned). Re-running that pane's echoed argv would hand the child a pathname as its
-    // instructions. Litter is cheaper than silently swapping a definition's body for its filename.
-    if (closedThisPane && pane.promptDir) {
-      try {
-        rmSync(pane.promptDir, { recursive: true, force: true });
-      } catch {
-        /* /tmp litter, not correctness */
-      }
-    }
-    // Untracked either way, and only here: at `exit` there is no later sweep, so keeping an unclosable pane
-    // registered buys nothing. `closePane`'s async path deliberately differs — another sweep may still run.
-    open.delete(pane.tab);
-  }
-  return closed;
-}
-
-/**
- * Close one tracked pane. Shared by the async sweep and the trim so they cannot disagree about what "closed"
- * means — which is the whole of R-62's lesson, one layer up.
- *
- * Returns whether the tab is **provably** gone. A close herdr refused leaves the pane tracked, so the `exit`
- * handler retries it; untracking on a failed close is what disabled the one control built for that failure.
- */
-async function closePane(exec: HerdrExec, pane: OpenPane): Promise<boolean> {
-  // **No `agent stop`.** It is not a herdr command — measured against 0.7.5, where it prints the usage banner
-  // and exits 0, which `defaultExec` reports as success. Two call sites here and one in `run-herdr.ts` issued it
-  // for nothing, and `docs/probes/g16-herdr` asserted it worked from a block that was never run. Closing the tab
-  // is the only kill herdr offers, and it does kill the child.
-  const reply = await exec(["tab", "close", pane.tab]).catch(() => undefined);
-  const closed = reply !== undefined && !parseReply(reply).error;
-  if (!closed) return false;
-  if (pane.promptDir) await rm(pane.promptDir, { recursive: true, force: true }).catch(() => undefined);
-  open.delete(pane.tab);
-  return true;
-}
-
-/**
- * Close every outstanding pane — the `agent_settled` path (ADR-0032).
- *
- * **A separate function from `reapOpenPanes` rather than a shared implementation**, and the reason is not
- * style. The sync one is `execFileSync` with a six-second total budget *by necessity*: an `exit` handler cannot
- * await. Running that at `agent_settled` would freeze pi for up to six seconds **every time the operator gets
- * their prompt back** — turning a feature that exists to make work visible into a stall.
- *
- * Both drain the same `Map`, keyed by tab id, so a double close is impossible and a pane herdr refused stays
- * registered for whichever sweep runs next.
- *
- * Sequential rather than concurrent: a fan-out's panes are at most `MAX_OPEN_PANES`, and eight `tab close`
- * calls in parallel against one herdr server buys nothing worth the burst.
- */
-export async function reapOpenPanesAsync(exec: HerdrExec = defaultExec): Promise<string[]> {
-  const closed: string[] = [];
-  for (const pane of [...open.values()]) {
-    // `keepTab` panes are registered only so their staged prompt can be reaped at `exit`; the tab itself is the
-    // operator's to close.
-    if (pane.keepTab) continue;
-    if (await closePane(exec, pane)) closed.push(pane.tab);
-  }
-  return closed;
-}
-
-/**
- * Keep at most `MAX_OPEN_PANES` open, closing the oldest first.
- *
- * The `Map`'s insertion order **is** the age order, so no timestamp is needed — and that is why `trackPane`
- * must never re-`set` an existing tab, which would move it to the back of the queue and make an old pane look
- * new.
- *
- * Whatever it closes is returned so the caller can **say so** rather than silently dropping a pane the operator
- * was reading (R-48's rule, applied to a display).
- */
-export async function trimOpenPanes(exec: HerdrExec = defaultExec): Promise<string[]> {
-  if (open.size <= MAX_OPEN_PANES) return [];
-  const closed: string[] = [];
-
-  // **Only SETTLED panes are candidates, oldest first.** A live sibling's pane is its child's only terminal, and
-  // closing a tab kills the child — see `OpenPane.settled`. If every open pane is live the cap is exceeded and
-  // nothing is closed, which is the right failure: a pane too many costs an operator a keystroke, and a killed
-  // child costs them the work.
-  //
-  // **Walks past what it cannot close**, rather than attempting `excess` panes from the front and calling it
-  // done. A pane herdr refuses to close used to sit at the head forever, so the cap silently stopped holding
-  // (measured: 30 panes for 30 delegates when every close was refused) and the same corpse was re-attacked on
-  // every spawn — O(n²) round-trips.
-  for (const pane of [...open.values()]) {
-    if (open.size - closed.length <= MAX_OPEN_PANES) break;
-    if (!pane.settled || pane.keepTab) continue;
-    if (await closePane(exec, pane)) closed.push(pane.tab);
-  }
-  return closed;
-}

package/src/pi-tools.ts

@@ -1,25 +0,0 @@
-/**
- * Facts about pi itself: its built-in tool names, and the capability that means "all of them".
- *
- * These lived in `agent-types.ts` until ADR-0016 deleted that module along with the rest of the
- * `@tintinweb/pi-subagents` port. They are not about agent types at all — `PI_BUILTIN_TOOLS` is how the
- * catalog tells a built-in from an extension tool, and `WILDCARD` is a capability id — so they outlive
- * the port and belong somewhere that does not name a package we no longer depend on.
- *
- * **`PI_BUILTIN_TOOLS` is a pinned observation, and it has already drifted once** (R-31): pi 0.84.1
- * exposes a `parallel` tool that the 0.83.0 list did not contain, which made it classify as an
- * *extension* capability. The list is used for classification only — never for enforcement, which is
- * `--tools`' job — so drift misfiles a capability rather than granting one. Keep it current anyway; a
- * misfiled capability is a confusing catalog.
- */
-
-import type { Capability } from "./resolve.ts";
-
-/** Capability held only by a delegator authorised to hand out everything. */
-export const WILDCARD: Capability = "tool:*";
-
-
-/** pi's built-in tools, observed against 0.84.1. `parallel` was added since 0.83.0 — see R-31. */
-export const PI_BUILTIN_TOOLS = [
-  "bash", "edit", "edit-diff", "find", "grep", "ls", "parallel", "read", "write",
-] as const;

package/src/producer-ipc-contract.ts

@@ -1,26 +0,0 @@
-import { createHash } from "node:crypto";
-import { isExecutionId } from "./execution-id.ts";
-import type { AttemptDemand } from "./resource-budget.ts";
-export const PRODUCER_IPC_LIMITS = Object.freeze({ frameBytes:1024, referenceBytes:128, childMs:3000, graceMs:50, maxElapsedMs:30000 });
-export interface ProducerIpcBinding { version:"producer-ipc-v1"; budgetDigest:string; orderId:string; experimentId:string; executionId:string; charterSha256:string; invocationId:string }
-export interface ProducerIpcReferences { claimRef:string; responseRef:string }
-const id = (v:unknown):v is string => typeof v === "string" && /^[a-zA-Z0-9:_-]{1,128}$/.test(v);
-const hash = (v:unknown):v is string => typeof v === "string" && /^[a-f0-9]{64}$/.test(v);
-export function ipcShape(value:unknown, keys:readonly 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||!d.enumerable||!Object.hasOwn(d,"value");})) throw new TypeError("closed producer IPC data required");
-}
-export function producerIpcBinding(value:ProducerIpcBinding):Readonly<ProducerIpcBinding> {
-  ipcShape(value,["version","budgetDigest","orderId","experimentId","executionId","charterSha256","invocationId"]);
-  if (value.version!=="producer-ipc-v1" || !hash(value.budgetDigest) || !hash(value.charterSha256) || !isExecutionId(value.executionId) || ![value.orderId,value.experimentId,value.invocationId].every(id)) throw new TypeError("exact producer IPC binding required");
-  return Object.freeze({version:value.version,budgetDigest:value.budgetDigest,orderId:value.orderId,experimentId:value.experimentId,executionId:value.executionId,charterSha256:value.charterSha256,invocationId:value.invocationId});
-}
-export const producerIpcBindingDigest = (value:ProducerIpcBinding) => createHash("sha256").update(JSON.stringify(producerIpcBinding(value))).digest("hex");
-export const producerIpcFrame = (value:ProducerIpcBinding):Buffer => Buffer.from(JSON.stringify({id:producerIpcBinding(value).invocationId,sequence:1})+"\n");
-/** Existing v4 reservation schema, not a new model/effort/skills experiment operation. */
-export function producerIpcDemand(value:ProducerIpcBinding):AttemptDemand {
-  const b=producerIpcBinding(value);return {attemptId:b.executionId,orderId:b.orderId,experimentId:b.experimentId,kind:"primary",parentAttemptId:null,inputBytes:Buffer.byteLength(JSON.stringify(b)),inputDigest:producerIpcBindingDigest(b)};
-}
-export function ipcReferences(value:ProducerIpcReferences):Readonly<ProducerIpcReferences> {
-  ipcShape(value,["claimRef","responseRef"]);if(!id(value.claimRef)||!id(value.responseRef))throw new TypeError("bounded evidence references required");
-  return Object.freeze({claimRef:value.claimRef,responseRef:value.responseRef});
-}