@sleepy_panda_srl/portulan 0.2.0 → 0.4.0

package/cli/recipe-output.mjs

@@ -0,0 +1,91 @@
+// Agent output for any recipe: one green count, complete failure streams.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { execFileSync } from "node:child_process";
+import { runRecipe } from "./recipe-runner.mjs";
+
+function spools(tmpdir) {
+    const dir = fs.mkdtempSync(path.join(tmpdir, "portulan-recipe-output-"));
+    const descriptors = [];
+    try {
+        for (const name of ["stdout", "stderr"]) {
+            const file = path.join(dir, name);
+            descriptors.push(fs.openSync(file, "wx+", 0o600));
+            fs.unlinkSync(file);
+        }
+        fs.rmdirSync(dir);
+        return descriptors;
+    } catch (error) {
+        for (const fd of descriptors) { try { fs.closeSync(fd); } catch {} }
+        fs.rmSync(dir, { recursive: true, force: true });
+        throw error;
+    }
+}
+
+async function replay(fd, destination) {
+    function* chunks() {
+        const buffer = Buffer.alloc(64 * 1024);
+        let offset = 0;
+        for (;;) {
+            const bytes = fs.readSync(fd, buffer, 0, buffer.length, offset);
+            if (bytes === 0) break;
+            offset += bytes;
+            yield Buffer.from(buffer.subarray(0, bytes));
+        }
+    }
+    await pipeline(Readable.from(chunks()), destination, { end: false });
+}
+
+export async function execute(command, { root = process.cwd(), env = process.env, tmpdir = os.tmpdir(), stdout = process.stdout, stderr = process.stderr, timeout = 600_000 } = {}) {
+    let descriptors = [];
+    try {
+        if (typeof command !== "string" || !command.trim()) throw new Error("one nonempty recipe command is required");
+        descriptors = spools(tmpdir);
+        const inherited = env.PORTULAN_RECIPE_MANAGED === "1";
+        const groupId = Number(env.PORTULAN_RECIPE_GROUP);
+        if (inherited && process.platform !== "win32") {
+            const actual = Number(execFileSync("ps", ["-o", "pgid=", "-p", String(process.pid)], { encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "pipe"] }).trim());
+            if (!Number.isInteger(groupId) || groupId <= 1 || actual !== groupId) throw new Error("inherited recipe group does not own this executor");
+        }
+        const result = await runRecipe({ id: "recipe", run: command }, {
+            root, env, timeout: inherited ? 0 : timeout, mergeOutput: false, inheritGroup: inherited, groupId,
+            onOutput: (name, chunk) => {
+                const fd = descriptors[name === "stdout" ? 0 : 1];
+                let offset = 0;
+                while (offset < chunk.length) {
+                    let wrote;
+                    try { wrote = fs.writeSync(fd, chunk, offset, chunk.length - offset); }
+                    catch (error) { stderr.write(`recipe-output: could not run — ${error.message}\n`); throw error; }
+                    if (wrote <= 0) throw new Error("output spool made no write progress");
+                    offset += wrote;
+                }
+            },
+        });
+        if (result.outcome !== "green") {
+            await replay(descriptors[0], stdout);
+            await replay(descriptors[1], stderr);
+            if (result.diagnostics?.length) stderr.write(`recipe-output: could not run — ${result.diagnostics.join("; ")}\n`);
+        }
+        for (const fd of descriptors) fs.closeSync(fd);
+        descriptors = [];
+        if (result.outcome === "green") { await pipeline(Readable.from(["GREEN — 1 recipe passed\n"]), stdout, { end: false }); return 0; }
+        return result.code ?? 2;
+    } catch (error) {
+        stderr.write(`recipe-output: could not run — ${error.message}\n`);
+        return 2;
+    } finally {
+        for (const fd of descriptors) { try { fs.closeSync(fd); } catch {} }
+    }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    const args = process.argv.slice(2);
+    if (args.length !== 2 || args[0] !== "--") {
+        process.stderr.write("usage: node cli/recipe-output.mjs -- <recipe-command>\n");
+        process.exitCode = 2;
+    } else process.exitCode = await execute(args[1]);
+}

