pi-daddy 0.43.1 → 0.44.0

package/src/kernel/bounded-read.ts

@@ -33,6 +33,97 @@
 import { constants } from "node:fs";
 import { open, type FileHandle } from "node:fs/promises";
 
+/** Explicitly trusted per-read I/O ports, never requester/environment input. */
+export interface BoundedReadPorts {
+  open(path: string, flags: number): Promise<FileHandle>;
+  read(
+    handle: FileHandle,
+    buffer: Buffer,
+    offset: number,
+    length: number,
+    position: number,
+  ): Promise<{ bytesRead: number }>;
+  close(handle: FileHandle): Promise<void>;
+}
+/** A failed read stays failed even after this explicit recovery capability succeeds. */
+export class BoundedReadCleanupError extends Error {
+  readonly cleanup: () => Promise<void>;
+  /** Latest physical failure, including falsy rejections; cause remains the original failure. */
+  lastCause: unknown;
+  constructor(cause: unknown, cleanup: () => Promise<void>) {
+    super("bounded reader descriptor cleanup unresolved; retain and explicitly retry", { cause });
+    this.name = "BoundedReadCleanupError";
+    this.lastCause = cause;
+    this.cleanup = cleanup;
+  }
+}
+
+const retained = new Set<BoundedReadCleanup>();
+/** Trusted diagnostics/recovery only; not admission, a quota, or a Root-wide shutdown join. */
+export function retainedBoundedReadCleanups(): readonly BoundedReadCleanupOwner[] {
+  return [...retained];
+}
+export interface BoundedReadCleanupOwner {
+  readonly handle: FileHandle | undefined;
+  cleanup(): Promise<void>;
+}
+class BoundedReadCleanup implements BoundedReadCleanupOwner {
+  private held: FileHandle | undefined;
+  private active?: Promise<void>;
+  private failure?: BoundedReadCleanupError;
+  private finish!: () => void;
+  private readonly reading = new Promise<void>((resolve) => (this.finish = resolve));
+  private readonly close: BoundedReadPorts["close"];
+  constructor(close: BoundedReadPorts["close"]) {
+    this.close = close;
+    retained.add(this);
+  }
+  acquired(handle: FileHandle) {
+    this.held = handle;
+  }
+  get handle() {
+    return this.held;
+  }
+  readSettled() {
+    this.finish();
+  }
+  cleanup(): Promise<void> {
+    if (this.active) return this.active;
+    // Publish before calling any trusted port: reentrant/concurrent cleanup shares this operation.
+    const operation = this.reading.then(async () => {
+      if (!this.held) {
+        retained.delete(this);
+        return;
+      }
+      try {
+        await this.close(this.held);
+      } catch (cause) {
+        this.failure ??= new BoundedReadCleanupError(cause, () => this.cleanup());
+        this.failure.lastCause = cause;
+        throw this.failure;
+      }
+      this.held = undefined;
+      retained.delete(this);
+    });
+    this.active = operation;
+    void operation.then(
+      () => {
+        this.active = undefined;
+      },
+      () => {
+        this.active = undefined;
+      },
+    );
+    return operation;
+  }
+}
+
+const boundedReadPorts: BoundedReadPorts = {
+  open,
+  read: (handle, buffer, offset, length, position) => handle.read(buffer, offset, length, position),
+  close: (handle) => handle.close(),
+};
+
 export interface BoundedReadLimits {
   /** Refuse anything at or over this, before allocating it. */
   maxBytes: number;
@@ -50,12 +141,13 @@ export interface BoundedReadLimits {
  * one definition that will not be offered — and a shared reader must not decide that for them.
  */
 export type BoundedReadFailure =
-  | { why: "unopenable"; detail: string }
+  | { why: "unopenable"; detail: string; code?: string }
   | { why: "not-a-regular-file"; detail: string }
   | { why: "too-large"; detail: string; size: number }
   | { why: "grew-while-reading"; detail: string }
   | { why: "timed-out"; detail: string }
-  | { why: "unreadable"; detail: string };
+  | { why: "invalid-utf8"; detail: string }
+  | { why: "unreadable"; detail: string; code?: string };
 
 export type BoundedReadResult = { ok: true; text: string } | ({ ok: false } & BoundedReadFailure);
 export type BoundedReadBytes = { ok: true; bytes: Buffer } | ({ ok: false } & BoundedReadFailure);
@@ -67,18 +159,42 @@ export type BoundedReadBytes = { ok: true; bytes: Buffer } | ({ ok: false } & Bo
  * UTF-8 round trip unchanged — a latin-1 byte that decodes to U+FFFD changes the file's digest, and that
  * check is only possible against the original buffer. Decoding here and re-encoding there would defeat it.
  */
-export async function readBoundedFile(path: string, limits: BoundedReadLimits): Promise<BoundedReadResult> {
-  const read = await readBoundedBytes(path, limits);
-  return read.ok ? { ok: true, text: read.bytes.toString("utf8") } : read;
+export async function readBoundedFile(
+  path: string,
+  limits: BoundedReadLimits,
+  ports: BoundedReadPorts = boundedReadPorts,
+): Promise<BoundedReadResult> {
+  const read = await readBoundedBytes(path, limits, ports);
+  if (!read.ok) return read;
+  try {
+    return { ok: true, text: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(read.bytes) };
+  } catch {
+    return { ok: false, why: "invalid-utf8", detail: `${path} is not valid UTF-8` };
+  }
+}
+
+/** Preserve typed I/O evidence; a caller must not classify absence by searching diagnostic prose. */
+function ioCode(error: unknown): { code?: string } {
+  if (error && typeof error === "object" && "code" in error && typeof error.code === "string")
+    return { code: error.code };
+  return {};
 }
 
-export async function readBoundedBytes(path: string, limits: BoundedReadLimits): Promise<BoundedReadBytes> {
+export async function readBoundedBytes(
+  path: string,
+  limits: BoundedReadLimits,
+  ports: BoundedReadPorts = boundedReadPorts,
+): Promise<BoundedReadBytes> {
   const now = limits.now ?? Date.now;
   let handle: FileHandle;
+  const cleanup = new BoundedReadCleanup((held) => ports.close(held));
   try {
-    handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    handle = await ports.open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    cleanup.acquired(handle);
   } catch (error) {
-    return { ok: false, why: "unopenable", detail: String(error) };
+    cleanup.readSettled();
+    await cleanup.cleanup();
+    return { ok: false, why: "unopenable", detail: String(error), ...ioCode(error) };
   }
   try {
     const info = await handle.stat();
@@ -106,7 +222,7 @@ export async function readBoundedBytes(path: string, limits: BoundedReadLimits):
           why: "timed-out",
           detail: `${path} did not finish reading within ${limits.timeoutMs}ms`,
         };
-      const { bytesRead } = await handle.read(buffer, filled, buffer.length - filled, filled);
+      const { bytesRead } = await ports.read(handle, buffer, filled, buffer.length - filled, filled);
       if (bytesRead === 0) break;
       filled += bytesRead;
     }
@@ -118,8 +234,9 @@ export async function readBoundedBytes(path: string, limits: BoundedReadLimits):
       };
     return { ok: true, bytes: buffer.subarray(0, filled) };
   } catch (error) {
-    return { ok: false, why: "unreadable", detail: String(error) };
+    return { ok: false, why: "unreadable", detail: String(error), ...ioCode(error) };
   } finally {
-    await handle.close().catch(() => {});
+    cleanup.readSettled();
+    await cleanup.cleanup();
   }
 }

package/src/kernel/capacity.ts

@@ -0,0 +1,123 @@
+/**
+ * Owner-local active descendant capacity. A reservation holds one child plus a disjoint subtree allowance.
+ * The allowance excludes this owner session. Conservatively hold all of it until the owned subtree settles;
+ * this permits reuse after settlement, but does not promise perfect utilization or a lifetime call limit.
+ */
+import type { CapturedWorkerCleanup, CapturedWorkerIdentity } from "./captured-worker-contract.ts";
+
+export type CapacityReservationState = "reserved" | "retained" | "released";
+export interface CapacityReservation {
+  readonly executionId: string;
+  readonly childAllowance: number;
+  readonly cost: number;
+  readonly state: CapacityReservationState;
+  readonly identity: CapturedWorkerIdentity | undefined;
+  /** Bind actual ownership before releasing the worker gate. Throws on replacement or a different execution. */
+  bindOwnership(identity: CapturedWorkerIdentity): void;
+  /** Only trusted executor facts belong here; model output and ledger projections never authorize release. */
+  finalize(cleanup: CapturedWorkerCleanup): CapacityReservationState;
+}
+export type CapacityReservationResult = { ok: true; reservation: CapacityReservation } | { ok: false; reason: string };
+export interface CapacityAllocator {
+  readonly total: number;
+  readonly available: number;
+  readonly reserved: number;
+  /** Still-held occurrences; released reservations are removed, execution IDs remain tombstoned. */
+  readonly retainedReservations: readonly CapacityReservation[];
+  reserve(executionId: string, childAllowance: number): CapacityReservationResult;
+}
+
+const identityKeys = [
+  "revision",
+  "executionId",
+  "nonce",
+  "root",
+  "rootDevice",
+  "rootInode",
+  "bootId",
+  "pidNamespace",
+  "helperPid",
+  "helperStartTicks",
+  "helperSha256",
+  "workerPid",
+  "ownershipPath",
+  "receiptPath",
+] as const;
+function sameIdentity(a: CapturedWorkerIdentity, b: CapturedWorkerIdentity): boolean {
+  return identityKeys.every((key) => a[key] === b[key]);
+}
+const validAllowance = (value: number): boolean => Number.isSafeInteger(value) && value >= 0;
+
+/** Synchronous reservations are atomic within the actual session owner, including overlapping tool calls. */
+export function createCapacityAllocator(total: number): CapacityAllocator {
+  if (!validAllowance(total)) throw new Error("descendant capacity must be a non-negative safe integer");
+  let available = total;
+  // Keep occurrence tombstones: a stale finalizer must never release a newly reused execution identifier.
+  const executions = new Set<string>();
+  const held = new Map<string, CapacityReservation>();
+  return Object.freeze({
+    total,
+    get available() {
+      return available;
+    },
+    get reserved() {
+      return total - available;
+    },
+    get retainedReservations() {
+      return [...held.values()].filter((reservation) => reservation.state === "retained");
+    },
+    reserve(executionId: string, childAllowance: number): CapacityReservationResult {
+      if (!executionId || executionId.length > 512 || executions.has(executionId))
+        return { ok: false, reason: "capacity reservation requires a fresh bounded execution identifier" };
+      if (!validAllowance(childAllowance) || !Number.isSafeInteger(childAllowance + 1))
+        return { ok: false, reason: "child allowance must be a non-negative safe integer below the numeric ceiling" };
+      const cost = childAllowance + 1;
+      if (cost > available)
+        return {
+          ok: false,
+          reason: `active descendant capacity exhausted: ${cost} reserved units requested, ${available} available`,
+        };
+      available -= cost;
+      executions.add(executionId);
+      let state: CapacityReservationState = "reserved";
+      let identity: CapturedWorkerIdentity | undefined;
+      const reservation: CapacityReservation = Object.freeze({
+        executionId,
+        childAllowance,
+        cost,
+        get state() {
+          return state;
+        },
+        get identity() {
+          return identity;
+        },
+        bindOwnership(actual: CapturedWorkerIdentity): void {
+          if (
+            state === "released" ||
+            actual.executionId !== executionId ||
+            (identity && !sameIdentity(identity, actual))
+          )
+            throw new Error("capacity ownership does not match its reserved execution");
+          identity = Object.freeze({ ...actual });
+        },
+        finalize(cleanup: CapturedWorkerCleanup): CapacityReservationState {
+          if (state === "released") return state;
+          const provenNotStarted = cleanup.state === "not-started" && !identity && state === "reserved";
+          const settled =
+            cleanup.state === "settled" &&
+            identity !== undefined &&
+            sameIdentity(identity, cleanup.identity) &&
+            sameIdentity(identity, cleanup.receipt.identity) &&
+            cleanup.receipt.state === "settled" &&
+            cleanup.receipt.reapedAll === true;
+          if (!provenNotStarted && !settled) return (state = "retained");
+          held.delete(executionId);
+          available += cost;
+          return (state = "released");
+        },
+      });
+      held.set(executionId, reservation);
+      return { ok: true, reservation };
+    },
+  });
+}

package/src/kernel/captured-worker-contract.ts

@@ -0,0 +1,29 @@
+/** Versioned, execution-bound worker facts. These records never grant capabilities. */
+export interface CapturedWorkerIdentity {
+  revision: 1;
+  executionId: string;
+  nonce: string;
+  root: string;
+  rootDevice: string;
+  rootInode: string;
+  bootId: string;
+  pidNamespace: string;
+  helperPid: number;
+  helperStartTicks: string;
+  helperSha256: string;
+  workerPid: number;
+  ownershipPath: string;
+  receiptPath: string;
+}
+export interface CapturedWorkerReceipt {
+  state: "settled";
+  identity: CapturedWorkerIdentity;
+  workerCode: number | null;
+  workerSignal: number;
+  reason: "worker-exit" | "owner-loss" | "cancelled" | "helper-signal" | "ownership-write-failed" | "start-failed";
+  reapedAll: true;
+}
+export type CapturedWorkerCleanup =
+  | { state: "settled"; identity: CapturedWorkerIdentity; receipt: CapturedWorkerReceipt }
+  | { state: "unknown"; identity?: CapturedWorkerIdentity; reason: string }
+  | { state: "not-started"; reason: string };

package/src/kernel/catalog.ts

@@ -19,6 +19,8 @@
  */
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { BoundedReadCleanupError } from "./bounded-read.ts";
+import { collectBoundedReadFailures } from "./bounded-read-failures.ts";
 import { resolveSkillResources, skillResourceName } from "./skill-resources.ts";
 import { join } from "node:path";
 import { loadDefinitions, type SkillDefinition } from "./definitions.ts";
@@ -133,16 +135,26 @@ export function makeCatalog(entries: CatalogEntry[], registryRefusal?: string):
   };
 }
 
