pi-daddy 0.13.0

package/src/ledger.ts

@@ -0,0 +1,214 @@
+/**
+ * Append-only grant ledger.
+ *
+ * Exists because pi-fabric's persisted execution trace records `args: {}` — it captures *that* a child
+ * ran, not *what it was authorised to do* (docs/probes/pi-fabric-eval probe 5). Without this record
+ * you cannot answer "what was this sub-agent permitted to do?" after the fact, which is the whole
+ * point of a governance layer.
+ *
+ * `denied` is the field that earns the file: an agent repeatedly requesting capabilities it does not
+ * hold is an escalation attempt, and it is invisible without a record.
+ *
+ * PRIVACY: capability ids, counts, and identifiers only. Never prompts, tool arguments, or results.
+ *
+ * ADR-0018 makes the boundary explicit rather than leaving it to be inferred, because a record now carries
+ * something about the child's instructions. **`definitionDigest` is an identifier**: a SHA-256 of an
+ * operator-authored file already committed to a repository, which names a version without reproducing it.
+ * **The task is not recorded, anywhere, ever** — it is assembled by the model from the parent's context and
+ * can carry anything the parent could see, so a ledger holding it would be a secrets sink. That half of
+ * "what was this child told to do?" is out of the ledger by decision, not by omission.
+ */
+
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { withFileLock } from "./file-lock.ts";
+import { dirname } from "node:path";
+import type { Capability, ResolveResult } from "./resolve.ts";
+import type { DefinitionDigest } from "./definitions.ts";
+import { DELEGATE_SUBJECT } from "./approval.ts";
+import type { ApprovalScope, ApprovalSource } from "./approval.ts";
+import type { PromptOutcomeKind } from "./approval-prompt.ts";
+
+export interface GrantRecord {
+  ts: string;
+  parentId: string;
+  childId: string;
+  depth: number;
+  agentType?: string;
+  requested: Capability[];
+  parentGrant: Capability[];
+  effective: Capability[];
+  denied: Capability[];
+  clipped: Capability[];
+  gatedBlocked: Capability[];
+  /** True when the spawn was refused outright rather than narrowed. */
+  blocked: boolean;
+  /** Present when the spawn was refused, or when resolution failed. */
+  reason?: string;
+  /**
+   * Gated capabilities satisfied for this spawn.
+   *
+   * The ledger used to have ONE flavour of no. It now has three, and they call for different responses:
+   *  - `denied` non-empty            -> an agent asked for more than it holds. ESCALATION ATTEMPT.
+   *  - `humanDenied`                 -> a person was asked and said no. WORKING AS DESIGNED.
+   *  - `gatedBlocked` with no source -> nobody was there to ask. A background run hit a gate; the fix is
+   *                                     an operator pre-approving it, not an incident.
+   */
+  approved?: Capability[];
+  approvalSource?: ApprovalSource;
+  /**
+   * WHERE each approved capability's yes came from — one entry per capability (R-46).
+   *
+   * `approvalSource` above is a single scalar and was written for a set: gate `tool:bash` and `tool:write`,
+   * let a persisted entry cover `bash` while a human clicks *Allow once* for `write`, and the record read
+   * `approved: ["tool:bash","tool:write"], approvalSource: "prompt"` — **asserting a human was asked about
+   * `tool:bash`, which they were not.** The ledger's whole job is answering "did a human authorise this?",
+   * so over-claiming in that direction is the worst available failure.
+   *
+   * The scalar is kept and is now written **only when every approved capability shares one source**, so a
+   * reader of old and new lines alike can trust it; when sources differ it is omitted and this map carries
+   * the truth. Two fields, one of which is a safe summary of the other — not two competing answers.
+   */
+  approvalSources?: Record<Capability, ApprovalSource>;
+  /**
+   * How far each prompted capability's yes reaches (F5). Same shape and same reason as `approvalSources`:
+   * `approvalScope` below is a **derived summary**, emitted only when every prompted capability shares one
+   * scope. This field decides propagation — `inheritApprovals` drops `once` — so a scalar that described
+   * one capability while claiming to describe the set was not merely a reporting defect.
+   */
+  approvalScopes?: Record<Capability, ApprovalScope>;
+  /** Present only when the source was a live prompt, and only when one scope covers the whole set. */
+  approvalScope?: ApprovalScope;
+  /** A human was asked and declined. Distinct from `denied`, which is an escalation attempt. */
+  humanDenied?: boolean;
+  /**
+   * WHY a gate went unsatisfied, when the answer was not a yes.
+   *
+   * `PromptOutcomeKind` has five members and this record kept exactly one of them (`humanDenied`, from
+   * `declined`). So `no-ui`, `dismissed` (a timeout or an abort) and `error` produced **identical** records
+   * — `gatedBlocked` non-empty, no `approvalSource`, `blocked: true` — and the only thing separating them
+   * was free-text `reason`, written for a human at the call site. Given a failed run, *"was there an
+   * operator who timed out, or was there nobody to ask?"* was not answerable from any field, and the fix
+   * for each is different: one is a queue or a longer `PI_GRANTS_APPROVAL_TIMEOUT`, the other is an
+   * operator pre-approving.
+   *
+   * The discriminant was already computed and thrown away. ADR-0026 leans on this vocabulary being able to
+   * say *"nobody was there to ask"* and be believed, so it is recorded rather than inferred.
+   *
+   * **Privacy is unchanged**: this is a fixed five-member enum, not text — nothing model-authored, nothing
+   * a task could carry.
+   */
+  gateOutcome?: PromptOutcomeKind;
+  /**
+   * WHICH operator-authored instructions this child was given (ADR-0018).
+   *
+   * Identifies, never reproduces: matching digests prove two children ran the same text, and a digest that
+   * no longer matches the file proves the definition changed since. **It says nothing about whether those
+   * instructions were correct or whether the child obeyed them** — it identifies text, it does not evaluate
+   * it. Absent for a `tools:`-style delegation, which has no definition.
+   */
+  definitionDigest?: DefinitionDigest;
+}
+
+export interface LedgerOptions {
+  /** Path to the JSONL file. Parent directories are created on demand. */
+  path: string;
+  /**
+   * When true, a ledger write failure throws instead of being swallowed.
+   *
+   * Default is `true` and that is deliberate: for a security control, an unrecorded grant should fail
+   * closed. Set false only where the ledger is advisory.
+   */
+  strict?: boolean;
+}
+
+export function buildRecord(args: {
+  parentId: string;
+  childId: string;
+  depth: number;
+  agentType?: string;
+  requested: Capability[];
+  parentGrant: Capability[];
+  result: ResolveResult;
+  blocked: boolean;
+  reason?: string;
+  approved?: Capability[];
+  approvalSources?: Record<Capability, ApprovalSource>;
+  approvalScopes?: Record<Capability, ApprovalScope>;
+  humanDenied?: boolean;
+  gateOutcome?: PromptOutcomeKind;
+  definitionDigest?: DefinitionDigest;
+  now: Date;
+}): GrantRecord {
+  // R-46: the scalar is a SUMMARY, emitted only when it cannot mislead. `buildRecord` derives it rather
+  // than accepting it, so a call site cannot supply one that disagrees with the map beside it.
+  const sources = args.approvalSources ?? {};
+  const distinct = [...new Set(Object.values(sources))];
+  const scopes = args.approvalScopes ?? {};
+  const distinctScopes = [...new Set(Object.values(scopes))];
+  return {
+    ts: args.now.toISOString(),
+    parentId: args.parentId,
+    childId: args.childId,
+    depth: args.depth,
+    agentType: args.agentType,
+    requested: args.requested,
+    parentGrant: args.parentGrant,
+    effective: args.result.effective,
+    denied: args.result.denied,
+    clipped: args.result.clipped,
+    gatedBlocked: args.result.gatedBlocked,
+    blocked: args.blocked,
+    reason: args.reason,
+    ...(args.approved && args.approved.length > 0 ? { approved: args.approved } : {}),
+    ...(distinct.length === 1 ? { approvalSource: distinct[0] } : {}),
+    ...(Object.keys(sources).length > 0 ? { approvalSources: sources } : {}),
+    ...(distinctScopes.length === 1 ? { approvalScope: distinctScopes[0] } : {}),
+    ...(Object.keys(scopes).length > 0 ? { approvalScopes: scopes } : {}),
+    ...(args.humanDenied ? { humanDenied: true } : {}),
+    // Written whenever a gate was reached and not satisfied by a yes. `granted` is omitted deliberately —
+    // an approved spawn already says so through `approvalSources`, and a field that appears on every record
+    // stops being a signal.
+    ...(args.gateOutcome && args.gateOutcome !== "granted" ? { gateOutcome: args.gateOutcome } : {}),
+    ...(args.definitionDigest ? { definitionDigest: args.definitionDigest } : {}),
+  };
+}
+
+// R-49: the lock moved to `src/file-lock.ts` so the approvals store could use the SAME one rather than
+// grow a second copy. Re-exported because `./ledger` is a published subpath and these were part of it.
+export { LOCK_TIMEOUT_MS, STALE_LOCK_MS } from "./file-lock.ts";
+
+// The reading half, split out under the file-size guard and re-exported so `./ledger` is unchanged for
+// anyone importing it. See `ledger-report.ts` for why the seam is where it is.
+export { verifyLedger, type LedgerReport } from "./ledger-report.ts";
+
+/**
+ * Serialise appends across processes.
+ *
+ * **Why the ledger needs it.** For most of this package's life cardinality was bounded to one by `delegate`
+ * being blocking, so there was never a second writer. Fan-out removes that: `ENV_LEDGER` propagates to
+ * children, so a subtree can have many processes appending to one file.
+ *
+ * A ledger write that cannot take the lock **fails the delegation closed** — see `appendRecord`'s `strict`
+ * — because a child running with granted capabilities and no audit line is what the ledger exists to
+ * prevent. That is the opposite of what the approvals store does with the same lock, and deliberately so.
+ */
+const withLedgerLock = <T>(path: string, write: () => Promise<T>): Promise<T> =>
+  withFileLock(path, "grant ledger", write);
+
+export async function appendRecord(options: LedgerOptions, record: GrantRecord): Promise<void> {
+  const line = `${JSON.stringify(record)}\n`;
+  try {
+    await mkdir(dirname(options.path), { recursive: true });
+    // O_APPEND alone is not enough once several processes write to one ledger — see `withLedgerLock`.
+    await withLedgerLock(options.path, () => appendFile(options.path, line, { encoding: "utf8", flag: "a" }));
+  } catch (error) {
+    if (options.strict ?? true) {
+      throw new Error(`grant ledger write failed (failing closed): ${String(error)}`);
+    }
+  }
+}
+
+/** True when this record shows an agent asking for more than it holds. */
+export function isEscalationAttempt(record: GrantRecord): boolean {
+  return record.denied.length > 0;
+}

