@sleepy_panda_srl/portulan 0.2.0 → 0.4.0

package/cli/doctor.mjs

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 // `doctor` — the Workspace Definition validator.
 //
-//   node cli/doctor.mjs [--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";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -18,14 +21,22 @@ import {
     composeFragments,
     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 { 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");
@@ -473,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;
@@ -506,6 +517,9 @@ export function validatePersona(text, { fail, pack, rel }) {
             fail("packs", `\`${pack}\`'s persona \`${rel}\` is missing ${part} — the five-part contract core/personas/README.md fixes`);
         }
     }
+    for (const problem of personaDeclarations(text).problems) {
+        fail("packs", `\`${pack}\`'s persona \`${rel}\` ${problem} — core/personas/README.md gives the fields a persona may declare, and none is defaulted`);
+    }
     const reach = text.split(/^##\s+Autonomy reach\b.*$/im)[1]?.split(/^##\s/m)[0];
     if (reach && claimsProhibited(reach)) {
         fail(
@@ -777,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}`);
@@ -824,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(
@@ -969,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)) {
@@ -1122,6 +1141,7 @@ export async function inspect(workspaceDir, options = {}) {
     }
 
     const composedPersonas = [];
+    const contextContributions = [];
 
     let resolvedPackRoots = null;
     let packsUnresolved = 0;
@@ -1143,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;
@@ -1159,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;
@@ -1186,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 ?? {};
 
@@ -1218,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",
@@ -1243,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",
@@ -1274,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",
@@ -1349,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",
@@ -1448,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",
@@ -1472,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);
@@ -1480,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(
@@ -1491,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 the one location a Claude Code host loads agents from",
+                            `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`);
@@ -1532,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}`);
         }
     }
@@ -1762,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) {
@@ -1850,7 +1918,7 @@ export async function inspect(workspaceDir, options = {}) {
               (stats.unassessed
                   ? `; ${stats.unassessed} unreadable and never assessed`
                   : "") +
-              ". Size and count only: ages live in git, which doctor does not read, so staleness belongs to `cli/librarian.mjs` — the scheduled pass, which may ask git and does"
+              ". Size and count only: memory ages are not measured here, so staleness belongs to `cli/librarian.mjs` — the scheduled pass, which may ask git and does"
             : "no memory records — nothing measured, nothing awaiting retirement",
     );
 
@@ -1867,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;
@@ -1876,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;
@@ -1885,10 +1961,100 @@ 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}`];
+    if (typeof workspace?.tree !== "string" || workspace.tree.trim() === "") return unmeasured("the workspace declares no tree to attribute usage to");
+    try {
+        const repo = path.resolve(workspaceDir, workspace.tree);
+        const roots = worktrees(repo);
+        if (roots === null || roots.length === 0) return unmeasured("the declared tree has no Git worktree ownership");
+        const branch = execFileSync("git", ["-C", repo, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10_000 }).trim();
+        if (!branch || branch === "HEAD") return unmeasured("the declared tree has no current named Git branch");
+        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"), ...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.
+        return unmeasured("optional local usage data could not be read or parsed; no totals were reported");
+    }
+}
+
 // ---------------------------------------------------------------- the command
 
 const ICON = { fail: "FAIL ", report: "note " };
@@ -1903,8 +2069,13 @@ function usage() {
     return [
         "portulan doctor — validate a workspace against the Workspace Definition",
         "",
-        "  portulan doctor [--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",
@@ -1920,13 +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 = [];
@@ -1953,7 +2136,14 @@ 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] === "--repo-root") {
+            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;
             } else if (argv[i] === "--pack-root") {
@@ -1969,34 +2159,61 @@ 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 [--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 } : {}),
                 ...(repoRoots.length ? { repoRoots } : {}),
             };
-            const { findings, stats } = await inspect(dir, { ...options, ...roots });
+            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` : ""),
             );
+            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`);