@sleepy_panda_srl/portulan 0.2.0 → 0.3.0

package/cli/drills.mjs

@@ -54,7 +54,7 @@ export const NOT_DRILLED = [
         why: "deliberately not a verify recipe — `../.portulan/identity.md` argues why: CI installs nothing, so declaring it would make a recipe that exits 2 on every run. It is checked at the supervised checkpoints and before a release, which is a rail on no calendar, and that cost is already stated in `../.portulan/verify/README.md`.",
     },
     {
-        rail: "Dependabot, the `copilot auto-review` ruleset, and `pr-labels`",
+        rail: "Dependabot and `pr-labels`",
         why: "platform watchers whose triggering condition is an event this repository cannot manufacture on a schedule. `0007`'s own honest limit applies — not every watcher can be forced red safely — and each carries its own recorded observation instead.",
     },
     {
@@ -163,7 +163,7 @@ export const DRILLS = [
         },
         exit: 1,
         tell: "fixture(s) failed",
-        why: "The jq programs the merge gates branch on are executed rather than described. A filter that silently changed shape would take the label gate down with it.",
+        why: "The jq programs the label gate branches on are executed rather than described. A filter that silently changed shape would take the label gate down with it.",
     },
     {
         rail: "index",
@@ -199,6 +199,17 @@ export const DRILLS = [
         tell: "does not reproduce",
         why: "The host writes one usage record per content block, so a reader that stops deduplicating by message id multiplies every figure by the blocks per request and still prints plausible numbers. The fixture's known totals are the only thing that tells those numbers from the true ones.",
     },
+    {
+        rail: "ledger",
+        perturb: {
+            file: "cli/ledger.mjs",
+            find: "if (!calls.has(result.call)) continue;",
+            replace: "if (result.call === null) continue;",
+        },
+        exit: 1,
+        tell: "✗ fixture: local is",
+        why: "A local worker's subagent reports its receipt back to the session that delegated it, so a reader that takes a receipt from any tool result counts the same local work twice, once from the Bash call that ran it and once from the report quoting it, and the hybrid line still reads like a figure. Only the hybrid fixture's known receipt count tells the two apart.",
+    },
     {
         rail: "control-chars",
         perturb: {
@@ -248,7 +259,7 @@ export const DRILLS = [
         rail: "pack-identity",
         perturb: {
             file: "README.md",
-            find: "**Current release: `0.2.0`**",
+            find: "**Current release: `0.3.0`**",
             replace: "**Current release: `0.1.3`** <!-- the drill edited this and did not stage it -->",
         },
         stage: false,
@@ -332,7 +343,7 @@ export const DRILLS = [
         rail: "version-carriers",
         perturb: {
             file: "README.md",
-            find: "**Current release: `0.2.0`**",
+            find: "**Current release: `0.3.0`**",
             replace: "**Current release: `0.1.3`**",
         },
         // Staged: this rail reads the index (`git show :<path>`), so an unstaged edit is invisible to it.
@@ -458,6 +469,17 @@ export const DRILLS = [
         tell: "is a tag or branch, not a commit",
         why: "The composed pack's own rail, drilled from the adopting workspace exactly as a workspace-owned one is — which is the property milestone 7's composition amendment bought and nothing else here re-checks.",
     },
+    {
+        rail: "tools/local-llm:runner-rails",
+        perturb: {
+            file: "packs/tools/local-llm/runner/local-llm.mjs",
+            find: "    if (!allowRemote && !LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase())) {",
+            replace: "    if (!allowRemote && false) {",
+        },
+        exit: 1,
+        tell: "non-loopback endpoint was not refused by assertLoopback",
+        why: "Loopback is the rail that keeps a local worker's context on the machine, and the runner holds it in code rather than in any permission rule the compiler emits, so a guard that stopped refusing would leave every other rail green. The drill removes the refusal and requires the pack's own recipe to see it.",
+    },
 
     // ------------------------------------------------------- the coverage rail, which is itself a rail
     {

package/cli/ledger.mjs

@@ -120,10 +120,60 @@ const writtenOf = (r) => r.written1h + r.written5m + r.writtenUnknown;
 
 const chainOf = (r) => (r.sidechain ? `agent:${r.agent ?? ""}` : "session");
 
+/** The local runner's receipt format, a whole line or nothing: a format, so any line that matches it is read as one. */
+const RECEIPT =
+    /^OK mode=([a-z]+) model=(\S+)(?: target=.+?)? attempts=([1-9]\d*) in=(?:(0|[1-9]\d*)t|\?) out=(?:(0|[1-9]\d*)t|\?) time=(?:(0|[1-9]\d*)ms|\?) rate=(?:(?:0|[1-9]\d*)(?:\.\d)?tok\/s|\?) spend=\$0\.00$/;
+
+/** A figure the runner printed as `?` is null, never 0. */
+export function receiptOf(line) {
+    const m = RECEIPT.exec(line);
+    if (m === null) return null;
+    const [attempts, input, output, time] = [m[3], m[4], m[5], m[6]].map((v) => (v === undefined ? null : Number(v)));
+    if (![attempts, input, output, time].every((v) => v === null || Number.isSafeInteger(v))) return null;
+    return { mode: m[1], model: m[2], attempts, in: input, out: output, time };
+}
+
+/** The ids of the Bash calls a record makes: each block's type, name and id, and nothing it says. */
+function bashCallsOf(record) {
+    const content = record.message?.content;
+    if (!Array.isArray(content)) return [];
+    return content.filter((b) => b !== null && typeof b === "object" && b.type === "tool_use" && b.name === "Bash" && text(b.id) !== null).map((b) => b.id);
+}
+
+/** A tool result's output as the host writes it: a string, or text blocks and nothing else. */
+function outputOf(content) {
+    if (typeof content === "string") return content;
+    if (!Array.isArray(content) || !content.length || !content.every((b) => b?.type === "text" && typeof b.text === "string")) return null;
+    return content.map((b) => b.text).join("\n");
+}
+
+/** The receipts in a user record's tool results, each still to be matched to the Bash call it answers. */
+function resultsOf(record) {
+    if (record === null || typeof record !== "object" || record.type !== "user" || !Array.isArray(record.message?.content)) return [];
+    const at = Date.parse(record.timestamp);
+    const found = [];
+    for (const block of record.message.content) {
+        if (block === null || typeof block !== "object" || block.type !== "tool_result" || text(block.tool_use_id) === null) continue;
+        const receipts = (outputOf(block.content) ?? "").split("\n").map(receiptOf).filter((r) => r !== null);
+        if (!receipts.length) continue;
+        found.push({
+            call: block.tool_use_id,
+            receipts,
+            branch: text(record.gitBranch),
+            cwd: text(record.cwd),
+            at: Number.isFinite(at) ? at : null,
+            sidechain: record.isSidechain === true,
+            agent: text(record.agentId),
+        });
+    }
+    return found;
+}
+
 export function readLine(line) {
     const usageLike = line.includes('"usage":');
     const boundaryLike = line.includes('"compact_boundary"');
-    if (!usageLike && !boundaryLike) return null;
+    const resultLike = line.includes('"tool_result"') && line.includes("spend=$0.00");
+    if (!usageLike && !boundaryLike && !resultLike) return null;
     let record;
     try {
         record = JSON.parse(line);
@@ -134,7 +184,12 @@ export function readLine(line) {
         return { boundary: true, sidechain: record.isSidechain === true, agent: text(record.agentId) };
     }
     const request = requestOf(record);
-    return request === null ? null : { request };
+    if (request !== null) {
+        const calls = bashCallsOf(record);
+        return calls.length ? { request, calls } : { request };
+    }
+    const results = resultLike ? resultsOf(record) : [];
+    return results.length ? { results } : null;
 }
 
 /** Claude Code 2.1.280, undocumented: one record per content block, so one request per message id. */
@@ -144,6 +199,8 @@ export function readTranscript(file) {
     const requests = [];
     const tally = { records: 0, duplicates: 0, malformed: 0, synthetic: 0, compactions: 0 };
     const figures = sessionFigures();
+    const calls = new Set();
+    const receipts = [];
     // Compacted contexts awaiting their next request, by chain, so a subagent's compaction is never the session's.
     const awaiting = new Set();
     for (const line of source.split("\n")) {
@@ -154,6 +211,15 @@ export function readTranscript(file) {
             tally.malformed += 1;
             continue;
         }
+        if (read.results) {
+            // Only a Bash result is read for the format: an agent's report quoting a receipt is no second one.
+            for (const result of read.results) {
+                if (!calls.has(result.call)) continue;
+                const { call, receipts: lines, ...where } = result;
+                lines.forEach((receipt, i) => receipts.push({ key: `${call}#${i}`, ...receipt, ...where }));
+            }
+            continue;
+        }
         foldFigures(figures, read);
         if (read.boundary) {
             tally.compactions += 1;
@@ -161,6 +227,7 @@ export function readTranscript(file) {
             continue;
         }
         const request = read.request;
+        for (const id of read.calls ?? []) calls.add(id);
         tally.records += 1;
         if (request.synthetic) {
             tally.synthetic += 1;
@@ -177,7 +244,7 @@ export function readTranscript(file) {
         request.compacted = awaiting.delete(chainOf(request));
         requests.push(request);
     }
-    return { requests, figures, ...tally };
+    return { requests, receipts, figures, ...tally };
 }
 
 /** The lifetime a request's writes used, or null where it wrote nothing it named. */
@@ -375,6 +442,8 @@ export function collect({ projects, roots }) {
     const contexts = [];
     const tally = { files: 0, records: 0, duplicates: 0, malformed: 0, synthetic: 0 };
     const seen = new Set();
+    const receipts = [];
+    const seenReceipts = new Set();
     for (const entry of transcriptFiles(projects, roots)) {
         let transcript;
         try {
@@ -400,8 +469,13 @@ export function collect({ projects, roots }) {
             tally.duplicates += inside.length - kept.length;
             if (kept.length) contexts.push({ file: entry.file, session: entry.session, agent, requests: kept, transcript: agent === null ? transcript : null });
         }
+        for (const r of transcript.receipts) {
+            if (!insideAny(r.cwd, roots) || seenReceipts.has(r.key)) continue;
+            seenReceipts.add(r.key);
+            receipts.push({ ...r, session: entry.session, agent: entry.agent ?? (r.sidechain ? `inline:${r.agent ?? "unnamed"}` : null) });
+        }
     }
-    return { contexts, ...tally };
+    return { contexts, receipts, ...tally };
 }
 
 const zero = () => ({ requests: 0, uncached: 0, written1h: 0, written5m: 0, writtenUnknown: 0, read: 0, output: 0 });
@@ -451,6 +525,20 @@ export function tally(contexts, branch) {
     };
 }
 
+/** What the lines in the receipt format on `branch` say, apart from every host figure: each null where none reported it. */
+export function tallyLocal(receipts, branch) {
+    const own = receipts.filter((r) => r.branch === branch);
+    const figure = (k) => (own.some((r) => r[k] !== null) ? own.reduce((sum, r) => sum + (r[k] ?? 0), 0) : null);
+    return {
+        receipts: own.length,
+        sessions: new Set(own.map((r) => r.session)).size,
+        in: figure("in"),
+        out: figure("out"),
+        time: figure("time"),
+        unreported: Object.fromEntries(["in", "out", "time"].map((k) => [k, own.filter((r) => r[k] === null).length])),
+    };
+}
+
 function sessionTotals(contexts) {
     const by = new Map();
     for (const c of contexts) {
@@ -574,7 +662,8 @@ export function ledger({ projects, config, roots, branch, lines = null, spend =
     const latest = latestSession(collected.contexts, branch);
     const priced = { declared: spend.multipliers, horizon: spend.horizon ?? HORIZON };
     const restart = latest === null ? null : { session: latest.session, ...thresholdFor(latest.transcript, priced) };
-    return { projects, roots, branch, collected, figures, host, restart, lines, priced };
+    const local = tallyLocal(collected.receipts, branch);
+    return { projects, roots, branch, collected, figures, local, host, restart, lines, priced };
 }
 
 const signed = (n) => (n > 0 ? `+${grouped(n)}` : n < 0 ? `−${grouped(-n)}` : "0");
@@ -590,9 +679,21 @@ function unjudged({ declared, horizon } = { declared: null, horizon: HORIZON })
     );
 }
 
+function localLine({ local: l, branch }) {
+    if (l.receipts === 0) return `  local worker: no line in the runner's receipt format on ${branch} is recorded here`;
+    const figure = (k, unit) => {
+        if (l[k] === null) return `${k} unreported`;
+        return `${k} ${grouped(l[k])} ${unit}${l.unreported[k] ? ` (${grouped(l.unreported[k])} receipt(s) did not report it)` : ""}`;
+    };
+    return (
+        `  local worker: ${grouped(l.receipts)} line(s) in the runner's receipt format, from Bash results in ${grouped(l.sessions)} session(s), at $0.00, none of it in the host's tokens or the restart threshold: ` +
+        `${figure("in", "tokens")}, ${figure("out", "tokens")}, ${figure("time", "ms")}`
+    );
+}
+
 export function print(report, say) {
     const { collected, figures: f, host, restart, lines, priced } = report;
-    say(`ledger: branch ${report.branch} — what this change spent, from Claude Code's own usage records (numbers only: nothing a context said is read)`);
+    say(`ledger: branch ${report.branch} — what this change spent, from Claude Code's own usage records (numbers only: nothing a context said is read but a line in the runner's receipt format in a Bash result)`);
     say(`  worktrees: ${report.roots.join(", ")}`);
     say(
         `  read: ${grouped(collected.files)} transcript(s) under ${report.projects}, ${grouped(collected.records)} usage record(s): ` +
@@ -601,6 +702,7 @@ export function print(report, say) {
     );
     if (f.main.requests + f.subagents.requests === 0) {
         say(`  no request on ${report.branch} is recorded here`);
+        say(localLine(report));
         say(unjudged(priced));
         return;
     }
@@ -613,6 +715,7 @@ export function print(report, say) {
     row("written, unstated", "writtenUnknown");
     row("read", "read");
     row("output", "output");
+    say(localLine(report));
     say(`  contexts opened: ${grouped(f.sessions + f.subagentContexts)} (${grouped(f.sessions)} session(s), ${grouped(f.subagentContexts)} subagent(s)); compactions: ${grouped(f.compactions)}`);
     say(`  largest context: ${grouped(f.largest)} tokens`);
     if (f.hitRate === null) say("  hit rate: none — no input was recorded, so none could be read from cache");
@@ -665,6 +768,7 @@ export function pinned(report) {
         rebuilt: f.rebuilt,
         causes: f.causes,
         host: report.host.map((h) => ({ session: h.session, difference: h.difference })),
+        local: report.local,
         threshold: report.restart?.threshold ?? null,
     };
 }

package/cli/portulan.mjs

@@ -23,7 +23,7 @@ export const SUBCOMMANDS = [
     {
         name: "doctor",
         module: "doctor.mjs",
-        summary: "validate a workspace against the Workspace Definition",
+        summary: "validate a workspace and report branch-owned host tokens beside local receipts; --static skips usage records",
     },
     {
         name: "compile",

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/telemetry.mjs

@@ -17,16 +17,31 @@ import { recipeSet, resolverFor } from "./recipe-set.mjs";
 import { isInside } from "./inside.mjs";
 
 // ---------------------------------------------------------------------------------------------
-// The offline audit: no verify recipe may reach the network
+// The offline audit: recipes reach neither the network nor local usage records
 // ---------------------------------------------------------------------------------------------
 
-/** Every mode in cli/ that can reach the network; a new one is unrailed until it has a row here. */
+/** Every network mode in cli/ or a pack (named from `<category>/<name>/`); a new one is unrailed until it has a row here. */
 export const NETWORK_MODES = Object.freeze([
     { module: "cli/review-meter.mjs", flag: "--fetch", what: "fetches review data from GitHub" },
     { module: "cli/telemetry.mjs", flag: "--export", what: "posts an OTLP payload to a collector" },
     { module: "cli/feedback.mjs", flag: "--approve", what: "files a GitHub issue with `gh issue create`" },
+    {
+        module: "tools/local-llm/runner/local-llm.mjs",
+        unless: "--verify-offline",
+        alsoUnless: ["eval", "--verify"],
+        what: "calls the model endpoint except offline rails and captured-record verification",
+    },
+]);
+
+/** Local usage is machine-specific too; static mode must be explicit on each recipe invocation. */
+export const LOCAL_RECORD_MODES = Object.freeze([
+    { module: "cli/doctor.mjs", requiresStatic: "--static", what: "reads local usage records by default" },
+    { module: "cli/portulan.mjs", subcommand: "doctor", requiresStatic: "--static", what: "dispatches to the local usage-record reader" },
+    { module: "portulan", subcommand: "doctor", requiresStatic: "--static", what: "dispatches to the local usage-record reader" },
 ]);
 
+export const modeSpelling = (m) => m.requiresStatic ? `${m.module}${m.subcommand ? ` ${m.subcommand}` : ""} without an immediate ${m.requiresStatic}` : (m.flag ? `${m.module} ${m.flag}` : `${m.module} with anything but ${m.unless} alone${m.alsoUnless ? ` or ${m.alsoUnless.join(" ")} alone` : ""}`);
+
 /** Whole-line comments only: a trailing `#` may sit inside a quote. */
 export const stripShellComments = (source) =>
     source
@@ -40,9 +55,35 @@ const tokenNamesModule = (token, module) => token === module || token.endsWith(`
 
 const tokenIsFlag = (token, flag) => token === flag || token.startsWith(`${flag}=`);
 
+/** An `unless` row passes only where every invocation is the module and its one safe flag, alone on its command. */
+const onlySafeInvocations = (source, m) =>
+    stripShellComments(source)
+        .replace(/\\\n/g, " ")
+        .split(/\n|;|&&?|\|\|?|\$\(|<\(|>\(|`/)
+        .every((segment) => {
+            const tokens = shellTokens(segment);
+            if (tokens[0] === "for" || ["[", "test"].includes(tokens[0]) || (tokens[0] === "if" && ["[", "test"].includes(tokens[1]))) return true;
+            return tokens.every((t, i) => !tokenNamesModule(t, m.module) || ((tokens.length === i + 2 && tokens[i + 1] === m.unless) || (m.alsoUnless && JSON.stringify(tokens.slice(i + 1)) === JSON.stringify(m.alsoUnless))));
+        });
+
+const onlyStaticInvocations = (source, mode) => stripShellComments(source)
+    .replace(/\\\n/g, " ")
+    .split(/\n|;|&&?|\|\|?|\$\(|<\(|>\(|`/)
+    .every((segment) => {
+        const words = shellTokens(segment);
+        const first = words[0];
+        // A path in a file test or dependency list is data, not a CLI invocation.
+        if (["for", "printf", "echo", "[", "test"].includes(first) || (first === "if" && words.slice(1, 3).some((w) => ["[", "test"].includes(w)))) return true;
+        return words.every((word, i) => !tokenNamesModule(word, mode.module) || (mode.subcommand && words[i + 1] !== mode.subcommand) || words[i + (mode.subcommand ? 2 : 1)] === mode.requiresStatic);
+    });
+
 export function auditRecipeSource(source) {
     const tokens = shellTokens(stripShellComments(source));
-    return NETWORK_MODES.filter((m) => tokens.some((t) => tokenNamesModule(t, m.module)) && tokens.some((t) => tokenIsFlag(t, m.flag)));
+    const network = NETWORK_MODES.filter((m) =>
+        m.flag ? tokens.some((t) => tokenNamesModule(t, m.module)) && tokens.some((t) => tokenIsFlag(t, m.flag)) : !onlySafeInvocations(source, m),
+    );
+    const local = LOCAL_RECORD_MODES.filter((m) => !onlyStaticInvocations(source, m));
+    return [...network, ...local];
 }
 
 export function auditRecipes({ workspaceDir, repoRoot, packRoots = [] }) {
@@ -72,9 +113,10 @@ export function auditRecipes({ workspaceDir, repoRoot, packRoots = [] }) {
     const findings = [];
     const read = [];
     for (const r of recipes) {
-        const script = String(r.run ?? "")
-            .split(/\s+/)
-            .find((t) => t.endsWith(".sh"));
+        const words = String(r.run ?? "").split(/\s+/).filter(Boolean);
+        // A run line that is itself a `node` invocation is the whole shell text the recipe runs, so it is graded as read.
+        const direct = words[0] === "node" && !words.some((t) => t.endsWith(".sh"));
+        const script = direct ? words.find((t) => /\.[cm]?js$/.test(t)) : words.find((t) => t.endsWith(".sh"));
         if (!script) {
             return { ok: false, why: `recipe ${JSON.stringify(r.id)} has no readable script in its run line (${JSON.stringify(r.run ?? null)}); this audit cannot grade what it cannot read` };
         }
@@ -89,7 +131,7 @@ export function auditRecipes({ workspaceDir, repoRoot, packRoots = [] }) {
             return { ok: false, why: `recipe ${JSON.stringify(r.id)} names ${script}, which could not be read — ${cause.message}` };
         }
         read.push(r.id);
-        for (const hit of auditRecipeSource(source)) findings.push({ recipe: r.id, script, ...hit });
+        for (const hit of auditRecipeSource(direct ? r.run : source)) findings.push({ recipe: r.id, script, ...hit });
     }
     return { ok: true, examined: read, findings };
 }
@@ -157,7 +199,7 @@ export const PRODUCERS = {
             return [
                 { name: "portulan.review.pull_requests", unit: "{pull_request}", description: "Merged pull requests in the metered window.", value: m.pullRequests },
                 { name: "portulan.review.submissions", unit: "{submission}", description: "Reviews the reviewer submitted across the window. Submission units, never fix-rounds.", value: m.submissions },
-                { name: "portulan.review.submissions_per_pull_request", unit: "1", description: "The figure a-review-loop-needs-a-bound.md bounds the loop on.", value: m.submissionsPerPullRequest },
+                { name: "portulan.review.submissions_per_pull_request", unit: "1", description: "The figure the retired a-review-loop-needs-a-bound.md bounded the loop on.", value: m.submissionsPerPullRequest },
                 { name: "portulan.review.submissions_no_inline", unit: "{submission}", description: "Submissions raising no inline comment.", value: m.noInline },
                 { name: "portulan.review.no_inline_rate", unit: "1", description: "An UPPER BOUND on the found-nothing rate; a submission carrying only suppressed notes counts in it.", value: m.noInlineRate },
                 { name: "portulan.review.pushes", unit: "{push}", description: "Distinct heads the reviewer saw — a floor on pushes, not a count of them.", value: m.pushes },
@@ -336,7 +378,7 @@ const USAGE = [
     "                    first: OTEL_EXPORTER_OTLP_METRICS_ENDPOINT (used as given) else",
     "                    OTEL_EXPORTER_OTLP_ENDPOINT (a base, +/v1/metrics); and",
     "                    OTEL_EXPORTER_OTLP_METRICS_HEADERS replacing OTEL_EXPORTER_OTLP_HEADERS",
-    "  --audit-recipes   assert that no recipe the workspace YIELDS can reach a network mode;",
+    "  --audit-recipes   assert that no recipe the workspace YIELDS can reach a network mode or read local usage records;",
     "                    takes --workspace and --pack-root, and needs no --config",
     "",
     "exit 0 the thing asked for happened · 1 a verdict (golden drift, or export while opted out)",
@@ -403,16 +445,16 @@ export async function run(argv = process.argv.slice(2), io = console, { env = pr
             return 2;
         }
         if (res.findings.length > 0) {
-            io.error(`telemetry: ${res.findings.length} verify recipe(s) can reach the network:`);
-            for (const f of res.findings) io.error(`  - ${f.recipe} (${f.script}) invokes ${f.module} ${f.flag}, which ${f.what}`);
-            io.error("A verify recipe may not make a network call: spec/slots.md and .portulan/verify/README.md");
+            io.error(`telemetry: ${res.findings.length} verify recipe(s) can reach the network or local usage records:`);
+            for (const f of res.findings) io.error(`  - ${f.recipe} (${f.script}) invokes ${modeSpelling(f)}, which ${f.what}`);
+            io.error("A verify recipe may not make a network call or read local usage records: spec/slots.md and .portulan/verify/README.md");
             io.error("both prohibit it, because a rail that moves with the network goes red about the world");
             io.error("rather than about the tree.");
             return 1;
         }
-        io.log(`telemetry: ${res.examined.length} yielded recipe(s) examined; none reaches a network mode`);
-        io.log(`  Modes railed: ${NETWORK_MODES.map((m) => `${m.module} ${m.flag}`).join(", ")}.`);
-        io.log("  A network mode with no row here is UNRAILED, and nothing can audit that a row was added.");
+        io.log(`telemetry: ${res.examined.length} yielded recipe(s) examined; none reaches a network mode or reads local usage records`);
+        io.log(`  Modes railed: ${[...NETWORK_MODES, ...LOCAL_RECORD_MODES].map(modeSpelling).join(", ")}.`);
+        io.log("  A network or local-record mode with no row here is UNRAILED, and nothing can audit that a row was added.");
         return 0;
     }
 

package/core/operating/context.md

@@ -148,6 +148,70 @@ each section's anchor and size, the same way. It prints from the file as it is,
 go stale. Nothing checks that a session outlined first; what the rule saves is measured by rerunning a
 task, never by a recipe, which may not read the host's usage records.
 
+## A local model runs without the host floor
+
+A model served on the machine itself costs nothing per token, so `0038`'s dollar arithmetic gives it no
+restart threshold. What it does cost is time to prefill, memory for each context it holds, and recall that
+still sags in a long context. And every turn it takes is a turn the parent session does not send again on
+each request after. So a local model is called as a context firewall, and four rules hold it:
+
+1. **A local worker runs without the host floor (`omitClaudeMd`) and under a hard input-byte ceiling.** It
+   is given one bounded input: a symbol span from [`cli/symbols.mjs`](../../cli/symbols.mjs), a file under
+   300 lines, a diff, or a log to compress, and never the parent session's instruction files. A prompt over
+   the ceiling is refused before a socket opens. _Why: a host floor of 44k to 85k tokens is prefilled into
+   a local model's cache on every cold context, where `0039` measured prompts of about 400 to 470 tokens
+   prefilling in 0.85 to 1.88 seconds._
+2. **Thinking effort is set explicitly at invocation**: low or off for a mechanical transform, bounded for
+   prose or review, never left to the chat template's default. _Why: one template `0039` read sets
+   reasoning effort to `xhigh` unless thinking is switched off, and under a 1,500-token cap that model
+   returned no answer on any of three tasks, every token spent thinking; at low effort it passed both
+   tasks it was rerun on._
+3. **A local edit is kept only on its verify command's exit `0`.** The runner applies the edit and runs the
+   command. On exit `0` one receipt line is all that enters the parent context (`0038` rule 5). On exit `1`
+   after its retries, or at once on any other exit, which is no verdict, it restores the file's original
+   bytes, and it does the same on SIGINT, SIGTERM and SIGHUP. **This is a rollback, not an atomic write**:
+   the verify needs the edited file in place, so any other signal that ends the runner, SIGKILL and SIGQUIT
+   among them, or a power loss between the edit and its verdict leaves the edit, and a transform with no
+   receipt is unverified. _Why not atomic: a scratch worktree would judge the last commit plus the edit
+   rather than the working copy plus the edit, would lack the untracked files a verify reads, and moving
+   the edit back after exit `0` would not be atomic either (`0039` ruling 4)._
+4. **Loopback is a rail, and routing is earned.** A local runner refuses an endpoint outside loopback
+   (`127.0.0.1`, `localhost`, `[::1]`) unless leaving it is proposed and approved. A screen grades an
+   installed model once per task against Portulan's own predicates, from
+   [`cli/comments.mjs`](../../cli/comments.mjs), [`cli/doctor.mjs`](../../cli/doctor.mjs) and
+   [`cli/skill-goldens.mjs`](../../cli/skill-goldens.mjs), and a model that fails it is not routed. Passing
+   it earns nothing. A role is routed to a local model by an A/B record under `0038` rule 4: the local model
+   as routed against the host's model on the same tasks, `k` runs per cell, captured once and railed to its
+   register in `evals/ab/`. _Why: an endpoint off the machine sends workspace context away under a local
+   tool's name, and the screen takes one sample per task with no baseline arm, while a cheaper model for a
+   role is earned by an A/B run, never assumed (`0039` ruling 5)._
+
+**What the runner holds today.** The [`tools/local-llm`](../../packs/tools/local-llm/README.md) pack's
+runner holds rules 1 to 3 and rule 4's loopback rail for the calls it makes. It sends the model its own
+short instructions and the input it was given, with the end of a red verify's output on a retry, and
+nothing else. It refuses a prompt over its ceiling before a socket opens, names the effort on every chat
+request, low unless set, requires a verify command for an edit and rolls back as rule 3 says, and refuses
+a host off loopback and a redirect away from it. Which inputs it is given is the caller's: only their
+bytes are checked. `--allow-remote` lifts the loopback rail on the caller's word, and the pack's
+`local-llm-off-loopback` gate has no matcher, so approval to leave loopback is the human's. Its `eval`
+subcommand is the screen. Its `runner-rails` recipe holds the loopback and ceiling refusals and the
+rollback on a red or no-verdict verify offline, with no network call; the rollback on a signal is held by
+the runner's tests. This repository composes the pack and registers its skill; the ledger reports local
+receipts beside the host's tokens. `doctor` includes that branch-owned usage report by default,
+with unavailable data reported as unmeasured; `--static` omits usage-record discovery for verification.
+The [captured A/B](../../evals/ab/local-worker.md) supports code
+at low effort (L5/H5), while shared prose is disabled because codify scored L0/H3, despite handoff's
+L5/H5. Operational defaults and explicit roles require the measured model at low effort; explicit
+model-only calls remain candidates. The record and register are regraded and byte-compared in CI,
+with shipped routing rederived from their turns. The `local-worker` persona declares
+`omitClaudeMd: true` and `effort: low`, and `compile` writes both into a workspace's binding against a
+committed golden.
+
+_(Provenance: proposal
+[`0039`](../../.portulan/proposals/0039-a-local-model-runs-without-the-host-floor-and-under-a-thinking-cap.md)'s
+measurement of two local models against three of this repository's tasks on 2026-10-27, and its rulings 4
+and 5 of 2026-10-30.)_
+
 ## What is machinery today, and what is not
 
 As of Workspace Definition 2.9 a workspace can declare the budget and the ratio, and both are checked
@@ -169,10 +233,21 @@ a section is never moved for its size alone. Claude Code 2.1.281 drops a comment
 before it loads an instruction file or rule (read in its program text on 2026-09-24), so the mark and the
 marker left behind cost nothing. This repository's own card holds its boot under the 7,500-token line of
 2026-09-23, railed at today's figure plus 2% by the same recipe. A pointer's repository is not measured,
-because a pointer declares no tree. **Still to land**: the exact mode that
-calibrates a ratio, the degradation report that says which tiers a host can express, the Stop-gate's
-named demotion, persona frontmatter and the librarian pass, one change at a time, in `0036`'s order of work
-and under row 12 of [`../../docs/plan.md`](../../docs/plan.md).
+because a pointer declares no tree. **A persona can declare what its context costs**: `model`, `effort`,
+`omitClaudeMd` and `cacheLifetime`, refused when malformed and never defaulted, which `compile` writes into
+the hand-written binding of a persona a composed pack ships and byte-compares under `--check`, printing
+each field a host cannot express, with the persona and the host, as its degradation report for personas.
+Claude Code 2.1.317 takes all four on an agent, and loads `agents/` only from a plugin root (both read
+in its program text on 2026-11-03), so in a tree that is not a plugin the compiled block is loaded by
+nothing, and the degradation report says so; in one that is, only while the plugin is installed and
+enabled, which `compile` cannot see. That stops short of the row: `compile` writes no
+`.claude/agents/`, where a repository that is not a plugin loads its agents, and no binding where none
+exists; a core persona's binding in this plugin's `agents/` is not compiled; and no host has been shown
+honouring a compiled field. **Still to land**: the
+exact mode that calibrates a ratio, the degradation report's half that says which tiers a host can
+express, the Stop-gate's named demotion and the librarian pass, one change at a time, in `0036`'s order
+of work and under row 12 of
+[`../../docs/plan.md`](../../docs/plan.md).
 Until each lands, the rule it would enforce is held by the human gate, and saying so is the point: a rule
 nothing checks, presented as one that something does, is the failure this page exists to prevent.
 

package/core/personas/README.md

@@ -21,6 +21,39 @@ context firewalls; Cognition — read-parallel / write-isolated.)_
 - **Read / write posture** — most personas read in parallel; writes are isolated to one place so two
   agents never clobber the same file.
 
+## What a persona may declare about its context
+
+Four optional frontmatter fields say what a fresh context for the role should cost, per
+[`../operating/context.md`](../operating/context.md): `model`, one model name or alias as a single
+token; `effort`, one of `low`, `medium`, `high`, `xhigh` or `max`; `omitClaudeMd`, `true` or `false`
+unquoted, whether the role runs without the project's instruction files; and `cacheLifetime`, `5m` or
+`1h`. The effort levels and the name `omitClaudeMd` are adopted from Claude Code's vocabulary, the first
+host to express them. `effort` sets the host subagent's reasoning effort, and is not the thinking cap the
+`tools/local-llm` runner's `--effort` sends with each request it makes. `doctor` fails a
+malformed value and `compile` refuses one, and neither supplies a value the persona did not write. For a
+persona a composed pack ships, `compile` writes the declared fields into the frontmatter of the role's
+hand-written host binding, `agents/<name>.md` in the workspace's tree, and leaves every other line of
+that file as its author wrote it; `--check` byte-compares the result, and a line inside the compiled
+block that `compile` did not write is refused rather than removed. One it cannot catch: a line added inside
+the block in exactly the spelling and order `compile` writes reads as compiled, and is dropped once the
+persona no longer declares that field, since the two cannot be told apart. And once a persona declares any
+field, `compile` owns every top-level key it could write, so a hand-written `experimental:` is refused
+even for a key other than `cacheTtl`. A field a host cannot express is
+named, with the persona and the host, in the degradation report `compile` prints. Claude Code takes all
+four on an agent (`cacheLifetime` as `experimental.cacheTtl`), and a vendored `AGENTS.md` takes none.
+**Claude Code loads `agents/` only from a plugin root**, and a repository that is not a plugin loads its
+agents from `.claude/agents/`, which `compile` does not write. So outside a plugin the compiled block is
+loaded by nothing, and the degradation report says so for each persona it applies to. Where the tree is
+a plugin root the report is silent, which is not proof of loading: a plugin's agents load only while it
+is installed and enabled, and `compile` cannot see that. _(Provenance:
+proposal `0036`'s order of work, item 7, and proposal `0039`'s first two rules. The host's keys, values
+and agent locations were read in Claude Code 2.1.317's program text on 2026-11-03.)_
+
+A binding has one persona owner across composed packs, including an unbound persona or one declaring
+no fields; duplicate destinations are refused before any artifact is written. The binding must be a
+regular file whose real path stays in the real declared tree, including its parent directories.
+`omitClaudeMd` accepts only unquoted `true` or `false`, in both declarations and compiled blocks.
+
 ## Status
 
 **Milestone 3 — contract, exemplars, and one host binding.** This README fixes the persona contract; the

package/core/skills/clarify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clarify
-description: Run a bounded clarification pass before planning a full-lane task whose intent is ambiguous or whose acceptance criteria are not yet testable. Use when the ask is underspecified, the constraints conflict, or the criteria can't be written as observable checks — surface the smallest set of decision-questions, get human answers, and fold them into EARS-shaped acceptance criteria before any code is planned.
+description: Run a bounded clarification pass before planning a full-lane task. Use when the ask is underspecified, the constraints conflict, or the criteria can't be written as observable checks — surface the smallest set of decision-questions, get human answers, and fold them into EARS-shaped acceptance criteria before any code is planned.
 ---
 
 # Skill — Clarify