pi-daddy 0.28.0 → 0.32.0

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * `pi-daddy` — scaffolding, read-only work inspection and the installed product guide.
+ * `pi-daddy` — scaffolding and ledger maintenance.
  *
  * Thin on purpose: argv in, `discoverSkillPackages` + `planInit` + `applyInit`, report out. Every decision
  * lives in `./init.ts`, `./grant-env.ts` and `./skill-packages.ts` as functions that touch no argv and print
@@ -17,26 +17,37 @@ import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { relative, resolve as resolvePath } from "node:path";
 import { pathToFileURL } from "node:url";
-import { UnsafeGrantError } from "./grant-env.ts";
-import { applyInit, countDeclaring, planInit, type InitPlan } from "./init.ts";
-import { registeredWorkspaceIds } from "./workspace.ts";
-import { discoverSkillPackages, skillPackageRoots, type RefusedSkill, type SkillPackage } from "./skill-packages.ts";
-import { declareWork, loadDeclaredWork } from "./work-command.ts";
-import { listWorkSetups, workPresentation } from "./work-setup.ts";
-import { panelText } from "./daily-panel.ts";
+import { UnsafeGrantError } from "./kernel/grant-env.ts";
+import {
+  applyInit,
+  countDeclaring,
+  planInit,
+  type InitPlan,
+  GITIGNORE_REINCLUDE_LINES,
+  settingsIgnoredByGit,
+} from "./governance/init.ts";
+import { registeredWorkspaceIds } from "./kernel/workspace.ts";
+import {
+  discoverSkillPackages,
+  skillPackageRoots,
+  type RefusedSkill,
+  type SkillPackage,
+} from "./kernel/skill-packages.ts";
+import { adoptLegacyEnvironment, legacyEnvironmentWarning } from "./kernel/env-names.ts";
+import { PI_PROJECT_DIR, PROJECT_FILES, PROJECT_STATE_DIRNAME } from "./kernel/project-paths.ts";
+import { repairLedger } from "./governance/record.ts";
+import { importLegacyLedger } from "./governance/ledger.ts";
+
+/** The reviewable record, as the operator sees it relative to the project (ADR-0076 PR 3c). */
+const SETTINGS_REL = `${PI_PROJECT_DIR}/${PROJECT_STATE_DIRNAME}/${PROJECT_FILES.settings}`;
 
 const USAGE = `pi-daddy — capability governance for pi sub-agents
 
 Usage:
-  pi-daddy init [--force] [--dir <path>]   prepare .pi/grants.env from enabled installed
+  pi-daddy init [--force] [--dir <path>]   prepare ${SETTINGS_REL} from enabled installed
                                            packages that declare skills (package.json "pi": {"skills": …})
-  pi-daddy work add --id <id> --outcome <text> [--dir <path>]
-                                           declare one current obligation for ordinary delegation
-  pi-daddy work list | work show [--dir <path>]
-                                           inspect saved setups or selected outcome (no model calls)
-  In Pi: /grants work                     guided multi-task/model/effort/dependency setup and run
-         /grants learning                 retained review, trust, adoption and later outcomes
-  pi-daddy guide | current               installed product guide / current requirement register
+  pi-daddy ledger repair <path> [--yes]   show the damaged tail of a ledger; --yes truncates it (ADR-0076)
+  pi-daddy ledger import <source> <target> copy a pre-format ledger into the record format; the source is untouched
   pi-daddy --help | --version
 
 init references skills already enabled in Pi at their installed or local paths. Legacy unregistered npm
@@ -45,14 +56,16 @@ stays unspawnable. Capabilities that can change your machine
 (bash, write, edit) are written COMMENTED — uncomment them deliberately. Review the files, then commit.
 
   --force   rewrite legacy unregistered npm SKILL.md copies that already exist. This DISCARDS any \`allowed-tools\` you added.
-            It never rewrites .pi/grants.env — delete that file if you want it regenerated.`;
+            It never rewrites ${SETTINGS_REL} — delete that file if you want it regenerated.`;
 
 export interface ParsedArgs {
-  command: "init" | "work-add" | "work-list" | "work-show" | "guide" | "current" | "help" | "version";
+  command: "init" | "ledger-repair" | "ledger-import" | "help" | "version";
+  importTarget?: string;
+  /** `ledger repair <path>`: the ledger file; `yes` applies, otherwise preview only. */
+  ledgerPath?: string;
+  yes?: boolean;
   dir?: string;
   force: boolean;
-  id?: string;
-  outcome?: string;
   /** Non-empty means refuse: argv said something this program does not understand. */
   errors: string[];
 }
@@ -71,54 +84,45 @@ export function parseArgs(argv: string[]): ParsedArgs {
   if (args.includes("--version") || args.includes("-v")) return { command: "version", force: false, errors: [] };
 
   const [command, ...tail] = args;
-  if(command==="guide"||command==="current")return{command,force:false,errors:tail.length?[`${command} takes no arguments`]:[]};
-  if (command !== "init" && command !== "work") return { command: "help", force: false, errors: [`unknown command "${command}"`] };
-  const work = command === "work";
-  const workVerb = tail[0];
-  const rest = work ? tail.slice(1) : tail;
-  if (work && !["add", "list", "show"].includes(workVerb)) return { command: "work-add", force: false, errors: ["work needs add, list or show; /grants work opens guided setup in Pi"] };
-
+  if (command === "ledger") {
+    // ADR-0076 PR 3d: `ledger repair <path> [--yes]` previews, --yes truncates; `ledger import <source> <target>`.
+    const [verb, target, ...flags] = tail;
+    if (verb === "import") {
+      const [source, dest, ...extra] = tail.slice(1);
+      if (!source || !dest || source.startsWith("-") || dest.startsWith("-") || extra.length)
+        return { command: "help", force: false, errors: ["ledger import needs: <source> <target>"] };
+      return { command: "ledger-import", force: false, errors: [], ledgerPath: source, importTarget: dest };
+    }
+    if (verb !== "repair" || !target || target.startsWith("-"))
+      return {
+        command: "help",
+        force: false,
+        errors: ["ledger needs: repair <path> [--yes] | import <source> <target>"],
+      };
+    const unknown = flags.filter((f) => f !== "--yes");
+    if (unknown.length) return { command: "help", force: false, errors: [`unknown option "${unknown[0]}"`] };
+    return { command: "ledger-repair", force: false, errors: [], ledgerPath: target, yes: flags.includes("--yes") };
+  }
+  if (command !== "init") return { command: "help", force: false, errors: [`unknown command "${command}"`] };
   const errors: string[] = [];
-  let dir: string | undefined;
   let force = false;
-  let id: string | undefined, outcome: string | undefined;
-  for (let i = 0; i < rest.length; i += 1) {
-    const arg = rest[i];
-    if (arg === "--force" && !work) {
+  let dir: string | undefined;
+  for (let i = 0; i < tail.length; i += 1) {
+    const arg = tail[i];
+    if (arg === "--force") {
       force = true;
-    } else if (arg === "--id" && work && workVerb === "add") {
-      const value = rest[i + 1];
-      if (value === undefined || value.startsWith("-")) errors.push("--id needs a value");
-      else { id = value; i += 1; }
-    } else if (arg === "--outcome" && work && workVerb === "add") {
-      const value = rest[i + 1];
-      if (value === undefined || value.startsWith("-")) errors.push("--outcome needs text");
-      else { outcome = value; i += 1; }
     } else if (arg === "--dir") {
-      const value = rest[i + 1];
-      // A flag is not a path. Without this, `--dir --force` consumed the flag as the directory AND left
-      // force on, then reported "nothing to scaffold" and exited 0 — the outcome this CLI's own comments
-      // call the worst available failure for a scaffolding command.
+      // A flag is never a path: `init --dir --force` used to scaffold into a directory named `--force`.
+      const value = tail[i + 1];
       if (value === undefined || value.startsWith("-")) errors.push("--dir needs a path");
       else {
         dir = value;
         i += 1;
       }
     } else {
-      // Was `rest.filter((a, i) => … && i !== dirIndex + 1)`, and with `--dir` absent `dirIndex` is -1, so
-      // the exemption became `i !== 0` and the FIRST argument was never checked. `init --Force` therefore
-      // parsed as a valid no-op run: it kept every file and exited 0, which is indistinguishable from a
-      // deliberate second run. Found by a reviewer, not by a test, because this file had none.
       errors.push(`unknown option ${arg}`);
     }
   }
-
-  if (work && workVerb !== "add") return { command: workVerb === "list" ? "work-list" : "work-show", force: false, errors, ...(dir ? { dir } : {}) };
-  if (work) {
-    if (!id && !errors.some(error => error.startsWith("--id"))) errors.push("--id needs a value");
-    if (!outcome && !errors.some(error => error.startsWith("--outcome"))) errors.push("--outcome needs text");
-    return { command: "work-add", force: false, errors, ...(id ? { id } : {}), ...(outcome ? { outcome } : {}), ...(dir ? { dir } : {}) };
-  }
   return { command: "init", dir, force, errors };
 }
 
@@ -133,7 +137,9 @@ async function init(cwd: string, force: boolean): Promise<number> {
     console.log(
       `pi-daddy init: no enabled configured skills or unregistered npm package declares skills (a package.json "pi": {"skills": [...]} ` +
         `field). Nothing to scaffold.\n\nLooked in:\n` +
-        skillPackageRoots(cwd).map((r) => `  ${r}\n`).join("") +
+        skillPackageRoots(cwd)
+          .map((r) => `  ${r}\n`)
+          .join("") +
         `\n  pi install npm:principal-pi-skills    # seven skills, and registers it with pi\n` +
         `  npm install principal-pi-skills      # or pin it in this project instead`,
     );
