@sleepy_panda_srl/portulan 0.3.0 → 0.4.1

package/cli/context.mjs

@@ -1,19 +1,22 @@
 #!/usr/bin/env node
-// What a context loads, measured: what a boot reads in full, and what the host loads into every context.
+// Measure boot reads and the project's always tier.
 //
 //   node cli/context.mjs --workspace <dir> [--repo <card>] [--rail <name>=<bytes>]...
-//   node cli/context.mjs --workspace <dir> --brief
+//   node cli/context.mjs --workspace <dir> --brief | --count-tokens <model>
 //
 // Exit 0 within every rail and declared budget · 1 a rail or budget exceeded · 2 could not run or judge a declared budget.
 
 import fs from "node:fs";
+import { isAbsentImportError } from "./import-files.mjs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { BOOT_CARD_LINE, IMPORT_DEPTH, importPath, importSpans } from "./compile.mjs";
+import { BOOT_CARD_LINE, CompileError, GUIDANCE_HOSTS, IMPORT_DEPTH, importPath, importSpans } from "./compile.mjs";
 import { offerText, splitOffers } from "./instructions.mjs";
 import { AGENT_DIR, parseFrontmatter } from "./plugin-lint.mjs";
 import { HOST_SKILL_DEPTH, manifestPath } from "./skills-set.mjs";
+import { readHandoffs, renderHandoffIndex } from "./index.mjs";
+import { handoffPolicy, handoffOverages, handoffTokens } from "./handoff-policy.mjs";
 
 export { IMPORT_DEPTH };
 
@@ -71,6 +74,28 @@ const grouped = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
 
 export const tokensOf = (bytes, ratio) => Math.round(bytes / ratio);
 
