pi-daddy 0.18.0 → 0.19.0

package/src/skill-packages.ts

@@ -30,7 +30,8 @@ import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import { ceilingForDefinition, parseSkillDefinition, type SkillDefinition } from "./definitions.ts";
 import { WILDCARD } from "./pi-tools.ts";
-import { AGENT_WILDCARD, type Capability } from "./resolve.ts";
+import { AGENT_WILDCARD, WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
+import { isSafeCapability } from "./capabilities.ts";
 
 export interface DiscoveredSkill {
   definition: SkillDefinition;
@@ -107,21 +108,27 @@ export function isSafeName(name: string): boolean {
  * grants), which is right for the enforcement path — the catalog refuses what it does not know — and is
  * exactly why the check has to be here, at the boundary that *generates* rather than the one that enforces.
  *
- * The grammar is the one `docs/SPEC.md` documents: `tool:<name>`, `skill:<name>`, `agent:<name>`, and
- * `ext:<pkg>/<tool>` where `<pkg>` may be npm-scoped. No wildcards — those are refused separately and
- * loudly, because "you tried to grant yourself everything" is a different fact from "that is not a name".
+ * The grammar is the one `docs/SPEC.md` documents: `tool:<name>`, `skill:<name>`, `agent:<name>`,
+ * `workspace:<id>`, and `ext:<pkg>/<tool>` where `<pkg>` may be npm-scoped. No wildcards — those are refused
+ * separately and loudly, because "you tried to grant yourself everything" is a different fact from "that is
+ * not a name".
+ *
+ * `workspace:` was absent until 2026-08-21, so the boundary that GENERATES grants could not emit the one
+ * capability ADR-0035's breaking change made mandatory: a package needing to route was reported as declaring
+ * something that "is not a name". A namespace has to be added here as well as to the enforcing path, and
+ * that is the whole lesson of the review this came out of.
  */
-export function isSafeCapability(id: Capability): boolean {
-  const segment = "[A-Za-z0-9][A-Za-z0-9._-]*";
-  return (
-    new RegExp(`^(tool|skill|agent):${segment}$`).test(id) ||
-    new RegExp(`^ext:(@${segment}/)?${segment}/${segment}$`).test(id)
-  );
-}
+// Imported as well as re-exported: a bare `export … from` does not bind the name in this module's scope, and
+// `refusalFor` below calls it. Re-exported because this has been the import site since 0.13.0.
+export { isSafeCapability };
 
-/** The two ids that confer root authority. A package declaring one is claiming it, not describing a need. */
+/**
+ * The ids that confer authority over a whole namespace. A package declaring one is claiming it, not
+ * describing a need — so it is reported as a *wildcard claim* rather than as a malformed name, which is a
+ * different sentence to show an operator. `workspace:*` belongs here for the same reason `agent:*` does.
+ */
 function wildcardsIn(capabilities: Capability[]): Capability[] {
-  return capabilities.filter((c) => c === WILDCARD || c === AGENT_WILDCARD);
+  return capabilities.filter((c) => c === WILDCARD || c === AGENT_WILDCARD || c === WORKSPACE_WILDCARD);
 }
 
 /**

package/src/workspace-lease.ts

@@ -14,6 +14,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { GovernanceRefusal, refusal } from "./refusals.ts";
 import type { ValidatedWorkspace, WorkspaceAccess } from "./workspace.ts";
+import { assertCloseBounds, HELPER_SOURCE, LEASE_READY, unrefStream } from "./lease-helper.ts";
 
 export const ENV_WORKSPACE_LEASE_DIR = "PI_GRANTS_WORKSPACE_LEASE_DIR";
 
@@ -22,28 +23,17 @@ export function defaultWorkspaceLeaseDir(env: NodeJS.ProcessEnv = process.env):
   return env[ENV_WORKSPACE_LEASE_DIR] ?? join(agentDir, "pi-daddy", "workspace-leases");
 }
 
-const LEASE_READY = "PI_DADDY_LEASE_READY";
-// The lock holder also owns crash cleanup for the governed child. If the parent dies, stdin closes;
-// the helper signals the attached process, or closes the herdr tab, before releasing flock. A raw
-// descendant deliberately detached by bash remains ADR-0012's OS-containment boundary, not a lease
-// guarantee. The process branch SIGTERMs, escalates to SIGKILL at +500ms, and releases at +750ms
-// WITHOUT confirming death (R-101). The herdr branch retries `tab close` a BOUNDED number of times
-// and then releases anyway, leaving a marker file: an unreleasable lock strands a worktree forever
-// with no in-product recovery, which is strictly worse than a recorded failure to close (R-102).
-const HELPER_SOURCE = `
-import { execFile } from "node:child_process";
-import { writeFileSync } from "node:fs";
-let clean=false, target=null, buffered="";
-process.stdout.write(${JSON.stringify(`${LEASE_READY}:`)}+process.pid+"\\n");
-process.stdin.setEncoding("utf8");
-process.stdin.on("data",chunk=>{buffered+=chunk;for(;;){const i=buffered.indexOf("\\n");if(i<0)break;const line=buffered.slice(0,i);buffered=buffered.slice(i+1);try{const value=JSON.parse(line);if(value.release)clean=true;else if(value.process_pid)target={process_pid:value.process_pid};else if(value.herdr_tab)target={herdr_tab:value.herdr_tab};}catch{}}});
-process.stdin.on("end",()=>{if(clean||!target)return process.exit(0);if(target.process_pid){try{process.kill(target.process_pid,"SIGTERM")}catch{return process.exit(0)}setTimeout(()=>{try{process.kill(target.process_pid,"SIGKILL")}catch{}},500);return setTimeout(()=>process.exit(0),750);}let left=Number(process.env.PI_DADDY_LEASE_CLOSE_ATTEMPTS||10);const giveUp=()=>{try{if(process.env.PI_DADDY_LEASE_MARKER)writeFileSync(process.env.PI_DADDY_LEASE_MARKER,JSON.stringify({reason:"herdr-close-failed",herdr_tab:target.herdr_tab})+"\\n")}catch{}process.exit(0)};const close=()=>execFile("herdr",["tab","close",target.herdr_tab],error=>{if(!error)return process.exit(0);if(--left<=0)return giveUp();setTimeout(close,1000)});close();});
-process.stdin.resume();`;
 
 /**
- * The ledger outcome for a release. ONE definition, exported, because two call sites had their own copies
- * and the check runner's copy asserted `released` unconditionally — reproducing in the evidence path the
- * exact defect this union was added to expose (R-100/R-103).
+ * The ledger outcome for a release. Exported because call sites had their own copies and the check runner's
+ * asserted `released` unconditionally — reproducing in the evidence path the exact defect this union was
+ * added to expose (R-100/R-103).
+ *
+ * **It is NOT the only definition, and saying so here was wrong.** `extensions/workspace-runtime.ts` keeps a
+ * private copy with no `not-held` arm, and it is the one the whole delegation path uses — so releasing a
+ * *read* lease on a delegated child is still recorded `released`, a handover the kernel never performed.
+ * Measured; open as R-141; the sentence claiming a single definition survived two review passes because
+ * `test/workspace.test.ts` pins the `not-held` arm on THIS function, which no delegation path calls.
  */
 export function leaseReleaseLedgerOutcome(
   outcome: LeaseReleaseOutcome | "retained",
@@ -78,9 +68,17 @@ export async function acquireWorkspaceLease(input: {
   signal?: AbortSignal;
   flockCommand?: string;
   acquisitionTimeoutMs?: number;
+  /**
+   * Bound on how long ONE `herdr tab close` attempt may take before it counts as failed (R-146). A hung
+   * herdr is not a failed herdr: without this the attempt never returns and the retry bound below is
+   * unreachable.
+   */
+  herdrCloseTimeoutMs?: number;
   /** Bound on the helper's `herdr tab close` retries before it releases the lock anyway (R-102). */
   herdrCloseAttempts?: number;
 }): Promise<WorkspaceLease> {
+  // Before the read-lease return, so both paths are validated (R-152).
+  assertCloseBounds(input);
   if (input.access === "read") {
     return {
       workspace: input.workspace,
@@ -89,7 +87,9 @@ export async function acquireWorkspaceLease(input: {
       recovered: false,
       attachProcess: () => {},
       attachHerdrTab: () => {},
-      markRetained: async () => {},
+      // A read lease took no kernel lock, so there is nothing to keep: `not-held` is the same answer
+      // `release()` gives, and it is the truth rather than a retention that never happened (R-152).
+      markRetained: async () => "not-held" as const,
       readCloseFailure: async () => null,
       lost: new Promise(() => {}),
       // No kernel lock was ever taken, so there is no handover to claim (R-105, release side).
@@ -108,7 +108,12 @@ export async function acquireWorkspaceLease(input: {
     process.execPath, "--input-type=module", "-e", HELPER_SOURCE,
   ], {
     stdio: ["pipe", "pipe", "pipe"],
-    env: { ...process.env, PI_DADDY_LEASE_MARKER: paths.marker, PI_DADDY_LEASE_CLOSE_ATTEMPTS: String(input.herdrCloseAttempts ?? 10) },
+    env: {
+      ...process.env,
+      PI_DADDY_LEASE_MARKER: paths.marker,
+      PI_DADDY_LEASE_CLOSE_ATTEMPTS: String(input.herdrCloseAttempts ?? 10),
+      PI_DADDY_LEASE_CLOSE_TIMEOUT_MS: String(input.herdrCloseTimeoutMs ?? 15_000),
+    },
     // Own process group, for two reasons. It lets teardown kill `flock` AND the helper holding the lock
     // file descriptor as one unit even before the helper has reported its pid (R-99), and it stops a
     // stray group signal — a terminal Ctrl-C, a closed window — from releasing a live writer's lock as
@@ -240,12 +245,67 @@ export async function acquireWorkspaceLease(input: {
     async markRetained(reason = "retained") {
       // Deliberately does NOT touch the kernel lock or the helper: the pane may still be live. It only
       // stops the record from looking like a crash.
+      //
+      // **Both guards below exist because the CALLER ledgers whatever this returns (R-152).**
+      //
+      // Already settled: `release()` checked `settled` and this did not, so a completed handover could be
+      // rewritten into `retained:…` and the memoized answer flipped with it — the mirror of the defect R-146
+      // fixed, reachable by the `try { … } finally { await lease.release() }` shape this API invites.
+      if (settled) return settled;
+      // Already dead: the helper is gone and the kernel lock with it, so the fact is `lost`. Recording a
+      // retention here tells an operator a pane may still be live and tells the next owner nothing crashed —
+      // precisely the two facts R-103's outcome union was added to keep apart.
+      if (holder.exitCode !== null || holder.signalCode !== null) return (settled = "lost");
       const current = await readMetadata(paths.metadata);
+      let recorded = false;
       if (current !== "malformed" && current?.token === token) {
-        await atomicMetadata(paths.metadata, {
+        recorded = await atomicMetadata(paths.metadata, {
           ...metadata, state: "released", released_at: new Date().toISOString(), release_reason: `retained:${reason}`,
-        }).catch(() => undefined);
+        }).then(() => true, () => false);
       }
+      /**
+       * **It must, however, let THIS process exit (R-146).** Leaving the helper alone is the decision;
+       * leaving the parent's three pipes and the child handle referenced was an accident, and it meant a
+       * retained lease wedged its own process forever — measured `exit=124` against `exit=0` for the same
+       * sequence ending in `release()`.
+       *
+       * **Which hosts it actually wedged, corrected after review.** `process.exit()` runs `exit` handlers and
+       * ignores pending handles, so this only bites a host that lets the loop drain: pi's **print** mode sets
+       * `process.exitCode` and returns (`dist/main.js`), and a library consumer — an ADR-0034 external
+       * controller calling this package directly — does the same. pi's interactive and rpc modes call
+       * `process.exit()` explicitly (`dist/modes/interactive/interactive-mode.js:3148`), so there the process
+       * still leaves and `pane-reaper`'s `process.once("exit")` sweep still runs. An earlier version of this
+       * comment claimed the sweep was lost generally and cited `src/cli.ts`, which has one subcommand
+       * (`init`) and can neither hold a lease nor open a pane.
+       *
+       * Unref rather than close, because the lock must outlive this call: when the parent does exit, the
+       * helper sees EOF and runs the path it was written for — bounded `herdr tab close` attempts, a marker
+       * file, then release anyway (R-102: an unreleasable lock strands a worktree with no in-product
+       * recovery, which is strictly worse than a recorded failure to close). Narrowed to this path on
+       * purpose: at spawn it would remove the accidental guarantee that a process cannot exit while a lease
+       * is still ACTIVE, which is a different decision and not this fix.
+       */
+      /**
+       * **Terminal (R-146).** `releasing` stops a late `holder.close` being reported as a lost lease, and
+       * `settled` stops a later `release()` running the clean handshake — which it did: measured, it returned
+       * `released`, overwrote `retained:herdr-close-failed` with `completed`, and sent `{release:true}` so the
+       * helper exited `clean` and never attempted the close. The pane retention exists to protect was
+       * abandoned silently, and the ledger asserted a clean handover for a lease kept *because* a pane would
+       * not close. No in-tree caller does this — but `WorkspaceLease` is a public export and
+       * `try { … } finally { await lease.release() }` is the obvious shape for the external controllers this
+       * whole fix is for.
+       */
+      releasing = true;
+      // **Settle only if the record was actually written.** An unwritable lease directory used to leave the
+      // record `state: "active"` while the ledger said `retained`, so the next owner reported a phantom
+      // `recovered: true` — and making retention terminal removed the later `release()` that would still have
+      // written the handover. Unsettled, that repair is available again; the residue is stated in R-152
+      // rather than implied, because nothing here can write a record to a directory that refuses writes.
+      if (recorded) settled = "retained";
+      holder.unref();
+      unrefStream(holder.stdout);
+      unrefStream(holder.stderr);
+      return "retained";
     },
     async readCloseFailure() {
       try {

package/src/workspace.ts

@@ -1,11 +1,14 @@
 import { createHash, randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
 import { once } from "node:events";
-import { mkdir, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
+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 { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { promisify } from "node:util";
 import { GovernanceRefusal, refusal } from "./refusals.ts";
+import { isSafeWorkspaceId, workspaceCapability } from "./capabilities.ts";
 
 const execFileAsync = promisify(execFile);
 export const ENV_WORKSPACE_REGISTRY = "PI_GRANTS_WORKSPACE_REGISTRY";
@@ -16,6 +19,17 @@ export type WorkspaceAccess = "read" | "write";
 export interface WorkspaceRegistryFile {
   version: 1;
   workspaces: Record<string, { path: string }>;
+  /**
+   * Where this was loaded from, carried so a refusal can NAME it.
+   *
+   * `docs/SPEC.md` claimed an unregistered id is refused "with `WORKSPACE_NOT_REGISTERED`, which names the
+   * file", and `catalog.ts` justified exempting the whole namespace from the unknown check on the strength of
+   * that — *"a second, weaker check here can only turn that precise refusal into a misleading one"*. The
+   * refusal named no file: the registry object had no idea where it came from. Carried on the object rather
+   * than passed per call so a caller cannot forget it. Optional because a hand-built literal (tests,
+   * `workspaceEntries` fixtures) has no source.
+   */
+  source?: string;
 }
 
 export interface ValidatedWorkspace {
@@ -25,14 +39,129 @@ export interface ValidatedWorkspace {
   gitCommonDir: string;
 }
 
+/**
+ * How long a registry read may take before it is a refusal rather than a wait.
+ *
+ * **R-79's defect class, and this reader reintroduced it.** That entry records a probe that hung forever on
+ * a FIFO with "no timeout anywhere in the path". This function used a bare `readFile`, which was survivable
+ * while it ran only at spawn time — and stopped being survivable when 0.19.0 began reading the registry from
+ * `buildCatalog` and `registeredWorkspaceIds`, both awaited inside `session_start`. Measured on `52135ca`:
+ * `PI_GRANTS_WORKSPACE_REGISTRY` pointing at a FIFO blocked session start indefinitely, so the session never
+ * reached the `holding [...]` line, the executor probe, or any control after it — and `delegate` awaits the
+ * same promise, so delegation hung too. A blocking special file, an unresponsive network mount or a hostile
+ * `mkfifo` all reach it.
+ *
+ * Two seconds because this is an operator-authored local JSON file: any legitimate one is a single-digit
+ * millisecond read (measured: 8ms), so the bound is three orders of magnitude of headroom and still bounded.
+ */
+const REGISTRY_READ_TIMEOUT_MS = 2_000;
+
+/** A registry is an operator-authored JSON file; anything approaching this is not one. */
+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(() => {});
+  }
   let parsed: unknown;
   try {
-    parsed = JSON.parse(await readFile(path, "utf8"));
+    parsed = JSON.parse(raw);
   } catch (error) {
     throw new GovernanceRefusal(refusal(
       "WORKSPACE_NOT_REGISTERED",
-      `workspace registry ${path} could not be read (${String(error)})`,
+      `workspace registry ${path} is not valid JSON (${String(error)})`,
       { registry_path: path },
     ));
   }
@@ -52,17 +181,61 @@ export async function loadWorkspaceRegistry(path: string): Promise<WorkspaceRegi
         { registry_path: path, workspace_id: id },
       ));
     }
+    // ADR-0035 made a registry id the tail of a CAPABILITY id (`workspace:<id>`), so this file is an input
+    // to the grant grammar and has to obey it — the STRICT one. This shipped with the loose
+    // `isWellFormedCapability` blocklist, and review measured what that let through: an id of `*` minted
+    // `WORKSPACE_WILDCARD` (an operator naming one worktree held routing over all of them), an id with a
+    // space became two capabilities because `ceilingForDefinition` splits on `[\s,]+`, and quote/`$()` ids
+    // reached a generated file whose own instructions say to paste them into `PI_GRANTS_GRANT`. See
+    // `isSafeCapability`, which is now the one grammar for both channels into that file.
+    if (!isSafeWorkspaceId(id)) {
+      throw new GovernanceRefusal(refusal(
+        "GRANT_ID_MALFORMED",
+        `workspace registry id ${JSON.stringify(id)} cannot be used: since ADR-0035 an id becomes the ` +
+          `capability ${JSON.stringify(workspaceCapability(id))}, and an id must match ` +
+          `[A-Za-z0-9][A-Za-z0-9._/-]* — slashes and dots are fine (a worktree named after its branch ` +
+          `works), but not spaces, quotes, commas, wildcards, shell metacharacters or non-ASCII, each of ` +
+          `which either splits into several capabilities or reaches a file you are told to source. ` +
+          `Rename it in ${path}.`,
+        { registry_path: path, workspace_id: id },
+      ));
+    }
+  }
+  return { version: 1, workspaces: structuredClone(file.workspaces), source: path };
+}
+
+/**
+ * The registered workspace ids, for `planInit` to scaffold and `/grants` to list. `[]` when there is no registry or it is broken.
+ *
+ * Fails SOFT, and only because nothing here is an authority: this decides which ids appear as COMMENTS in a
+ * generated file. `loadWorkspaceRegistry` throws a GovernanceRefusal naming the file, and that refusal is
+ * the operator's signal at the point of use, where routing genuinely depends on it. Swallowing it there
+ * would be unsafe; swallowing it here costs a suggestion. Same argument as `buildCatalog`'s.
+ *
+ * Lives here rather than in `init.ts` because it reads the filesystem, and `planInit` — the centrepiece of
+ * 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).
+ */
+export async function registeredWorkspaceIds(registryPath = process.env[ENV_WORKSPACE_REGISTRY]): Promise<string[]> {
+  if (!registryPath) return [];
+  try {
+    return Object.keys((await loadWorkspaceRegistry(registryPath)).workspaces).sort();
+  } catch {
+    return [];
   }
-  return { version: 1, workspaces: structuredClone(file.workspaces) };
 }
 
 export async function resolveWorkspace(registry: WorkspaceRegistryFile, workspaceId: string): Promise<ValidatedWorkspace> {
   const registered = Object.hasOwn(registry.workspaces, workspaceId) ? registry.workspaces[workspaceId] : undefined;
+  const known = Object.keys(registry.workspaces).sort();
   if (!registered) {
     throw new GovernanceRefusal(refusal(
       "WORKSPACE_NOT_REGISTERED",
-      `workspace ${JSON.stringify(workspaceId)} is not present in the operator-owned registry`,
-      { workspace_id: workspaceId },
+      `workspace ${JSON.stringify(workspaceId)} is not present in the operator-owned registry` +
+        (registry.source ? ` ${registry.source}` : "") +
+        (known.length > 0 ? ` — it lists: ${known.join(", ")}` : " — it lists nothing"),
+      { workspace_id: workspaceId, ...(registry.source ? { registry_path: registry.source } : {}) },
     ));
   }
   return validateRegisteredWorkspace({ workspaceId, registeredRoot: registered.path });