+/** Trusted loader dependencies, not catalog/request configuration. */
+export interface CatalogLoaders {
+  definitions?: typeof loadDefinitions;
+  registry?: typeof loadWorkspaceRegistry;
+}
+
 /** Build the live catalog. `observedTools` comes from a provider payload; null when not yet seen. */
-export async function buildCatalog(input: {
-  cwd: string;
-  observedTools: string[] | null;
-  /** Operator workspace registry (`PI_DADDY_WORKSPACE_REGISTRY`). Absent or unreadable yields no entries. */
-  registryPath?: string;
-}): Promise<Catalog> {
-  const [skills, definitions, workspaces] = await Promise.all([
-    loadSkills(input.cwd),
-    loadDefinitions(input.cwd),
+export async function buildCatalog(
+  input: {
+    cwd: string;
+    snapshot?: { skills: CatalogEntry[]; definitions: Map<string, SkillDefinition> };
+    observedTools: string[] | null;
+    /** Operator workspace registry (`PI_DADDY_WORKSPACE_REGISTRY`). Absent or unreadable yields no entries. */
+    registryPath?: string;
+  },
+  loaders: CatalogLoaders = {},
+): Promise<Catalog> {
+  const outcomes = await Promise.allSettled([
+    Promise.resolve().then(() => input.snapshot?.skills ?? loadSkills(input.cwd)),
+    Promise.resolve().then(() => input.snapshot?.definitions ?? (loaders.definitions ?? loadDefinitions)(input.cwd)),
     // Fails SOFT, and only because nothing here is an authority. A malformed registry must not stop a
     // session from starting — `loadWorkspaceRegistry` throws a GovernanceRefusal naming the file, and that
     // refusal is the operator's signal at the point of USE, where routing actually depends on it. Swallowing
@@ -151,15 +163,32 @@ export async function buildCatalog(input: {
     // **What the refusal is no longer allowed to do is vanish.** This handler was `() => []`, so the display
     // list was lost AND the reason with it. The reason now rides on the catalog and `/grants` prints it.
     input.registryPath
-      ? loadWorkspaceRegistry(input.registryPath).then(
-          (r) => ({ entries: workspaceEntries(r, input.registryPath), refusal: undefined as string | undefined }),
-          (error: unknown) => ({
-            entries: [] as CatalogEntry[],
-            refusal: error instanceof Error ? error.message : String(error),
-          }),
-        )
+      ? Promise.resolve()
+          .then(() => (loaders.registry ?? loadWorkspaceRegistry)(input.registryPath!))
+          .then(
+            (r) => ({ entries: workspaceEntries(r, input.registryPath), refusal: undefined as string | undefined }),
+            (error: unknown) => {
+              if (error instanceof BoundedReadCleanupError) throw error;
+              return {
+                entries: [] as CatalogEntry[],
+                refusal: error instanceof Error ? error.message : String(error),
+              };
+            },
+          )
       : Promise.resolve({ entries: [] as CatalogEntry[], refusal: undefined as string | undefined }),
   ]);
+  // Join EVERY started branch before ordinary discovery fallback can discard a physical close failure.
+  const cleanup = collectBoundedReadFailures(
+    outcomes.flatMap((result) => (result.status === "rejected" ? [result.reason] : [])),
+  );
+  if (cleanup) throw cleanup;
+  const value = <T>(result: PromiseSettledResult<T>): T => {
+    if (result.status === "rejected") throw result.reason;
+    return result.value;
+  };
+  const skills = value(outcomes[0]);
+  const definitions = value(outcomes[1]);
+  const workspaces = value(outcomes[2]);
   return makeCatalog(
     [
       // pi's built-ins are seeded unconditionally, because they are known statically and the catalog is

package/src/kernel/chain.ts

@@ -152,6 +152,7 @@ export function composeStepTask(template: string, previous: string | undefined):
 
 /** One chain step as `runOneDelegation` takes it: the operator's spec with its task composed. */
 export interface ChainStep {
+  definitionId?: string;
   task: string;
   agent?: string;
   tools?: string[];

package/src/kernel/definitions.ts

@@ -61,6 +61,10 @@ export function isDefinitionPackageVersion(value: unknown): value is string {
 }
 
 export interface SkillDefinition {
+  /** Immutable selected-resource identity, independent of the model-authored name. */
+  definitionId?: string;
+  selectedSkillHash?: string;
+  binding?: Readonly<{ package: "principal-pi-skills"; phase: string }>;
   /** From the path, never the frontmatter — see `parseSkillDefinition`. */
   name: string;
   description: string;
@@ -68,6 +72,8 @@ export interface SkillDefinition {
   allowedTools?: string;
   /** The spec's sanctioned extension point: a map of string keys to string values. */
   metadata?: Record<string, string>;
+  /** Raw authored JSON pairs; validated only when runtime selection needs them. */
+  runtimePreferences?: string;
   /** Everything after the frontmatter — the child's system prompt. */
   body: string;
   source: string;
@@ -160,6 +166,7 @@ export function parseSkillDefinition(source: string, text: string): SkillDefinit
     name: skillResourceName(source),
     description,
     allowedTools: fields.get("allowed-tools"),
+    runtimePreferences: fields.get("runtime-preferences"),
     metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
     body: text.slice(match[0].length).trim(),
     source,
@@ -232,11 +239,13 @@ export const DEFINITION_READ_TIMEOUT_MS = 2_000;
 export async function loadDefinitions(
   cwd: string,
   skipped?: (path: string, reason: string) => void,
+  // Trusted per-loader reader, never a skill's metadata or environment input.
+  readFile: typeof readBoundedFile = readBoundedFile,
 ): Promise<Map<string, SkillDefinition>> {
   const definitions = new Map<string, SkillDefinition>();
   const packageVersions = new Map<string, string | undefined>();
   for (const { path, metadata } of (await resolveSkillResources(cwd)).skills) {
-    const read = await readBoundedFile(path, {
+    const read = await readFile(path, {
       maxBytes: DEFINITION_MAX_BYTES,
       timeoutMs: DEFINITION_READ_TIMEOUT_MS,
     });
@@ -247,7 +256,7 @@ export async function loadDefinitions(
     const parsed = parseSkillDefinition(path, read.text);
     if (parsed && metadata.origin === "package" && metadata.baseDir) {
       if (!packageVersions.has(metadata.baseDir)) {
-        const manifest = await readBoundedFile(join(metadata.baseDir, "package.json"), {
+        const manifest = await readFile(join(metadata.baseDir, "package.json"), {
           maxBytes: DEFINITION_MAX_BYTES,
           timeoutMs: DEFINITION_READ_TIMEOUT_MS,
         });

package/src/kernel/fanout.ts

@@ -1,35 +1,16 @@
-/**
- * Bounded synchronous fan-out — ADR-0015's option A′, and the cardinality bound ADR-0008 never had.
- *
- * **The gap this closes.** ADR-0008 bounds what each child may *hold* and says nothing about how many
- * children exist. `resolve()` is a set operation; nowhere in `src/` was there a count. Blocking `delegate`
- * bounded cardinality to one *by accident of being blocking*, so the invariant was never tested. Fan-out
- * removes that accident: with `maxDepth: 2` and five children per call, five delegators each spawning five
- * is thirty concurrent model sessions — **every ledger line individually correct and narrow, the aggregate
- * a machine DoS and an uncapped bill.** The critic's verdict on this was that silence is itself a finding.
- *
- * **Why a budget rather than a per-call limit.** A per-call cap of K with depth D still permits K^D
- * descendants, which is the same exponential wearing a smaller number. A *budget* is subtractive and
- * therefore total: a session holding budget B may create at most B descendants in its whole subtree,
- * because it spends from B to spawn and hands each child a share of what is left. That composes across
- * process boundaries with **no shared state** — the same property that makes depth work — so it needs no
- * registry, no lock and no counter file.
- *
- * It is deliberately NOT a concurrency limit. How many run at once is a resource question for the executor;
- * how many may exist at all is a governance question, and this is the governance answer.
- */
-
+/** Active descendant allocation arithmetic. Enforcement requires the shared owner allocator in capacity.ts. */
 import { parseBound } from "./propagation.ts";
+import { GovernanceRefusal, refusal } from "./refusals.ts";
 
-/** Total descendants a session may create across its entire subtree, when nothing is configured. */
+/** Active descendant allowance, excluding the owner session, when nothing is configured. */
 export const DEFAULT_FANOUT_BUDGET = 8;
 
 /**
  * Hard ceiling on children in a single call, independent of budget.
  *
  * A budget alone would let one call spend all of it at once, and a hundred simultaneous `pi` processes is
- * a different failure from a hundred spread over a session. This is the blast-radius bound; the budget is
- * the total bound. Both are needed because they answer different questions.
+ * a different failure from a hundred spread over a session. The owner allocator also conserves active
+ * capacity across overlapping calls.
  */
 export const MAX_CHILDREN_PER_CALL = 8;
 
@@ -43,15 +24,16 @@ export const MAX_CHILDREN_PER_CALL = 8;
  */
 export const MAX_CHAIN_STEPS = MAX_CHILDREN_PER_CALL;
 
-/** Read the budget from the environment, failing to the default on absent *or* malformed input. */
+/** Absent uses the existing default; explicit zero stays exhausted and malformed input refuses. */
 export function budgetFromEnv(raw: string | undefined): number {
+  if (raw === undefined) return DEFAULT_FANOUT_BUDGET;
   const parsed = parseBound(raw);
-  // Malformed and zero both fall back rather than disabling fan-out silently — G7's rule. A budget that a
-  // typo can switch off is the A-S4 defect wearing different clothes. To genuinely forbid delegation an
-  // operator sets `maxDepth: 0`, which says what it means.
-  return parsed === undefined || parsed === null || parsed === 0 ? DEFAULT_FANOUT_BUDGET : parsed;
+  if (parsed === null || parsed === undefined)
+    throw new GovernanceRefusal(
+      refusal("FANOUT_EXCEEDED", "PI_DADDY_FANOUT must be a non-negative safe decimal integer"),
+    );
+  return parsed;
 }
-
 export interface BudgetSplit {
   ok: boolean;
   reason?: string;
@@ -60,7 +42,7 @@ export interface BudgetSplit {
 }
 
 /**
- * Spend `count` from a budget and divide the remainder among the children.
+ * Propose disjoint child allowances from currently available capacity; this does not reserve anything.
  *
  * The parent pays one unit per child it creates *before* sharing what is left, so a subtree can never
  * exceed the budget it started with: spawning is itself an expenditure, not a free act that only its
@@ -68,7 +50,10 @@ export interface BudgetSplit {
  * inventing it — the safe direction, and the reason a deep tree converges to zero instead of oscillating.
  */
 export function splitBudget(budget: number, count: number): BudgetSplit {
-  if (count <= 0) return { ok: false, reason: "a fan-out needs at least one child", perChild: 0 };
+  if (!Number.isSafeInteger(budget) || budget < 0)
+    return { ok: false, reason: "capacity must be a non-negative safe integer", perChild: 0 };
+  if (!Number.isSafeInteger(count) || count <= 0)
+    return { ok: false, reason: "a fan-out needs at least one child", perChild: 0 };
   if (count > MAX_CHILDREN_PER_CALL) {
     return {
       ok: false,

package/src/kernel/grant-env.ts

@@ -140,8 +140,6 @@ export interface ProjectSettings {
   ledger: string;
   /** Gated by default (ADR-0012): closed under subsumption, so gating tool:write also gates tool:bash. */
   gatedByDefault: Capability[];
-  /** Cumulative provider-reported USD cost at which the episode asks whether to continue. */
-  episodeCostCeiling: number;
 }
 
 export function buildProjectSettings(input: GrantEnvInput): ProjectSettings {
@@ -168,7 +166,6 @@ export function buildProjectSettings(input: GrantEnvInput): ProjectSettings {
     cautions: [...input.cautions],
     ledger: PROJECT_FILES.ledger,
     gatedByDefault: ["tool:bash"],
-    episodeCostCeiling: 5,
   };
 }
 

package/src/kernel/model-preflight.ts

@@ -16,6 +16,7 @@ export function supportedModelEfforts(model: {
 
 export interface ModelCatalogue {
   find(provider: string, modelId: string): unknown;
+  getProviderAuthStatus?(provider: string): { configured: boolean };
 }
 
 /** Resolve an explicit provider/id against pi's own session catalogue without probing credentials or network. */
@@ -42,3 +43,31 @@ export function preflightModel(
     { model: model || "(empty)" },
   );
 }
+
+/** Exact candidate only; never enumerate providers, resolve credentials, probe, or clamp effort. */
+export function runtimePairUnavailable(
+  choice: { model?: string; thinking?: string },
+  catalogue: ModelCatalogue,
+  allowUnresolved = false,
+): string | undefined {
+  if (!choice.model) return undefined; // No explicit/current choice: preserve Pi's ordinary configured default.
+  const slash = choice.model.indexOf("/");
+  const provider = choice.model.slice(0, slash),
+    id = choice.model.slice(slash + 1);
+  if (slash <= 0 || !id) return "runtime model needs provider/model";
+  const model = catalogue.find(provider, id);
+  if (!model) return allowUnresolved ? undefined : `model ${choice.model} is not in pi's session catalogue`;
+  if (
+    choice.thinking !== undefined &&
+    typeof model === "object" &&
+    model !== null &&
+    "reasoning" in model &&
+    !supportedModelEfforts(model as { reasoning: boolean }).includes(choice.thinking as never)
+  ) {
+    return `model ${choice.model} does not support thinking ${choice.thinking}`;
+  }
+  // configured:false cannot distinguish keyless, missing and unknown public provider auth semantics.
+  // Reading the passive status is permitted evidence; never turn it into an authentication attempt.
+  catalogue.getProviderAuthStatus?.(provider);
+  return undefined;
+}