pi-daddy 0.34.0 → 0.36.0

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/delegate-types.ts

@@ -90,7 +90,18 @@ export interface DelegationContext {
    * reads nothing. What it returns reaches the child as an appended system prompt or as fork arguments; it can
    * carry no capability, so nothing here can widen a grant.
    */
-  stageHandoff?: (granted: ContextRequest) => {
+  /**
+   * Turn ids a composition-layer selector chose for a `pruned` handoff (ADR-0077's second decision point).
+   *
+   * Composition, because choosing may mean asking an advisor and the kernel does no I/O and knows no advisor. The
+   * ids can only NARROW: staging keeps the intersection with what the deterministic rule already surfaced, so a
+   * selector cannot introduce a turn the rule did not offer, whatever it returns.
+   */
+  handoffTurnIds?: readonly string[];
+  stageHandoff?: (
+    granted: ContextRequest,
+    options?: { keepTurnIds?: readonly string[] },
+  ) => {
     contextPrompt?: string;
     forkFrom?: { sessionPath: string; sessionDir: string; sessionId: string };
     record?: Delegation["handoffRecord"];

package/src/kernel/delegate.ts

@@ -326,7 +326,9 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
     handoff.mode !== "none" && result.effective.includes(contextCapability(handoff.mode)) ? handoff : undefined;
   const canSubDelegate = result.effective.includes(DELEGATE_CAPABILITY);
   // Only for a handoff that survived, so a refused mode reads no file and forks no session.
-  const staged = grantedHandoff ? ctx.stageHandoff?.(grantedHandoff) : undefined;
+  const staged = grantedHandoff
+    ? ctx.stageHandoff?.(grantedHandoff, ctx.handoffTurnIds ? { keepTurnIds: ctx.handoffTurnIds } : {})
+    : undefined;
   if (staged?.refusal)
     return denied({ ...empty, requested, result, reason: staged.refusal }, "CONTEXT_REQUEST_INVALID");
   const plan = planSpawn({

package/src/kernel/env-names.ts

@@ -48,6 +48,20 @@ export const ENV_GOVERNANCE = "PI_DADDY_GOVERNANCE";
  * inherited a paid credential its grant never named. Measured in review.
  */
 export const ENV_ADVISOR_KEY = "PI_DADDY_ADVISOR_KEY";
+/**
+ * Which advisor is in force, or absent for none (ADR-0077).
+ *
+ * **The enable lives here rather than in the project settings file, and that is a correction.** 0.34.0 read it from
+ * `.pi/pi-daddy/settings.json`, which `grant-store.ts` is explicit about: that file 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 is kept outside the workspace for exactly that reason, and an advisor switch needs the same treatment for a
+ * neighbouring one — a child that could flip it on would make the operator's NEXT session ship its own description
+ * to a third party. The settings file may still narrow (a model, a timeout, or `enabled: false`); it can no longer
+ * turn one on.
+ */
+export const ENV_ADVISOR = "PI_DADDY_ADVISOR";
+/** Overrides the adapter's pinned model. In the environment, never the workspace file: a model is a destination. */
+export const ENV_ADVISOR_MODEL = "PI_DADDY_ADVISOR_MODEL";
 
 /** Every variable that shapes governance. The `childEnv` hook may set none of these. */
 export const GOVERNANCE_ENV_KEYS: readonly string[] = Object.freeze([
@@ -74,6 +88,8 @@ export const GOVERNANCE_ENV_KEYS: readonly string[] = Object.freeze([
   ENV_RETAIN_NATIVE_SESSIONS,
   ENV_GOVERNANCE,
   ENV_ADVISOR_KEY,
+  ENV_ADVISOR,
+  ENV_ADVISOR_MODEL,
 ]);
 
 /**

package/src/kernel/propagation.ts

@@ -31,7 +31,9 @@ import { WORKSPACE_WILDCARD } from "./resolve.ts";
 import { inheritApprovals, type InheritableApproval } from "./approval.ts";
 import { assertCapabilitiesArePropagatable } from "./capabilities.ts";
 import {
+  ENV_ADVISOR_MODEL,
   ENV_ADVISOR_KEY,
+  ENV_ADVISOR,
   ENV_GRANT,
   ENV_FANOUT,
   ENV_PARENT_ID,
@@ -76,9 +78,14 @@ export {
  * to give it.
  */
 export const GRANT_ENV_KEYS = [
-  // Not governance state, but the same rule applies for a stronger reason: a credential the parent holds is not
-  // something a child inherits by being spawned (ADR-0077).
+  // Not governance state, but the same rule applies for a stronger reason: neither a credential the parent holds
+  // nor the switch that points it at a third party is something a child inherits by being spawned (ADR-0077).
+  //
+  // **This strips the PROCESS executor's environment.** A Herdr pane inherits the daemon's environment, which this
+  // function never sees (R-148), so a daemon started from a shell exporting these two hands them to every pane
+  // child. Named here rather than claimed away: "stripped from every child" would be false on that path.
   ENV_ADVISOR_KEY,
+  ENV_ADVISOR,
   ENV_GRANT,
   ENV_DEPTH,
   ENV_MAX_DEPTH,

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 [];
   }
 }