@sleepy_panda_srl/portulan 0.3.0 → 0.4.1

package/cli/recipe-runner.mjs

@@ -0,0 +1,131 @@
+// Shared asynchronous recipe execution, bounded output and process-tree cleanup.
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, execFileSync } from "node:child_process";
+
+const CANNOT_RUN = new Set([2, 126, 127]);
+export const INTERRUPTIONS = ["SIGINT", "SIGTERM", "SIGHUP"];
+
+/** A stream's last `limit` bytes, retaining at most `limit` and one chunk. */
+export function tailKeeper(limit = 64 * 1024) {
+    const chunks = [];
+    let held = 0;
+    return {
+        add(chunk) {
+            chunks.push(chunk);
+            held += chunk.length;
+            while (held - chunks[0].length >= limit) held -= chunks.shift().length;
+        },
+        get held() { return held; },
+        text: () => Buffer.concat(chunks).subarray(-limit).toString("utf8"),
+    };
+}
+
+export function windowsTaskkill(env, access = fs.accessSync) {
+    const root = env.SystemRoot || env.SYSTEMROOT || "C:\\Windows";
+    if (!path.win32.isAbsolute(root)) throw new Error("taskkill requires an absolute Windows system root");
+    const command = path.win32.join(root, "System32", "taskkill.exe");
+    access(command, fs.constants.F_OK);
+    return command;
+}
+
+/** Signal only a recipe-owned group, or force its Windows tree with a bounded system utility. */
+export function terminateTree(pid, signal, { platform = process.platform, kill = process.kill.bind(process), exec = execFileSync, taskkill } = {}) {
+    if (!Number.isInteger(pid) || pid <= 0) throw new Error("recipe has no valid process id");
+    if (platform === "win32") {
+        if (!taskkill) throw new Error("taskkill was not preflighted");
+        exec(taskkill, ["/PID", String(pid), "/T", "/F"], { timeout: 1000, windowsHide: true, stdio: "pipe" });
+    } else {
+        try { kill(-pid, signal); } catch (error) { if (error.code !== "ESRCH") throw error; }
+    }
+}
+
+export function runRecipe(recipe, { root, env = process.env, timeout = 600_000, onOutput = null, mergeOutput = true, inheritGroup = false, groupId = null }) {
+    return new Promise((resolve) => {
+        const kept = tailKeeper();
+        const failures = [];
+        let child, taskkill, limit, grace, drain;
+        let settled = false, closed = false, stopping = false, escalated = false, late = false;
+        let status = null, interrupted = null;
+        const handlers = new Map();
+        const record = (error) => failures.push(String(error?.message ?? error));
+        const terminate = (signal) => terminateTree(inheritGroup && process.platform !== "win32" ? groupId : child.pid, signal, { taskkill });
+        const pipes = () => { child?.stdout?.destroy(); child?.stderr?.destroy(); };
+        const settle = () => {
+            if (settled) return;
+            settled = true;
+            for (const timer of [limit, grace, drain]) clearTimeout(timer);
+            for (const [signal, handler] of handlers) process.removeListener(signal, handler);
+            const code = failures.length || late || interrupted ? null : status;
+            if (code === 0) return resolve({ id: recipe.id, outcome: "green" });
+            const why = [
+                ...failures,
+                ...(interrupted ? [`interrupted by ${interrupted}`] : []),
+                ...(late ? [`killed at its time limit of ${timeout / 1000} s`] : []),
+            ];
+            resolve({ id: recipe.id, outcome: code === null || CANNOT_RUN.has(code) ? "could not run" : "red", code,
+                output: kept.text() + (why.length ? `\n${why.join("\n")}` : ""),
+                ...(onOutput ? { diagnostics: why } : {}),
+                ...(late ? { timedOut: true } : {}),
+                ...(interrupted ? { interrupted } : {}) });
+        };
+        const hardStop = () => {
+            try { terminate("SIGKILL"); }
+            catch (error) {
+                record(error);
+                try { child.kill("SIGKILL"); } catch (error) { record(error); }
+            }
+            escalated = true;
+            if (closed) return settle();
+            drain = setTimeout(() => {
+                record(new Error("recipe did not close after forced termination"));
+                pipes();
+                child.unref();
+                settle();
+            }, 1000);
+        };
+        const stop = (signal) => {
+            if (settled) return;
+            if (signal && interrupted === null) interrupted = signal;
+            if (stopping) return;
+            stopping = true;
+            clearTimeout(limit);
+            clearTimeout(drain);
+            if (process.platform === "win32") return hardStop();
+            try { terminate(signal || "SIGTERM"); } catch (error) { record(error); }
+            // The group may outlive its leader and pipes: neither event cancels escalation.
+            grace = setTimeout(hardStop, 250);
+        };
+        try {
+            for (const signal of INTERRUPTIONS) {
+                const handler = () => stop(signal);
+                handlers.set(signal, handler);
+                process.on(signal, handler);
+            }
+            if (process.platform === "win32") taskkill = windowsTaskkill(env);
+            if (inheritGroup && process.platform !== "win32" && (!Number.isInteger(groupId) || groupId <= 1)) throw new Error("inherited recipe group is invalid");
+            child = spawn("bash", ["-c", `${mergeOutput ? "exec 2>&1\n" : ""}${inheritGroup ? "" : "export PORTULAN_RECIPE_GROUP=$$\n"}${recipe.run}`], {
+                cwd: root, env: { ...env, PORTULAN_RECIPE_MANAGED: "1" }, detached: process.platform !== "win32" && !inheritGroup, windowsHide: true, stdio: ["ignore", "pipe", "pipe"],
+            });
+        } catch (error) { record(error); settle(); return; }
+        for (const [name, stream] of [["stdout", child.stdout], ["stderr", child.stderr]]) {
+            stream.on("data", (chunk) => {
+                kept.add(chunk);
+                try { onOutput?.(name, chunk); } catch (error) { record(error); stop(); }
+            });
+            stream.on("error", (error) => { record(error); stop(); });
+        }
+        child.on("error", (error) => { record(error); if (!child.pid) settle(); else stop(); });
+        child.on("exit", (code) => {
+            status = code;
+            clearTimeout(limit);
+            if (!stopping) drain = setTimeout(() => { pipes(); settle(); }, 1000);
+        });
+        child.on("close", (code) => {
+            status = code;
+            closed = true;
+            if (!stopping || escalated) settle();
+        });
+        if (!inheritGroup) limit = setTimeout(() => { late = true; stop(); }, timeout);
+    });
+}

