pi-daddy 0.17.0 → 0.18.0

package/src/approval.ts

@@ -11,6 +11,7 @@
 
 import { WILDCARD } from "./pi-tools.ts";
 import type { Capability, ResolveResult } from "./resolve.ts";
+import { approvalBindingsEqual, type ApprovalBinding } from "./correlation.ts";
 
 /** How far a single yes reaches in time. */
 export type ApprovalScope = "once" | "session" | "always";
@@ -110,6 +111,11 @@ export interface InheritableApproval {
    * no file to hash — and, per ADR-0019, is never persisted or offered `always` for the same reason.
    */
   bodySha256?: string;
+  /**
+   * Exact delegation binding for controllers that supply correlation/workspace context (ADR-0034).
+   * Bound approvals are deliberately not inherited: authority for one task must not become subtree-wide.
+   */
+  binding?: ApprovalBinding;
 }
 
 /**
@@ -133,7 +139,7 @@ export function inheritApprovals(approved: InheritableApproval[], grant: Capabil
   return [
     ...new Set(
       approved
-        .filter((a) => a.scope !== "once" && a.capability !== WILDCARD && held.has(a.capability))
+        .filter((a) => a.scope !== "once" && a.binding === undefined && a.capability !== WILDCARD && held.has(a.capability))
         // A definition subject MUST carry a pin to cross a boundary (ADR-0022, hardened after F1).
         //
         // `verifyInherited` honours an unpinned entry by decision — `<delegate>` names no file and a
@@ -234,6 +240,8 @@ export interface ApprovalEntry {
    * predates 0.10.0 and cannot be verified, which `entryVerdict` treats as changed: fail closed.
    */
   bodyAtApproval?: string;
+  /** Exact task/grant/workspace/context/parent binding for correlated controller calls (ADR-0034). */
+  binding?: ApprovalBinding;
 }
 
 export type EntryVerdict =