package/cli/recipe-runner.md

@@ -0,0 +1,68 @@
+# Recipe execution and cleanup
+
+`finish` and the Stop-gate share `recipe-runner.mjs`. Finish allows ten minutes.
+Stop allows ninety seconds unless its trusted workspace declares
+`verify.stopTimeout` in seconds at spec 2.14 or later. Recompile after declaring it:
+the compiled Stop hook allows that deadline plus sixty seconds for other checks
+and cleanup. An invalid declaration prevents execution. Output is drained as it arrives; only the last
+64 KiB and at most one incoming chunk are retained.
+
+Stop reads both command and deadline from the hook-told workspace and runs in the
+hook-told root. The payload's session worktree selects its record/work checks,
+and cannot choose executable policy. Verification of that other worktree remains
+the separate #311 trust question; a green here covers the told tree.
+
+After three actual recipe refusals in a session, further Stops skip that recipe
+and release explicitly unverified/RED. Repairing files then does not resume
+automatic verification in that session: run it explicitly before claiming done,
+or use a new session. A still-pending handoff at its cap, nine total refusals, or
+the thirteenth consecutive hook-provoked Stop also suppresses recipe execution.
+Skipped runs never charge a recipe failure or become green evidence. A handoff
+that clears before the other bounds allows execution again; ordinary Stops reset
+the chain, and a measured green before the recipe cap clears its streak.
+
+The deadline tests inject a long selection and exercise a short live timeout;
+they demonstrate configuration and cleanup, not a real five-minute recipe or a
+live host's outer-timeout enforcement. Counter-file failure/concurrent-write
+limits remain; this is not a cross-session scheduler or a cache of green trees.
+
+On POSIX, Bash starts in a detached process group. A timeout sends TERM to the group;
+SIGINT, SIGTERM and SIGHUP received by the active runner are forwarded to it. After
+250 ms the runner sends KILL to that group, even if Bash has already exited or closed
+its pipes. Repeated interruptions do not restart that grace period. Cleanup allows
+one further second for closure and reports failures as could-not-run. Finish retains
+an observed interruption, stops its recipe loop, rolls back its provisional commit
+and pushes nothing.
+
+On Windows, the runner checks an absolute system `taskkill.exe` path before starting
+Bash. Cleanup invokes `/PID <owned pid> /T /F` with a one-second command timeout;
+this is forced tree termination rather than POSIX signal forwarding. Missing tools
+and termination errors produce could-not-run diagnostics. Command construction and
+error paths have unit controls here; native Windows execution has not been tested.
+
+A normally exiting recipe keeps the existing behavior: inherited pipes are drained
+for at most one second, and background processes can continue. Descendants that
+intentionally escape the POSIX group are outside its cleanup. OS signal denial,
+runner SIGKILL and failures outside active recipe execution cannot promise cleanup
+or commit rollback. This runner does not impose a deadline on finish's other Git
+operations.
+
+`recipe-set --agent` wraps each command in `recipe-output.mjs`. That executor
+spools stdout and stderr separately to private descriptors, unlinks their names
+before starting the child, and replays all bytes on failure. Green is one counted
+line. The runner's ordinary tail remains bounded; the executor's failure stream
+is complete at its own boundary. Output capture, replay or setup failures return
+could-not-run, never green.
+
+The runner marks the environment of its owned child. A nested executor shares
+that process group and delegates its deadline to the outer runner. On POSIX it
+checks its actual group with `ps` before inheriting ownership, so the outer
+timeout or interruption reaches every descendant even if the executor is killed.
+An inner capture failure also terminates that owned group. Anonymous descriptors
+leave no named temporary logs behind on a hard kill. Standalone executors own
+their own recipe group and a ten-minute deadline. Native Windows execution of
+this output mode remains untested, as does its forced-termination filesystem
+behavior; inability to create anonymous spools refuses execution.
+
+The platform mechanisms follow [Node's detached-process documentation](https://nodejs.org/api/child_process.html#optionsdetached)
+and [Microsoft's taskkill reference](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/taskkill).

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/review-meter.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// The review-loop meter: the figures that bound this repository's review loop, derived from its reviews.
+// The review-loop meter: the historical figures of this repository's Copilot review loop, derived from its reviews.
 //
 // Fix-rounds are not derivable from the API: whether a push answers a submission is a fact about its contents.
 
@@ -13,7 +13,7 @@ export const SNAPSHOT_VERSION = "1";
 // A prefix, not an equality: the reviewer is `copilot-pull-request-reviewer[bot]` on reviews and `Copilot` on comments.
 export const REVIEWER_PREFIX = "copilot";
 
-// The review-loop rule retires once submissions per pull request stay below this for a full milestone.
+// The retirement threshold the review-loop rule stated: submissions per pull request below this for a full milestone.
 export const RETIRE_THRESHOLD = 2.0;
 
 const isReviewer = (login) =>
@@ -174,10 +174,14 @@ export function renderRegister(m) {
     lines.push("> it is regenerated and byte-compared, so a hand-edit survives exactly until the next run.");
     lines.push(">");
     lines.push("> **Every figure here is in SUBMISSION units** — every review the reviewer submits, one");
-    lines.push("> per push, including on the branch as opened. It is not the fix-round unit that");
-    lines.push("> `../../.portulan/memory/a-review-loop-needs-a-bound.md` rule 4 bounds, and no figure");
-    lines.push("> here may be read as one. See `../../cli/review-meter.mjs` for why fix-rounds are not");
-    lines.push("> derivable from the API at all.");
+    lines.push("> per push, including on the branch as opened. It is not the fix-round unit that rule 4");
+    lines.push("> of the retired `a-review-loop-needs-a-bound.md` bounded, and no figure here may be read");
+    lines.push("> as one. See `../../cli/review-meter.mjs` for why fix-rounds are not derivable from the");
+    lines.push("> API at all.");
+    lines.push(">");
+    lines.push("> **This register is historical.** It measures the Copilot review loop, which left this");
+    lines.push("> repository's review path on 2026-10-30, by the maintainer's decision; the record that");
+    lines.push("> bounded the loop retired with it.");
     lines.push("");
     lines.push(`- **Repository:** \`${m.repository}\``);
     lines.push(`- **Captured:** ${m.captured}`);
@@ -210,8 +214,9 @@ export function renderRegister(m) {
     lines.push("## Against the record's own retirement threshold");
     lines.push("");
     lines.push(
-        `\`a-review-loop-needs-a-bound.md\` retires when submissions per pull request measures below ` +
-            `**${RETIRE_THRESHOLD.toFixed(1)}** for a full milestone. This window measures ` +
+        `\`a-review-loop-needs-a-bound.md\` was to retire when submissions per pull request measured below ` +
+            `**${RETIRE_THRESHOLD.toFixed(1)}** for a full milestone, and retired on 2026-10-30 on its other ` +
+            `condition, Copilot review leaving the review path. This window measures ` +
             `**${round2(m.submissionsPerPullRequest)}**, which is ` +
             `${m.belowRetireThreshold === null ? "unmeasured" : m.belowRetireThreshold ? "**below**" : "**at or above**"} it.`,
     );
@@ -221,7 +226,7 @@ export function renderRegister(m) {
             "field the API carries, so this tool measures a window of merged pull requests and the " +
             "record's *for a full milestone* clause is not evaluated here. Reading this row as the " +
             "retirement condition met would be reading a different measure than the one the record " +
-            "states.",
+            "stated.",
     );
     lines.push("");
     lines.push("## Per pull request");

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),
+    ];
+}