package/cli/recipe-set.mjs

@@ -2,7 +2,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { resolvePack, rootPlan, shadowedCopy } from "./compile.mjs";
 import { AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
@@ -23,6 +23,8 @@ const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
 /** The token a composed `run` uses to name its own pack's files. */
 const PACK_ROOT_TOKEN = "${PACK_ROOT}";
+const quote = (word) => `'${word.replaceAll("'", "'\\''")}'`;
+export const agentCommand = (command) => `${quote(process.execPath)} ${quote(path.join(path.dirname(fileURLToPath(import.meta.url)), "recipe-output.mjs"))} -- ${quote(command)}`;
 
 /** Its `:` is outside `$defs/slug`, so a composed id never equals a workspace id or `verify.default`. */
 export function composedId(packRef, id) {
@@ -115,6 +117,13 @@ export function recipeSet(manifest, options = {}) {
     if (recipes.length === 0) return refuse("the manifest yields no verify recipes — refusing to report green");
 
     const declaredDefault = manifest?.verify?.default;
+    if (options.agent) {
+        for (const recipe of recipes) {
+            recipe.run = agentCommand(recipe.run);
+            const bad = invalidRunnable(recipe.id, recipe.run, "agent executor", { requireSlug: false });
+            if (bad) return refuse(bad);
+        }
+    }
     return { ok: true, recipes, default: declaredDefault == null ? declaredDefault : String(declaredDefault) };
 }
 
@@ -228,7 +237,7 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
         stderr.write(`${err.message}\n`);
         return 2;
     }
-    const set = recipeSet(manifest, { resolve });
+    const set = recipeSet(manifest, { resolve, agent: argv.includes("--agent") });
     if (!set.ok) {
         stderr.write(`${set.reason}\n`);
         return set.exitCode;
@@ -238,5 +247,5 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
 }
 
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
-    process.exit(run(process.argv.slice(2)));
+    process.exitCode = run(process.argv.slice(2));
 }

package/cli/ritual-contexts.mjs