@@ -310,9 +318,14 @@ export interface ResolveApprovalsInput {
   subject: string;
   /** Approval KEYS approved for this session, in memory only. */
   sessionApprovals: ReadonlySet<string>;
-  /** Persisted entries by key, ALREADY validity-filtered by the store. */
+  /** Exact bindings for correlated session approvals. Kept separate so legacy keys remain compatible. */
+  sessionApprovalBindings?: ReadonlyMap<string, ApprovalBinding>;
+  /** Persisted entries by key, ALREADY definition/expiry-filtered by the store. */
   persisted: ReadonlyMap<string, ApprovalEntry>;
-  /** Capabilities approved further up the tree and inherited with the grant. */
+  /** When present, only an exact binding may satisfy this gate. */
+  expectedBinding?: ApprovalBinding;
+  /** Same-key persisted entries dropped specifically because their expiry passed. */
+  expiredKeys?: ReadonlySet<string>;
   /**
    * `capability@subject` keys inherited from the delegator (ADR-0014).
    *
@@ -326,7 +339,12 @@ export interface ResolveApprovalsResult {
   approved: Capability[];
   /** Gated capabilities still requiring a live human. */
   needsPrompt: Capability[];
+  /** A same-key approval existed but named another task/workspace/context/parent. */
+  scopeMismatched: Capability[];
+  expired: Capability[];
   sources: Record<Capability, ApprovalSource>;
+  scopes: Record<Capability, ApprovalScope>;
+  expiresAt: Record<Capability, string>;
 }
 
 /**
@@ -342,23 +360,38 @@ export function resolveApprovals(input: ResolveApprovalsInput): ResolveApprovals
   const inherited = input.inherited ?? new Set<string>();
   const approved: Capability[] = [];
   const needsPrompt: Capability[] = [];
-  const sources: Record<Capability, ApprovalSource> = {};
+  const scopeMismatched: Capability[] = [];
+  const expired: Capability[] = [];
+  const sources: Record<Capability, ApprovalSource> = {}, scopes: Record<Capability, ApprovalScope> = {};
+  const expiresAt: Record<Capability, string> = {};
 
   for (const capability of [...new Set(input.gated)].sort()) {
     const key = approvalKey(capability, input.subject);
-    if (inherited.has(key)) {
-      approved.push(capability);
-      sources[capability] = "inherited";
-    } else if (input.sessionApprovals.has(key)) {
-      approved.push(capability);
-      sources[capability] = "session";
-    } else if (input.persisted.has(key)) {
-      approved.push(capability);
-      sources[capability] = "persisted";
+    const expected = input.expectedBinding;
+    const sessionBinding = input.sessionApprovalBindings?.get(key);
+    const persisted = input.persisted.get(key);
+    const inheritedApplies = expected === undefined && inherited.has(key);
+    const legacySessionApplies = expected === undefined && input.sessionApprovals.has(key);
+    const boundSessionApplies = expected !== undefined && approvalBindingsEqual(sessionBinding, expected);
+    const persistedApplies = persisted !== undefined && (
+      expected === undefined ? persisted.binding === undefined : approvalBindingsEqual(persisted.binding, expected)
+    );
+
+    if (inheritedApplies) {
+      approved.push(capability); sources[capability] = "inherited"; scopes[capability] = "session";
+    } else if (legacySessionApplies || boundSessionApplies) {
+      approved.push(capability); sources[capability] = "session"; scopes[capability] = "session";
+    } else if (persistedApplies) {
+      approved.push(capability); sources[capability] = "persisted"; scopes[capability] = "always";
+      expiresAt[capability] = persisted!.expiresAt;
     } else {
       needsPrompt.push(capability);
+      if (input.expiredKeys?.has(key)) expired.push(capability);
+      else if (expected !== undefined && (sessionBinding !== undefined || persisted !== undefined || input.sessionApprovals.has(key))) {
+        scopeMismatched.push(capability);
+      }
     }
   }
 
-  return { approved, needsPrompt, sources };
+  return { approved, needsPrompt, scopeMismatched, expired, sources, scopes, expiresAt };
 }

package/src/chain.ts

@@ -29,7 +29,7 @@ import { randomBytes } from "node:crypto";
  * How much of a step's output crosses to the next step.
  *
  * A child may return up to `DEFAULT_MAX_OUTPUT_BYTES` (1 MiB); pasting that into a task would spend most of the
- * next child's context on its predecessor's transcript. 64 KiB is a generous summary and a poor transcript, which
+ * next child's context on its predecessor's transcript. 32 KiB is a generous summary and a poor transcript, which
  * is the right side of that line for a handoff.
  */
 export const HANDOFF_MAX_BYTES = 32 * 1024;
