pi-daddy 0.34.0 → 0.36.0

package/extensions/run-delegation.ts

@@ -12,6 +12,8 @@
  */
 
 import { nativeDelegationContext } from "./delegation-native.ts";
+import { adviseEffort } from "./effort-advice.ts";
+import { advisePruning } from "./pruning-advice.ts";
 import { DELEGATE_SUBJECT, shouldSeekApproval } from "../src/kernel/approval.ts";
 import { planDelegation } from "../src/kernel/delegate.ts";
 import {
@@ -249,6 +251,8 @@ export async function runOneDelegation(
     agent: spec.agent,
     tools: spec.tools,
     model: spec.model ?? defaultModel,
+    // Filled below, once the refusals that doom a delegation are known: asking first shipped the task text for a
+    // child that never starts, which is the ordering this module already fixed for the approval dialog.
     thinking: spec.thinking,
     context: spec.context,
     correlation: spec.workspace
@@ -289,6 +293,28 @@ export async function runOneDelegation(
     Boolean(executorRefusal || modelRefusal),
   );
   executorRefusal ||= nativeRefusal;
+
+  // ADR-0077's first decision point, after the refusal checks for the reason above. Fills a blank from the levels
+  // the CHILD's model reports; never overrules a caller, and yields today's behaviour whenever there is no answer.
+  if (!executorRefusal && !modelRefusal)
+    request.thinking = await adviseEffort({
+      session,
+      requested: spec.thinking,
+      model: spec.model ?? defaultModel,
+      registry: ctx.modelRegistry,
+      task: spec.task,
+      agent: spec.agent,
+      signal,
+    });
+
+  const planContext = await handoffPlanContext({
+    session,
+    base: extra,
+    task: spec.task,
+    blocked: Boolean(executorRefusal || modelRefusal),
+    preview: () => planWithApprovals(session, request, extra, null, signal, preApproved).then((r) => r.plan),
+    ...(signal ? { signal } : {}),
+  });
   let preparedWorkspace: PreparedWorkspace | undefined;
   let approvalOutcome: ApprovalOutcome | undefined;
   let plan: ReturnType<typeof planDelegation>;
@@ -297,7 +323,7 @@ export async function runOneDelegation(
     // 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.
-    const preview = await planWithApprovals(session, request, extra, null, signal, preApproved);
+    const preview = await planWithApprovals(session, request, planContext, null, signal, preApproved);
     plan = preview.plan;
     if (plan.ok || shouldSeekApproval(plan.result)) {
       try {
@@ -311,7 +337,7 @@ export async function runOneDelegation(
           ledgerPath: session.ledgerPath,
         });
         request.correlation = preparedWorkspace.correlation;
-        const gated = await planWithApprovals(session, request, extra, ctx, signal, preApproved);
+        const gated = await planWithApprovals(session, request, planContext, ctx, signal, preApproved);
         plan = gated.plan;
         approvalOutcome = gated.approval;
       } catch (error) {
@@ -326,7 +352,7 @@ export async function runOneDelegation(
     const gated = await planWithApprovals(
       session,
       request,
-      extra,
+      planContext,
       executorRefusal || modelRefusal ? null : ctx,
       signal,
       preApproved,
@@ -409,3 +435,35 @@ export async function runOneDelegation(
     onProgress,
   });
 }
+
+/**
+ * The planner context for one delegation, including a `pruned` handoff narrowed by an advisor (ADR-0077).
+ *
+ * **Exported and taking its own `preview`, so the ordering is forced by a test rather than by a reviewer.** Three
+ * properties live here and each was, at some point in this change's history, true only because somebody had
+ * checked it by hand: an advisor is not asked for a delegation that is already refused; it is not asked until a
+ * plan says the `pruned` handoff actually survived the ceiling, the grant and the gate; and the ids it returns
+ * reach the planner. Reviewers measured all three by mutating the source and finding the suite still green. A
+ * function with a seam is the only version of this that a test can hold.
+ */
+export async function handoffPlanContext(input: {
+  session: Parameters<typeof advisePruning>[0]["session"];
+  base: Record<string, unknown>;
+  task: string;
+  /** A refusal is already certain, so nothing may be asked. */
+  blocked: boolean;
+  /** Plans with no human in the loop; its result decides whether an advisor is consulted at all. */
+  preview: () => Promise<{ handoff?: { mode: string } }>;
+  signal?: AbortSignal;
+}): Promise<Record<string, unknown>> {
+  if (input.blocked) return { ...input.base };
+  const plan = await input.preview();
+  if (plan.handoff?.mode !== "pruned") return { ...input.base };
+  const ids = await advisePruning({
+    session: input.session,
+    granted: plan.handoff as Parameters<typeof advisePruning>[0]["granted"],
+    task: input.task,
+    ...(input.signal ? { signal: input.signal } : {}),
+  });
+  return ids ? { ...input.base, handoffTurnIds: ids } : { ...input.base };
+}

package/extensions/session-report.ts

@@ -57,6 +57,21 @@ export async function reportSessionStart(session: GrantsSession, ctx: SessionRep
       "warning",
     );
   }
+  // **Rule 8's loud half for the two reads that discover what exists.** Both of these used to fail soft and
+  // say nothing, and review established that session start — not `/grants` — is where every other such
+  // notice lives (a malformed bound above, ledger corruption and an executor refusal below). A reason an
+  // operator has to ask for is a reason most operators never see.
+  //
+  // The definitions one matters more than it looks: the 1 MiB bound is NEW behaviour, so a definition that
+  // loaded yesterday can be absent today, and without this line the only symptom is `unknown agent "x"` at
+  // the moment somebody tries to delegate to it.
+  for (const reason of session.definitionSkips)
+    ctx.ui.notify(`grants: a definition was not loaded — ${reason}`, "warning");
+  if (session.catalog.registryRefusal)
+    ctx.ui.notify(
+      `grants: workspace registry unreadable, no workspace is routable this session — ${session.catalog.registryRefusal}`,
+      "warning",
+    );
   // ADR-0014: a pre-0.6 in-workspace approvals file is IGNORED, not migrated — importing it would
   // import exactly the entries whose trustworthiness the move exists to remove. Say so, because an
   // operator whose approvals silently stopped applying deserves to know why.

package/extensions/session.ts

@@ -49,8 +49,10 @@ import { republishable } from "./approvals.ts";
 import { storedGrantSessionState } from "./stored-grant-session.ts";
 import { nativeSessionRootFromEnv, type NativeSessionHost } from "../src/executors/native-session-target.ts";
 import { createHandoffStager, type ParentSession } from "./context-staging.ts";
+import { createAdvisorSession, type AdvisorSession } from "./advisor-session.ts";
 import { join } from "node:path";
-import { agentDir } from "../src/kernel/project-paths.ts";
+import { readFileSync, statSync } from "node:fs";
+import { agentDir, projectSettingsPath } from "../src/kernel/project-paths.ts";
 import { ENV_ALLOW_UNRESOLVED_MODELS } from "../src/kernel/model-preflight.ts";
 import { beginExtensionLifecycle, rememberChildPublication, type ReloadLifecycle } from "./reload-environment.ts";
 import { reconcileSessionEnvironment } from "./session-environment.ts";
@@ -87,7 +89,7 @@ import {
   ENV_ACTIVITY_ROOT,
   ENV_ACTIVITY_TASK,
 } from "../src/products/activity-timeline.ts";
-import { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE } from "../src/kernel/env-names.ts";
+import { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE, ENV_ADVISOR } from "../src/kernel/env-names.ts";
 export { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE } from "../src/kernel/env-names.ts";
 import { adoptLegacyEnvironment } from "../src/kernel/env-names.ts";
 
@@ -157,6 +159,8 @@ export interface GrantsSession extends NativeSessionHost {
    * context handoff (ADR-0078): its file path for `fork`, its message turns for `pruned`.
    */
   parentSession?: ParentSession;
+  /** ADR-0077: the session's advisor, off unless the environment enables one. Never consulted for authority. */
+  advisorSession: AdvisorSession;
   /** Root identity keyed to ctx.sessionManager once session_start supplies it. */
   reloadLifecycle: ReloadLifecycle;
   /** Approval keys approved for this session. In memory only — this dies with the process. */
@@ -182,6 +186,16 @@ export interface GrantsSession extends NativeSessionHost {
   observedTools: string[] | null;
   /** ADR-0016: `SKILL.md` definitions, keyed by name. The format this package spawns from now. */
   definitions: Map<string, SkillDefinition>;
+  /**
+   * Definitions discovery dropped, and why — reported at session start (ADR-0076, rule 8).
+   *
+   * Review found the bound shipped without this: `loadDefinitions` grew a `skipped` callback and NO
+   * production caller passed one, so an oversized or unreadable `SKILL.md` still vanished with nothing
+   * anywhere explaining it. That is worse than the `catch { continue }` it replaced, because the bound is
+   * new behaviour — a 2 MiB definition used to load. A capability that only a test can observe is not a
+   * capability.
+   */
+  definitionSkips: string[];
   catalog: Catalog;
   /**
    * The in-flight catalog build, so `delegate` can wait for it instead of racing it.
@@ -251,7 +265,9 @@ export interface GrantsSession extends NativeSessionHost {
  * about what loading means, so there is one.
  */
 export async function loadProjectDefinitions(session: GrantsSession, cwd: string): Promise<void> {
-  session.definitions = await loadDefinitions(cwd);
+  const skips: string[] = [];
+  session.definitions = await loadDefinitions(cwd, (_path, reason) => skips.push(reason));
+  session.definitionSkips = skips;
   session.catalogReady = buildCatalog({
     cwd,
     observedTools: session.observedTools,
@@ -296,13 +312,25 @@ export function createGrantsSession(
   const bounds = depthConfig(environment[ENV_DEPTH], environment[ENV_MAX_DEPTH]);
   const { depth, maxDepth } = bounds;
   const emptyCatalog = makeCatalog([]);
+  // ADR-0077. The environment decides whether there is an advisor at all; the project's settings block may only
+  // narrow it. The block IS read — the first version passed `undefined` and every narrowing the release advertised
+  // was dead code reachable only from tests, which review measured: `enabled: false` turned nothing off.
+  //
+  // Read from `storeCwd` for `loadStoredGrantStateSync`'s reason: this factory runs before any hook, so `ctx.cwd`
+  // does not exist yet. Reading a workspace-writable file here is safe precisely because it can only narrow.
+  const advisorSession = createAdvisorSession({
+    block: projectAdvisorBlock(storeCwd),
+    ...(storedLedger ? { ledgerPath: storedLedger } : {}),
+  });
   const session: GrantsSession = {
+    advisorSession,
     adoptedLegacyEnv,
     governed,
     inherited,
     depth,
     maxDepth,
     malformedBounds: bounds.malformed,
+    definitionSkips: [],
     // ADR-0012: `bash` is gated by DEFAULT — but only in a governed session. An ungoverned one
     // (no PI_DADDY_GRANT) still blocks nothing, so "governance is opt-in" holds exactly where it always
     // did. Inside a session the operator already chose to govern, handing a child `bash` hands it an
@@ -361,12 +389,16 @@ export function createGrantsSession(
       observerExtensionPath: session.observerExtensionPath,
       childEnv: activityChildEnv(session.activity),
       // ADR-0078: composition reads, the kernel decides. Called only for a mode that survived the gate.
-      stageHandoff: (granted) =>
+      // `options` is forwarded, and its absence is why the second decision point was dead in production: a
+      // one-parameter arrow is assignable to a two-parameter type, so the ids reached here and were discarded while
+      // the advisor had already been asked. Review measured it. `test/pruning-advice.test.ts` now goes through this
+      // function rather than calling the stager directly.
+      stageHandoff: (granted, options) =>
         createHandoffStager({
           cwd: session.cwd,
           forkRoot: join(agentDir(), "context-forks"),
           ...(session.parentSession ? { parentSession: session.parentSession } : {}),
-        })(granted),
+        })(granted, options),
       catalog: await session.catalogReady,
       // R-32: where each granted skill lives, so `planSpawn` can pass `--skill` for those and only those.
       // Derived from the catalog's own `source`, so it cannot drift from what was discovered.
@@ -420,3 +452,27 @@ export function createGrantsSession(
   };
   return session;
 }
+
+/**
+ * The `advisor` block of `.pi/pi-daddy/settings.json`, or undefined.
+ *
+ * Unreadable, absent or malformed all yield undefined: this file is the reviewable record, not authority, and the
+ * only thing it can do to an advisor is turn one off. A parse failure therefore costs nothing worth reporting.
+ */
+function projectAdvisorBlock(cwd: string): unknown {
+  // Only when an advisor could exist at all. This runs in every session including every child, before any hook, and
+  // a child can never use the result because `PI_DADDY_ADVISOR` is stripped from it.
+  if (!process.env[ENV_ADVISOR]?.trim()) return undefined;
+  try {
+    const path = projectSettingsPath(cwd);
+    // Bounded and type-checked first: this is the third unbounded session-start read AGENTS.md warns about, and the
+    // only one whose path a governed child holding `tool:write` can replace with a FIFO — which would hang pi
+    // before any hook exists to report it.
+    const stats = statSync(path);
+    if (!stats.isFile() || stats.size > 1024 * 1024) return undefined;
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>).advisor : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.34.0",
+  "version": "0.36.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",

package/src/advisors/decider.ts

@@ -32,9 +32,13 @@ export type Answer =
 
 export interface AdviceRequest {
   /**
-   * What the advisor is told about the situation. **Caller-composed and deliberately not the raw task**: the task
-   * is never stored (ADR-0021) and must not be shipped to a third party either, so a caller passes the facts it
-   * chose, and the record below names them by key without their values.
+   * What the advisor is told about the situation, composed by the caller.
+   *
+   * **Sent, never recorded.** The task is never STORED (ADR-0021) and that still holds — `createAdvisor` writes the
+   * question keys and the answers and never this object. But an advisor cannot judge a task it cannot see, so a
+   * caller that needs one judged does send it, and the operator's consent for that is the advisor being off by
+   * default. An earlier draft of this paragraph said the raw task "must not be shipped to a third party either",
+   * which the first decision point then did; the rule that survived review is the narrower and true one.
    */
   state: Readonly<Record<string, unknown>>;
   questions: Readonly<Record<string, Question>>;

package/src/advisors/settings.ts

@@ -1,24 +1,34 @@
 /**
  * Whether an advisor is on, and which one (ADR-0077).
  *
- * **Default off, and off is the whole configuration when nothing says otherwise.** An advisor sends a description
- * of the caller's situation to a third party, so it is not something a package turns on for somebody: it is turned
- * on in `.pi/pi-daddy/settings.json`, the file an operator reviews and commits, beside the grant that governs
- * everything else. Malformed configuration disables the advisor and says so, which is this project's rule for
- * configuration everywhere: a typo must not be a way to enable something.
+ * **Default off, and only the environment can turn it on.** An advisor sends a description of the caller's
+ * situation to a third party, so enabling one is `PI_DADDY_ADVISOR=jev` plus a key — both outside the workspace,
+ * both stripped from every child.
+ *
+ * 0.34.0 read the enable from `.pi/pi-daddy/settings.json` and that was wrong for the reason `grant-store.ts`
+ * states about the same file: it is writable by any child holding `tool:write`, so it is "the reviewable record of
+ * the decision, not the thing the enforcer reads". A grant lives outside the workspace precisely so a child cannot
+ * widen the next session's ceiling; an advisor switch a child could flip would make the operator's next session
+ * ship its own description to a third party, which is the same self-defeating shape. The settings block may still
+ * NARROW — a shorter timeout, or `enabled: false` to turn an advisor off for one project — and can never turn one
+ * on, choose its model, or lengthen its bound. A model is a destination rather than a narrowing, so `model` in the
+ * block is refused with a message naming `PI_DADDY_ADVISOR_MODEL`, and a timeout is clamped to the default rather
+ * than trusted. Malformed configuration disables the advisor and says so: a typo must not be a way to enable anything.
  *
  * **Not a dashboard toggle**, which is what the programme originally sketched. The dashboard is a read-only
  * renderer in a separate process that "never affects enforcement" (ADR-0036), and a control there that wrote to
  * settings would be the first thing it ever wrote. Turning an advisor on is an operator decision that belongs in
  * the reviewable file; `/grants` reports what is in force. That is a deliberate departure from the roadmap line.
  *
- * The key is never in this file. It is read from the environment, because a settings file is committed and an API
- * key must not be.
+ * The key is never in the settings file either, because that file is committed and an API key must not be.
  */
 
 // Spelled once, in the kernel's table, so this layer cannot drift from the list `childEnv` refuses to write.
 export { ENV_ADVISOR_KEY as ADVISOR_KEY_ENV } from "../kernel/env-names.ts";
-import { ENV_ADVISOR_KEY } from "../kernel/env-names.ts";
+import { ENV_ADVISOR, ENV_ADVISOR_KEY, ENV_ADVISOR_MODEL } from "../kernel/env-names.ts";
+import { DEFAULT_ADVICE_TIMEOUT_MS } from "./advisor.ts";
+export { ENV_ADVISOR_MODEL } from "../kernel/env-names.ts";
+export { ENV_ADVISOR } from "../kernel/env-names.ts";
 
 export interface AdvisorSettings {
   enabled: boolean;
@@ -41,23 +51,49 @@ export const ADVISOR_OFF: AdvisorSettings = Object.freeze({ enabled: false, deci
  * their session without having successfully asked for it. Both are worse than a sentence naming the field.
  */
 export function advisorSettingsFrom(raw: unknown, env: NodeJS.ProcessEnv = process.env): AdvisorSettings {
-  if (raw === undefined || raw === null) return ADVISOR_OFF;
-  if (typeof raw !== "object" || Array.isArray(raw))
+  // The environment decides WHETHER, before the workspace is consulted at all. A settings file that asks for an
+  // advisor nobody enabled is not a configuration error; it is simply a project that would use one if the operator
+  // turned it on, so it is reported rather than refused.
+  const requested = env[ENV_ADVISOR]?.trim();
+  if (!requested) return ADVISOR_OFF;
+  if (requested !== "jev")
+    return { ...ADVISOR_OFF, refusal: `${ENV_ADVISOR}=${requested} names no advisor this release knows` };
+
+  const block = raw === undefined || raw === null ? {} : raw;
+  if (typeof block !== "object" || Array.isArray(block))
     return { ...ADVISOR_OFF, refusal: "settings.advisor must be an object; no advisor is enabled" };
-  const block = raw as Record<string, unknown>;
-  const unknownKeys = Object.keys(block).filter((key) => !["enabled", "decider", "model", "timeoutMs"].includes(key));
+  const fields = block as Record<string, unknown>;
+  // `model` stays KNOWN so the refusal below can say why it is refused, rather than reporting it as a typo.
+  const unknownKeys = Object.keys(fields).filter((key) => !["enabled", "decider", "model", "timeoutMs"].includes(key));
+  // Key names are echoed back, and this file is workspace-writable: a key containing an escape sequence or a
+  // newline would otherwise forge lines in the `/grants` panel, which is a trust surface. Review measured a forged
+  // `grant tool:*` line. Sanitised and truncated before it reaches any renderer.
   if (unknownKeys.length > 0)
-    return { ...ADVISOR_OFF, refusal: `settings.advisor has unknown field(s) ${unknownKeys.join(", ")}` };
-  if (block.enabled !== true) return ADVISOR_OFF;
-  if (block.decider !== "jev")
+    return {
+      ...ADVISOR_OFF,
+      refusal: `settings.advisor has unknown field(s) ${unknownKeys
+        .map((key) => key.replace(/[^\w.-]/g, "?").slice(0, 40))
+        .join(", ")}`,
+    };
+  // A project may switch it OFF; it may never switch it on, which is why `true` is not read. Anything that is not
+  // exactly `true` disables: `"false"`, `0` and `null` used to leave the advisor ON with no word said, which is
+  // rule 8 inverted — the one control this file retains failing open.
+  if (fields.enabled !== undefined && fields.enabled !== true)
+    return { ...ADVISOR_OFF, refusal: "settings.advisor.enabled is not true for this project" };
+  if (fields.decider !== undefined && fields.decider !== "jev")
     return { ...ADVISOR_OFF, refusal: `settings.advisor.decider must be "jev"; no advisor is enabled` };
-  if (block.model !== undefined && typeof block.model !== "string")
-    return { ...ADVISOR_OFF, refusal: "settings.advisor.model must be a string" };
+  // **A model is a DESTINATION, not a narrowing.** Letting this workspace-writable file choose it would let a child
+  // holding `tool:write` point the operator's next session at a generative model of its choosing, billed to the
+  // operator's key — the same self-defeating shape this release moved the enable switch to close, one step
+  // sideways. Review measured it. The model comes from the environment or not at all.
+  if ((fields as Record<string, unknown>).model !== undefined)
+    return { ...ADVISOR_OFF, refusal: `settings.advisor.model is not a narrowing; set ${ENV_ADVISOR_MODEL} instead` };
   if (
-    block.timeoutMs !== undefined &&
-    (!Number.isInteger(block.timeoutMs) || (block.timeoutMs as number) < 1 || (block.timeoutMs as number) > 30_000)
+    fields.timeoutMs !== undefined &&
+    (!Number.isInteger(fields.timeoutMs) || (fields.timeoutMs as number) < 1 || (fields.timeoutMs as number) > 30_000)
   )
     return { ...ADVISOR_OFF, refusal: "settings.advisor.timeoutMs must be an integer between 1 and 30000" };
+  const model = env[ENV_ADVISOR_MODEL]?.trim();
   const key = env[ENV_ADVISOR_KEY]?.trim();
   if (!key)
     return {
@@ -67,7 +103,11 @@ export function advisorSettingsFrom(raw: unknown, env: NodeJS.ProcessEnv = proce
   return {
     enabled: true,
     decider: "jev",
-    ...(typeof block.model === "string" ? { model: block.model } : {}),
-    ...(block.timeoutMs !== undefined ? { timeoutMs: block.timeoutMs as number } : {}),
+    ...(model ? { model } : {}),
+    // Clamped, never raised: a longer bound is not a narrowing either, and a child-writable 30s would be a stall on
+    // every delegation.
+    ...(fields.timeoutMs !== undefined
+      ? { timeoutMs: Math.min(fields.timeoutMs as number, DEFAULT_ADVICE_TIMEOUT_MS) }
+      : {}),
   };
 }

package/src/cli.ts

@@ -150,7 +150,15 @@ async function init(cwd: string, force: boolean): Promise<number> {
 
   let plan: InitPlan;
   try {
-    plan = planInit(packages, cwd, await registeredWorkspaceIds());
+    // A registry that cannot be read scaffolds no workspace capabilities. That was silent, so the operator
+    // saw a plan with none and no way to tell it apart from having registered none (rule 8).
+    plan = planInit(
+      packages,
+      cwd,
+      await registeredWorkspaceIds(undefined, (reason) =>
+        console.error(`pi-daddy init: workspace registry unreadable, scaffolding none — ${reason}`),
+      ),
+    );
   } catch (error) {
     // R-78's backstop reaching the surface. Nothing is written: a grant that could mean something to a
     // shell is not a grant, and half-scaffolding a project would be worse than scaffolding none of it.

package/src/kernel/bounded-read.ts

@@ -0,0 +1,125 @@
+/**
+ * One bounded reader for the operator-authored files this package reads at SESSION START.
+ *
+ * **Why this is a module rather than a pattern to copy.** `loadWorkspaceRegistry` worked out the correct
+ * shape the expensive way — R-79 hung forever on a FIFO, a `stat`-then-`readFile` rewrite reintroduced the
+ * hang through a TOCTOU, and `AbortSignal.timeout` turned out never to interrupt a libuv read. That comment
+ * block ends with "One reader is why that cannot happen again", and then a second session-start read
+ * (`loadDefinitions`, reading each `SKILL.md`) went on using a bare `readFile`. The guards were not copied
+ * because copying them correctly is exactly what the registry's own history says nobody manages.
+ *
+ * What the shape buys, restated once here so neither caller has to:
+ *
+ *  - `O_NONBLOCK` on the open. A FIFO blocks inside `open(2)` before any read starts, so a signal or a
+ *    deadline checked between chunks can never rescue it; a non-blocking open returns instead.
+ *  - every check against the HELD DESCRIPTOR. `stat` by name followed by a read by name is a TOCTOU, and the
+ *    attacker is any process at the same uid — swapping a regular file for a FIFO between the two hangs the
+ *    reader. `fstat` on a descriptor has no name left to re-resolve.
+ *  - a deadline checked BETWEEN chunks, which is all an `AbortSignal` ever managed. Its honest limit: a
+ *    stalled open or a single wedged read cannot be interrupted from in-process.
+ *  - a size bound checked twice, before the read from `fstat` and again after, because a file can grow
+ *    between the two. **The buffer is `maxBytes + 1` regardless of the file's size, and that is deliberate.**
+ *    Review proposed sizing it from `fstat` instead; that would be faster and would silently break the second
+ *    check, because a file whose reported size understates its content — anything under procfs, and any file
+ *    that grows — would fill its small buffer exactly and come back as a successful truncated read. The cost
+ *    was measured rather than assumed: 500 allocations of 1 MiB + 1 take 8.1ms for an RSS delta of 2.8 MB,
+ *    because `allocUnsafe` never touches the pages.
+ *
+ * **The clock is injected** so the deadline is forced by a test rather than by a reviewer. Before this
+ * module the registry's deadline could be deleted outright and all 876 tests still passed (measured at
+ * `7096f78`), which is rule 7's "a test that cannot fail is worse than no test" with the production change
+ * named: delete the `now() > deadline` branch below and `bounded-read.test.ts` fails.
+ */
+import { constants } from "node:fs";
+import { open, type FileHandle } from "node:fs/promises";
+
+export interface BoundedReadLimits {
+  /** Refuse anything at or over this, before allocating it. */
+  maxBytes: number;
+  /** How long the chunk loop may run before the read is a refusal rather than a wait. */
+  timeoutMs: number;
+  /** Injected only by tests; production passes nothing and gets the wall clock. */
+  now?: () => number;
+}
+
+/**
+ * Why a bounded read did not produce text.
+ *
+ * A discriminated reason rather than a thrown error, because the two callers disagree about what a failure
+ * MEANS — an unreadable registry is a governance refusal naming the file, while an unreadable `SKILL.md` is
+ * 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: "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 };
+
+export type BoundedReadResult = { ok: true; text: string } | ({ ok: false } & BoundedReadFailure);
+export type BoundedReadBytes = { ok: true; bytes: Buffer } | ({ ok: false } & BoundedReadFailure);
+
+/**
+ * The same read, handing back raw bytes.
+ *
+ * `skill-packages.ts` needs the bytes rather than a string, because it asserts that a definition survives a
+ * 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 readBoundedBytes(path: string, limits: BoundedReadLimits): Promise<BoundedReadBytes> {
+  const now = limits.now ?? Date.now;
+  let handle: FileHandle;
+  try {
+    handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+  } catch (error) {
+    return { ok: false, why: "unopenable", detail: String(error) };
+  }
+  try {
+    const info = await handle.stat();
+    if (!info.isFile())
+      return {
+        ok: false,
+        why: "not-a-regular-file",
+        detail: `${path} is not a regular file — a FIFO, device or socket here would block rather than fail`,
+      };
+    if (info.size > limits.maxBytes)
+      return {
+        ok: false,
+        why: "too-large",
+        size: info.size,
+        detail: `${path} is ${info.size} bytes, over the ${limits.maxBytes} limit`,
+      };
+
+    const deadline = now() + limits.timeoutMs;
+    const buffer = Buffer.allocUnsafe(limits.maxBytes + 1);
+    let filled = 0;
+    while (filled < buffer.length) {
+      if (now() > deadline)
+        return {
+          ok: false,
+          why: "timed-out",
+          detail: `${path} did not finish reading within ${limits.timeoutMs}ms`,
+        };
+      const { bytesRead } = await handle.read(buffer, filled, buffer.length - filled, filled);
+      if (bytesRead === 0) break;
+      filled += bytesRead;
+    }
+    if (filled > limits.maxBytes)
+      return {
+        ok: false,
+        why: "grew-while-reading",
+        detail: `${path} exceeded the ${limits.maxBytes} limit while being read — it grew after its size was checked`,
+      };
+    return { ok: true, bytes: buffer.subarray(0, filled) };
+  } catch (error) {
+    return { ok: false, why: "unreadable", detail: String(error) };
+  } finally {
+    await handle.close().catch(() => {});
+  }
+}

package/src/kernel/catalog.ts

@@ -44,6 +44,17 @@ export interface Catalog {
   all: Capability[];
   byKind(kind: CapabilityKind): Capability[];
   has(capability: Capability): boolean;
+  /**
+   * Why the workspace registry contributed nothing, when one was named and could not be read.
+   *
+   * The catalog fails SOFT on a bad registry — a malformed one must not stop a session starting — and the
+   * refusal used to be discarded by `() => []` at the call below. That is rule 8's silent safe-mode: one
+   * malformed entry removed every workspace from `/grants`, from the catalog and from `init`, and produced
+   * no message anywhere, so an operator saw an empty list and could not tell it apart from having
+   * registered nothing. Failing soft is still right; failing soft and SILENTLY was not. `undefined` means
+   * no registry was named, or it read cleanly.
+   */
+  registryRefusal?: string;
 }
 
 /** Split observed tool names into pi built-ins and extension-provided tools. */
@@ -107,7 +118,7 @@ export function workspaceEntries(registry: WorkspaceRegistryFile, source?: strin
 }
 
 /** Assemble a catalog from parts. Pure, so it is testable without a filesystem. */
-export function makeCatalog(entries: CatalogEntry[]): Catalog {
+export function makeCatalog(entries: CatalogEntry[], registryRefusal?: string): Catalog {
   const deduped = new Map<Capability, CatalogEntry>();
   for (const entry of entries) if (!deduped.has(entry.capability)) deduped.set(entry.capability, entry);
   const list = [...deduped.values()].sort((a, b) => a.capability.localeCompare(b.capability));
@@ -118,6 +129,7 @@ export function makeCatalog(entries: CatalogEntry[]): Catalog {
     all: ids,
     byKind: (kind) => list.filter((e) => e.kind === kind).map((e) => e.capability),
     has: (capability) => idSet.has(capability),
+    ...(registryRefusal === undefined ? {} : { registryRefusal }),
   };
 }
 
@@ -135,30 +147,39 @@ export async function buildCatalog(input: {
     // 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
     // it there would be unsafe; swallowing it here costs a display list.
+    //
+    // **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) => workspaceEntries(r, input.registryPath),
-          () => [] as CatalogEntry[],
+          (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([] as CatalogEntry[]),
-  ]);
-  return makeCatalog([
-    // pi's built-ins are seeded unconditionally, because they are known statically and the catalog is
-    // consulted BEFORE any provider request has happened — `/grants` runs at that point. Without this,
-    // every capability looked "unknown" until the first model call, so the preview refused grants that
-    // enforcement would have allowed: R-28's failure shape (a diagnostic disagreeing with the enforcer)
-    // reappearing through a different door.
-    //
-    // The trade-off, stated plainly: in a session started with `--tools read`, this still lists `bash`
-    // as an existing capability, so a delegation naming it passes the *unknown* check and is refused by
-    // the *grant* check instead ("this session does not hold it"). That is the better error anyway, and
-    // the grant check — not this catalog — is the authority. Nothing here grants anything.
-    ...PI_BUILTIN_TOOLS.map((name) => ({ capability: `tool:${name}` as const, kind: "builtin" as const })),
-    ...(input.observedTools ? classifyToolNames(input.observedTools) : []),
-    ...skills,
-    ...definitionEntries(definitions),
-    ...workspaces,
+      : Promise.resolve({ entries: [] as CatalogEntry[], refusal: undefined as string | undefined }),
   ]);
+  return makeCatalog(
+    [
+      // pi's built-ins are seeded unconditionally, because they are known statically and the catalog is
+      // consulted BEFORE any provider request has happened — `/grants` runs at that point. Without this,
+      // every capability looked "unknown" until the first model call, so the preview refused grants that
+      // enforcement would have allowed: R-28's failure shape (a diagnostic disagreeing with the enforcer)
+      // reappearing through a different door.
+      //
+      // The trade-off, stated plainly: in a session started with `--tools read`, this still lists `bash`
+      // as an existing capability, so a delegation naming it passes the *unknown* check and is refused by
+      // the *grant* check instead ("this session does not hold it"). That is the better error anyway, and
+      // the grant check — not this catalog — is the authority. Nothing here grants anything.
+      ...PI_BUILTIN_TOOLS.map((name) => ({ capability: `tool:${name}` as const, kind: "builtin" as const })),
+      ...(input.observedTools ? classifyToolNames(input.observedTools) : []),
+      ...skills,
+      ...definitionEntries(definitions),
+      ...workspaces.entries,
+    ],
+    workspaces.refusal,
+  );
 }
 
 /**