@@ -0,0 +1,103 @@
+// Own native settings without inventing a gate policy.
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+export const CONTEXT_CAP_ENV = "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS";
+const object = v => v !== null && typeof v === "object" && !Array.isArray(v);
+export function readContextCap(manifest, pack) {
+    const c = manifest?.contributes?.contexts;
+    if (c === undefined) return null;
+    const bad = why => { throw Error(`\`${pack}\` contributes.contexts ${why}`); };
+    if (manifest.category !== "rituals" || !pack.startsWith("rituals/")) bad("is reserved for ritual packs");
+    if (manifest?.portulan?.pack !== "1.1") bad("requires supported Pack Definition 1.1");
+    if (!object(c) || Object.keys(c).length !== 1 || !Object.hasOwn(c, "max_concurrent_subagents")) bad("requires only max_concurrent_subagents");
+    const n = c.max_concurrent_subagents;
+    if (!Number.isSafeInteger(n) || n < 1) bad("max_concurrent_subagents must be a positive safe integer");
+    return n;
+}
+export function contextCaps(contributions, unresolved = []) {
+    const sources = contributions.filter(c => c.contextCap != null).map(c => {
+        if (!Number.isSafeInteger(c.contextCap) || c.contextCap < 1) throw Error("invalid contributes.contexts count");
+        return { pack: c.pack, limit: c.contextCap, origin: c.origin ?? null, version: c.version ?? null };
+    }).sort((a, b) => a.pack.localeCompare(b.pack));
+    if (sources.length && unresolved.length) throw Error("ritual contexts cap cannot compile while composed packs remain unresolved; their contributions are unknown");
+    return { limit: sources.length ? sources.reduce((n, s) => Math.min(n, s.limit), Infinity) : null, sources, unknown: unresolved.length };
+}
+export function contextCapLines(cap) {
+    if (cap.limit === null) return cap.unknown ? ["No context cap found in resolved packs; unresolved pack contributions are unknown."] : [];
+    return [
+        `Claude Code: ${CONTEXT_CAP_ENV}=${cap.limit}, minimum of ${cap.sources.map(s => `${s.pack}=${s.limit}`).join(", ")}; compiled for ordinary fresh native Agent admission within one session.`,
+        "Parent excluded; project setting applies across rituals. Total children, requests, time and tokens are unbounded. Resumes and /subtask forks can exceed the admission limit; workflows/team agents have independent limits. Higher-precedence settings and native experimental/ultracode bypasses can defeat it. Measured on Claude Code 2.1.321; not a universal hard ceiling.",
+        "GitHub repository ruleset and AGENTS guidance: context cap not compiled by these adapters.",
+    ];
+}
+const keys = (v, required, optional = []) => object(v) && required.every(k => Object.hasOwn(v, k)) && Object.keys(v).every(k => [...required, ...optional].includes(k));
+const canonical = v => Array.isArray(v) ? v.map(canonical) : object(v) ? Object.fromEntries(Object.keys(v).sort().map(k => [k, canonical(v[k])])) : v;
+const fingerprint = v => {
+    const payload = structuredClone(v); delete payload.$portulan.digest;
+    return createHash("sha256").update(JSON.stringify(canonical(payload))).digest("hex");
+};
+const sourcesValid = sources => Array.isArray(sources) && sources.length > 0 && sources.every((s, i) =>
+    keys(s, ["pack", "limit", "origin", "version"]) && /^rituals\/[a-z0-9][a-z0-9-]*$/.test(s.pack) && Number.isSafeInteger(s.limit) && s.limit > 0 &&
+    [null, "tree", "outside-tree", "discovered"].includes(s.origin) && (s.version === null || typeof s.version === "string") &&
+    (i === 0 || sources[i - 1].pack.localeCompare(s.pack) < 0));
+const capValid = (env, sources) => keys(env, [CONTEXT_CAP_ENV]) && sourcesValid(sources) && env[CONTEXT_CAP_ENV] === String(Math.min(...sources.map(s => s.limit)));
+const commandValid = (v, action) => keys(v, ["type", "command"]) && v.type === "command" && typeof v.command === "string" && new RegExp(String.raw`^node "[^"\r\n]+[/\\]advisory\.mjs" ${action}(?: --(?:read|write-5m|write-1h|horizon|resume-tokens) [0-9.eE+-]+)*$`).test(v.command);
+const hookValid = (v, action) => Array.isArray(v) && v.length === 1 && keys(v[0], ["hooks"]) && Array.isArray(v[0].hooks) && v[0].hooks.length === 1 && commandValid(v[0].hooks[0], action);
+function adviceOwned(v) {
+    const m = v?.$portulan;
+    return keys(v, ["$portulan", "hooks", "statusLine"], ["includeGitInstructions", "promptCacheTtl", "env"]) &&
+        keys(m, ["generated", "kind", "digest", "source", "warning"], ["sessions", "spend", "packs", "contexts"]) &&
+        m.generated === "cli/compile.mjs" && m.kind === "advisory" && /^[a-f0-9]{64}$/.test(m.digest) && m.digest === fingerprint(v) &&
+        typeof m.source === "string" && !path.isAbsolute(m.source) && !m.source.split("/").includes("..") && /(?:^|\/)workspace\.json$/.test(m.source) && typeof m.warning === "string" &&
+        ["sessions", "spend"].every(k => !Object.hasOwn(m, k) || m[k] === m.source) &&
+        (!Object.hasOwn(m, "packs") || (Array.isArray(m.packs) && m.packs.length > 0 && m.packs.every((p, i) => keys(p, ["pack", "origin", "version"]) && typeof p.pack === "string" && ["tree", "outside-tree", "discovered"].includes(p.origin) && (p.version === null || typeof p.version === "string") && (i === 0 || m.packs[i - 1].pack.localeCompare(p.pack) < 0)))) &&
+        (!Object.hasOwn(v, "includeGitInstructions") || typeof v.includeGitInstructions === "boolean") && (!Object.hasOwn(v, "promptCacheTtl") || ["5m", "1h"].includes(v.promptCacheTtl)) &&
+        (Object.hasOwn(v, "env") ? capValid(v.env, m.contexts) : !Object.hasOwn(m, "contexts")) &&
+        keys(v.hooks, ["PostToolUse", "UserPromptSubmit"], ["Stop"]) && hookValid(v.hooks.PostToolUse, "tool") && hookValid(v.hooks.UserPromptSubmit, "prompt") &&
+        (!Object.hasOwn(v.hooks, "Stop") || hookValid(v.hooks.Stop, "stop")) && commandValid(v.statusLine, "status");
+}
+export function capOnlyPlan(root, cap, advice = null) {
+    const file = path.join(root, ".claude/settings.json");
+    const parent = path.dirname(file), desired = advice !== null || cap.limit !== null;
+    let parentStat;
+    try { parentStat = fs.lstatSync(parent); } catch (e) { if (e.code !== "ENOENT") throw e; }
+    if (parentStat && (!parentStat.isDirectory() || parentStat.isSymbolicLink())) {
+        if (!desired) return null;
+        throw Error("native settings parent is not an owned directory");
+    }
+    let current = null, old = null, links = 1;
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            if (!desired) return null;
+            throw Error("native settings is not a regular owned file");
+        }
+        links = stat.nlink;
+        current = fs.readFileSync(file, "utf8");
+        try { old = JSON.parse(current); } catch { /* foreign */ }
+    } catch (e) { if (e.code !== "ENOENT") throw e; }
+    const generated = old?.$portulan?.generated === "cli/compile.mjs";
+    const marked = generated && old.$portulan.kind === "ritual-contexts";
+    const advisory = generated && old.$portulan.kind === "advisory";
+    if (advisory && advice === null) return null;
+    if (links !== 1 && (desired || marked)) throw Error("native settings is multiply linked; refusing replacement or removal");
+    if (cap.limit === null && !marked && !advisory && generated && Object.hasOwn(old?.env ?? {}, CONTEXT_CAP_ENV)) throw Error("previous policy-generated settings retain a stale context cap after policy removal; preserve and resolve those settings explicitly, or restore the policy and recompile");
+    const legacy = marked && keys(old, ["$portulan", "env"]) && keys(old.$portulan, ["generated", "kind", "sources"]) && capValid(old.env, old.$portulan.sources);
+    const owned = legacy || (advisory && adviceOwned(old));
+    if (current !== null && !owned && (desired || marked)) throw Error("native compile refuses settings with edited, unrelated or unowned content; preserve it and resolve ownership explicitly");
+    if (!desired && !owned) return null;
+    const value = advice !== null ? structuredClone(advice) : cap.limit === null ? null : {
+        $portulan: { generated: "cli/compile.mjs", kind: "ritual-contexts", sources: cap.sources },
+        env: { [CONTEXT_CAP_ENV]: String(cap.limit) },
+    };
+    if (advice !== null) { value.$portulan.kind = "advisory"; value.$portulan.digest = fingerprint(value); }
+    return { file, current, text: value === null ? null : JSON.stringify(value, null, 2) + "\n" };
+}
+export function emitCapOnly(plan, { check, say }) {
+    if (!plan || plan.current === plan.text) return 0;
+    if (check) { say("RED — native Claude settings drifted; recompile"); return 1; }
+    if (plan.text === null) { fs.rmSync(plan.file); say(`removed ${plan.file} — no ritual cap remains`); }
+    else { fs.mkdirSync(path.dirname(plan.file), { recursive: true }); fs.writeFileSync(plan.file, plan.text); say(`wrote ${plan.file}`); }
+    return 0;
+}