@@ -158,7 +164,9 @@ async function init(cwd: string, force: boolean): Promise<number> {
     console.log(
       `found ${pkg.name}@${pkg.version} — ${pkg.skills.length} skill(s), ` +
         `${declaring} declaring allowed-tools` +
-        (pkg.unreadable.length > 0 ? `, ${pkg.unreadable.length} declared but unreadable (${pkg.unreadable.join(", ")})` : "") +
+        (pkg.unreadable.length > 0
+          ? `, ${pkg.unreadable.length} declared but unreadable (${pkg.unreadable.join(", ")})`
+          : "") +
         // Counted on this line as well as named below it: a reader who stops at the first line must not
         // read "0 skill(s)" as "this package ships none".
         (pkg.refused.length > 0 ? `, ${pkg.refused.length} REFUSED` : ""),
@@ -171,21 +179,22 @@ async function init(cwd: string, force: boolean): Promise<number> {
   // `--force` is destructive and says so at the moment it acts, not only in `--help` — which is the one
   // place the operator running the command is not reading.
   if (force) {
-    const existing = plan.skills.filter(s => !s.referenced).length;
+    const existing = plan.skills.filter((s) => !s.referenced).length;
     console.log(
       `\n--force: rewriting up to ${existing} SKILL.md cop${existing === 1 ? "y" : "ies"} from the installed\n` +
-        `packages. Any \`allowed-tools\` you wrote in them is DISCARDED. .pi/grants.env is never rewritten.`,
+        `packages. Any \`allowed-tools\` you wrote in them is DISCARDED. settings.json is never rewritten.`,
     );
   }
 
   const outcome = await applyInit(plan, { force });
   const short = (path: string) => relative(cwd, path) || path;
-  for (const skill of plan.skills.filter(s => s.referenced)) console.log(`using ${short(skill.sourcePath)} (enabled in Pi; no copy)`);
+  for (const skill of plan.skills.filter((s) => s.referenced))
+    console.log(`using ${short(skill.sourcePath)} (enabled in Pi; no copy)`);
   for (const path of outcome.written) console.log(`wrote ${short(path)}`);
   for (const path of outcome.kept) console.log(`kept  ${short(path)} (already present — left exactly as it is)`);
   for (const failure of outcome.failed) console.error(`FAILED ${short(failure.path)}: ${failure.error}`);
 
-  report(plan);
+  await report(plan);
   // A refusal is a non-zero exit so CI can see it: a package that tried to write a capability into the
   // grant through a name or a declaration is a fact a build should be able to fail on.
   return outcome.failed.length > 0 || refused.length > 0 ? 1 : 0;
@@ -210,7 +219,7 @@ function reportRefusal(pkg: SkillPackage, refusal: RefusedSkill): string {
       return (
         `${head} declares ${refusal.detail.join(", ")} — that is root authority, not a description of what ` +
         `the skill needs, and a package may not hand it to itself. ${refusal.detail.includes("tool:*") ? "tool:* satisfies EVERY capability" : "agent:* authorises every definition on disk"}. ` +
-        `Add it by hand to PI_GRANTS_GRANT if you genuinely mean it.`
+        `Add it by hand to PI_DADDY_GRANT if you genuinely mean it.`
       );
     case "not-utf8":
       return `${head} is not valid UTF-8, so it cannot be copied verbatim — pi-daddy will not rewrite its bytes.`;
@@ -218,7 +227,7 @@ function reportRefusal(pkg: SkillPackage, refusal: RefusedSkill): string {
 }
 
 /** What the operator has to do next, and what pi-daddy deliberately did not do for them. */
-function report(plan: InitPlan): void {
+async function report(plan: InitPlan): Promise<void> {
   const undeclared = plan.skills.filter((s) => s.withheld === "undeclared");
   const patterned = plan.skills.filter((s) => s.withheld === "pattern");
 
@@ -231,7 +240,7 @@ function report(plan: InitPlan): void {
         `${undeclared.map((s) => s.name).join(", ")}.\n` +
         `Each copy carries a commented \`allowed-tools:\` line. pi-daddy does not choose ceilings — that\n` +
         `decision is what you review and commit, so it is yours to write. Then add each \`agent:<name>\`\n` +
-        `to PI_GRANTS_GRANT in .pi/grants.env.`,
+        `to the grant in ${SETTINGS_REL}.`,
     );
   }
 
@@ -239,7 +248,7 @@ function report(plan: InitPlan): void {
     const needed = [...plan.withheldCapabilities].map(([c, who]) => `${c} (${who.join(", ")})`).join(", ");
     console.log(
       `\nWITHHELD BY DEFAULT: ${needed}.\n` +
-        `These can change your machine, so they are written COMMENTED in .pi/grants.env along with the\n` +
+        `These can change your machine, so they are listed under \`withheld\` in settings.json along with the\n` +
         `\`agent:\` ids of the definitions that need them. Uncomment deliberately — that is the decision.`,
     );
   }
@@ -256,8 +265,8 @@ function report(plan: InitPlan): void {
     const blocked = plan.skills.filter((s) => s.withheld === "needs-withheld").map((s) => s.name);
     console.log(
       `\nROUTABLE WORKSPACES: ${plan.routableWorkspaces.join(", ")}.\n` +
-        `Routing a child to one needs its id in PI_GRANTS_GRANT (ADR-0035); without it the delegation is\n` +
-        `refused WORKSPACE_NOT_AUTHORIZED. They are listed COMMENTED in .pi/grants.env and never granted for\n` +
+        `Routing a child to one needs its id in PI_DADDY_GRANT (ADR-0035); without it the delegation is\n` +
+        `refused WORKSPACE_NOT_AUTHORIZED. They are listed under \`routableWorkspaces\` in settings.json and never granted for\n` +
         `you — which worktree a child starts in is not something a package can declare.` +
         (blocked.length > 0
           ? `\nUntil you grant one, these cannot be spawned: ${blocked.join(", ")} — add the capability, then\n` +
@@ -268,12 +277,17 @@ function report(plan: InitPlan): void {
 
   console.log(
     `\nLive grant (${plan.grant.length} capabilities): ${plan.grant.join(", ")}\n\n` +
-      `  $EDITOR .pi/grants.env         # review it, then commit it\n` +
-      `  source .pi/grants.env && pi    # /grants lists every definition and its verdict`,
+      ((await settingsIgnoredByGit(plan.settingsPath)) === true
+        ? `  NOTE: git ignores ${SETTINGS_REL} (root .gitignore covers ${PI_PROJECT_DIR}/); add ${GITIGNORE_REINCLUDE_LINES.join(" and ")} to commit it\n`
+        : "") +
+      `  $EDITOR ${SETTINGS_REL}   # review it, then commit it\n` +
+      `  pi                                   # /grants lists every definition and its verdict`,
   );
 }
 
 export async function main(argv: string[]): Promise<number> {
+  const adoptedLegacy = adoptLegacyEnvironment(process.env);
+  if (adoptedLegacy.length > 0) console.error(legacyEnvironmentWarning(adoptedLegacy));
   const parsed = parseArgs(argv);
 
   if (parsed.command === "version") {
@@ -293,31 +307,64 @@ export async function main(argv: string[]): Promise<number> {
     console.log(USAGE);
     return 0;
   }
-  if(parsed.command==="guide"||parsed.command==="current"){
-    console.log(await readFile(new URL(parsed.command==="guide"?"../PRODUCT-GUIDE.md":"../REQUIREMENTS.md",import.meta.url),"utf8"));return 0;
-  }
-  if (parsed.command === "work-list" || parsed.command === "work-show") {
-    const cwd=resolvePath(parsed.dir??process.cwd());
-    if(parsed.command==="work-list") {const setups=await listWorkSetups(cwd);console.log(setups.map((s,i)=>`${i+1}. ${panelText(s.setup.outcome)} — ${s.setup.tasks.length} tasks; up to ${s.setup.maxParallel} parallel`).join("\n")||"No saved multi-task setups. In Pi: /grants work");}
-    else {const state=await loadDeclaredWork(resolvePath(cwd,".pi/work-current.json")),view=state?await workPresentation(state):null;console.log(view?[panelText(view.outcome),...view.obligations.map(o=>`- ${panelText(o.outcome)}`)].join("\n"):state?"Selected legacy work; outcome text unavailable":"No work selected. In Pi: /grants work");}
-    return 0;
+  if (parsed.command === "ledger-import") {
+    const source = resolvePath(process.cwd(), parsed.ledgerPath!),
+      target = resolvePath(process.cwd(), parsed.importTarget!);
+    const result = await importLegacyLedger(source, target);
+    if (result.skipped === "source-missing") {
+      console.error(`pi-daddy: no such file: ${source}`);
+      return 1;
+    }
+    if (result.skipped === "target-exists") {
+      console.error(`pi-daddy: ${target} already exists; import writes only into a new file`);
+      return 1;
+    }
+    console.log(
+      `pi-daddy: imported ${result.imported} record(s) from ${source} into ${target}; the source is untouched` +
+        (result.stoppedAt !== null ? `. Stopped at unparsable source line ${result.stoppedAt}.` : "."),
+    );
+    return result.stoppedAt === null ? 0 : 1;
   }
-  if (parsed.command === "work-add") {
-    const declared = await declareWork({
-      cwd: resolvePath(parsed.dir ?? process.cwd()),
-      id: parsed.id!,
-      outcome: parsed.outcome!,
-    });
+  if (parsed.command === "ledger-repair") {
+    const path = resolvePath(process.cwd(), parsed.ledgerPath!);
+    const preview = await repairLedger(path, { apply: false });
+    if (preview.missing) {
+      console.error(`pi-daddy: no such file: ${path}`);
+      return 1;
+    }
+    if (preview.preFormat) {
+      console.error(
+        `pi-daddy: ${path} predates the record format; repairing it would delete it whole. ` +
+          `Run \`pi-daddy ledger import ${path} <target>\` instead. Nothing was changed.`,
+      );
+      return 1;
+    }
+    if (preview.dropped.length === 0) {
+      console.log(`pi-daddy: ${path} is intact (${preview.keptLines} records); nothing to repair`);
+      return 0;
+    }
+    // Line numbers and sizes only: a torn line can contain exactly the task text this program never prints.
     console.log(
-      `pi-daddy work: declared ${declared.id}\n` +
-      `  ledger    ${declared.ledgerPath}\n` +
-      `  selection ${declared.statePath}\n\n` +
-      `Ordinary governed delegations from this project will record attempts after the Pi extension loads it.\n` +
-      `Run /reload in an existing Pi session, then /grants dashboard. Runtime success is not acceptance.`,
+      `pi-daddy: ${path} is damaged after record ${preview.keptLines}; ${preview.dropped.length} line(s) would be dropped:\n` +
+        preview.dropped
+          .map((line, i) => `  line ${preview.keptLines + i + 1}: ${Buffer.byteLength(line, "utf8")} bytes`)
+          .join("\n"),
     );
+    if (preview.droppedParseable > 0)
+      console.log(
+        `pi-daddy: WARNING — ${preview.droppedParseable} of those lines still parse as records. This looks like damage in the ` +
+          `middle of the file, not a torn tail; repairing drops every record after it. Inspect before you truncate.`,
+      );
+    if (!parsed.yes) {
+      console.log(
+        "pi-daddy: preview only. Re-run with --yes to truncate the damaged tail; intact records are never rewritten.",
+      );
+      return 1;
+    }
+    const result = await repairLedger(path, { apply: true });
+    console.log(`pi-daddy: dropped ${result.dropped.length} line(s); ${result.keptLines} records remain`);
     return 0;
   }
-
   // ABSOLUTE, always. `readSkill` compares a resolved entry against the package directory, and a relative
   // `--dir` made that comparison false for every entry: every declared skill of every package was reported
   // "declared but unreadable", nothing was copied, a degenerate grants.env was written anyway, and the exit

package/src/executors/activity-session.ts

@@ -0,0 +1,54 @@
+/**
+ * The activity session: a pi session file every governed child writes to, so its parent can tell working from hung.
+ *
+ * PR 3e (ADR-0038 note). A `pi --print` child gives its parent nothing on stdout until it exits, so a wall clock
+ * cannot tell a build from a hang. pi's SessionManager appends one line to its session file for every message and
+ * tool result as they happen (read from pi's `session-manager.js`: `appendFileSync` per entry), so the file's size
+ * and mtime are a progress signal that costs the child nothing and needs no output-format change. When the plan
+ * already carries `--session` (native-session retention), that file is the probe; otherwise a private temporary
+ * file is allocated for the run and removed afterwards.
+ */
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface ActivitySession {
+  /** The child argv, with `--session <file>` in place of `--no-session` when a file was allocated here. */
+  readonly args: string[];
+  /** The session file being watched. */
+  readonly path: string;
+  /** A marker that changes whenever pi appended to the file; `undefined` until the file exists. */
+  probe(): Promise<string | undefined>;
+  /** Remove the temporary file, if this run allocated one. Never removes a retention target. */
+  dispose(): Promise<void>;
+}
+
+export async function activitySessionFor(planArgs: string[], executionId: string): Promise<ActivitySession> {
+  const flag = planArgs.indexOf("--session");
+  const probeFor = (path: string) => async () => {
+    try {
+      const s = await stat(path);
+      return `${s.size}:${s.mtimeMs}`;
+    } catch {
+      return undefined;
+    }
+  };
+  if (flag >= 0 && planArgs[flag + 1]) {
+    const path = planArgs[flag + 1];
+    return { args: planArgs, path, probe: probeFor(path), dispose: async () => undefined };
+  }
+  // Private to this uid (mkdtemp is 0o700) and named by the execution so a leaked directory is attributable.
+  const directory = await mkdtemp(join(tmpdir(), `pi-daddy-${executionId.replace(/[^a-zA-Z0-9_-]/g, "_")}-`));
+  const path = join(directory, "session.jsonl");
+  const noSession = planArgs.indexOf("--no-session");
+  const args =
+    noSession >= 0
+      ? [...planArgs.slice(0, noSession), "--session", path, ...planArgs.slice(noSession + 1)]
+      : [...planArgs.slice(0, -1), "--session", path, planArgs[planArgs.length - 1]];
+  return {
+    args,
+    path,
+    probe: probeFor(path),
+    dispose: () => rm(directory, { recursive: true, force: true }).catch(() => undefined),
+  };
+}

package/src/executors/executor.ts

@@ -0,0 +1,123 @@
+/**
+ * Which executor runs a governed child — ADR-0031.
+ *
+ * `PI_DADDY_HERDR` is three-state, and **absent means probe**. That reverses ADR-0016 point 6's opt-in, and
+ * the reversal is narrower than it sounds: nothing is detected from `herdr` being on `PATH` (option C, rejected
+ * by name), only from a server that *answered*. The grant, the depth bound, the gate and `--tools` enforcement
+ * are identical either way — `planSpawn` produces one plan and both executors enforce it.
+ *
+ * **Pure on purpose.** The probe is I/O and lives in `herdr-cli.ts`; the DECISION is a table, and a table that
+ * fits on one screen is the only reason a reversal like this is reviewable at all.
+ *
+ * The disclosure string is part of the return value rather than composed at the call site, because ADR-0031's
+ * defence against "this relocates silently" is that every outcome says what it chose AND what to set instead.
+ * Two call sites composing that separately is how one of them comes to omit it (R-28).
+ */
+
+import type { HerdrProbe } from "./herdr-cli.ts";
+
+export { EXECUTOR_KINDS, type ExecutorKind } from "../kernel/delegate-types.ts";
+import type { ExecutorKind } from "../kernel/delegate-types.ts";
+import { ENV_HERDR } from "../kernel/env-names.ts";
+export { ENV_HERDR } from "../kernel/env-names.ts";
+
+export interface ExecutorChoice {
+  kind: ExecutorKind;
+  /** The operator named it: `PI_DADDY_HERDR` was exactly `0` or `1`. */
+  forced: boolean;
+  /** Whether a probe was needed at all — false only for `0`. */
+  probed: boolean;
+  /**
+   * Set ONLY when herdr was demanded and is unreachable. Every delegation must refuse with this.
+   *
+   * Note that `kind` stays `"herdr"` in that case, deliberately: nothing downstream may mistake a refusing
+   * session for a working process-executor one.
+   */
+  refusal?: string;
+  /** One line for the session banner and `/grants`. Always present. */
+  disclosure: string;
+}
+
+/** `0` is the one value that needs no probe: the operator ruled herdr out, so asking is pure cost. */
+export function needsProbe(raw: string | undefined): boolean {
+  return raw === undefined || raw === "1";
+}
+
+export function chooseExecutor(raw: string | undefined, probe: HerdrProbe | null): ExecutorChoice {
+  if (raw === "0") {
+    return {
+      kind: "process",
+      forced: true,
+      probed: false,
+      disclosure: "captured subprocess (PI_DADDY_HERDR=0) — children have no terminal",
+    };
+  }
+
+  if (raw === "1") {
+    if (probe?.ok) {
+      return { kind: "herdr", forced: true, probed: true, disclosure: "herdr panes (PI_DADDY_HERDR=1)" };
+    }
+    // Refusal, not fallback — the operator's decision of 2026-08-17, against the alternative of falling back
+    // loudly. A fallback nobody reads is R-25's shape; refusing keeps the ledger unable to name a child that
+    // ran somewhere nobody chose. A `null` probe lands here too: if the probe failed so badly it produced no
+    // result, herdr was still demanded, and failing closed means refusing.
+    const why = probe?.error ?? "the herdr probe did not succeed";
+    return {
+      kind: "herdr",
+      forced: true,
+      probed: true,
+      refusal:
+        `PI_DADDY_HERDR=1 demands the herdr executor and herdr is not answering (${why}). ` +
+        `Delegation is refused rather than quietly relocated to a captured subprocess, so this session's ` +
+        `ledger can never contain a child that ran somewhere nobody chose. Start herdr, or unset ` +
+        `PI_DADDY_HERDR to let this session probe, or set PI_DADDY_HERDR=0 to choose subprocesses.`,
+      disclosure: `herdr panes DEMANDED but unreachable (${why}) — every delegation will refuse`,
+    };
+  }
+
+  if (raw !== undefined) {
+    // Rule 8: fail closed and be loud. An unrecognised value must not relocate a run, and must not break
+    // delegation either — the operator meant *something*, and the dependency-free executor is the safe read.
+    // The empty string lands here rather than with `undefined`, which keeps absent-versus-empty
+    // distinguishable exactly as `PI_DADDY_GATED` does.
+    return {
+      kind: "process",
+      forced: false,
+      probed: probe !== null,
+      disclosure:
+        `captured subprocess — PI_DADDY_HERDR is set to an unrecognised value and was ignored. ` +
+        `Use 1 (demand herdr panes), 0 (demand subprocesses), or unset it to probe.`,
+    };
+  }
+
+  if (probe?.ok) {
+    return { kind: "herdr", forced: false, probed: true, disclosure: "herdr panes (probed — herdr is answering)" };
+  }
+  if (probe === null) {
+    // **The pre-probe seed, and it must not claim a probe happened.** `createGrantsSession` builds a choice
+    // synchronously with `probe: null` because S-5 forces the factory to run before any hook; `resolveExecutor`
+    // replaces it during `session_start`. This branch previously fell through to the one below and reported
+    // `probed: true` with the word "(probed)" in its disclosure — a fabricated observation, indistinguishable
+    // from a real negative probe.
+    //
+    // Unreachable in practice today (pi awaits the `session_start` emit before the first prompt, verified by a
+    // reviewer against real pi), which is exactly why it is worth making honest rather than leaving to be
+    // discovered: if a throw ever strands a session on this reading, the disclosure should say so.
+    return {
+      kind: "process",
+      forced: false,
+      probed: false,
+      disclosure: "not yet probed — settling at session start",
+    };
+  }
+  return {
+    kind: "process",
+    forced: false,
+    probed: true,
+    // Names the remedy on the same line as the state. The gap that produced ADR-0031 was not that the
+    // operator could not see which executor ran — it was that seeing it would not have told them what to do.
+    disclosure:
+      `captured subprocess (probed — no herdr answering${probe?.error ? `: ${probe.error}` : ""}). ` +
+      `Set PI_DADDY_HERDR=1 to demand panes.`,
+  };
+}