package/src/pane-reaper.ts

@@ -0,0 +1,132 @@
+/**
+ * Close herdr panes this process opened but never got to close.
+ *
+ * `runHerdrPane` closes its pane in a `finally`, which covers a thrown error and a timeout — **not the
+ * process being killed**. A pi session interrupted mid-fan-out left one pane per in-flight child, and
+ * `docs/probes/g16-herdr` records that an orphaned pane is not trivially closable afterwards.
+ *
+ * **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";
+
+export interface OpenPane {
+  /** herdr tab id — what `tab close` takes. */
+  tab: string;
+  /** Agent name, so the agent is stopped before its tab goes away. */
+  name: string;
+  /** Staged system-prompt directory, removed with the pane it belonged to. */
+  promptDir?: string;
+}
+
+/**
+ * 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;
+    try {
+      syncExec(["agent", "stop", pane.name]);
+    } catch {
+      /* the agent may already be gone; the tab is what matters */
+    }
+    try {
+      syncExec(["tab", "close", pane.tab]);
+      closed.push(pane.tab);
+    } catch {
+      /* an orphan we could not close: `herdr tab close` is the manual remedy, as documented above */
+    }
+    if (pane.promptDir) {
+      try {
+        rmSync(pane.promptDir, { recursive: true, force: true });
+      } catch {
+        /* /tmp litter, not correctness */
+      }
+    }
+    open.delete(pane.tab);
+  }
+  return closed;
+}

package/src/pi-tools.ts

@@ -0,0 +1,25 @@
+/**
+ * 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;