@@ -156,6 +156,8 @@ export interface ChainStep {
   agent?: string;
   tools?: string[];
   model?: string;
+  correlation?: import("./correlation.ts").CorrelationMetadata;
+  workspace?: { workspace_id: string; access: import("./workspace.ts").WorkspaceAccess };
 }
 
 /**

package/src/check-runner.ts

@@ -0,0 +1,341 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdtemp, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, isAbsolute, join } from "node:path";
+import { normaliseCorrelation, type CorrelationMetadata } from "./correlation.ts";
+import {
+  appendLedgerEvent,
+  buildWorkspaceLeaseEvent,
+  type CheckReceiptLedgerEvent,
+  LEDGER_VERSION,
+} from "./ledger.ts";
+import { computeGitCandidateIdentity } from "./git-identity.ts";
+import { runChild } from "./run-child.ts";
+import { GovernanceRefusal, refusal } from "./refusals.ts";
+import {
+  acquireWorkspaceLease,
+  defaultWorkspaceLeaseDir,
+  type ValidatedWorkspace,
+  type WorkspaceAccess,
+  leaseAcquisitionOutcome,
+  leaseReleaseLedgerOutcome,
+} from "./workspace.ts";
+
+export interface CheckDefinition {
+  /** Absolute operator-owned executable. PATH lookup is deliberately not part of the contract. */
+  executable: string;
+  /** Exact argv elements. Never a shell command string. */
+  argv: string[];
+  /** Fixed non-sensitive environment values. */
+  env?: Record<string, string>;
+  /** Explicit inherited names. Sensitive names are still removed. */
+  inherit_env?: string[];
+  timeout_ms?: number;
+  max_output_bytes?: number;
+  /** Checks are assumed capable of writing unless the operator declares read. */
+  workspace_access?: WorkspaceAccess;
+}
+
+export interface CheckRegistry {
+  version: 1;
+  checks: Record<string, CheckDefinition>;
+}
+
+export interface CheckReceipt {
+  schema_version: "1.0";
+  receipt_id: string;
+  check_id: string;
+  executable: string;
+  executable_sha256: string;
+  argv: string[];
+  argv_sha256: string;
+  cwd: string;
+  cwd_sha256: string;
+  started_at: string;
+  ended_at: string;
+  exit_code: number | null;
+  signal: NodeJS.Signals | null;
+  timed_out: boolean;
+  aborted: boolean;
+  truncated: boolean;
+  output_sha256: string;
+  workspace_id: string;
+  workspace_access: WorkspaceAccess;
+  head_sha: string;
+  tree_sha: string;
+  correlation?: CorrelationMetadata;
+}
+
+const SAFE_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SENSITIVE_ENV_NAME = /(?:^|_)(?:TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH|COOKIE|PRIVATE_KEY|API_KEY)(?:_|$)|^PI_GRANTS_|^(?:AWS|GITHUB|GITLAB|AZURE|GOOGLE)_/i;
+
+export function buildCheckEnvironment(
+  definition: CheckDefinition,
+  inherited: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const name of definition.inherit_env ?? []) {
+    if (!SAFE_ENV_NAME.test(name) || SENSITIVE_ENV_NAME.test(name)) continue;
+    if (inherited[name] !== undefined) env[name] = inherited[name];
+  }
+  for (const [name, value] of Object.entries(definition.env ?? {})) {
+    if (!SAFE_ENV_NAME.test(name) || SENSITIVE_ENV_NAME.test(name)) continue;
+    env[name] = value;
+  }
+  return env;
+}
+
+function validateDefinition(checkId: string, value: CheckDefinition | undefined): CheckDefinition {
+  if (!value) {
+    throw new GovernanceRefusal(refusal(
+      "CHECK_NOT_CONFIGURED", `check ${JSON.stringify(checkId)} is not present in operator-owned configuration`, { check_id: checkId },
+    ));
+  }
+  if (!isAbsolute(value.executable) || !Array.isArray(value.argv) || value.argv.some((item) => typeof item !== "string")) {
+    throw new GovernanceRefusal(refusal(
+      "CHECK_CONFIGURATION_INVALID", `check ${JSON.stringify(checkId)} requires an absolute executable and argv string array`,
+      { check_id: checkId },
+    ));
+  }
+  for (const bound of [value.timeout_ms, value.max_output_bytes]) {
+    if (bound !== undefined && (!Number.isInteger(bound) || bound <= 0)) {
+      throw new GovernanceRefusal(refusal(
+        "CHECK_CONFIGURATION_INVALID", `check ${JSON.stringify(checkId)} has a non-positive runtime bound`, { check_id: checkId },
+      ));
+    }
+  }
+  return value;
+}
+
+function receiptId(receipt: Omit<CheckReceipt, "receipt_id">): string {
+  return createHash("sha256").update(JSON.stringify(receipt), "utf8").digest("hex");
+}
+
+export async function runNamedCheck(input: {
+  checkId: string;
+  registry: CheckRegistry;
+  workspace: ValidatedWorkspace;
+  correlation?: CorrelationMetadata;
+  inheritedEnv?: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
+  leaseDir?: string;
+  ledgerPath?: string;
+}): Promise<{
+  output: string;
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  receipt: CheckReceipt;
+}> {
+  if (input.registry?.version !== 1 || !input.registry.checks || typeof input.registry.checks !== "object") {
+    throw new GovernanceRefusal(refusal("CHECK_CONFIGURATION_INVALID", "check registry must contain {version:1, checks:{...}}"));
+  }
+  const definition = validateDefinition(input.checkId, input.registry.checks[input.checkId]);
+  let executable: string;
+  try {
+    executable = await realpath(definition.executable);
+    if (!(await stat(executable)).isFile()) throw new Error("not a file");
+  } catch (error) {
+    throw new GovernanceRefusal(refusal(
+      "CHECK_CONFIGURATION_INVALID", `check ${JSON.stringify(input.checkId)} executable is not a real file (${String(error)})`,
+      { check_id: input.checkId },
+    ));
+  }
+
+  const argvSha256 = createHash("sha256").update(JSON.stringify(definition.argv), "utf8").digest("hex");
+  const cwdSha256 = createHash("sha256").update(input.workspace.root, "utf8").digest("hex");
+  const access = definition.workspace_access ?? "write";
+  // Evidence checks coordinate exclusively so their pre/post candidate identities cannot overlap another
+  // governed writer. `access` still records what the configured executable is intended to do.
+  const leaseAccess: WorkspaceAccess = "write";
+  const ownerId = `check:${input.checkId}:${randomUUID()}`;
+  const correlation = normaliseCorrelation(input.correlation);
+  let lease: Awaited<ReturnType<typeof acquireWorkspaceLease>> | undefined;
+  let stagedDir: string | undefined;
+  /** Failures of best-effort RECORDS, reported alongside whatever actually happened — never instead of it. */
+  const notes: string[] = [];
+  let releaseReason = "failed";
+  try {
+    try {
+      lease = await acquireWorkspaceLease({
+        workspace: input.workspace, access: leaseAccess, leaseDir: input.leaseDir ?? defaultWorkspaceLeaseDir(),
+        ownerId, signal: input.signal,
+      });
+    } catch (error) {
+      if (input.ledgerPath) await appendLedgerEvent(
+        { path: input.ledgerPath, strict: true },
+        buildWorkspaceLeaseEvent({
+          childId: ownerId, workspaceId: input.workspace.workspaceId, root: input.workspace.root, access: leaseAccess,
+          outcome: "refused",
+          correlation, now: new Date(),
+          ...(error instanceof GovernanceRefusal
+            ? { refusal: { code: error.code, message: error.message, ...(error.details ? { details: error.details } : {}) } }
+            : {}),
+        }),
+      );
+      throw error;
+    }
+    if (input.ledgerPath) {
+      try {
+        await appendLedgerEvent(
+          { path: input.ledgerPath, strict: true },
+          buildWorkspaceLeaseEvent({
+            childId: ownerId, workspaceId: input.workspace.workspaceId, root: input.workspace.root, access: leaseAccess,
+            outcome: leaseAcquisitionOutcome(leaseAccess, lease.recovered), recovered: lease.recovered,
+            correlation, now: new Date(),
+          }),
+        );
+      } catch (error) {
+        await lease.release("ledger-failed");
+        lease = undefined;
+        throw error;
+      }
+    }
+
+    const before = await computeGitCandidateIdentity(input.workspace);
+    for (const [name, supplied, actual] of [
+      ["head_sha", correlation?.head_sha, before.headSha], ["tree_sha", correlation?.tree_sha, before.treeSha],
+    ] as const) {
+      if (supplied && supplied !== actual) throw new GovernanceRefusal(refusal(
+        "CHECK_IDENTITY_MISMATCH", `check ${JSON.stringify(input.checkId)} ${name} does not match the validated workspace`,
+        { check_id: input.checkId, supplied, actual },
+      ));
+    }
+    const executableBytes = await readFile(executable);
+    const executableSha256 = createHash("sha256").update(executableBytes).digest("hex");
+    stagedDir = await mkdtemp(join(tmpdir(), "pi-daddy-check-exec-"));
+    const stagedExecutable = join(stagedDir, basename(executable));
+    await writeFile(stagedExecutable, executableBytes, { mode: 0o700 });
+    await chmod(stagedExecutable, 0o700);
+    const leaseAbort = new AbortController();
+    let leaseLost = false;
+    lease.lost.then(() => { leaseLost = true; leaseAbort.abort(); });
+    const checkSignal = input.signal ? AbortSignal.any([input.signal, leaseAbort.signal]) : leaseAbort.signal;
+    const started = new Date();
+    const result = await runChild({
+      command: "setpriv", args: ["--pdeathsig", "KILL", "--", stagedExecutable, ...definition.argv],
+      env: buildCheckEnvironment(definition, input.inheritedEnv), cwd: input.workspace.root,
+      signal: checkSignal, timeoutMs: definition.timeout_ms, maxOutputBytes: definition.max_output_bytes,
+      onSpawn: (pid) => lease!.attachProcess(pid),
+    });
+    const ended = new Date();
+    releaseReason = input.signal?.aborted ? "cancelled" : result.timedOut ? "timeout" : result.aborted ? "failed" : "completed";
+    // Every throw below re-stamps this. Without that, a check refused for CHECK_IDENTITY_MISMATCH still
+    // wrote `released / completed` from the `finally` — the LAST lease event for that owner — so the trail
+    // still read like a clean run and `verifyLedger` still counted a clean release. The R-114 fix added a
+    // refusal line beside the misleading one instead of correcting it.
+    if (result.spawnError) throw new GovernanceRefusal(refusal(
+      "EXECUTOR_UNAVAILABLE", `check ${JSON.stringify(input.checkId)} could not start its constrained executor`,
+      { check_id: input.checkId },
+    ));
+    if (leaseLost) throw new GovernanceRefusal(refusal(
+      "WORKSPACE_LEASE_STALE", `check ${JSON.stringify(input.checkId)} lost its workspace lease while running`,
+      { check_id: input.checkId },
+    ));
+    const after = await computeGitCandidateIdentity(input.workspace);
+    if (leaseLost) throw new GovernanceRefusal(refusal(
+      "WORKSPACE_LEASE_STALE", `check ${JSON.stringify(input.checkId)} lost its workspace lease before receipt`,
+      { check_id: input.checkId },
+    ));
+    if (before.headSha !== after.headSha || before.treeSha !== after.treeSha) {
+      throw new GovernanceRefusal(refusal(
+        "CHECK_IDENTITY_MISMATCH", `check ${JSON.stringify(input.checkId)} workspace changed while it ran`,
+        { check_id: input.checkId },
+      ));
+    }
+    // The candidate is now measured and the process is dead. End the lease before writing the receipt so
+    // lease loss cannot race a blocked ledger append and leave behind evidence from an unprotected run.
+    // Record what release actually DID. This asserted `released` unconditionally and threw the outcome
+    // away, so the evidence path reproduced the very defect the outcome union was added to expose: a lost
+    // or unrecorded handover ledgered as a clean one, with `lease = undefined` stopping the `finally` from
+    // ever noticing (R-100/R-103, found while reviewing the fix for R-99).
+    const releaseOutcome = await lease.release(releaseReason);
+    lease = undefined;
+    if (leaseLost) throw new GovernanceRefusal(refusal(
+      "WORKSPACE_LEASE_STALE", `check ${JSON.stringify(input.checkId)} lost its workspace lease before receipt`,
+      { check_id: input.checkId },
+    ));
+    if (input.ledgerPath) await appendLedgerEvent(
+      { path: input.ledgerPath, strict: true },
+      buildWorkspaceLeaseEvent({
+        childId: ownerId, workspaceId: input.workspace.workspaceId, root: input.workspace.root, access: leaseAccess,
+        outcome: leaseReleaseLedgerOutcome(releaseOutcome, releaseReason), releaseReason, correlation, now: new Date(),
+      }),
+    );
+    const body: Omit<CheckReceipt, "receipt_id"> = {
+      schema_version: "1.0", check_id: input.checkId, executable, executable_sha256: executableSha256,
+      argv: [...definition.argv], argv_sha256: argvSha256, cwd: input.workspace.root, cwd_sha256: cwdSha256,
+      started_at: started.toISOString(), ended_at: ended.toISOString(), exit_code: result.code,
+      signal: result.signal ?? null, timed_out: result.timedOut, aborted: result.aborted, truncated: result.truncated,
+      output_sha256: createHash("sha256").update(result.text, "utf8").digest("hex"),
+      workspace_id: input.workspace.workspaceId, workspace_access: access,
+      head_sha: before.headSha, tree_sha: before.treeSha, ...(correlation ? { correlation } : {}),
+    };
+    const receipt: CheckReceipt = { receipt_id: receiptId(body), ...body };
+    if (input.ledgerPath) {
+      const event: CheckReceiptLedgerEvent = {
+        ledgerVersion: LEDGER_VERSION, event: "check_receipt", ts: ended.toISOString(), childId: ownerId,
+        receiptId: receipt.receipt_id, workspaceId: input.workspace.workspaceId, checkId: input.checkId,
+        treeSha: receipt.tree_sha, ...(correlation ? { correlation } : {}),
+      };
+      await appendLedgerEvent({ path: input.ledgerPath, strict: true }, event);
+    }
+    return { output: result.text, exitCode: result.code, signal: result.signal ?? null, receipt };
+  } catch (error) {
+    // The run did not complete, so the release must not be recorded as if it had. Without this the
+    // `finally` wrote `released / completed` as the LAST lease event for a refused check, so the trail
+    // still read like a clean run and `verifyLedger` still counted a clean release — the R-114 fix put a
+    // refusal line beside the misleading one instead of correcting it.
+    if (releaseReason === "completed") releaseReason = "refused";
+    // The single most important negative result this feature can produce — CHECK_IDENTITY_MISMATCH, "the
+    // workspace changed while the check ran" — used to leave NO ledger evidence at all, while the
+    // `finally` recorded `released, reason: completed`, so the trail read like a clean run (R-114).
+    if (input.ledgerPath) {
+      await appendLedgerEvent(
+        {
+          path: input.ledgerPath,
+          // Best effort, and loud: this records a failure, so it must not replace the failure. A strict
+          // append that threw here would substitute "ledger write failed" for the evidence-integrity
+          // refusal that actually happened (R-115).
+          strict: false,
+          // NOT empty. `onFailure` exists because a non-strict append is a choice not to fail closed and
+          // never a choice to be silent — the comment above says "loud", and an empty callback is the
+          // definition of swallowing. This guards the evidence record itself, so losing it silently is
+          // how a mutated workspace came to leave a trail that read like a clean run.
+          onFailure: (cause) => { notes.push(`check refusal record failed: ${String(cause)}`); },
+        },
+        buildWorkspaceLeaseEvent({
+          childId: ownerId, workspaceId: input.workspace.workspaceId, root: input.workspace.root, access: leaseAccess,
+          outcome: "refused",
+          refusal: error instanceof GovernanceRefusal
+            ? { code: error.code, message: error.message, ...(error.details ? { details: error.details } : {}) }
+            : refusal("CHECK_IDENTITY_UNAVAILABLE", `check ${JSON.stringify(input.checkId)} failed (${String(error)})`),
+          correlation, now: new Date(),
+        }),
+      );
+    }
+    throw error;
+  } finally {
+    if (stagedDir) await rm(stagedDir, { recursive: true, force: true });
+    if (lease) {
+      // `release()` cannot throw (R-99), and the record of it is best-effort for the same reason as
+      // above: a `finally` that throws destroys whatever the caller was already returning or raising.
+      const outcome = await lease.release(releaseReason);
+      if (input.ledgerPath) await appendLedgerEvent(
+        {
+          path: input.ledgerPath,
+          strict: false,
+          onFailure: (cause) => { notes.push(`check lease release record failed: ${String(cause)}`); },
+        },
+        buildWorkspaceLeaseEvent({
+          childId: ownerId, workspaceId: input.workspace.workspaceId, root: input.workspace.root, access: leaseAccess,
+          outcome: outcome === "lost"
+            ? "lost"
+            : outcome === "released-unrecorded"
+              ? "released-unrecorded"
+              : releaseReason === "timeout" ? "timeout" : "released",
+          releaseReason, correlation, now: new Date(),
+        }),
+      );
+    }
+  }
+}