@sleepy_panda_srl/portulan 0.3.0 → 0.4.0

package/cli/doctor.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 // `doctor` — the Workspace Definition validator.
 //
-//   node cli/doctor.mjs [--static] [--pack-root <dir>|auto]... [--repo-root <dir>]... <workspace-dir>...
+//   node cli/doctor.mjs [--agent] [--static | --count-tokens <model>] [--pack-root <dir>|auto]... [--repo-root <dir>]... <workspace-dir>...
 //
 // Exit 0 every workspace validates · 1 at least one does not · 2 could not run.
 
+import { readContextCap, contextCaps, contextCapLines } from "./ritual-contexts.mjs";
+import { readStopPolicy } from "./stop-policy.mjs";
 import fs from "node:fs";
 import { execFileSync } from "node:child_process";
 import path from "node:path";
@@ -20,15 +22,21 @@ import {
     packDifferences,
     shadowedCopy,
     personaDeclarations,
+    bindingDirectory,
+    readOwnedText,
 } from "./compile.mjs";
 import { isInside, recordType } from "./index.mjs";
-import { parseFrontmatter, AGENT_DIR } from "./plugin-lint.mjs";
+import { parseFrontmatter } from "./frontmatter.mjs";
 import { resolveGovernor, AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
 import { composedId } from "./recipe-set.mjs";
-import { alwaysLine } from "./context.mjs";
+import { alwaysLine, alwaysTier, declaredContext, treeOf, ESTIMATED_BYTES_PER_TOKEN, countAlways, countLine, countRoot, ContextError, handoffReport } from "./context.mjs";
+import { handoffPolicy } from "./handoff-policy.mjs";
+import { movableSections } from "./instructions.mjs";
 import { formLine } from "./form.mjs";
 import { sessionsLine } from "./sessions.mjs";
-import { hostPaths, ledger, print, readSpend, worktrees, linesChanged } from "./ledger.mjs";
+import { cacheRiskLines } from "./cache-risk.mjs";
+import { spendAnalysis } from "./spend-analysis.mjs";
+import { hostPaths, ledger, print, readSpend, restartSaving, worktrees, linesChanged, GENERAL_READ, HORIZON } from "./ledger.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_SCHEMA = path.resolve(HERE, "..", "spec", "workspace.schema.json");
@@ -476,7 +484,7 @@ export function validateContributions(packDir, contributes, { fail, report, pack
         }
         let text;
         try {
-            text = fs.readFileSync(contained.real, "utf8");
+            text = readOwnedText(contained.real, packDir);
         } catch (cause) {
             fail("packs", `\`${pack}\`'s persona \`${rel}\` could not be read — ${cause.code ?? cause.message}. Only a missing file means absent`);
             continue;
@@ -783,7 +791,7 @@ export async function inspect(workspaceDir, options = {}) {
     const manifestPath = path.join(dir, "workspace.json");
     let workspace;
     try {
-        workspace = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        workspace = JSON.parse(readOwnedText(manifestPath, dir));
     } catch (cause) {
         // A verdict about the workspace, not an environment failure: exit 1, not 2.
         fail("schema", `no readable manifest at ${path.relative(process.cwd(), manifestPath)} — ${cause.message}`);
@@ -830,6 +838,9 @@ export async function inspect(workspaceDir, options = {}) {
             ["sessions", 11, workspace.sessions],
             ["spend", 12, workspace.spend],
             ["spend.restart", 13, workspace.spend?.restart],
+            ["spend.resume", 16, workspace.spend?.resume],
+            ["handoffs.series", 15, workspace.handoffs?.series],
+            ["handoffs.index.budget", 15, workspace.handoffs?.index?.budget],
         ]) {
             if (major === 2 && minor < since && value !== undefined) {
                 fail(
@@ -975,6 +986,8 @@ export async function inspect(workspaceDir, options = {}) {
     });
 
     // ---------------------------------------------------------------- cross-field
+    try { readStopPolicy(workspace); } catch (error) { fail("cross", error.message); }
+
     // Own recipes only: a composed recipe may never be the workspace's `verify.default`.
     const ids = (workspace.verify?.recipes ?? []).map((r) => r.id);
     if (!ids.includes(workspace.verify?.default)) {
@@ -1128,6 +1141,7 @@ export async function inspect(workspaceDir, options = {}) {
     }
 
     const composedPersonas = [];
+    const contextContributions = [];
 
     let resolvedPackRoots = null;
     let packsUnresolved = 0;
@@ -1149,7 +1163,13 @@ export async function inspect(workspaceDir, options = {}) {
         const claimed = roots.filter((root) => originOf.get(root) !== "discovered");
         report("packs", `resolution root ${plan.source} — ${plan.why}`);
         for (const name of workspace.packs) {
-            const found = resolvePack(name, roots);
+            let found;
+            try { found = resolvePack(name, roots); }
+            catch (cause) {
+                fail("packs", `\`${name}\` could not be resolved — ${cause.message}`);
+                packsUnresolved += 1;
+                continue;
+            }
             if (!found.dir) {
                 if (claimed.length === 0) {
                     stats.unverifiable += 1;
@@ -1165,7 +1185,7 @@ export async function inspect(workspaceDir, options = {}) {
             }
             let manifest;
             try {
-                manifest = JSON.parse(fs.readFileSync(found.manifest, "utf8"));
+                manifest = JSON.parse(readOwnedText(found.manifest, found.dir));
             } catch (cause) {
                 fail("packs", `\`${name}\` resolves to ${path.relative(dir, found.manifest)} but its manifest is unreadable — ${cause.message}`);
                 continue;
@@ -1192,6 +1212,10 @@ export async function inspect(workspaceDir, options = {}) {
                 }
                 continue;
             }
+            let contextCap;
+            try { contextCap = readContextCap(manifest, name); }
+            catch (e) { fail("packs", e.message); continue; }
+            contextContributions.push({ pack: name, contextCap });
             stats.packs += 1;
             const c = manifest.contributes ?? {};
 
@@ -1224,11 +1248,15 @@ export async function inspect(workspaceDir, options = {}) {
 
             // First match wins and discovered roots come first, so an installed copy can shadow the tree's.
             {
-                const shadowed = shadowedCopy(name, origin, roots, (r) => originOf.get(r)) ?? { dir: null };
+                let shadowed = { dir: null };
+                try { shadowed = shadowedCopy(name, origin, roots, (r) => originOf.get(r)) ?? shadowed; }
+                catch (cause) {
+                    report("packs", `\`${name}\` is SHADOWED — the other copy could not be read (${cause.message}), so what differs could not be compared`);
+                }
                 if (shadowed.dir) {
                     let other = null;
                     try {
-                        other = JSON.parse(fs.readFileSync(shadowed.manifest, "utf8"));
+                        other = JSON.parse(readOwnedText(shadowed.manifest, shadowed.dir));
                     } catch (cause) {
                         report(
                             "packs",
@@ -1249,6 +1277,11 @@ export async function inspect(workspaceDir, options = {}) {
         }
     }
 
+    try {
+        const caps = contextCaps(contextContributions, Array(packsUnresolved).fill(null));
+        for (const line of contextCapLines(caps)) report("contexts", line);
+    } catch (e) { fail("contexts", e.message); }
+
     if (workspace.librarian && !workspace.slots?.memory) {
         fail(
             "cross",
@@ -1280,6 +1313,8 @@ export async function inspect(workspaceDir, options = {}) {
     }
 
     const alwaysTokens = workspace.context?.always?.budget?.tokens;
+    try { handoffPolicy(workspace); }
+    catch (error) { fail("schema", error.message); }
     if (alwaysTokens !== undefined && !positive(alwaysTokens)) {
         fail(
             "schema",
@@ -1355,6 +1390,10 @@ export async function inspect(workspaceDir, options = {}) {
         }
     }
     const horizonRequests = workspace.spend?.horizon?.requests;
+    const resumeTokens = workspace.spend?.resume?.tokens;
+    if (resumeTokens !== undefined && !(Number.isFinite(resumeTokens) && resumeTokens >= 0)) {
+        fail("schema", "spend.resume.tokens must be a finite nonnegative number of input-equivalent tokens; absent means unknown, not zero");
+    }
     if (horizonRequests !== undefined && !positive(horizonRequests)) {
         fail(
             "schema",
@@ -1454,21 +1493,32 @@ export async function inspect(workspaceDir, options = {}) {
                     `so there is no repository to look in. Unverifiable, not unbound`,
             );
         }
-        // Both sides realpathed: a tree under a link (macOS `/var`) would otherwise refuse ordinary bindings.
+        // Compare canonical paths for aliased trees.
         let realTree = treeRoot;
         try {
             if (treeRoot) realTree = fs.realpathSync(treeRoot);
         } catch {
-            // Already reported by the claims checks; the declared path keeps the containment test running.
+            // Path validation reports the tree failure.
+        }
+        let bindingDir = null;
+        if (treeRoot) {
+            try { bindingDir = bindingDirectory(treeRoot); }
+            catch (error) {
+                (error.unread ? report : fail)("bindings", `host binding directory could not be determined: ${error.message}`);
+                stats.unverifiable += composedPersonas.length;
+            }
         }
-        for (const persona of treeRoot ? composedPersonas : []) {
-            const rel = path.join(AGENT_DIR, `${persona.key}.md`);
+        for (const persona of treeRoot && bindingDir ? composedPersonas : []) {
+            if (!SLUG_PATTERN.test(persona.key)) {
+                fail("bindings", `\`${persona.pack}\`'s \`${persona.rel}\` keys its host binding to \`${persona.key}\`, which is not a single host name; an escaping name leaves this workspace's tree`);
+                continue;
+            }
+            const rel = path.join(bindingDir, `${persona.key}.md`);
             const where = `\`${persona.pack}\`'s \`${persona.rel}\``;
             const keyed = persona.keyedBy === "declaration" ? "" : " (keyed by filename — the persona declares no `name`)";
             const file = path.join(treeRoot, rel);
 
-            // The key is a pack's free text, so it is contained before it is opened: lexically here, since the
-            // realpath test below is skipped where nothing exists.
+            // Pack keys must stay inside the tree before any read.
             if (!isInside(treeRoot, path.resolve(treeRoot, rel))) {
                 fail(
                     "bindings",
@@ -1478,6 +1528,14 @@ export async function inspect(workspaceDir, options = {}) {
                 continue;
             }
 
+            let stat = null;
+            try { stat = fs.lstatSync(file); }
+            catch (cause) {
+                if (cause.code !== "ENOENT") {
+                    report("bindings", `${where}'s binding at \`${rel}\` could not be examined — ${cause.code ?? cause.message}. Unread, not absent`);
+                    continue;
+                }
+            }
             let real = null;
             try {
                 real = fs.realpathSync(file);
@@ -1486,7 +1544,7 @@ export async function inspect(workspaceDir, options = {}) {
                     report("bindings", `${where}'s binding at \`${rel}\` could not be resolved — ${cause.code ?? cause.message}. Unread, not absent`);
                     continue;
                 }
-                // ENOENT falls through to the read below, which reports the persona unbound.
+                // Missing files remain unbound.
             }
             if (real !== null && !isInside(realTree, real)) {
                 fail(
@@ -1497,15 +1555,19 @@ export async function inspect(workspaceDir, options = {}) {
                 );
                 continue;
             }
+            if (stat !== null && !stat.isFile()) {
+                fail("bindings", `${where}'s binding at \`${rel}\` is not a regular file; it was not read`);
+                continue;
+            }
             let text;
             try {
-                text = fs.readFileSync(file, "utf8");
+                text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(file));
             } catch (cause) {
                 if (cause.code === "ENOENT") {
                     report(
                         "bindings",
                         `${where} has no host binding at \`${rel}\`${keyed} — reported, not failed: a persona without one is unbound rather than wrong, ` +
-                            "and this is where a Claude Code plugin's agents load from — a repository that is not a plugin loads its agents from `.claude/agents/`",
+                            `the selected ${bindingDir === "agents" ? "plugin" : "project"} location is where this tree's Claude Code agents load`,
                     );
                 } else {
                     report("bindings", `${where}'s binding at \`${rel}\` could not be read — ${cause.code ?? cause.message}. Unread, not absent`);
@@ -1538,7 +1600,7 @@ export async function inspect(workspaceDir, options = {}) {
                 );
                 continue;
             }
-            // Declared, not compared: a binding may grant less, or other, than its persona describes.
+            // Tool grants are declared, not compared to charter prose.
             report("bindings", `${where} is bound by \`${rel}\`${keyed} — ${BINDING_OK}`);
         }
     }
@@ -1768,7 +1830,7 @@ export async function inspect(workspaceDir, options = {}) {
                     : "";
                 report(
                     "enforcement",
-                    `this workspace composes ${fragments} gate rule(s) from the packs that resolved and declares no \`gates\` policy for them to join, so nothing here compiles them — \`compile\` exits 2 on this shape rather than emitting a partial policy${incomplete}`,
+                    `this workspace composes ${fragments} gate rule(s) from the packs that resolved and declares no \`gates\` policy for them to join, so nothing here compiles these gates; restart advice, session settings, guidance, personas or a ritual cap can still compile independently${incomplete}`,
                 );
             }
         } catch (cause) {
@@ -1873,7 +1935,14 @@ export async function inspect(workspaceDir, options = {}) {
     );
 
     const always = alwaysLine(dir, workspace);
-    (always.verdict === "over" || always.verdict === "unjudged" ? fail : report)("context", always.line);
+    const agentsAlways = alwaysLine(dir, workspace, { host: "agents-md" });
+    for (const measured of [always, agentsAlways]) {
+        (measured.verdict === "over" || measured.verdict === "unjudged" ? fail : report)("context", measured.line);
+    }
+    try {
+        const handoffs = handoffReport(dir, workspace);
+        for (const line of handoffs.lines) (handoffs.over && line.startsWith("handoffs cap:") ? fail : report)("handoffs", line);
+    } catch (error) { fail("handoffs", `could not report: ${error.message}`); }
 
     // Never a verdict: failing it would turn red every workspace drafted before the new form.
     let form;
@@ -1882,6 +1951,7 @@ export async function inspect(workspaceDir, options = {}) {
     } catch (error) {
         form = `not read — ${error.message}`;
     }
+    if ((agentsAlways.verdict === "over" || agentsAlways.verdict === "unjudged") && form.startsWith("today's form")) form += "; resolve the AGENTS.md budget verdict before applying this migration";
     report("form", form);
 
     let sessions;
@@ -1891,10 +1961,71 @@ export async function inspect(workspaceDir, options = {}) {
         sessions = `not read — ${error.message}`;
     }
     report("sessions", sessions);
+    try {
+        const root = treeOf(dir, workspace);
+        if (root !== null) for (const line of cacheRiskLines(root)) report("cache-risk", line);
+    } catch { report("cache-risk", "project configuration unassessed — the declared tree could not be read."); }
+    report("lever", `Claude Code project domain: ${biggestLeverLine(dir, workspace)}`);
 
     return { dir, workspace, findings, stats };
 }
 
+export function demotionCandidates(workspaceDir, workspace) {
+    const root = treeOf(workspaceDir, workspace);
+    if (root === null) return [];
+    const always = alwaysTier(root);
+    if (always.missing.length || always.outside.length || always.tooDeep.length) {
+        throw new DoctorError("the always-tier measurement is incomplete");
+    }
+    const candidates = [];
+    const add = (label, bytes) => {
+        const routing = Buffer.byteLength(`Read ${JSON.stringify(label)} on demand.\n`, "utf8");
+        if (bytes > routing) candidates.push({ label, bytes: bytes - routing, routing });
+    };
+    for (const entry of always.entries) {
+        const rel = path.relative(root, entry.file).split(path.sep).join("/");
+        if (entry.label === "instructions") {
+            for (const section of movableSections(fs.readFileSync(entry.file, "utf8"), entry.file)) {
+                add(`${rel}: ${section.title}`, section.bytes);
+            }
+        } else if (!entry.label.endsWith("description") && entry.file !== always.card && rel !== "core/engine.md") {
+            add(rel, entry.bytes);
+        }
+    }
+    return candidates.sort((a, b) => b.bytes - a.bytes || (a.label < b.label ? -1 : a.label > b.label ? 1 : 0));
+}
+
+export function biggestLeverLine(workspaceDir, workspace, evidence = null) {
+    const limits = "model and cache-lifetime changes unpriced";
+    try {
+        if (workspace.kind === "pointer" || treeOf(workspaceDir, workspace) === null) return `unmeasured — no repository tree; ${limits}`;
+        const ratio = declaredContext(workspace).ratio ?? ESTIMATED_BYTES_PER_TOKEN;
+        const spend = readSpend(workspace.spend, "this workspace");
+        const session = evidence?.restart;
+        const measured = session && [session.fresh, session.context, session.horizon, session.multipliers?.read, session.multipliers?.write].every((v) => Number.isFinite(v) && v > 0);
+        const horizon = measured ? session.horizon : spend.horizon ?? HORIZON;
+        const read = measured ? session.multipliers.read : spend.multipliers?.read ?? GENERAL_READ;
+        const candidates = demotionCandidates(workspaceDir, workspace).map((c) => ({
+            action: `review demoting ${JSON.stringify(c.label)} on demand`,
+            saving: c.bytes / ratio * horizon * read,
+            basis: `${c.bytes} B after ${c.routing} B routing allowance / ${ratio} B per token; assumes unused throughout the horizon`,
+        }));
+        if (measured && session.resume != null && session.horizonDeclared) candidates.push({
+            action: "review restarting the recorded session",
+            saving: restartSaving({ fresh: session.fresh, context: session.context, horizon, read, write: session.multipliers.write, resume: session.resume }),
+            basis: `${horizon} × ${read} × (${session.context} − ${session.fresh}) − ${session.multipliers.write} × ${session.fresh} − ${session.resume}; resume expense priced in input-equivalent tokens`,
+        });
+        const winner = candidates.filter((c) => Number.isFinite(c.saving) && c.saving > 0).sort((a, b) => b.saving - a.saving || (a.action < b.action ? -1 : 1))[0];
+        const assumptions = `${horizon} requests at ${read}× read (${spend.multipliers === null ? "general, undeclared" : "declared"}); ` +
+            `${session?.unavailable === "usage" ? "restart not compared: input usage counters are invalid or incomplete" : session?.unavailable === "branch-scope" ? "restart not compared: latest session tail is outside branch-owned scope" : measured && session.resume != null && session.horizonDeclared ? "recorded restart compared" : "session-dependent levers not compared: explicit horizon and resume expense required"}${evidence?.malformed ? "; partial usage data" : ""}; ${limits}`;
+        return winner
+            ? `biggest lever: ${winner.action} — up to ~${Number(winner.saving.toPrecision(6)).toLocaleString("en-US", { maximumSignificantDigits: 6 })} estimated input-equivalent tokens; ${winner.basis}; ${assumptions}; quantified demotion/restart candidates only, not an overall winner or guaranteed session savings`
+            : `no positive measured lever; ${assumptions}`;
+    } catch {
+        return `unmeasured — context or spend inputs are invalid, unreadable or incomplete; session-dependent levers not compared; ${limits}`;
+    }
+}
+
 /** Optional usage accounting: a data failure never changes the workspace-validation verdict. */
 export async function workspaceUsageReport(workspaceDir, workspace, options = {}) {
     const unmeasured = (why) => [`  note spend      unmeasured — ${why}`];
@@ -1908,12 +2039,15 @@ export async function workspaceUsageReport(workspaceDir, workspace, options = {}
         const host = hostPaths(options.env ?? process.env, options.home);
         if (host.why !== undefined) return unmeasured("the configured usage-record location is ambiguous");
         const report = ledger({ ...host, roots, branch, lines: linesChanged(repo, branch), spend: readSpend(workspace.spend, "this workspace") });
+        options.onLedger?.({ restart: report.restart, malformed: report.collected.malformed });
         const lines = [];
+        const analysis = spendAnalysis(report).map(line => `  note spend      ${line}`);
         if (report.collected.malformed) lines.push(`  note spend      partial data — ${report.collected.malformed} malformed usage line(s) were ignored`);
         if (report.figures.main.requests + report.figures.subagents.requests === 0 && report.local.receipts === 0) {
-            return [...lines, ...unmeasured("no host requests or local receipts on this branch are recorded here")];
+            return [...lines, ...unmeasured("no host requests or local receipts on this branch are recorded here"), ...analysis];
         }
         print(report, (line) => lines.push(line));
+        lines.push(...analysis);
         return lines;
     } catch {
         // Parser messages can quote a private record. Never print them or a raw usage line.
@@ -1935,9 +2069,13 @@ function usage() {
     return [
         "portulan doctor — validate a workspace against the Workspace Definition",
         "",
-        "  portulan doctor [--static] [--pack-root <dir>|auto]... [--repo-root <dir>]... <workspace-dir> [<workspace-dir> ...]",
+        "  portulan doctor [--agent] [--static | --count-tokens <model>] [--pack-root <dir>|auto]... [--repo-root <dir>]... <workspace-dir> [<workspace-dir> ...]",
         "",
         "  --static      skip local usage records; validation and plugin discovery remain unchanged.",
+        "  Always tiers: Claude Code and vendored AGENTS.md are measured and budgeted independently.",
+        "  --count-tokens <model>  validate both budgets, then send only the Claude Code project corpus to Anthropic.",
+        "                Requires ANTHROPIC_API_KEY; unavailable with --static or in CI. No manifest is changed.",
+        "  --agent       one counted line on green; complete reports on failure (also PORTULAN_AGENT=1).",
         "  --pack-root   where declared packs are resolved from; `auto` discovers the host's plugin cache.",
         "                A named root REPLACES every other source. A directory actually named `auto` is `./auto`",
         "  --repo-root   where the repositories this workspace's cards NAME are checked out, so their",
@@ -1953,14 +2091,25 @@ function usage() {
 
 /** Runs against each workspace directory and returns the exit code; never throws. */
 export async function run(argv, options = {}) {
-    const say = options.quiet ? () => {} : (line = "") => process.stdout.write(`${line}\n`);
+    const agent = argv.includes("--agent") || (options.env ?? process.env).PORTULAN_AGENT === "1";
+    const buffered = [];
+    const total = { workspaces: 0, notes: 0, claims: 0, providers: [] };
+    const say = options.quiet ? () => {} : agent ? (line = "") => buffered.push(line) : (line = "") => process.stdout.write(`${line}\n`);
+    const complete = (code, help = false) => {
+        if (agent && !options.quiet) {
+            if (code === 0 && !help) process.stdout.write(`GREEN — doctor: ${total.workspaces} workspace(s), ${total.notes} note(s), ${total.claims} claim(s) checked${total.providers.length ? "; " + total.providers.join("; ") : ""}\n`);
+            else if (buffered.length) process.stdout.write(buffered.join("\n") + "\n");
+        }
+        return code;
+    };
     // Before any other argument is judged, so help is never outranked by a complaint about the rest.
     if (argv.includes("--help") || argv.includes("-h")) {
         say(usage());
-        return 0;
+        return complete(0, true);
     }
     try {
         let staticMode = false;
+        let countModel = null;
         const namedRoots = [];
         let discoverPacks = false;
         const repoRoots = [];
@@ -1987,8 +2136,13 @@ export async function run(argv, options = {}) {
         };
         const REPO_ROOT = { unresolvable: "a repository ungoverned", holds: "repositories" };
         for (let i = 0; i < argv.length; i += 1) {
-            if (argv[i] === "--static") {
+            if (argv[i] === "--agent") {
+                continue;
+            } else if (argv[i] === "--static") {
                 staticMode = true;
+            } else if (argv[i] === "--count-tokens") {
+                if (countModel !== null || !argv[i + 1] || argv[i + 1].startsWith("-")) throw new DoctorError("--count-tokens needs one explicit provider model ID");
+                countModel = argv[++i];
             } else if (argv[i] === "--repo-root") {
                 repoRoots.push(directoryRoot("--repo-root", argv[i + 1], REPO_ROOT));
                 i += 1;
@@ -2005,15 +2159,20 @@ export async function run(argv, options = {}) {
         }
         const bothAsked = namedWithAuto(namedRoots, discoverPacks);
         if (bothAsked) throw new DoctorError(bothAsked);
+        if (countModel !== null && staticMode) throw new DoctorError("--count-tokens is unavailable with --static; verify recipes stay offline");
         if (dirs.length === 0) {
             if (!options.quiet) {
-                process.stderr.write("usage: node cli/doctor.mjs [--static] [--pack-root <dir>|auto]... [--repo-root <dir>]... <workspace-dir> [<workspace-dir> ...]\n");
+                process.stderr.write("usage: node cli/doctor.mjs [--agent] [--static | --count-tokens <model>] [--pack-root <dir>|auto]... [--repo-root <dir>]... <workspace-dir> [<workspace-dir> ...]\n");
             }
-            return 2;
+            return complete(2);
         }
 
         let failed = 0;
         for (const dir of dirs) {
+            if (countModel !== null) {
+                try { countRoot(path.resolve(dir)); }
+                catch (error) { throw new DoctorError(error instanceof ContextError ? error.message : "provider source validation could not run"); }
+            }
             const roots = {
                 ...(namedRoots.length ? { packRoots: namedRoots } : {}),
                 ...(discoverPacks ? { discoverPacks } : {}),
@@ -2021,21 +2180,40 @@ export async function run(argv, options = {}) {
             };
             const { findings, stats, workspace } = await inspect(dir, { ...options, ...roots });
             const bad = findings.filter((f) => f.severity === "fail");
+            let evidence = null;
+            const usageLines = !staticMode && !options.quiet && !bad.length && workspace
+                ? await workspaceUsageReport(path.resolve(dir), workspace, { ...options, onLedger: (report) => { evidence = report; } }) : [];
+            total.workspaces += 1;
+            total.notes += findings.length - bad.length;
+            total.claims += stats.claims;
             say(display(dir));
-            for (const f of findings) say(`  ${ICON[f.severity]} ${f.check.padEnd(10)} ${f.message}`);
+            if (countModel !== null && bad.length) {
+                say(`  RED — ${bad.length} validation failure(s); provider count skipped. Run doctor --static separately for validation details.`);
+                say();
+                failed += 1;
+                continue;
+            }
+            for (const f of findings) say(`  ${ICON[f.severity]} ${f.check.padEnd(10)} ${f.check === "lever" && evidence !== null ? `Claude Code project domain: ${biggestLeverLine(path.resolve(dir), workspace, evidence)}` : f.message}`);
             say(
                 `  ${bad.length ? "RED" : "GREEN"} — ${bad.length} failure(s), ` +
                     `${findings.length - bad.length} note(s), ${stats.claims} claim(s) checked` +
                     (stats.unverifiable ? `, ${stats.unverifiable} unverifiable` : ""),
             );
-            if (!staticMode && !options.quiet && !bad.length && workspace) {
-                for (const line of await workspaceUsageReport(path.resolve(dir), workspace, options)) say(line);
+            for (const line of usageLines) say(line);
+            if (countModel !== null && !bad.length && workspace) {
+                try {
+                    const provider = countLine(await countAlways(path.resolve(dir), { ...options.countOptions, model: countModel }));
+                    total.providers.push(provider);
+                    say(provider);
+                }
+                catch (error) { throw new DoctorError(error instanceof ContextError ? error.message : "provider token count could not run"); }
             }
             say();
             if (bad.length) failed += 1;
         }
-        return failed ? 1 : 0;
+        return complete(failed ? 1 : 0);
     } catch (error) {
+        complete(2);
         // Anything reaching here could not be judged, a defect in doctor included: 2, never a verdict.
         if (!options.quiet) {
             process.stderr.write(`doctor: ${error instanceof DoctorError ? error.message : `unanticipated failure — ${error.stack ?? error}`}\n`);

package/cli/drills.mjs

@@ -13,10 +13,11 @@ import { isInside } from "./inside.mjs";
 import { recipeSet, resolverFor } from "./recipe-set.mjs";
 
 const RAIL_TIMEOUT_MS = 10 * 60 * 1000;
+const RAIL_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
 
 export const DRILL_SESSION_PREFIX = "portulan-drill";
 
-/** Hooks answer in their stdout JSON and exit 0 either way, so their drills judge by a tell read from stdout. */
+/** Hook drills judge stdout JSON: exit 0 carries either verdict. */
 export const NON_RECIPE_RAILS = [
     {
         id: "stop-gate",
@@ -63,9 +64,20 @@ export const NOT_DRILLED = [
     },
 ];
 
-/** A rail that reads only the index misses a created file unless the drill sets `stage`. */
+/** Index-only rails need `stage` for a created file. */
 export const DRILLS = [
-    // ------------------------------------------------------------------------- the yielded recipes
+    {
+        rail: "cache-stability",
+        perturb: {
+            file: ".claude/rules/portulan/boot.md",
+            find: "# Portulan boot card",
+            replace: "# Portulan boot card\n\nCurrent date: 2099-12-31",
+        },
+        exit: 1,
+        tell: "differ from the committed golden",
+        why: "A volatile prefix change must require review of the committed baseline (#516), even when two renders agree.",
+    },
+    // The yielded recipes
     {
         rail: "docs",
         perturb: {
@@ -259,7 +271,7 @@ export const DRILLS = [
         rail: "pack-identity",
         perturb: {
             file: "README.md",
-            find: "**Current release: `0.3.0`**",
+            find: "**Current release: `0.4.0`**",
             replace: "**Current release: `0.1.3`** <!-- the drill edited this and did not stage it -->",
         },
         stage: false,
@@ -343,7 +355,7 @@ export const DRILLS = [
         rail: "version-carriers",
         perturb: {
             file: "README.md",
-            find: "**Current release: `0.3.0`**",
+            find: "**Current release: `0.4.0`**",
             replace: "**Current release: `0.1.3`**",
         },
         // Staged: this rail reads the index (`git show :<path>`), so an unstaged edit is invisible to it.
@@ -385,6 +397,17 @@ export const DRILLS = [
         tell: "invokes cli/review-meter.mjs --fetch",
         why: "A verify recipe that can reach the network goes red about the world rather than about the tree, and this repository prohibits it in three carriers while nothing checked it. The drill proves the checker sees a real invocation — spread across continued lines, the spelling a recipe actually uses — rather than only the literal string a test would hand it.",
     },
+    {
+        rail: "telemetry",
+        perturb: {
+            file: ".portulan/verify/doctor.sh",
+            find: "node cli/doctor.mjs --static --pack-root packs",
+            replace: "node cli/doctor.mjs --pack-root packs",
+        },
+        exit: 1,
+        tell: "invokes cli/doctor.mjs without an immediate --static",
+        why: "Doctor reads local usage records by default. Removing static mode from its recipe must fail the source audit before verification can depend on this machine's records. The drill runs telemetry, never the altered doctor recipe; filesystem-denial tests separately prove the static runtime path does not consult usage files.",
+    },
     {
         rail: "ab",
         perturb: {
@@ -481,7 +504,7 @@ export const DRILLS = [
         why: "Loopback is the rail that keeps a local worker's context on the machine, and the runner holds it in code rather than in any permission rule the compiler emits, so a guard that stopped refusing would leave every other rail green. The drill removes the refusal and requires the pack's own recipe to see it.",
     },
 
-    // ------------------------------------------------------- the coverage rail, which is itself a rail
+    // The coverage rail, which is itself a rail
     {
         rail: "drills",
         perturb: {
@@ -497,7 +520,7 @@ export const DRILLS = [
         why: "The allow-list is what stops a misspelled recipe id being silently reclassified as a rail of its own, leaving the real recipe undrilled while the coverage check reports green. A drill naming a rail nothing yields is the shortest path to that state.",
     },
 
-    // ------------------------------------------------------------------------- the two non-recipe rails
+    // The two non-recipe rails
     {
         rail: "stop-gate",
         perturb: {
@@ -839,6 +862,7 @@ function runRail({ rail, worktree, stdin, workspaceRel }) {
             // After the spread, so a drill's own `cwd` cannot point the hook at another tree.
             input: `${JSON.stringify({ ...payload, cwd: worktree })}\n`,
             timeout: RAIL_TIMEOUT_MS,
+            maxBuffer: RAIL_MAX_BUFFER_BYTES,
             // Set, never inherited: the hooks read their tree and workspace from these two.
             env: { ...process.env, CLAUDE_PROJECT_DIR: worktree, PORTULAN_WORKSPACE: workspaceRel },
         });
@@ -850,6 +874,7 @@ function runRail({ rail, worktree, stdin, workspaceRel }) {
         cwd: worktree,
         encoding: "utf8",
         timeout: RAIL_TIMEOUT_MS,
+        maxBuffer: RAIL_MAX_BUFFER_BYTES,
     });
     if (result.error) throw new CouldNotRun(`rail \`${rail.id}\` could not run — ${result.error.message}`);
     return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };

package/cli/finish.md

@@ -0,0 +1,34 @@
+# Finish verification boundaries
+
+Finish resolves the recipe set before staging tracked changes or creating its
+provisional commit. An empty result from `treeRoots` asks for normal recipe-set
+resolution; it does not mean verification succeeded without any recipes.
+
+| Workspace and roots | Behavior |
+| --- | --- |
+| No composed packs | The tree's pack directories are not probed. Declared workspace recipes still run. |
+| Tree roots contain every composed pack | Finish names those roots, avoiding an installed copy shadowing the tree. |
+| Tree roots are absent, empty or incomplete | Normal recipe-set resolution and its shadow checks apply. An installed pack can supply the missing recipes; an unresolved pack refuses the operation before commit. |
+| Explicit `--pack-root <directory>` | Only the named roots are used. Missing directories are refused, and missing packs do not fall back to an installed copy. |
+
+The controls in `finish.test.mjs` cover these cases. For an absent tree directory,
+the installed-pack fixture compares recipe-set's yielded identities against actual
+execution markers. The unavailable-pack fixture checks that no commit hook ran and
+that HEAD, the index, the worktree and the remote branch remain unchanged.
+
+Bash parse failures are **could not run**, with exit 2 and the diagnostic included
+in finish's report. A provisional commit made before the recipes ran is undone and
+its changes stay staged; nothing is pushed. Both tested recipe forms parse after
+the wrapper's `exec 2>&1` redirection. These controls do not demonstrate coverage
+of Bash startup failures.
+
+The manifest recipe format rejects newlines, carriage returns and tabs before
+Bash runs. The CLI controls therefore use a single-line missing `fi` and a leading
+`)`. Line numbers can differ between Bash versions. These are Bash's wrapper-script
+diagnostics, not a general promise to translate recipe line numbers.
+The historical two-line example in the review follow-up can be passed directly to
+`runRecipe`, but is not accepted as a current manifest recipe.
+
+This reference records concrete boundaries investigated for the historical review
+follow-up. That review posted no findings identifying a different empty-root case;
+these controls do not establish what its unspecified concern meant.