pi-daddy 0.21.0 → 0.22.0

package/extensions/grants.ts

@@ -40,6 +40,7 @@ import { planWithApprovals } from "./run-delegation.ts";
 import { createGrantsSession, loadProjectDefinitions, resolveExecutor, type GrantsSession } from "./session.ts";
 import { reportSessionStart } from "./session-report.ts";
 import { SPAWN_TOOLS, tripwireReason } from "./tripwire.ts";
+import { reportGrantStoreRefusal } from "./grant-store-refusal.ts";
 import {
   defaultDashboardPaths,
   offerDashboardHandshake,
@@ -93,6 +94,11 @@ export default function (pi: ExtensionAPI) {
       );
     }
     try {
+      try {
+        await reportGrantStoreRefusal(session, ctx.ui);
+      } catch (error) {
+        ctx.ui.notify(`grants: stored-grant refusal reporting failed (${String(error)}); the session remains refused.`, "error");
+      }
       // Guarded together, and guarded at all because of R-60 rather than because either one throws today:
       // both loaders swallow their own filesystem errors, so this catch is currently unreachable. The point
       // is that "currently" is not a property anyone can rely on — `verifyLedger` was also harmless until

package/extensions/run-delegation.ts

@@ -24,6 +24,7 @@ import {
 import type { InheritableApproval } from "../src/approval.ts";
 import type { GrantsSession } from "./session.ts";
 import type { CorrelationMetadata } from "../src/correlation.ts";
+import { preflightModel, type ModelCatalogue } from "../src/model-preflight.ts";
 import { GovernanceRefusal, refusal as structuredRefusal } from "../src/refusals.ts";
 import { executePlannedChild, type DelegationOutcome } from "./execute-child.ts";
 import { recordDelegationDecision, type ApprovalLedgerFacts } from "./delegation-ledger.ts";
@@ -57,6 +58,7 @@ interface ChildSpec {
 interface DelegationToolContext extends ApprovalUIContext {
   cwd: string;
   model?: { provider: string; id: string };
+  modelRegistry: ModelCatalogue;
 }
 
 /** A planned delegation, plus whatever approvals contributed to it. */
@@ -274,11 +276,17 @@ export async function runOneDelegation(
   // requested and refused, and stored approvals still count toward it — nothing is *hidden*, only nobody is
   // *asked*. It is the same argument `/grants` uses for its preview.
   const executorRefusal = session.executor.refusal;
+  const modelRefusal = preflightModel(
+    request.model,
+    ctx.modelRegistry,
+    session.modelResolutionCache,
+    session.allowUnresolvedModels,
+  );
   let preparedWorkspace: PreparedWorkspace | undefined;
   let approvalOutcome: ApprovalOutcome | undefined;
   let plan: ReturnType<typeof planDelegation>;
 
-  if (spec.workspace && !executorRefusal) {
+  if (spec.workspace && !executorRefusal && !modelRefusal) {
     // Check non-liftable refusals before taking a lease, and take the lease before asking a human. This
     // preserves both anti-race rules: a doomed spawn cannot bank approval, and a conflicting writer starts
     // no child process.
@@ -307,7 +315,14 @@ export async function runOneDelegation(
       }
     }
   } else {
-    const gated = await planWithApprovals(session, request, extra, executorRefusal ? null : ctx, signal, preApproved);
+    const gated = await planWithApprovals(
+      session,
+      request,
+      extra,
+      executorRefusal || modelRefusal ? null : ctx,
+      signal,
+      preApproved,
+    );
     plan = gated.plan;
     approvalOutcome = gated.approval;
   }
@@ -315,6 +330,10 @@ export async function runOneDelegation(
   if (executorRefusal) {
     const message = `grants: ${executorRefusal}`;
     plan = { ...plan, ok: false, reason: message, refusal: structuredRefusal("EXECUTOR_UNAVAILABLE", message) };
+  } else if (modelRefusal) {
+    // This is a routing preflight, not a grant decision: preserve the resolved capability facts and replace
+    // only the outcome. It is still recorded by the common refusal path, and no lease, dialog or child starts.
+    plan = { ...plan, ok: false, reason: modelRefusal.message, refusal: modelRefusal };
   }
 
   // The capability decision provisions the child, so this append remains load-bearing and fails closed.

package/extensions/session.ts

@@ -44,8 +44,10 @@ import type { Capability } from "../src/resolve.ts";
 import { loadDefinitions } from "../src/definitions.ts";
 import { buildCatalog } from "../src/catalog.ts";
 import { ENV_WORKSPACE_REGISTRY } from "../src/workspace.ts";
-import { grantStorePath, loadStoredGrantSync, projectLedgerPath } from "../src/grant-store.ts";
+import type { GrantStoreRefusalReason } from "../src/grant-store.ts";
 import { republishable } from "./approvals.ts";
+import { storedGrantSessionState } from "./stored-grant-session.ts";
+import { ENV_ALLOW_UNRESOLVED_MODELS } from "../src/model-preflight.ts";
 
 /**
  * Run governed children in herdr panes instead of captured child processes.
@@ -118,6 +120,10 @@ export interface GrantsSession {
   readonly fanoutBudget: number;
   /** Whether `delegate` / `delegate_all` are registered at all (S-5). Decided on the INHERITED grant. */
   readonly mayDelegate: boolean;
+  /** Operator escape hatch for custom model resolution. Exact `1`, read once for the session. */
+  readonly allowUnresolvedModels: boolean;
+  /** Results from pi's synchronous model catalogue, shared by every delegation in this session. */
+  readonly modelResolutionCache: Map<string, boolean>;
   /** Path to this extension, so a child granted `tool:delegate` can delegate in turn. */
   readonly extensionPath?: string;
 
@@ -183,6 +189,8 @@ export interface GrantsSession {
    * `createGrantsSession` for why the factory cannot use `ctx.cwd`.
    */
   readonly storeCwd: string;
+  /** Invalid stored state fails closed and is reported/ledgered during session_start. */
+  readonly grantStoreRefusal?: { reason: GrantStoreRefusalReason; path: string };
   /**
    * Adopt the project choice made DURING the session — grant plus optional default ledger — without restart.
    *
@@ -260,14 +268,13 @@ export function createGrantsSession(extensionPath: string | undefined): GrantsSe
   const storeCwd = process.cwd();
   // One root-only store read supplies both decisions made by `/grants init`. A child always has ENV_GRANT,
   // so it cannot activate a ledger merely because its routed cwd happens to have a v2 store (ADR-0037).
-  const stored = grantRaw === undefined ? loadStoredGrantSync(storeCwd) : null;
-  const governed = grantRaw !== undefined || stored !== null;
-  const inherited: Capability[] = grantRaw !== undefined ? parseList(grantRaw) : (stored?.grant ?? [WILDCARD]);
+  const storedState = storedGrantSessionState(grantRaw, storeCwd);
+  const { governed, inherited, refusal: grantStoreRefusal } = storedState;
   const ledgerRaw = process.env[ENV_LEDGER];
   // Capture provenance before publishChildEnv writes this session's derived default into process.env. A later
   // `/grants init` for ctx.cwd must not mistake our own publication for an operator override.
   const ledgerFromEnvironment = ledgerRaw !== undefined;
-  const storedLedger = stored?.projectLedger ? projectLedgerPath(storeCwd) : undefined;
+  const storedLedger = storedState.defaultLedger;
   // G7 / A-S4 + B-I4: strict, three-way parsing that fails CLOSED. A malformed bound used to yield
   // `NaN`, and every comparison against `NaN` is false, so depth limiting switched itself off.
   const bounds = depthConfig(process.env[ENV_DEPTH], process.env[ENV_MAX_DEPTH]);
@@ -310,6 +317,8 @@ export function createGrantsSession(extensionPath: string | undefined): GrantsSe
      * before any tools are observed. An ungoverned session registers it as before.
      */
     mayDelegate: !governed || inherited.includes(DELEGATE_CAPABILITY) || inherited.includes(WILDCARD),
+    allowUnresolvedModels: process.env[ENV_ALLOW_UNRESOLVED_MODELS] === "1",
+    modelResolutionCache: new Map<string, boolean>(),
     extensionPath,
 
     sessionApprovals: new Set<string>(),
@@ -350,6 +359,7 @@ export function createGrantsSession(extensionPath: string | undefined): GrantsSe
     }),
 
     storeCwd,
+    ...(grantStoreRefusal ? { grantStoreRefusal } : {}),
 
     adoptGrant: (grant: Capability[], projectLedger?: string) => {
       // Governed too, not just bounded. A session that starts with no grant and then runs `/grants init` is

package/extensions/stored-grant-session.ts

@@ -0,0 +1,33 @@
+import {
+  grantStorePath,
+  loadStoredGrantStateSync,
+  projectLedgerPath,
+  type GrantStoreRefusalReason,
+  type StoredGrant,
+} from "../src/grant-store.ts";
+import { WILDCARD } from "../src/pi-tools.ts";
+import { parseList } from "../src/propagation.ts";
+import type { Capability } from "../src/resolve.ts";
+
+export interface StoredGrantSessionState {
+  stored?: StoredGrant;
+  refusal?: { reason: GrantStoreRefusalReason; path: string };
+  governed: boolean;
+  inherited: Capability[];
+  defaultLedger?: string;
+}
+
+/** Resolve the root-only project store while preserving the environment's absolute precedence. */
+export function storedGrantSessionState(grantRaw: string | undefined, cwd: string): StoredGrantSessionState {
+  const state = grantRaw === undefined ? loadStoredGrantStateSync(cwd) : { state: "absent" as const };
+  const stored = state.state === "valid" ? state.stored : undefined;
+  const refusal = state.state === "refuse" ? { reason: state.reason, path: grantStorePath(cwd) } : undefined;
+  return {
+    ...(stored ? { stored } : {}),
+    ...(refusal ? { refusal } : {}),
+    governed: grantRaw !== undefined || stored !== undefined || refusal !== undefined,
+    inherited: grantRaw !== undefined ? parseList(grantRaw) : stored?.grant ?? (refusal ? [] : [WILDCARD]),
+    // Invalid state authorises only a refusal line at this conventional path; no child can start from it.
+    defaultLedger: stored?.projectLedger || refusal ? projectLedgerPath(cwd) : undefined,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
   "keywords": [
     "pi-package",
@@ -161,6 +161,7 @@
     "typecheck": "tsc -p tsconfig.check.json",
     "test": "node --test test/*.test.ts",
     "test:integration": "node --test test-integration/*.it.ts",
+    "test:integration:ci": "node --test test-integration/approval.it.ts test-integration/governance.it.ts",
     "contracts:generate": "node scripts/generate-ledger-v3-contract.ts",
     "prepack": "npm run build",
     "test:smoke": "node scripts/smoke-installed.mjs",
@@ -175,6 +176,7 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.83.0",
+    "@types/node": ">=22",
     "typebox": ">=1.0.0"
   },
   "devDependencies": {

package/src/check-runner.ts

@@ -3,6 +3,7 @@ import { chmod, mkdtemp, readFile, realpath, rm, stat, writeFile } from "node:fs
 import { tmpdir } from "node:os";
 import { basename, isAbsolute, join } from "node:path";
 import { normaliseCorrelation, type CorrelationMetadata } from "./correlation.ts";
+import { runWithFinalizers } from "./finalization.ts";
 import {
   appendLedgerEvent,
   buildCheckReceiptLedgerEvent,
@@ -163,27 +164,28 @@ export async function runNamedCheck(input: {
   /** Failures of best-effort RECORDS, reported alongside whatever actually happened — never instead of it. */
   const notes: string[] = [];
   let releaseReason = "failed";
-  try {
+  return runWithFinalizers(async () => {
     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({
-          executionId, parentExecutionId,
-          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;
-    }
+      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({
+            executionId, parentExecutionId,
+            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(
@@ -329,29 +331,39 @@ export async function runNamedCheck(input: {
       );
     }
     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({
-          executionId, parentExecutionId,
-          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(),
-        }),
-      );
     }
-  }
+  }, [
+    {
+      label: "staged check cleanup failed",
+      run: async () => {
+        if (stagedDir) await rm(stagedDir, { recursive: true, force: true });
+      },
+    },
+    {
+      label: "workspace lease finalizer failed",
+      run: async () => {
+        if (!lease) return;
+        // `release()` cannot throw (R-99), and the record of it is best-effort for the same reason as
+        // above: a finalizer must not destroy 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({
+            executionId, parentExecutionId,
+            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(),
+          }),
+        );
+      },
+    },
+  ]);
 }

package/src/correlation.ts

@@ -7,12 +7,18 @@ import { isLedgerCorrelationIdentifier } from "./ledger-identifiers.ts";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
 
+export interface AssuranceScope {
+  type: "entire-run" | "selectors";
+  selectors: string[];
+}
+
 /**
  * Non-authoritative workflow metadata copied onto runtime and ledger events.
  *
- * pi-daddy deliberately does not interpret assurance labels, sources, scope selectors, timestamps or
- * sequence floors. In particular, a digest-looking value here never substitutes for a digest computed by
- * the planner. The snake_case names are the wire vocabulary used by external controllers.
+ * pi-daddy interprets only the pinned correlation wire contract: schema version 1.0 and the closed
+ * assurance-scope shape. Labels, selector meanings, timestamps and sequence floors remain non-authoritative.
+ * In particular, a digest-looking value here never substitutes for a digest computed by the planner. The
+ * snake_case names are the wire vocabulary used by external controllers.
  */
 export interface CorrelationMetadata {
   schema_version?: string;
@@ -25,7 +31,7 @@ export interface CorrelationMetadata {
   assurance_effective?: string;
   policy_label?: string;
   assurance_source?: string;
-  assurance_scope?: JsonValue;
+  assurance_scope?: AssuranceScope;
   activated_at?: string;
   plan_digest?: string;
   definition_digest?: string;
@@ -93,6 +99,29 @@ function correlationTooLarge(message: string, details?: Record<string, string |
   return new GovernanceRefusal(refusal("CORRELATION_TOO_LARGE", `correlation metadata: ${message}`, details));
 }
 
+function normaliseAssuranceScope(value: unknown): AssuranceScope {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw correlationRefusal("assurance_scope must be an object with type and selectors");
+  }
+  const scope = value as Record<string, unknown>;
+  const keys = Object.keys(scope).sort();
+  if (keys.length !== 2 || keys[0] !== "selectors" || keys[1] !== "type") {
+    throw correlationRefusal("assurance_scope must contain only type and selectors");
+  }
+  if (!Array.isArray(scope.selectors) || !scope.selectors.every((selector) => typeof selector === "string" && selector.length > 0)) {
+    throw correlationRefusal("assurance_scope selectors must be non-empty strings");
+  }
+  if (scope.type === "entire-run") {
+    if (scope.selectors.length !== 0) throw correlationRefusal("entire-run assurance_scope requires empty selectors");
+    return { type: "entire-run", selectors: [] };
+  }
+  if (scope.type === "selectors") {
+    if (scope.selectors.length === 0) throw correlationRefusal("selectors scope requires at least one selector");
+    return { type: "selectors", selectors: [...scope.selectors] };
+  }
+  throw correlationRefusal("assurance_scope type must be entire-run or selectors");
+}
+
 /**
  * Snapshot bounded JSON metadata so a caller cannot mutate a record after planning, and so nothing
  * unbounded or undeclared can reach the ledger through it.
@@ -138,7 +167,7 @@ export function normaliseCorrelation(input: CorrelationMetadata | undefined): Co
           { limit: MAX_CORRELATION_SCOPE_BYTES, actual: size },
         );
       }
-      output[key] = value;
+      output[key] = normaliseAssuranceScope(value);
       continue;
     }
     if (CORRELATION_NUMERIC.has(key as keyof CorrelationMetadata)) {
@@ -149,6 +178,12 @@ export function normaliseCorrelation(input: CorrelationMetadata | undefined): Co
       continue;
     }
     if (typeof value !== "string") throw correlationRefusal(`${key} must be a string`, { field: key });
+    if (key === "schema_version" && value !== "1.0") {
+      throw correlationRefusal(`unsupported schema_version ${value}; supported version is 1.0`, {
+        field: key,
+        supported: "1.0",
+      });
+    }
     if (value.length > MAX_CORRELATION_FIELD_CHARS) {
       throw correlationTooLarge(
         `${key} exceeds ${MAX_CORRELATION_FIELD_CHARS} characters`,
@@ -183,6 +218,8 @@ export interface ApprovalBinding {
   definition_sha256?: string;
   workspace_id?: string;
   context_id?: string;
+  tree_sha?: string;
+  last_change_seq?: number;
   parent_id: string;
 }
 
@@ -210,6 +247,10 @@ export function buildApprovalBinding(input: {
   workspaceId?: string;
   /** Caller-declared label. Narrows only; never a claim that anything was enforced. */
   contextId?: string;
+  /** Optional upstream tree identity. When supplied, later approval use must match it exactly. */
+  treeSha?: string;
+  /** Optional upstream change floor. When supplied, later approval use must match it exactly. */
+  lastChangeSeq?: number;
 }): ApprovalBinding {
   const requested = [...new Set(input.requested)].sort();
   const effective = [...new Set(input.effective)].sort();
@@ -223,6 +264,8 @@ export function buildApprovalBinding(input: {
     ...(input.definitionSha256 ? { definition_sha256: input.definitionSha256 } : {}),
     ...(input.workspaceId ? { workspace_id: input.workspaceId } : {}),
     ...(input.contextId ? { context_id: input.contextId } : {}),
+    ...(input.treeSha !== undefined ? { tree_sha: input.treeSha } : {}),
+    ...(input.lastChangeSeq !== undefined ? { last_change_seq: input.lastChangeSeq } : {}),
     parent_id: input.parentId,
   };
 }
@@ -238,6 +281,10 @@ export function approvalBindingDigest(binding: ApprovalBinding): string {
     definition_sha256: binding.definition_sha256 ?? null,
     workspace_id: binding.workspace_id ?? null,
     context_id: binding.context_id ?? null,
+    // Keep the exact pre-ADR-0039 serialization when both additions are absent: persisted approvals store
+    // this digest, so unconditional null placeholders would invalidate every existing bound approval.
+    ...(binding.tree_sha !== undefined ? { tree_sha: binding.tree_sha } : {}),
+    ...(binding.last_change_seq !== undefined ? { last_change_seq: binding.last_change_seq } : {}),
     parent_id: binding.parent_id,
   };
   return createHash("sha256").update(JSON.stringify(ordered), "utf8").digest("hex");
@@ -253,10 +300,12 @@ export function isApprovalBinding(value: unknown): value is ApprovalBinding {
     Array.isArray(binding.requested) && binding.requested.every((item) => typeof item === "string") &&
     Array.isArray(binding.effective) && binding.effective.every((item) => typeof item === "string") &&
     typeof binding.parent_id === "string" &&
-    ["definition_sha256", "workspace_id", "context_id"].every((key) => {
+    ["definition_sha256", "workspace_id", "context_id", "tree_sha"].every((key) => {
       const value = (binding as Record<string, unknown>)[key];
       return value === undefined || typeof value === "string";
     }) &&
+    (binding.last_change_seq === undefined ||
+      (typeof binding.last_change_seq === "number" && Number.isFinite(binding.last_change_seq))) &&
     // Self-consistency. This guard's only trust boundary is a binding parsed off DISK
     // (`approval-store.ts`), so an internally contradictory record — digests that do not match the
     // capability arrays sitting beside them — must be unrepresentable rather than merely unlikely.

package/src/delegation-approval.ts

@@ -26,8 +26,8 @@ export function resolveDelegationApproval(input: {
   spawned?: SkillDefinition;
   definitionDigest?: DefinitionDigest;
   /**
-   * Present iff this call is task-bound. Its VALUES never enter the binding — only its presence selects
-   * the exact-bound regime over the legacy subject-scoped one.
+   * Present iff this call is task-bound. Most values remain labels; optional tree_sha/last_change_seq enter
+   * the binding only to narrow a supplied approval to the upstream tree state that was reviewed.
    */
   correlation?: CorrelationMetadata;
   /** Trusted: an id that was resolved against the operator registry and leased. Never a caller claim. */
@@ -89,6 +89,8 @@ export function resolveDelegationApproval(input: {
         parentId: input.parentId,
         workspaceId: input.boundWorkspaceId,
         contextId: input.boundContextId,
+        treeSha: input.correlation?.tree_sha,
+        lastChangeSeq: input.correlation?.last_change_seq,
       })
     : undefined;
 

package/src/finalization.ts

@@ -0,0 +1,79 @@
+interface Finalizer {
+  label: string;
+  run: () => void | Promise<void>;
+}
+
+const FINALIZER_ERRORS = Symbol("pi-daddy.finalizer-errors");
+
+type ErrorWithFinalizers = Error & { [FINALIZER_ERRORS]?: unknown[] };
+
+/**
+ * Run every finalizer without allowing one of their failures to replace the operation's primary error.
+ *
+ * Error identity is preserved when possible: refusal codes and `instanceof` checks are part of callers'
+ * control flow. Finalizer failures are attached and added to the primary message instead of wrapping it.
+ */
+export async function runWithFinalizers<T>(operation: () => Promise<T>, finalizers: readonly Finalizer[]): Promise<T> {
+  let primaryPresent = false;
+  let primary: unknown;
+  let result: T | undefined;
+
+  try {
+    result = await operation();
+  } catch (error) {
+    primaryPresent = true;
+    primary = error;
+  }
+
+  const failures: Array<{ label: string; error: unknown }> = [];
+  for (const finalizer of finalizers) {
+    try {
+      await finalizer.run();
+    } catch (error) {
+      failures.push({ label: finalizer.label, error });
+    }
+  }
+
+  if (primaryPresent) {
+    if (failures.length > 0) throw appendFinalizerFailures(primary, failures);
+    throw primary;
+  }
+  if (failures.length === 1) throw failures[0].error;
+  if (failures.length > 1) {
+    throw new AggregateError(
+      failures.map((failure) => failure.error),
+      failures.map((failure) => `${failure.label}: ${String(failure.error)}`).join("; "),
+    );
+  }
+  return result as T;
+}
+
+/** True when a primary error retained a finalizer failure of the requested kind. */
+export function hasFinalizerError(error: unknown, predicate: (value: unknown) => boolean): boolean {
+  return error instanceof Error && (error as ErrorWithFinalizers)[FINALIZER_ERRORS]?.some(predicate) === true;
+}
+
+function appendFinalizerFailures(primary: unknown, failures: ReadonlyArray<{ label: string; error: unknown }>): unknown {
+  if (primary instanceof Error) {
+    const target = primary as ErrorWithFinalizers;
+    try {
+      const prior = target[FINALIZER_ERRORS] ?? [];
+      Object.defineProperty(target, FINALIZER_ERRORS, {
+        configurable: true,
+        value: [...prior, ...failures.map((failure) => failure.error)],
+      });
+      target.message = [
+        target.message,
+        ...failures.map((failure) => `${failure.label}: ${String(failure.error)}`),
+      ].join("; ");
+      return target;
+    } catch {
+      // A frozen foreign error cannot be annotated. Keep it as the first AggregateError member and cause.
+    }
+  }
+  return new AggregateError(
+    [primary, ...failures.map((failure) => failure.error)],
+    [String(primary), ...failures.map((failure) => `${failure.label}: ${String(failure.error)}`)].join("; "),
+    { cause: primary },
+  );
+}

package/src/git-identity.ts

@@ -3,6 +3,7 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
+import { runWithFinalizers } from "./finalization.ts";
 import { GovernanceRefusal, refusal } from "./refusals.ts";
 import type { ValidatedWorkspace } from "./workspace.ts";
 
@@ -33,20 +34,23 @@ export async function computeGitCandidateIdentity(workspace: ValidatedWorkspace)
   const git = async (args: string[]) => (await execFileAsync("git", ["-C", workspace.root, ...args], {
     env, encoding: "utf8", maxBuffer: 16 * 1024 * 1024,
   })).stdout.trim();
-  try {
-    const headSha = await git(["rev-parse", "HEAD"]);
-    await git(["read-tree", "HEAD"]);
-    await git(["add", "-A"]);
-    const treeSha = await git(["write-tree"]);
-    if (!/^[a-f0-9]{40,64}$/i.test(headSha) || !/^[a-f0-9]{40,64}$/i.test(treeSha)) throw new Error("Git returned an invalid object id");
-    return { headSha, treeSha };
-  } catch (error) {
-    throw new GovernanceRefusal(refusal(
-      "CHECK_IDENTITY_UNAVAILABLE",
-      `could not compute exact Git head/candidate-tree identity for workspace ${workspace.workspaceId} (${String(error)})`,
-      { workspace_id: workspace.workspaceId },
-    ));
-  } finally {
-    await rm(dir, { recursive: true, force: true });
-  }
+  return runWithFinalizers(async () => {
+    try {
+      const headSha = await git(["rev-parse", "HEAD"]);
+      await git(["read-tree", "HEAD"]);
+      await git(["add", "-A"]);
+      const treeSha = await git(["write-tree"]);
+      if (!/^[a-f0-9]{40,64}$/i.test(headSha) || !/^[a-f0-9]{40,64}$/i.test(treeSha)) throw new Error("Git returned an invalid object id");
+      return { headSha, treeSha };
+    } catch (error) {
+      throw new GovernanceRefusal(refusal(
+        "CHECK_IDENTITY_UNAVAILABLE",
+        `could not compute exact Git head/candidate-tree identity for workspace ${workspace.workspaceId} (${String(error)})`,
+        { workspace_id: workspace.workspaceId },
+      ));
+    }
+  }, [{
+    label: "temporary Git index cleanup failed",
+    run: () => rm(dir, { recursive: true, force: true }),
+  }]);
 }