pi-daddy 0.35.0 → 0.36.0

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,
+  );
 }
 
 /**

package/src/kernel/definitions.ts

@@ -20,7 +20,7 @@
  */
 
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { readBoundedFile } from "./bounded-read.ts";
 import { resolveSkillResources, skillResourceName } from "./skill-resources.ts";
 import { CAPABILITY_NAMESPACE_PREFIXES } from "./capabilities.ts";
 import type { Capability } from "./resolve.ts";
@@ -194,22 +194,52 @@ export function ceilingForDefinition(definition: SkillDefinition): DefinitionCei
   return { capabilities: [...capabilities].sort(), patterns, undeclared: false };
 }
 
+/**
+ * A `SKILL.md` is an operator-authored markdown file; anything approaching this is not one.
+ *
+ * The same order of magnitude as the registry's bound and for the same reason. Measured at `7096f78`: a
+ * bare `readFile` pulled an 8 MiB `SKILL.md` into memory in 8ms without complaint, and this loop runs once
+ * per discovered skill inside `session_start`.
+ */
+export const DEFINITION_MAX_BYTES = 1 << 20;
+
+/** A definition read is a local file read; a second is three orders of magnitude of headroom. */
+export const DEFINITION_READ_TIMEOUT_MS = 2_000;
+
 /**
  * Read definitions from Pi's enabled resources, including installed packages and local overrides.
  * Resolver precedence and filters are shared with the capability catalog; unregistered npm packages
  * are not runtime resources until legacy init explicitly scaffolds them.
+ *
+ * **Bounded, and loud about what it dropped.** This used a bare `readFile` with `catch { continue }`, which
+ * is both halves of what rule 8 forbids: unbounded, and silent. `resolveSkillResources` filters by
+ * `statSync(...).isFile()`, so a FIFO *named* in the resource list is already dropped — but that check is by
+ * NAME and the read that followed was by name too, which is the TOCTOU the registry's own comment block
+ * describes swapping a regular file for a FIFO through. `readBoundedFile` makes every check against the held
+ * descriptor. `skipped` exists so a caller can say which paths were dropped and why, rather than an operator
+ * finding a definition absent from `/grants` with nothing anywhere explaining it.
  */