+export function handoffReport(dir, manifest) {
+    const policy = handoffPolicy(manifest);
+    if (manifest.slots?.handoffs === undefined) return { lines: [], over: false };
+    const declared = declaredContext(manifest);
+    const ratio = declared.ratio ?? ESTIMATED_BYTES_PER_TOKEN;
+    const series = readHandoffs(dir, manifest);
+    const sizes = series.records.map(r => r.bytes).sort((a, b) => a - b);
+    const middle = Math.floor(sizes.length / 2);
+    const median = sizes.length ? sizes.length % 2 ? sizes[middle] : (sizes[middle - 1] + sizes[middle]) / 2 : 0;
+    const size = bytes => `${bytes} B (~${handoffTokens(bytes, ratio)} tokens)`;
+    const lines = [`handoffs: ${sizes.length} record(s), total ${size(series.bytes)}, median ${size(median)}; ${declared.ratio === null ? "estimate" : "declared ratio"} ${ratio} bytes per token; on-read, excluded from boot and always tier`];
+    for (const record of [...series.records].sort((a, b) => b.bytes - a.bytes || a.file.localeCompare(b.file)).slice(0, 3)) lines.push(`handoffs largest: ${record.file} — ${size(record.bytes)}`);
+    if (manifest.handoffs?.index?.path) {
+        if (series.records.some(r => r.date === null || r.heading === null)) throw new ContextError("handoff index cannot render: repair the filename dates and H1 headings with portulan index");
+        const text = renderHandoffIndex(manifest, series);
+        lines.push(`handoffs index: ${manifest.handoffs.index.path}, rendered ${size(Buffer.byteLength(text))}; ${policy.window === null ? "budget undeclared" : `budget ${policy.window} tokens`}`);
+    } else lines.push("handoffs index: undeclared — no index measured");
+    const overages = handoffOverages(series, policy);
+    lines.push(policy.cap === null ? "handoffs cap: undeclared — report only" : `handoffs cap: ${policy.cap} tokens, cutoff ${policy.cutoff}; ${overages.bound.length} bound over, ${overages.historical.length} on/before cutoff over (reported, never railed)`);
+    return { lines, over: overages.bound.length > 0 };
+}
+
 function sizeOf(file, what) {
     let stat;
     try {
@@ -90,14 +115,11 @@ function readText(file, what) {
     }
 }
 
-// Only these are absent: a denied read or a loop of links, read as absent, would be a green over less than the host loads.
-const ABSENT = new Set(["ENOENT", "ENOTDIR", "ENAMETOOLONG", "ERR_INVALID_ARG_VALUE"]);
-
 function statOf(file) {
     try {
         return fs.statSync(file);
     } catch (error) {
-        if (ABSENT.has(error.code)) return null;
+        if (isAbsentImportError(error)) return null;
         throw new ContextError(`${file} could not be read (${error.code ?? error.message})`);
     }
 }
@@ -142,7 +164,7 @@ export function declaredContext(manifest) {
         throw new ContextError(`context.ratio.bytes_per_token is ${shown(bytesPerToken)}, not a finite number of at least 1`);
     }
     if (typeof ratio.calibrated_by !== "string" || ratio.calibrated_by === "") {
-        throw new ContextError(`context.ratio.calibrated_by is ${shown(ratio.calibrated_by)}, not the id of the host whose exact count calibrated the ratio`);
+        throw new ContextError(`context.ratio.calibrated_by is ${shown(ratio.calibrated_by)}, not a non-empty compile-host calibration ID`);
     }
     let budget = null;
     if (context.always !== undefined) {
@@ -310,11 +332,19 @@ export function bootReadSet(workspaceDir, manifest, { bundleRoot = BUNDLE_ROOT,
 // ===========================================================================================
 
 export function importsOf(text) {
-    return importSpans(text)
+    return measuredImports(text, "import text")
         .map(({ target }) => importPath(target))
         .filter((bare) => bare !== null);
 }
 
+function measuredImports(text, file) {
+    try { return importSpans(text); }
+    catch (error) {
+        if (error instanceof CompileError) throw new ContextError(`${file}: ${error.message}`);
+        throw error;
+    }
+}
+
 const inside = (root, file) => {
     const rel = path.relative(root, file);
     return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
@@ -364,15 +394,51 @@ function walkMarkdown(dir, kept) {
     return out;
 }
 
-export function alwaysTier(repoRoot) {
+export function alwaysTier(repoRoot, { includeText = false, host = "claude-code", materializeImport } = {}) {
+    if (!Object.hasOwn(GUIDANCE_HOSTS, host)) throw new ContextError("unknown project guidance host");
     const entries = [];
     const missing = [];
     const outside = [];
     const tooDeep = [];
     const seen = new Set();
+    const captured = new Map();
+    const source = (file) => {
+        const real = realOf(file);
+        if (!includeText || !captured.has(real)) {
+            let raw;
+            try { raw = fs.readFileSync(file); }
+            catch { throw new ContextError("an always-tier source could not be read"); }
+            const text = raw.toString("utf8");
+            if (!Buffer.from(text, "utf8").equals(raw)) throw new ContextError("an always-tier source is not valid UTF-8");
+            const value = { text, bytes: raw.length };
+            if (!includeText) return value;
+            captured.set(real, value);
+        }
+        return captured.get(real);
+    };
 
     // Judged on real paths: a link out of the repository is named, never opened, since it is not this repository's to measure.
     const realRoot = realOf(repoRoot);
+    if (host === "agents-md") {
+        const file = path.join(repoRoot, "AGENTS.md");
+        let entry;
+        try { entry = fs.lstatSync(file); }
+        catch (error) {
+            if (!isAbsentImportError(error)) throw new ContextError(`AGENTS.md could not be inspected (${error.code ?? "read error"})`);
+        }
+        if (entry) {
+            let real, raw;
+            try {
+                real = fs.realpathSync(file);
+                if (!inside(realRoot, real) || !fs.statSync(file).isFile()) throw new Error("source boundary");
+                raw = fs.readFileSync(file);
+            } catch (error) { throw new ContextError(`AGENTS.md is present but cannot be measured within the repository (${error.code ?? "nonregular or outside source"})`); }
+            const text = raw.toString("utf8");
+            if (!Buffer.from(text, "utf8").equals(raw)) throw new ContextError("AGENTS.md is not valid UTF-8");
+            entries.push({ label: "vendored instructions", file, bytes: raw.length, ...(includeText ? { text } : {}) });
+        }
+        return { entries, scoped: 0, unlisted: 0, missing, outside, tooDeep, card: null };
+    }
     const kept = (file) => {
         const real = realOf(file);
         if (real === realRoot || inside(realRoot, real)) return true;
@@ -386,13 +452,14 @@ export function alwaysTier(repoRoot) {
         while (queue.length) {
             const { file, label, depth, scoped } = queue.shift();
             const real = realOf(file);
+            const { text, bytes } = source(file);
             if (!(scoped && depth === 0)) {
                 if (seen.has(real)) continue;
                 seen.add(real);
                 const imported = `import, depth ${depth}${scoped ? ", of a path-scoped rule" : ""}`;
-                entries.push({ label: depth === 0 ? label : imported, file, bytes: sizeOf(file, file) });
+                entries.push({ label: depth === 0 ? label : imported, file, bytes, ...(includeText ? { text } : {}) });
             }
-            for (const { target } of importSpans(readText(file, file))) {
+            for (const { target } of measuredImports(text, file)) {
                 const bare = importPath(target);
                 if (bare === null) continue;
                 const spelled = `@${target} (in ${path.relative(repoRoot, file)})`;
@@ -400,8 +467,12 @@ export function alwaysTier(repoRoot) {
                     outside.push(spelled);
                     continue;
                 }
-                const resolved = path.resolve(path.dirname(file), bare);
-                if (!isFile(resolved)) {
+                let resolved = path.resolve(path.dirname(file), bare);
+                if (depth + 1 < IMPORT_DEPTH) {
+                    const projected = materializeImport?.({ file: resolved, source: file, bare, depth });
+                    if (projected !== undefined) resolved = projected;
+                }
+                if (resolved === null || !isFile(resolved)) {
                     missing.push(spelled);
                     continue;
                 }
@@ -418,19 +489,24 @@ export function alwaysTier(repoRoot) {
             }
         }
     };
-    follow(
-        ["CLAUDE.md", path.join(".claude", "CLAUDE.md")]
-            .map((rel) => path.join(repoRoot, rel))
-            .filter((file) => isFile(file) && kept(file))
-            .map((file) => ({ file, label: "instructions" })),
-    );
+    const instructions = [];
+    for (const rel of ["CLAUDE.md", path.join(".claude", "CLAUDE.md")]) {
+        const file = path.join(repoRoot, rel);
+        let entry;
+        try { entry = fs.lstatSync(file); }
+        catch (error) { if (!isAbsentImportError(error)) throw new ContextError(`${rel} could not be inspected (${error.code ?? "read error"})`); }
+        if (!entry) continue;
+        if (!isFile(file)) throw new ContextError(`${rel} is present but not a readable regular file`);
+        if (kept(file)) instructions.push({ file, label: "instructions" });
+    }
+    follow(instructions);
 
     let scoped = 0;
     let card = null;
     const unscoped = [];
     const pathScoped = [];
     for (const file of walkMarkdown(path.join(repoRoot, ".claude", "rules"), kept)) {
-        const text = readText(file, file);
+        const { text } = source(file);
         const { fields } = parseFrontmatter(text);
         if (fields && Object.hasOwn(fields, "paths")) {
             scoped += 1;
@@ -445,12 +521,12 @@ export function alwaysTier(repoRoot) {
     // The host lists a skill's, command's or agent's description in every context, and loads the body when it is invoked.
     let unlisted = 0;
     const describe = (file, label) => {
-        const description = descriptionOf(readText(file, file));
+        const description = descriptionOf(source(file).text);
         if (description === null) {
             unlisted += 1;
             return;
         }
-        entries.push({ label, file, bytes: Buffer.byteLength(description, "utf8") });
+        entries.push({ label, file, bytes: Buffer.byteLength(description, "utf8"), ...(includeText ? { text: description } : {}) });
     };
     const skills = path.join(repoRoot, ".claude", "skills");
     if (isDir(skills) && kept(skills)) {
@@ -471,6 +547,72 @@ export function alwaysTier(repoRoot) {
     return { entries, scoped, unlisted, missing, outside, tooDeep, card };
 }
 
+export function countRoot(workspaceDir) {
+    let manifest;
+    try { manifest = readManifest(workspaceDir); }
+    catch { throw new ContextError("provider counting needs a readable, valid JSON workspace manifest"); }
+    if (!WORKSPACE_KINDS.includes(manifest.kind)) throw new ContextError("provider counting needs a supported governing workspace kind");
+    try { declaredContext(manifest); }
+    catch { throw new ContextError("provider counting needs a valid workspace context declaration"); }
+    let root;
+    try { root = treeOf(workspaceDir, manifest); }
+    catch { throw new ContextError("provider counting needs a readable repository tree"); }
+    if (root === null) throw new ContextError("provider counting needs a measurable repository tree");
+    return root;
+}
+
+export async function countAlways(workspaceDir, { model, env = process.env, fetch = globalThis.fetch, timeoutMs = 30_000 } = {}) {
+    if (typeof model !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/.test(model)) throw new ContextError("--count-tokens needs an explicit provider model ID");
+    if (env.CI) throw new ContextError("provider token counting is unavailable in CI; verify recipes stay offline");
+    const root = countRoot(workspaceDir);
+    let always;
+    try { always = alwaysTier(root, { includeText: true }); }
+    catch (error) { throw new ContextError(error instanceof ContextError && error.message.includes("UTF-8") ? "an always-tier source is not valid UTF-8" : "always-tier sources or imports could not be measured"); }
+    if (always.missing.length || always.outside.length || always.tooDeep.length) throw new ContextError("always-tier imports are missing, outside the measured tree or too deep; no provider request made");
+    const bytes = always.entries.reduce((sum, entry) => sum + entry.bytes, 0);
+    const result = { provider: "Anthropic", model, bytes, tokens: null, ratio: null, files: always.entries.map((entry) => path.relative(root, entry.file)) };
+    if (!bytes) return result;
+    const key = env.ANTHROPIC_API_KEY;
+    if (typeof key !== "string" || !key || /\s/.test(key)) throw new ContextError("ANTHROPIC_API_KEY is required for provider counting");
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new ContextError("provider timeout must be a positive whole number of milliseconds");
+    const controller = new AbortController();
+    let timer;
+    const expired = new Promise((_, reject) => {
+        timer = setTimeout(() => { controller.abort(); reject(new ContextError("provider token count timed out")); }, timeoutMs);
+    });
+    try {
+        const load = async () => {
+            let response;
+            try {
+                response = await fetch("https://api.anthropic.com/v1/messages/count_tokens", {
+                    method: "POST", redirect: "error", signal: controller.signal,
+                    headers: { "Content-Type": "application/json", "anthropic-version": "2026-10-21", Authorization: `Bearer ${key}` },
+                    body: JSON.stringify({ model, messages: [{ role: "user", content: always.entries.filter((entry) => entry.bytes).map((entry) => ({ type: "text", text: entry.text })) }] }),
+                });
+            } catch { throw new ContextError("provider token count request failed"); }
+            if (response.redirected) throw new ContextError("provider token count redirect refused");
+            if (!response.ok) throw new ContextError(`provider token count failed (HTTP ${Number.isInteger(response.status) ? response.status : "unavailable"})`);
+            let body;
+            try { body = await response.json(); }
+            catch { throw new ContextError("provider returned an invalid token count response"); }
+            if (!Number.isSafeInteger(body?.input_tokens) || body.input_tokens <= 0) throw new ContextError("provider input_tokens is not a positive safe integer token count");
+            return body.input_tokens;
+        };
+        const tokens = await Promise.race([load(), expired]);
+        return { ...result, tokens, ratio: bytes / tokens };
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+export function countLine(result) {
+    if (!result.bytes) return "project always corpus: empty (0 B); no request made and no ratio available";
+    return `${result.provider} provider estimate (${result.model}): ${result.tokens} input tokens for ${result.bytes} B of measured project source; ` +
+        `effective ratio ${result.ratio.toFixed(6)} B/token${result.ratio < 1 ? " (below the manifest's minimum; not declarable)" : " (approximate; assess manually before declaring a host ratio)"}. ` +
+        "API framing/system-added tokens may be included; actual host usage may differ. No manifest written. " +
+        "Excludes personal/global instructions, auto-memory, system/tools/MCP, plugin descriptions, scoped-rule bodies and on-invoke bodies.";
+}
+
 export function pluginDescriptions(bundleRoot = BUNDLE_ROOT) {
     const file = manifestPath(bundleRoot);
     if (!isFile(file)) return { unavailable: "this bundle carries no .claude-plugin/plugin.json, so it is not the plugin" };
@@ -560,15 +702,15 @@ export function treeOf(workspaceDir, manifest) {
     return repoRoot;
 }
 
-export function judgeBudget(declared, bytes) {
+export function judgeBudget(declared, bytes, { offer = true } = {}) {
     const tokens = tokensOf(bytes, declared.ratio ?? ESTIMATED_BYTES_PER_TOKEN);
     if (declared.budget === null) {
         return {
             verdict: "undeclared",
             tokens,
             text:
-                "budget: undeclared (context.always.budget.tokens) — a report, not a rail; init would offer the larger of " +
-                `${grouped(OFFER_FLOOR_TOKENS)} tokens and today's load: ${grouped(Math.max(OFFER_FLOOR_TOKENS, tokens))} tokens`,
+                "budget: undeclared (context.always.budget.tokens) — a report, not a rail" +
+                (offer ? "; init offers a projected budget for both guidance formats at your accepted ratio, with an 8,000-token floor" : ""),
         };
     }
     if (tokens > declared.budget) {
@@ -615,7 +757,9 @@ export function measure(workspaceDir, { bundleRoot = BUNDLE_ROOT, repo = null }
 // ===========================================================================================
 
 /** `over` and `unjudged` are verdicts; `unmeasured` is a report, said where no budget waits on the figure. */
-export function alwaysLine(workspaceDir, manifest, { bundleRoot = BUNDLE_ROOT } = {}) {
+export function alwaysLine(workspaceDir, manifest, { bundleRoot = BUNDLE_ROOT, host = "claude-code" } = {}) {
+    if (!Object.hasOwn(GUIDANCE_HOSTS, host)) throw new ContextError("unknown project guidance host");
+    const claude = host === "claude-code";
     // Read raw, so a budget whose key is malformed still counts as one somebody meant to declare.
     const budgeted = manifest.context?.always !== undefined;
     // The tree as declared, before it is checked, since checking it is one of the things that can fail on it.
@@ -623,7 +767,7 @@ export function alwaysLine(workspaceDir, manifest, { bundleRoot = BUNDLE_ROOT }
         [typeof manifest.tree === "string" ? path.resolve(workspaceDir, manifest.tree) : null, "the repository"],
         [path.resolve(bundleRoot), "the plugin"],
     ];
-    const said = (verdict, text) => ({ verdict, line: printable(relativeTo(`${MEASURED_HOST}: ${text}`, roots)) });
+    const said = (verdict, text) => ({ verdict, line: printable(relativeTo(`${GUIDANCE_HOSTS[host].label}: ${text}`, roots)) });
     const notMeasured = (why) =>
         budgeted ? said("unjudged", `the declared budget cannot be judged — ${why}`) : said("unmeasured", `the always tier is not measured — ${why}`);
     let declared;
@@ -634,14 +778,14 @@ export function alwaysLine(workspaceDir, manifest, { bundleRoot = BUNDLE_ROOT }
         if (manifest.kind === "pointer") return notMeasured("the manifest is a pointer, which declares no tree, so the repository it sits in is not measured here");
         root = treeOf(workspaceDir, manifest);
         if (root === null) return notMeasured("this workspace declares no tree, so there is no repository here whose instruction files a host would load");
-        always = alwaysTier(root);
+        always = alwaysTier(root, { host });
     } catch (error) {
         if (!(error instanceof ContextError)) throw error;
         return notMeasured(error.message);
     }
     let plugin;
     try {
-        plugin = pluginDescriptions(bundleRoot);
+        plugin = claude ? pluginDescriptions(bundleRoot) : null;
     } catch (error) {
         if (!(error instanceof ContextError)) throw error;
         plugin = { unavailable: error.message };
@@ -649,10 +793,10 @@ export function alwaysLine(workspaceDir, manifest, { bundleRoot = BUNDLE_ROOT }
 
     const ratio = declared.ratio ?? ESTIMATED_BYTES_PER_TOKEN;
     const bytes = sum(always.entries);
-    const judged = judgeBudget(declared, bytes);
+    const judged = judgeBudget(declared, bytes, { offer: claude });
     const parts = [
         `this repository's always tier is ~${grouped(judged.tokens)} tokens, ${grouped(bytes)} B at ${ratio} bytes per token` +
-            (declared.ratio === null ? ", proposal 0036's estimate: none is declared" : `, declared, calibrated by ${declared.calibratedBy}`),
+            (declared.ratio === null ? ", proposal 0036's estimate: none is declared" : host === declared.calibratedBy ? `, declared, calibrated by ${declared.calibratedBy}` : `, shared declared ratio extrapolated to this host; calibration reference ${declared.calibratedBy}`),
     ];
     if (always.entries.length) {
         // Stable, so files of one size keep the host's own order.
@@ -662,27 +806,29 @@ export function alwaysLine(workspaceDir, manifest, { bundleRoot = BUNDLE_ROOT }
                 (always.entries.length > top.length ? `, of ${grouped(always.entries.length)} files` : ""),
         );
     } else {
-        parts.push("nothing in it: no CLAUDE.md, .claude/CLAUDE.md, unscoped rule, or project skill, command or agent");
+        parts.push(claude ? "nothing in it: no CLAUDE.md, .claude/CLAUDE.md, unscoped rule, or project skill, command or agent" : "nothing in it: no root AGENTS.md");
     }
     const scoped = always.scoped;
-    parts.push(scoped === 0 ? "no path-scoped rule sits on-path" : scoped === 1 ? "1 path-scoped rule sits on-path" : `${grouped(scoped)} path-scoped rules sit on-path`);
+    if (claude) parts.push(scoped === 0 ? "no path-scoped rule sits on-path" : scoped === 1 ? "1 path-scoped rule sits on-path" : `${grouped(scoped)} path-scoped rules sit on-path`);
     const outside = always.outside.length;
-    parts.push(
+    if (claude) parts.push(
         outside === 0
             ? "no import or link out of the repository loads"
             : outside === 1
               ? "1 import or link out of the repository loads and is not counted"
               : `${grouped(outside)} imports or links out of the repository load and are not counted`,
     );
-    parts.push(
+    if (claude) parts.push(
         plugin.unavailable === undefined
             ? `the Portulan plugin's descriptions add ~${grouped(tokensOf(sum(plugin.entries), ratio))} tokens wherever it is enabled, Portulan's to budget, not this workspace's`
             : `the Portulan plugin's descriptions are not measured — ${plugin.unavailable}`,
     );
+    if (!claude) parts.push("root AGENTS.md only: pointer targets and at-sign text are not expanded; personal, above-tree, nested files and plugins are excluded");
+    if (claude && (always.missing.length || always.tooDeep.length)) parts.push(`${always.missing.length} missing imports and ${always.tooDeep.length} beyond the host's import depth are not loaded or counted`);
     parts.push(judged.text);
     // `init` and `upgrade` draft a card importing the identity whole, so over a budget that import is the demotion to name.
     const identity = typeof manifest.slots?.identity === "string" ? path.resolve(workspaceDir, manifest.slots.identity) : null;
-    const whole = judged.verdict === "over" && identity !== null ? always.entries.find((e) => e.label.startsWith("import") && path.resolve(e.file) === identity) : undefined;
+    const whole = claude && judged.verdict === "over" && identity !== null ? always.entries.find((e) => e.label.startsWith("import") && path.resolve(e.file) === identity) : undefined;
     if (whole) {
         parts.push(
             `the tier imports ${path.relative(root, identity)} whole, ~${grouped(tokensOf(whole.bytes, ratio))} tokens: one demotion is to make it an on-demand read, ` +
@@ -690,7 +836,7 @@ export function alwaysLine(workspaceDir, manifest, { bundleRoot = BUNDLE_ROOT }
         );
     }
     const over = judged.verdict === "over";
-    const offer = offerText(splitOffers(root, { ratio, floor: OFFER_FLOOR_TOKENS, over }), { over, workspace: path.relative(root, workspaceDir).split(path.sep).join("/") || "." });
+    const offer = claude ? offerText(splitOffers(root, { ratio, floor: OFFER_FLOOR_TOKENS, over }), { over, workspace: path.relative(root, workspaceDir).split(path.sep).join("/") || "." }) : null;
     if (offer !== null) parts.push(offer);
     return said(judged.verdict, parts.join("; "));
 }
@@ -714,17 +860,20 @@ function printable(text) {
 // ===========================================================================================
 
 function parseArgs(argv) {
-    const options = { workspace: null, repo: null, rails: new Map(), brief: false };
+    const options = { workspace: null, repo: null, rails: new Map(), brief: false, countModel: null };
     for (let i = 0; i < argv.length; i += 1) {
         const flag = argv[i];
         if (flag === "--brief") {
             if (options.brief) throw new ContextError("--brief is given twice");
             options.brief = true;
-        } else if (flag === "--workspace" || flag === "--repo" || flag === "--rail") {
+        } else if (flag === "--workspace" || flag === "--repo" || flag === "--rail" || flag === "--count-tokens") {
             const value = argv[i + 1];
             i += 1;
             if (value === undefined) throw new ContextError(`${flag} needs a value`);
-            if (flag === "--workspace") options.workspace = value;
+            if (flag === "--count-tokens") {
+                if (options.countModel !== null) throw new ContextError("--count-tokens is given twice");
+                options.countModel = value;
+            } else if (flag === "--workspace") options.workspace = value;
             else if (flag === "--repo") options.repo = value;
             else {
                 const match = /^([a-z]+)=([1-9]\d*)$/.exec(value);
@@ -739,17 +888,23 @@ function parseArgs(argv) {
         }
     }
     if (options.workspace === null) throw new ContextError("--workspace <dir> is required: the directory holding workspace.json");
+    if (options.countModel !== null && (options.brief || options.repo !== null || options.rails.size)) throw new ContextError("--count-tokens is a separate provider report; omit --brief, --repo and --rail");
     if (options.brief && (options.repo !== null || options.rails.size)) {
         throw new ContextError("--brief prints the always tier's line, which judges no rail and reads no card — run without it to use --repo or --rail");
     }
     return options;
 }
 
-export function run(argv, say = (line) => process.stdout.write(`${line}\n`), { bundleRoot = BUNDLE_ROOT, cwd = process.cwd() } = {}) {
+export function run(argv, say = (line) => process.stdout.write(`${line}\n`), { bundleRoot = BUNDLE_ROOT, cwd = process.cwd(), countOptions = {} } = {}) {
     let options;
     let result;
     try {
         options = parseArgs(argv);
+        if (options.countModel !== null) {
+            return countAlways(path.resolve(cwd, options.workspace), { ...countOptions, model: options.countModel })
+                .then((result) => { say(countLine(result)); return 0; })
+                .catch((error) => { say(`  ✗ ${error instanceof ContextError ? error.message : "provider token count could not run"}`); return 2; });
+        }
         if (options.brief) {
             const workspaceDir = path.resolve(cwd, options.workspace);
             const { verdict, line } = alwaysLine(workspaceDir, readManifest(workspaceDir), { bundleRoot });
@@ -862,6 +1017,12 @@ export function run(argv, say = (line) => process.stdout.write(`${line}\n`), { b
         }
     }
 
+    try {
+        const handoffs = handoffReport(path.resolve(cwd, options.workspace), readManifest(path.resolve(cwd, options.workspace)));
+        for (const text of handoffs.lines) say(`  ${text}`);
+        red ||= handoffs.over;
+    } catch (error) { couldNot.push(`handoffs: ${error.message}`); }
+
     if (couldNot.length) {
         for (const c of couldNot) say(`  ✗ ${c}`);
         return 2;
@@ -872,7 +1033,7 @@ export function run(argv, say = (line) => process.stdout.write(`${line}\n`), { b
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
     // `process.exitCode` rather than `process.exit`, so a pipe that has not drained is not cut short.
     try {
-        process.exitCode = run(process.argv.slice(2));
+        process.exitCode = await run(process.argv.slice(2));
     } catch (cause) {
         process.stderr.write(
             `context: could not run — ${cause?.stack ?? cause}\n` +