package/cli/sessions.mjs

@@ -74,7 +74,8 @@ export function sessionsLine(manifest) {
     parts.push(multipliersWords(spend.multipliers) ?? "multipliers the general ones");
     const horizon = horizonWords(spend.horizon);
     if (horizon !== null) parts.push(horizon);
-    if (spend.restart === "block") parts.push("a turn's end held once at the restart threshold");
+    if (spend.resume?.tokens !== undefined) parts.push(`resume expense ${spend.resume.tokens} input-equivalent tokens`);
+    if (spend.restart === "block") parts.push("a turn's end held once only with explicit horizon, resume expense and positive estimated savings");
     if (lifetime === null && workspace.kind === "repository") {
         parts.push("`portulan upgrade` prints the five-minute lifetime's offer and its trade-off");
     }

package/cli/spend-analysis.mjs

@@ -0,0 +1,111 @@
+// Class indices compare stated assumptions, never bills or route quality.
+import { CLASSES, GENERAL_READ, WRITE_BY_LIFETIME, RECORDED_ROLES, SPEND_FIGURES, restartSaving } from "./ledger.mjs";
+
+const classes = ["uncached", "written", "read", "output"];
+const efforts = ["low", "medium", "high", "max"];
+const families = ["opus", "sonnet", "haiku", "fable", "mythos"];
+const causes = ["compaction", "model change", "effort change", "lifetime lapsed", "unexplained"];
+const grouped = n => n.toLocaleString("en-US", { maximumFractionDigits: 0 });
+const estimate = n => n.toLocaleString("en-US", { maximumSignificantDigits: 8 });
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const count = n => Number.isSafeInteger(n) && n >= 0;
+const leaders = scores => {
+    const max = Math.max(...Object.values(scores));
+    return max <= 0 ? [] : classes.filter(k => Math.abs(scores[k] - max) <= max * Number.EPSILON * 8);
+};
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+function scopeLines(label, contexts, rates) {
+    const total = Object.fromEntries(CLASSES.map(k => [k, 0]));
+    const roles = new Map(), inferred = Object.fromEntries(causes.map(k => [k, 0]));
+    let contributing = 0, requests = 0;
+    try {
+        for (const c of contexts) {
+            if (c.requests.length) contributing++;
+            for (const r of c.requests) {
+                if (r.usageMissing || r.usageUnsafe) return [`${label}: class analysis unassessed — usage counters are missing or invalid; totals are partial.`];
+                requests++;
+                for (const k of CLASSES) {
+                    if (!count(r[k]) || !count(total[k] + r[k])) throw Error();
+                    total[k] += r[k];
+                }
+                if (r.rebuild) inferred[causes.includes(r.rebuild.cause) ? r.rebuild.cause : "unexplained"]++;
+                const role = RECORDED_ROLES.includes(r.role) ? r.role : c.agent === null ? "main" : "unattributed subagent";
+                if (!roles.has(role)) roles.set(role, { output: 0, efforts: {}, models: {} });
+                const into = roles.get(role), effort = efforts.includes(r.effort) ? r.effort : "unknown";
+                const family = families.find(f => typeof r.model === "string" && new RegExp(`^(?:claude-)?${f}(?:-|$)`).test(r.model)) ?? "unknown";
+                into.output += r.output;
+                into.efforts[effort] = (into.efforts[effort] ?? 0) + r.output;
+                into.models[family] = (into.models[family] ?? 0) + r.output;
+            }
+        }
+        if (!requests) return [`${label}: no host requests in this scope; local receipts excluded.`];
+        const written = total.written1h + total.written5m + total.writtenUnknown;
+        if (!count(written)) throw Error();
+        const knownWrites = total.written1h * rates.write["1h"] + total.written5m * rates.write["5m"];
+        const low = { uncached: total.uncached, written: knownWrites + total.writtenUnknown * Math.min(...Object.values(rates.write)), read: total.read * rates.read, output: total.output * 5 };
+        const high = { ...low, written: knownWrites + total.writtenUnknown * Math.max(...Object.values(rates.write)) };
+        if (![...Object.values(low), ...Object.values(high)].every(Number.isFinite)) throw Error();
+        const first = leaders(low), last = leaders(high), certain = same(first, last);
+        const index = classes.map(k => `${k} ~${estimate(low[k])}${low[k] === high[k] ? "" : `..${estimate(high[k])}`}`).join(", ");
+        const verdict = certain ? first.length ? `dominant ${first.join(" + ")}${first.length > 1 ? " (tie)" : ""}` : "no nonzero dominant class"
+            : `uncertain dominance (lower-bound leaders ${first.join(" + ")}; upper-bound leaders ${last.join(" + ")})`;
+        const lines = [
+            `${label} tokens: ${grouped(requests)} requests; uncached ${grouped(total.uncached)}, written ${grouped(written)}, read ${grouped(total.read)}, output ${grouped(total.output)}.`,
+            `${label} class index: ${index}; ${verdict}.`,
+        ];
+        if (total.writtenUnknown) lines.push(`${label}: ${grouped(total.writtenUnknown)} write tokens have unstated TTL; index spans min/max of both write rates.`);
+        for (const key of new Set([...first, ...last])) {
+            const lever = {
+                read: "session length and tool output; compare a restart only with supported estimates",
+                written: `fresh contexts, TTL gaps and cache busts; ${grouped(contributing)} contributing contexts; inferred rebuilds: ${causes.map(k => `${k} ${inferred[k]}`).join(", ")}`,
+                output: "effort and model by recorded role; alternate-route savings unpriced without quality evidence",
+                uncached: "caching may not be engaged; inspect uncached tails and cache controls",
+            }[key];
+            lines.push(`${label} ${key} lever: ${lever}.`);
+        }
+        if (first.includes("output") || last.includes("output")) {
+            for (const [role, r] of [...roles].sort(([a], [b]) => compare(a, b))) {
+                const histogram = values => Object.entries(values).filter(([, n]) => n > 0).sort(([a], [b]) => compare(a, b)).map(([k, n]) => `${k} ${grouped(n)}`).join(", ") || "none";
+                lines.push(`${label} output role ${role}: ${grouped(r.output)} tokens; recorded effort ${histogram(r.efforts)}; model family ${histogram(r.models)}.`);
+            }
+        }
+        return lines;
+    } catch { return [`${label}: class analysis unassessed — token counts or estimated indices are unsafe or overflow.`]; }
+}
+
+function counterfactual(figure) {
+    if (figure?.unavailable === "branch-scope") return "restart counterfactual unpriced: latest session tail is outside branch-owned scope.";
+    if (figure?.unavailable === "usage") return "restart counterfactual unpriced: input usage counters are invalid or incomplete.";
+    const unavailable = "restart counterfactual unpriced: explicit horizon, resume expense and usable latest-branch figures required; model/effort and TTL alternatives are not priced here.";
+    if (!figure?.horizonDeclared || figure.resume == null) return unavailable;
+    const { fresh, context, horizon, resume } = figure, read = figure.multipliers?.read, write = figure.multipliers?.write;
+    if (![fresh, context, horizon, resume, read, write].every(Number.isFinite) || fresh <= 0 || context < 0 || horizon <= 0 || resume < 0 || read <= 0 || write <= 0) return unavailable;
+    try {
+        const continuing = horizon * read * context, restarting = horizon * read * fresh + write * fresh + resume;
+        const saving = restartSaving({ fresh, context, horizon, resume, read, write });
+        if (![continuing, restarting].every(Number.isFinite)) return unavailable;
+        return `restart counterfactual: continue reads ~${estimate(continuing)} vs restart write + reads + resume ~${estimate(restarting)} input-equivalents; estimated saving ~${estimate(saving)}${saving <= 0 ? " (no positive saving)" : ""}; fixed-context comparison using caller-supplied horizon/resume, not a forecast.`;
+    } catch { return unavailable; }
+}
+
+export function spendAnalysis(report) {
+    const contexts = report.collected.contexts;
+    if (!contexts.some(c => c.requests.length)) return [];
+    const rates = report.priced?.declared ?? { read: GENERAL_READ, write: WRITE_BY_LIFETIME };
+    if (!SPEND_FIGURES.read.holds(rates.read) || ["5m", "1h"].some(k => !SPEND_FIGURES.write.holds(rates.write?.[k]))) return ["class analysis unassessed — invalid rate assumptions."];
+    const sessions = new Map();
+    for (const c of contexts) for (const r of c.requests) {
+        if (Number.isFinite(r.at)) sessions.set(c.session, Math.max(sessions.get(c.session) ?? -Infinity, r.at));
+    }
+    const chosen = [...sessions].sort(([a, x], [b, y]) => y - x || compare(String(a), String(b))).slice(0, 5).map(([id]) => id);
+    const undated = new Set(contexts.map(c => c.session).filter(id => !sessions.has(id))).size;
+    const branch = contexts.map(c => ({ ...c, requests: c.requests.filter(r => r.branch === report.branch) }));
+    return [
+        `class index assumptions: uniform input rate across models; uncached 1×, read ${rates.read}×, writes 5m ${rates.write["5m"]}× / 1h ${rates.write["1h"]}× (${report.priced?.declared ? "declared" : "general, undeclared"}); output 5× assumed. Estimated normalized input-equivalents, not monetary dominance or a bill; local receipts excluded${report.collected.malformed ? "; partial usage data" : ""}.`,
+        ...scopeLines("branch", branch, rates),
+        `recent selection: latest ${chosen.length} of at most 5 timed owned parent sessions across branches/worktrees; latest main/child timestamp, session-ID tie break; all owned requests in selected sessions included; ${undated} wholly undated sessions excluded.`,
+        ...scopeLines("recent", contexts.filter(c => chosen.includes(c.session)), rates),
+        counterfactual(report.restart),
+    ];
+}

package/cli/spend-offer.md

@@ -0,0 +1,53 @@
+# Init's spend offer
+
+`init` offers `spend.multipliers` and `spend.horizon.requests` independently. Each is
+declared only after accepting its interview answer or providing `--multipliers
+'<JSON>'` / `--horizon <positive integer>`. The answers file takes the same keys as
+strings; flags win. A declined offer leaves the key absent. A pointer has no spend
+policy and refuses these options. Either declaration requires spec 2.12.
+
+For Claude Code, the helper reads model IDs, timestamps, repository paths and usage
+presence from local assistant records. It selects the latest main-context record
+for this repository, ignoring synthetic records, sidechains, separate subagents
+and foreign paths. Conflicting latest models, missing models or unreadable records
+give a general offer with a reason. Malformed lines are counted and disclosed.
+Conversation content is not inspected. A configured model does not replace a
+recorded one. The last recorded model need not be the next session's model.
+
+The offer tries these sources in order:
+
+1. A matching `modelPricing.overrides` row in the system managed settings file:
+   `/Library/Application Support/ClaudeCode/managed-settings.json` on macOS,
+   `/etc/claude-code/managed-settings.json` on Linux, or
+   `C:\Program Files\ClaudeCode\managed-settings.json` on Windows. Exact model IDs
+   precede supported canonical IDs with an eight-digit snapshot suffix removed.
+   All four rates must be finite numbers in 0–10000. `input` and `cacheRead` must
+   also be positive, the read/input ratio at most one, and write/input at least
+   one, for `spend` to represent them. One `cacheWrite` rate supplies both
+   lifetimes; a global multiplier cancels in ratios. Unusable rows fall through
+   with a reason. User/project/local `modelPricing` settings are ignored, as the
+   host ignores them. See the [host contract](https://code.claude.com/docs/en/settings-reference#modelpricing).
+2. The table embedded in `spend-offer.mjs`, checked **2026-11-09** against the
+   [vendor's price page](https://platform.claude.com/docs/en/about-claude/pricing).
+   The explicit Claude API model IDs use cache reads at 0.025 for Fable/Mythos
+   5.1/5.2, 0.05 for Opus/Sonnet 5.5, and 0.1 for the other listed IDs; writes are
+   1.25 at five minutes and 2 at one hour. This is a dated offer, updated with the
+   product, without a runtime fetch. Unknown IDs and provider-specific aliases
+   are not guessed. Only known canonical IDs and their eight-digit snapshots
+   normalize; custom gateway overrides require an exact match.
+3. General figures: read 0.1, writes 1.25/2. The horizon offered is 20 requests
+   still to go, which the task or workspace should replace with its own estimate.
+
+The file is **not an effective-settings resolver**. A nonempty JSON drop-in set
+at `managed-settings.d` makes the file source unavailable rather than pretending
+to merge it. Remote managed settings, MDM/plist/registry, policy helpers and
+embedding-host sources are not inspected; they can supersede the file. The offer
+names that condition. Native Windows discovery is not demonstrated here. See
+[managed source precedence](https://code.claude.com/docs/en/managed-settings).
+Other hosts and unsupported models get the general offer. A declaration is the
+workspace's value, not a verified billing rate.
+
+`spend-offer.test.mjs` uses injected local transcript and managed-file paths. All
+verification is offline; no recipe reads the operator's usage records or managed
+pricing. Accepted drafts are validated by `doctor`, and `compile` carries their
+figures onto advisory commands.

package/cli/spend-offer.mjs

@@ -0,0 +1,93 @@
+// Local evidence for init's optional spend declaration.
+import fs from "node:fs";
+import path from "node:path";
+import { GENERAL_READ, WRITE_BY_LIFETIME, HORIZON, hostPaths, transcriptFiles, readSpend } from "./ledger.mjs";
+import { isInside } from "./inside.mjs";
+
+export const PRICE_DATE = "2026-11-09";
+export const PRICE_SOURCE = "https://platform.claude.com/docs/en/about-claude/pricing";
+export const PRICE_READS = {
+    "claude-fable-5-2": 0.025, "claude-mythos-5-2": 0.025,
+    "claude-fable-5-1": 0.025, "claude-mythos-5-1": 0.025,
+    "claude-opus-5-5": 0.05, "claude-sonnet-5-5": 0.05,
+    "claude-haiku-5-5": 0.1, "claude-fable-5": 0.1, "claude-mythos-5": 0.1,
+    "claude-opus-5": 0.1, "claude-sonnet-5": 0.1,
+    "claude-opus-4-8": 0.1, "claude-opus-4-7": 0.1, "claude-opus-4-6": 0.1,
+    "claude-opus-4-5": 0.1, "claude-opus-4-1": 0.1, "claude-opus-4": 0.1,
+    "claude-sonnet-4-6": 0.1, "claude-sonnet-4-5": 0.1, "claude-sonnet-4": 0.1,
+    "claude-haiku-4-5": 0.1,
+};
+
+export function recordedModel(target, projects) {
+    let latest = -Infinity;
+    const models = new Set();
+    let malformed = 0;
+    try {
+        for (const { file, agent } of transcriptFiles(projects, [target])) {
+            if (agent !== null) continue;
+            for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+                if (!line.trim()) continue;
+                let r;
+                try { r = JSON.parse(line); } catch { malformed++; continue; }
+                if (r?.type !== "assistant" || r.isSidechain || r.agentId || !r.message?.usage || typeof r.message.usage !== "object" || Array.isArray(r.message.usage) || r.message.model === "<synthetic>" || typeof r.timestamp !== "string" || typeof r.cwd !== "string" || !path.isAbsolute(r.cwd) || !isInside(target, r.cwd)) continue;
+                const at = Date.parse(r.timestamp);
+                if (!Number.isFinite(at) || at < latest) continue;
+                if (at > latest) { latest = at; models.clear(); }
+                models.add(typeof r.message.model === "string" && r.message.model ? r.message.model : null);
+            }
+        }
+    } catch (error) {
+        return { model: null, reason: `recorded model could not be read (${error.code ?? "unreadable"})` };
+    }
+    const model = models.size === 1 ? [...models][0] : null;
+    const reason = model === null ? (models.size > 1 ? "conflicting latest recorded models" : "no recorded model") : `last recorded model ${JSON.stringify(model)}`;
+    return { model, reason: reason + (malformed ? `; ignored ${malformed} malformed record(s)` : "") };
+}
+
+export function managedPricingFile(platform = process.platform) {
+    if (platform === "darwin") return "/Library/Application Support/ClaudeCode/managed-settings.json";
+    if (platform === "win32") return "C:\\Program Files\\ClaudeCode\\managed-settings.json";
+    return "/etc/claude-code/managed-settings.json";
+}
+
+function hostMultipliers(model, canonical, file) {
+    if (file === null) return { reason: "file-based managed pricing not supplied" };
+    try {
+        const dropins = path.join(path.dirname(file), "managed-settings.d");
+        if (fs.existsSync(dropins) && fs.readdirSync(dropins).some(name => name.endsWith(".json"))) return { reason: "managed-settings.d may supersede file pricing; drop-ins are not resolved" };
+        if (!fs.statSync(file).isFile()) return { reason: "managed pricing is not a regular file" };
+        const pricing = JSON.parse(fs.readFileSync(file, "utf8"))?.modelPricing;
+        const overrides = pricing?.overrides;
+        if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) return { reason: "no file-based modelPricing override" };
+        const row = Object.hasOwn(overrides, model) ? overrides[model] : canonical !== null && Object.hasOwn(overrides, canonical) ? overrides[canonical] : null;
+        if (row === null) return { reason: "no matching file-based modelPricing override" };
+        if (!row || ["input", "output", "cacheRead", "cacheWrite"].some(key => typeof row[key] !== "number" || !Number.isFinite(row[key]) || row[key] < 0 || row[key] > 10000)) return { reason: "invalid file-based modelPricing override" };
+        try {
+            const multipliers = { read: row.cacheRead / row.input, write: { "5m": row.cacheWrite / row.input, "1h": row.cacheWrite / row.input } };
+            readSpend({ multipliers }, "host offer");
+            return { multipliers };
+        } catch { return { reason: "file-based modelPricing override is unrepresentable by spend" }; }
+    } catch (error) {
+        return { reason: error.code === "ENOENT" ? "no file-based managed pricing" : `file-based managed pricing unreadable (${error.code ?? "invalid JSON"})` };
+    }
+}
+
+export function spendOffer(target, options = {}) {
+    const paths = hostPaths(options.env, options.home);
+    const recorded = options.projects !== undefined ? recordedModel(target, options.projects) : paths.why ? { model: null, reason: "host record path is not absolute" } : recordedModel(target, paths.projects);
+    const { model } = recorded;
+    const normalized = model?.replace(/-\d{8}$/, "");
+    const canonical = normalized && Object.hasOwn(PRICE_READS, normalized) ? normalized : null;
+    const host = model === null ? { reason: "host pricing needs a recorded model" } : hostMultipliers(model, canonical, options.managedFile === undefined ? managedPricingFile(options.platform) : options.managedFile);
+    const source = host.multipliers ? "file-based managed modelPricing (conditional on this file being active)" : canonical !== null ? `Claude Code table ${PRICE_DATE}, ${PRICE_SOURCE}` : "general multipliers";
+    const multipliers = host.multipliers ?? { read: canonical === null ? GENERAL_READ : PRICE_READS[canonical], write: { ...WRITE_BY_LIFETIME } };
+    return { multipliers, horizon: HORIZON, source, reason: `${recorded.reason}; ${host.reason ?? "one cacheWrite rate supplies both lifetimes; a global multiplier cancels"}` };
+}
+
+export function spendOfferLines(offer) {
+    return [
+        `spend.multipliers offer ${JSON.stringify(offer.multipliers)} — ${offer.source}; ${offer.reason}`,
+        `spend.horizon offer {"requests":${offer.horizon}} — requests still to go, not requests already used; choose a task's expected remainder`,
+        "Only accepted answers or explicit --multipliers '<JSON>' / --horizon <requests> declare these at spec 2.12. Remote, MDM/registry, helper and embedding-host pricing are not inspected; other providers and unsupported model IDs use general figures. Confirm against your rates and next model.",
+    ];
+}