-export async function loadDefinitions(cwd: string): Promise<Map<string, SkillDefinition>> {
+export async function loadDefinitions(
+  cwd: string,
+  skipped?: (path: string, reason: string) => void,
+): Promise<Map<string, SkillDefinition>> {
   const definitions = new Map<string, SkillDefinition>();
   for (const { path } of (await resolveSkillResources(cwd)).skills) {
-    let text: string;
-    try {
-      text = await readFile(path, "utf8");
-    } catch {
+    const read = await readBoundedFile(path, {
+      maxBytes: DEFINITION_MAX_BYTES,
+      timeoutMs: DEFINITION_READ_TIMEOUT_MS,
+    });
+    if (!read.ok) {
+      skipped?.(path, read.detail);
       continue;
     }
-    const parsed = parseSkillDefinition(path, text);
-    if (parsed && !definitions.has(parsed.name)) definitions.set(parsed.name, parsed);
+    const parsed = parseSkillDefinition(path, read.text);
+    if (!parsed) skipped?.(path, `${path} has no readable frontmatter with a description`);
+    // Shadowing is legitimate — a project override is SUPPOSED to win over a package's copy — but review
+    // pointed out it was the one remaining drop with no word said, in the very function being made loud.
+    else if (definitions.has(parsed.name))
+      skipped?.(path, `${path} is shadowed by an earlier definition named ${parsed.name}`);
+    else definitions.set(parsed.name, parsed);
   }
   return definitions;
 }

package/src/kernel/skill-packages.ts

@@ -6,9 +6,16 @@
  */
 
 import { readdir, readFile, realpath } from "node:fs/promises";
+import { readBoundedBytes } from "./bounded-read.ts";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
-import { ceilingForDefinition, parseSkillDefinition, type SkillDefinition } from "./definitions.ts";
+import {
+  ceilingForDefinition,
+  parseSkillDefinition,
+  type SkillDefinition,
+  DEFINITION_MAX_BYTES,
+  DEFINITION_READ_TIMEOUT_MS,
+} from "./definitions.ts";
 import { resolveSkillResources, skillResourceName } from "./skill-resources.ts";
 import { WILDCARD } from "./pi-tools.ts";
 import { AGENT_WILDCARD, WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
@@ -146,12 +153,17 @@ async function readSkill(packageDir: string, entry: string): Promise<DiscoveredS
   // smoke test one day earlier and not applied here.
   const realPackageDir = await realpath(packageDir).catch(() => packageDir);
   for (const path of [join(target, "SKILL.md"), ...(target.endsWith(".md") ? [target] : [])]) {
-    let bytes: Buffer;
-    try {
-      bytes = await readFile(path);
-    } catch {
-      continue;
-    }
+    // **Bounded with the SAME limit the runtime loader uses, because the two must agree about which
+    // definitions exist.** Review measured the divergence: a 2 MiB `SKILL.md` was refused by
+    // `loadDefinitions` and accepted here, so `pi-daddy init` wrote `agent:advice` into the operator's grant
+    // for a definition the session could never load, and the eventual `delegate` said only
+    // `unknown agent "advice"`. An unreadable entry lands in `unreadable`, which `init` already prints.
+    const read = await readBoundedBytes(path, {
+      maxBytes: DEFINITION_MAX_BYTES,
+      timeoutMs: DEFINITION_READ_TIMEOUT_MS,
+    });
+    if (!read.ok) continue;
+    const bytes = read.bytes;
     const realPath = await realpath(path).catch(() => path);
     if (!realPath.startsWith(realPackageDir + sep)) return null;
 
@@ -255,8 +267,13 @@ export async function discoverSkillPackages(cwd: string): Promise<SkillPackage[]
     }
   }
   for (const resource of resolved.skills) {
-    const bytes = await readFile(resource.path).catch(() => null);
-    if (bytes === null) continue;
+    // Same bound, same reason: this is the third `SKILL.md` reader and it feeds `planInit`.
+    const resourceRead = await readBoundedBytes(resource.path, {
+      maxBytes: DEFINITION_MAX_BYTES,
+      timeoutMs: DEFINITION_READ_TIMEOUT_MS,
+    });
+    if (!resourceRead.ok) continue;
+    const bytes = resourceRead.bytes;
     const text = bytes.toString("utf8");
     const resourceName = skillResourceName(resource.path);
     if (seenSkills.has(resourceName)) continue;

package/src/kernel/workspace.ts

@@ -1,9 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
 import { once } from "node:events";
-import { mkdir, open, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
-import type { FileHandle } from "node:fs/promises";
-import { constants } from "node:fs";
+import { mkdir, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
+import { readBoundedFile } from "./bounded-read.ts";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { promisify } from "node:util";
@@ -60,111 +59,36 @@ const REGISTRY_READ_TIMEOUT_MS = 2_000;
 const REGISTRY_MAX_BYTES = 1 << 20;
 
 export async function loadWorkspaceRegistry(path: string): Promise<WorkspaceRegistryFile> {
-  // **One handle, opened non-blocking, and every check made against THAT handle.** Three defects made this
-  // the shape rather than `stat`-then-`readFile`:
-  //
-  //  - `AbortSignal.timeout` cannot rescue a FIFO: a signal is observed between chunks, while a FIFO blocks
-  //    inside `open(2)` before any read begins. `O_NONBLOCK` makes the open itself return instead (measured:
-  //    1ms), which is what actually bounds this path. R-79's defect class, and R-136's.
-  //  - `stat` by name followed by `readFile` by name is a TOCTOU: swapping a regular file for a FIFO between
-  //    the two hung the loader indefinitely, and the attacker is any process at the same uid — precisely the
-  //    actor the mode check below cannot exclude. Measured, 5 of 6 iterations completing in ~1ms and the
-  //    sixth never returning. `fstat` on a held descriptor has no name to re-resolve.
-  //  - a second reader (the ADR-0035 registry pin, since reverted to its own PR) reimplemented the guards and
-  //    got them wrong. One reader is why that cannot happen again.
-  let handle: FileHandle;
-  try {
-    handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
-  } catch (error) {
-    throw new GovernanceRefusal(
-      refusal("WORKSPACE_NOT_REGISTERED", `workspace registry ${path} could not be opened (${String(error)})`, {
-        registry_path: path,
-      }),
-    );
-  }
-  let raw: string;
-  try {
-    const info = await handle.stat();
-    if (!info.isFile()) {
-      throw new GovernanceRefusal(
-        refusal(
-          "WORKSPACE_NOT_REGISTERED",
-          `workspace registry ${path} is not a regular file — refusing to read it. A FIFO, device or socket ` +
-            `at ${ENV_WORKSPACE_REGISTRY} would block session start rather than fail, because opening one ` +
-            `waits for a writer that may never come.`,
-          { registry_path: path },
-        ),
-      );
-    }
-    if (info.size > REGISTRY_MAX_BYTES) {
-      throw new GovernanceRefusal(
-        refusal(
-          "WORKSPACE_NOT_REGISTERED",
-          `workspace registry ${path} is ${info.size} bytes, over the ${REGISTRY_MAX_BYTES} limit — refusing ` +
-            `rather than reading it into memory at session start.`,
-          { registry_path: path },
-        ),
-      );
-    }
-    // **Ownership and mode are NOT checked here, and that is a scope decision (R-137, ADR-0036).** A
-    // previous revision refused a registry not owned by this user or writable by others. Those guards are
-    // about *tamper resistance*, which is a different question from the one ADR-0035 raised, and they went in
-    // mid-review without an ADR — where they promptly acquired a false claim ("nobody ELSE may rewrite it":
-    // it inspects the file and never its parent directory, and `rename(2)` needs only directory write) and a
-    // false-positive refusal of `0664`, which `umask 002` produces for every file an operator creates.
-    //
-    // What IS checked above is what ADR-0035 made this reader's problem: it began reading the registry at
-    // SESSION START, so the read must be bounded and must not block. Integrity is R-137, open and measured.
-    // The deadline is checked BETWEEN chunks, which is all `AbortSignal.timeout` ever did on the previous
-    // implementation — review measured 74 of 200 one-MiB reads completing in full with `signal.aborted`
-    // already true, because a signal is never observed *inside* a libuv read request. An explicit check makes
-    // the bound as real as it can be in-process, and its limit is the same one honestly stated below: a
-    // stalled `open` or a single wedged read cannot be interrupted from here.
-    const deadline = Date.now() + REGISTRY_READ_TIMEOUT_MS;
-    const buffer = Buffer.allocUnsafe(REGISTRY_MAX_BYTES + 1);
-    let filled = 0;
-    while (filled < buffer.length) {
-      if (Date.now() > deadline) {
-        throw new GovernanceRefusal(
-          refusal(
-            "WORKSPACE_NOT_REGISTERED",
-            `workspace registry ${path} did not finish reading within ${REGISTRY_READ_TIMEOUT_MS}ms — ` +
-              `refusing rather than waiting, because session start awaits this read.`,
-            { registry_path: path },
-          ),
-        );
-      }
-      const { bytesRead } = await handle.read(buffer, filled, buffer.length - filled, filled);
-      if (bytesRead === 0) break;
-      filled += bytesRead;
-    }
-    if (filled > REGISTRY_MAX_BYTES) {
-      throw new GovernanceRefusal(
-        refusal(
-          "WORKSPACE_NOT_REGISTERED",
-          `workspace registry ${path} exceeded the ${REGISTRY_MAX_BYTES} limit while being read — it grew ` +
-            `after its size was checked. Refusing rather than allocating it.`,
-          { registry_path: path },
-        ),
-      );
-    }
-    raw = buffer.subarray(0, filled).toString("utf8");
-  } catch (error) {
-    if (error instanceof GovernanceRefusal) throw error;
-    const timedOut = error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
-    throw new GovernanceRefusal(
-      refusal(
-        "WORKSPACE_NOT_REGISTERED",
-        timedOut
-          ? `workspace registry ${path} did not return within ${REGISTRY_READ_TIMEOUT_MS}ms — refusing rather ` +
-              `than waiting, because session start awaits this read.`
-          : `workspace registry ${path} could not be read (${String(error)})`,
-        { registry_path: path },
-      ),
-    );
-  } finally {
-    await handle.close().catch(() => {});
+  // The guards this call carries — non-blocking open, every check on the held descriptor, a deadline between
+  // chunks, the size bound checked twice — were worked out HERE and now live in `bounded-read.ts`, because a
+  // second session-start reader went on using a bare `readFile` rather than copying them. The mapping from a
+  // reason to a refusal stays here: only this caller knows that an unreadable registry is a governance
+  // refusal naming the file, and its messages are unchanged.
+  const read = await readBoundedFile(path, {
+    maxBytes: REGISTRY_MAX_BYTES,
+    timeoutMs: REGISTRY_READ_TIMEOUT_MS,
+  });
+  if (!read.ok) {
+    const message =
+      read.why === "not-a-regular-file"
+        ? `workspace registry ${path} is not a regular file — refusing to read it. A FIFO, device or socket ` +
+          `at ${ENV_WORKSPACE_REGISTRY} would block session start rather than fail, because opening one ` +
+          `waits for a writer that may never come.`
+        : read.why === "too-large"
+          ? `workspace registry ${path} is ${read.size} bytes, over the ${REGISTRY_MAX_BYTES} limit — ` +
+            `refusing rather than reading it into memory at session start.`
+          : read.why === "grew-while-reading"
+            ? `workspace registry ${path} exceeded the ${REGISTRY_MAX_BYTES} limit while being read — it ` +
+              `grew after its size was checked. Refusing rather than allocating it.`
+            : read.why === "timed-out"
+              ? `workspace registry ${path} did not finish reading within ${REGISTRY_READ_TIMEOUT_MS}ms — ` +
+                `refusing rather than waiting, because session start awaits this read.`
+              : read.why === "unopenable"
+                ? `workspace registry ${path} could not be opened (${read.detail})`
+                : `workspace registry ${path} could not be read (${read.detail})`;
+    throw new GovernanceRefusal(refusal("WORKSPACE_NOT_REGISTERED", message, { registry_path: path }));
   }
+  const raw = read.text;
   let parsed: unknown;
   try {
     parsed = JSON.parse(raw);
@@ -237,12 +161,22 @@ export async function loadWorkspaceRegistry(path: string): Promise<WorkspaceRegi
  * that module — documents itself as "Pure: no filesystem". It is a registry concern; this is where the
  * registry lives. Moved when `init.ts` crossed the 400-line ceiling, which this project splits for rather
  * than raising (`delegate.ts` at 413, `grants.ts` at 398).
+ *
+ * **`onRefusal` exists because `catch { return [] }` was rule 8's silent safe-mode.** A malformed registry
+ * made `pi-daddy init` scaffold with no workspace capabilities at all and say nothing about why, which an
+ * operator cannot tell apart from having registered none. Failing soft stays — `init` must work without a
+ * registry — but the reason is handed to the caller instead of discarded. A caller that passes nothing keeps
+ * the old behaviour, which is why this is an optional parameter and not a changed return type.
  */
-export async function registeredWorkspaceIds(registryPath = process.env[ENV_WORKSPACE_REGISTRY]): Promise<string[]> {
+export async function registeredWorkspaceIds(
+  registryPath = process.env[ENV_WORKSPACE_REGISTRY],
+  onRefusal?: (reason: string) => void,
+): Promise<string[]> {
   if (!registryPath) return [];
   try {
     return Object.keys((await loadWorkspaceRegistry(registryPath)).workspaces).sort();
-  } catch {
+  } catch (error) {
+    onRefusal?.(error instanceof Error ? error.message : String(error));
     return [];
   }
 }