@sleepy_panda_srl/portulan 0.3.0 → 0.4.1

package/cli/ledger.mjs

@@ -38,6 +38,7 @@ export const KEY_LIMIT = 200;
 
 /** The classes a request is billed in, in the order a report prints them. */
 export const CLASSES = ["uncached", "written1h", "written5m", "writtenUnknown", "read", "output"];
+export const RECORDED_ROLES = ["implementer", "reviewer", "librarian", "supervisor", "local-worker"];
 
 export class LedgerError extends Error {
     constructor(message) {
@@ -84,33 +85,55 @@ export function mayHold(name, root) {
 }
 
 /** null for a record that is not an API response with usage; no content field is ever read. */
+export const INPUT_USAGE_MASK = 1 | 4 | 8;
+export const inputUnusable = r => Boolean((r.usageMissing & INPUT_USAGE_MASK) || (r.usageUnsafe & 1));
+
+export function usageOf(usage) {
+    const lifetimes = usage.cache_creation !== null && typeof usage.cache_creation === "object" ? usage.cache_creation : {};
+    const written1h = count(lifetimes.ephemeral_1h_input_tokens);
+    const written5m = count(lifetimes.ephemeral_5m_input_tokens);
+    const writeParts = (lifetimes.ephemeral_5m_input_tokens === undefined ? 0 : 1) | (lifetimes.ephemeral_1h_input_tokens === undefined ? 0 : 2);
+    const invalid = value => value !== undefined && (!Number.isSafeInteger(value) || value < 0);
+    const inputUnsafe = [usage.input_tokens, usage.cache_creation_input_tokens, usage.cache_read_input_tokens, lifetimes.ephemeral_1h_input_tokens, lifetimes.ephemeral_5m_input_tokens].some(invalid) ||
+        !Number.isSafeInteger(count(usage.input_tokens) + Math.max(count(usage.cache_creation_input_tokens), written1h + written5m) + count(usage.cache_read_input_tokens)) ||
+        (usage.cache_creation_input_tokens !== undefined && count(usage.cache_creation_input_tokens) < written1h + written5m);
+    return {
+        usageMissing: (usage.input_tokens === undefined ? 1 : 0) | (usage.output_tokens === undefined ? 2 : 0) |
+            (usage.cache_read_input_tokens === undefined ? 4 : 0) | (usage.cache_creation_input_tokens === undefined && writeParts !== 3 ? 8 : 0),
+        usageUnsafe: (inputUnsafe ? 1 : 0) | (invalid(usage.output_tokens) ? 2 : 0),
+        writeTotal: Number.isSafeInteger(usage.cache_creation_input_tokens) && usage.cache_creation_input_tokens >= 0 ? usage.cache_creation_input_tokens : null,
+        writeParts,
+        uncached: count(usage.input_tokens),
+        written1h,
+        written5m,
+        writtenUnknown: Math.max(0, count(usage.cache_creation_input_tokens) - written1h - written5m),
+        read: count(usage.cache_read_input_tokens),
+        output: count(usage.output_tokens),
+    };
+}
+
 function requestOf(record) {
     if (record === null || typeof record !== "object" || record.type !== "assistant") return null;
     const message = record.message;
     if (message === null || typeof message !== "object") return null;
     const usage = message.usage;
     if (usage === null || typeof usage !== "object") return null;
-    // The host's own records, an interruption or an API error, with no request behind them.
+    // Synthetic host records have no request behind them.
     if (message.model === "<synthetic>") return { synthetic: true };
-    const lifetimes = usage.cache_creation !== null && typeof usage.cache_creation === "object" ? usage.cache_creation : {};
-    const written1h = count(lifetimes.ephemeral_1h_input_tokens);
-    const written5m = count(lifetimes.ephemeral_5m_input_tokens);
     const at = Date.parse(record.timestamp);
+    const roleParts = text(record.attributionAgent)?.split(":");
+    const role = roleParts?.every(part => /^[a-zA-Z0-9_-]+$/.test(part)) && RECORDED_ROLES.includes(roleParts.at(-1)) ? roleParts.at(-1) : null;
     return {
         id: text(message.id) ?? text(record.requestId) ?? text(record.uuid),
         model: text(message.model),
         effort: text(record.effort),
+        role,
+        ...usageOf(usage),
         branch: text(record.gitBranch),
         cwd: text(record.cwd),
         at: Number.isFinite(at) ? at : null,
         sidechain: record.isSidechain === true,
         agent: text(record.agentId),
-        uncached: count(usage.input_tokens),
-        written1h,
-        written5m,
-        writtenUnknown: Math.max(0, count(usage.cache_creation_input_tokens) - written1h - written5m),
-        read: count(usage.cache_read_input_tokens),
-        output: count(usage.output_tokens),
     };
 }
 
@@ -120,16 +143,19 @@ 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. */
+/** A whole-line local receipt is read wherever it appears. */
 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$/;
+    /^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|\?)(?: reasoning=(?:(0|[1-9]\d*)t|\?) cached-in=(?:(0|[1-9]\d*)t|\?))? 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;
+    const [reasoning, cached] = [m[7], m[8]].map((v) => (v === undefined ? null : Number(v)));
+    if (![attempts, input, output, time, reasoning, cached].every((v) => v === null || Number.isSafeInteger(v))) return null;
+    if (reasoning !== null && (output === null || reasoning > output)) return null;
+    if (cached !== null && (input === null || cached > input)) return null;
     return { mode: m[1], model: m[2], attempts, in: input, out: output, time };
 }
 
@@ -193,12 +219,14 @@ export function readLine(line) {
 }
 
 /** Claude Code 2.1.280, undocumented: one record per content block, so one request per message id. */
-export function readTranscript(file) {
-    const source = fs.readFileSync(file, "utf8");
+export function readTranscript(file, { end = null } = {}) {
+    const bytes = fs.readFileSync(file, end === null ? "utf8" : undefined);
+    if (end !== null && (!Number.isSafeInteger(end) || end < 0 || end > bytes.length)) throw new LedgerError("the bounded transcript snapshot changed");
+    const source = end === null ? bytes : bytes.subarray(0, end).toString("utf8");
     const byId = new Map();
     const requests = [];
     const tally = { records: 0, duplicates: 0, malformed: 0, synthetic: 0, compactions: 0 };
-    const figures = sessionFigures();
+    let parentCompactions = 0;
     const calls = new Set();
     const receipts = [];
     // Compacted contexts awaiting their next request, by chain, so a subagent's compaction is never the session's.
@@ -220,8 +248,8 @@ export function readTranscript(file) {
             }
             continue;
         }
-        foldFigures(figures, read);
         if (read.boundary) {
+            if (!read.sidechain) parentCompactions += 1;
             tally.compactions += 1;
             awaiting.add(chainOf(read));
             continue;
@@ -235,15 +263,26 @@ export function readTranscript(file) {
         }
         const prior = request.id === null ? undefined : byId.get(request.id);
         if (prior !== undefined) {
-            // The host writes a request again per content block, and its output count may grow: keep each largest.
+            // Merge growing block counters; unclassified writes remain the residual of the reported total.
             tally.duplicates += 1;
             for (const c of CLASSES) prior[c] = Math.max(prior[c], request[c]);
+            prior.usageMissing &= request.usageMissing;
+            prior.writeParts |= request.writeParts;
+            prior.usageUnsafe |= request.usageUnsafe;
+            if (request.writeTotal !== null) prior.writeTotal = Math.max(prior.writeTotal ?? 0, request.writeTotal);
+            if (prior.writeTotal !== null || prior.writeParts === 3) prior.usageMissing &= ~8;
+            if (prior.writeTotal !== null) prior.writtenUnknown = Math.max(0, prior.writeTotal - prior.written1h - prior.written5m);
+            if (!Number.isSafeInteger(contextOf(prior)) || (prior.writeTotal !== null && prior.written1h + prior.written5m > prior.writeTotal)) prior.usageUnsafe |= 1;
             continue;
         }
         if (request.id !== null) byId.set(request.id, request);
         request.compacted = awaiting.delete(chainOf(request));
         requests.push(request);
     }
+    const figures = sessionFigures();
+    for (const r of requests) foldCanonical(figures, r);
+    figures.compactions = parentCompactions;
+    figures.pending = awaiting.has("session");
     return { requests, receipts, figures, ...tally };
 }
 
@@ -279,7 +318,7 @@ export function markRebuilds(requests) {
     return requests;
 }
 
-/** Latest request ids remembered to pass over repeats: the host writes a request's blocks back to back. */
+/** Hot IDs only; raw streams need canonical confirmation. */
 const RECENT = 16;
 
 /** Every field JSON-safe: `./advisory.mjs` keeps these between calls and folds in only the lines since. */
@@ -296,8 +335,12 @@ export function foldFigures(figures, read) {
     }
     const r = read.request;
     if (r === undefined || r.synthetic || r.sidechain) return figures;
+    if (r.id !== null && figures.recent.includes(r.id)) return figures;
+    return foldUniqueRequest(figures, r);
+}
+
+function foldUniqueRequest(figures, r) {
     if (r.id !== null) {
-        if (figures.recent.includes(r.id)) return figures;
         figures.recent.push(r.id);
         if (figures.recent.length > RECENT) figures.recent.shift();
     }
@@ -314,11 +357,18 @@ export function foldFigures(figures, read) {
     return figures;
 }
 
+export function foldCanonical(figures, r) {
+    if (r.synthetic || r.sidechain) return figures;
+    if (r.compacted) { figures.compactions += 1; figures.pending = true; }
+    return foldUniqueRequest(figures, r);
+}
+
 /** Each test is the one `./doctor.mjs` applies to the same key, so a manifest `doctor` passes is one these take. */
 export const SPEND_FIGURES = {
     read: { holds: (v) => Number.isFinite(v) && v > 0 && v <= 1, is: "a number above 0 and at most 1" },
     write: { holds: (v) => Number.isFinite(v) && v >= 1, is: "a number of at least 1" },
     requests: { holds: (v) => Number.isInteger(v) && v > 0, is: "a positive integer" },
+    resume: { holds: (v) => Number.isFinite(v) && v >= 0, is: "a finite nonnegative number of input-equivalent tokens" },
 };
 
 /** What a crossed restart threshold does: `"advise"` says the line; `"block"` also holds the turn's end once. */
@@ -330,7 +380,7 @@ export function overflowingWrite({ read, write }) {
 
 /** Each part null where undeclared; throws at the first fault, since no reader may rely on `doctor` having run. */
 export function readSpend(value, where) {
-    if (value === undefined) return { multipliers: null, horizon: null, restart: null };
+    if (value === undefined) return { multipliers: null, horizon: null, restart: null, resume: null };
     const refuse = (what) => new LedgerError(`\`spend\` in ${where} ${what}; ../spec/slots.md gives its shape, and \`doctor\` names every finding`);
     const code = (key) => `\`${key}\``;
     const shaped = (v, at, keys, allRequired) => {
@@ -345,7 +395,7 @@ export function readSpend(value, where) {
         if (!SPEND_FIGURES[range].holds(v)) throw refuse(`${at}sets ${code(key)} to ${JSON.stringify(v)}, which is not ${SPEND_FIGURES[range].is}`);
         return v;
     };
-    shaped(value, "", ["multipliers", "horizon", "restart"], false);
+    shaped(value, "", ["multipliers", "horizon", "restart", "resume"], false);
     let multipliers = null;
     if (value.multipliers !== undefined) {
         const m = shaped(value.multipliers, "at `multipliers` ", ["read", "write"], true);
@@ -357,7 +407,8 @@ export function readSpend(value, where) {
     }
     const horizon = value.horizon === undefined ? null : figure(shaped(value.horizon, "at `horizon` ", ["requests"], true).requests, "at `horizon` ", "requests", "requests");
     if (value.restart !== undefined && !RESTARTS.includes(value.restart)) throw refuse(`sets \`restart\` to ${JSON.stringify(value.restart)}, which is neither ${RESTARTS.map((r) => `"${r}"`).join(" nor ")}`);
-    return { multipliers, horizon, restart: value.restart ?? null };
+    const resume = value.resume === undefined ? null : figure(shaped(value.resume, "at `resume` ", ["tokens"], true).tokens, "at `resume` ", "tokens", "resume");
+    return { multipliers, horizon, restart: value.restart ?? null, resume };
 }
 
 export function multipliers({ declared = null, lifetime = null } = {}) {
@@ -367,11 +418,14 @@ export function multipliers({ declared = null, lifetime = null } = {}) {
     return { read: GENERAL_READ, write: WRITE_BY_LIFETIME[at], lifetime: at, recorded, source: "undeclared" };
 }
 
-/** `C* ≈ F × (1 + m_w / (n × m_r))`, in whole tokens. */
-export function restartThreshold({ fresh, write, read, horizon = HORIZON }) {
+/** Break-even context including additional resume expense; display rounding never decides profitability. */
+export function restartThreshold({ fresh, write, read, horizon = HORIZON, resume = 0 }) {
     if (!(fresh > 0 && write > 0 && read > 0 && horizon > 0)) throw new LedgerError("a restart threshold needs a fresh context, both multipliers and a horizon, each above zero");
-    const threshold = Math.round(fresh * (1 + write / (horizon * read)));
-    if (!Number.isFinite(threshold)) throw new LedgerError(`the restart threshold ${fresh} × (1 + ${write} / (${horizon} × ${read})) overflows, so these multipliers give none`);
+    if (!SPEND_FIGURES.resume.holds(resume)) throw new LedgerError("resume expense must be finite and nonnegative");
+    const reads = horizon * read;
+    const expense = fresh * write + resume;
+    const threshold = Math.ceil(fresh + expense / reads);
+    if (![reads, expense, threshold].every(Number.isFinite)) throw new LedgerError(`the restart threshold ${fresh} × (1 + ${write} / (${horizon} × ${read})) with resume expense ${resume} overflows, so these figures give none`);
     return threshold;
 }
 
@@ -382,16 +436,33 @@ export function describeMultipliers(m) {
     return `multipliers undeclared: the general read ${m.read}× and the ${m.write}× of ${at}`;
 }
 
+export function restartSaving({ fresh, context, horizon, read, write, resume = 0 }) {
+    const gross = horizon * read * (context - fresh);
+    const written = write * fresh;
+    const saving = gross - written - resume;
+    if (![gross, written, resume, saving].every(Number.isFinite)) throw new LedgerError("the estimated restart saving overflows, so no comparison is usable");
+    // Eight rounding units at the largest operand bound these products and subtractions, without a fixed cost margin.
+    const error = Math.max(Math.abs(gross), Math.abs(written), Math.abs(resume)) * Number.EPSILON * 8;
+    return Math.abs(saving) <= error ? 0 : saving;
+}
+
 /** null with no request yet, or none since the last compaction: the context held is the one it replaced. */
-export function figureOf(figures, { declared = null, horizon = HORIZON } = {}) {
+export function figureOf(figures, { declared = null, horizon = null, resume = null } = {}) {
     if (figures.fresh === null || figures.pending || figures.fresh === 0) return null;
     const m = multipliers({ declared, lifetime: figures.freshLifetime ?? figures.lifetime });
-    const threshold = restartThreshold({ fresh: figures.fresh, write: m.write, read: m.read, horizon });
-    return { fresh: figures.fresh, context: figures.last, threshold, horizon, multipliers: m, compactions: figures.compactions, requests: figures.requests };
+    const n = horizon ?? HORIZON;
+    const threshold = restartThreshold({ fresh: figures.fresh, write: m.write, read: m.read, horizon: n, resume: resume ?? 0 });
+    const saving = restartSaving({ fresh: figures.fresh, context: figures.last, horizon: n, read: m.read, write: m.write, resume: resume ?? 0 });
+    return { fresh: figures.fresh, context: figures.last, threshold, horizon: n, horizonDeclared: horizon !== null, resume, saving, multipliers: m, compactions: figures.compactions, requests: figures.requests };
 }
 
 export function thresholdFor(transcript, options = {}) {
-    return figureOf(transcript.figures, options);
+    const main = transcript.requests?.filter(r => !r.sidechain) ?? [];
+    if (!main.length) return figureOf(transcript.figures, options);
+    const first = main[Math.max(0, main.findLastIndex(r => r.compacted))], last = main.at(-1);
+    if ([first, last].some(inputUnusable)) return { unavailable: "usage" };
+    const lifetime = main.findLast(r => lifetimeOf(r) !== null);
+    return figureOf({ ...transcript.figures, fresh: contextOf(first), last: contextOf(last), freshLifetime: lifetimeOf(first), lifetime: lifetime ? lifetimeOf(lifetime) : null }, options);
 }
 
 function listDir(dir) {
@@ -660,8 +731,11 @@ export function ledger({ projects, config, roots, branch, lines = null, spend =
     const figures = tally(collected.contexts, branch);
     const host = config === null ? [] : compareHost(collected.contexts, hostTotals(config, roots));
     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) };
+    const priced = { declared: spend.multipliers, horizon: spend.horizon ?? null, resume: spend.resume ?? null };
+    const last = latest?.transcript.requests.findLast(r => !r.sidechain);
+    const restart = latest === null ? null : last?.branch !== branch || !latest.requests.includes(last)
+        ? { session: latest.session, unavailable: "branch-scope" }
+        : { session: latest.session, ...thresholdFor(latest.transcript, priced) };
     const local = tallyLocal(collected.receipts, branch);
     return { projects, roots, branch, collected, figures, local, host, restart, lines, priced };
 }
@@ -670,12 +744,12 @@ const signed = (n) => (n > 0 ? `+${grouped(n)}` : n < 0 ? `−${grouped(-n)}` :
 
 const short = (id) => id.slice(0, 8);
 
-function unjudged({ declared, horizon } = { declared: null, horizon: HORIZON }) {
+function unjudged({ declared, horizon, resume = null } = { declared: null, horizon: null }) {
     const m = declared ?? { read: GENERAL_READ, write: WRITE_BY_LIFETIME };
     return (
         "  restart: no session on this branch has a request with a time to judge; a threshold would take a horizon of " +
-        `${horizon} requests and ${declared === null ? "the general multipliers, undeclared" : "the declared multipliers"}: ` +
-        `read ${m.read}×, writes ${m.write["5m"]}× for five minutes and ${m.write["1h"]}× for an hour`
+        `${horizon ?? HORIZON} requests (${horizon === null ? "default" : "declared"}) and ${declared === null ? "the general multipliers, undeclared" : "the declared multipliers"}: ` +
+        `read ${m.read}×, writes ${m.write["5m"]}× for five minutes and ${m.write["1h"]}× for an hour; ${resume === null ? "resume cost unknown" : `resume expense ${resume} input-equivalent tokens`}`
     );
 }
 
@@ -700,6 +774,8 @@ export function print(report, say) {
             `${grouped(collected.duplicates)} per-block duplicate(s) counted once, ${grouped(collected.synthetic)} host-written record(s) with no request behind them, ` +
             `${grouped(collected.malformed)} line(s) that did not parse`,
     );
+    const uncertain = (collected.contexts ?? []).reduce((n, c) => n + c.requests.filter(r => r.usageMissing || r.usageUnsafe).length, 0);
+    if (uncertain) say(`  usage: ${grouped(uncertain)} owned request(s) have missing or invalid counters; totals are partial, sanitized zeros are not known observations`);
     if (f.main.requests + f.subagents.requests === 0) {
         say(`  no request on ${report.branch} is recorded here`);
         say(localLine(report));
@@ -732,6 +808,14 @@ export function print(report, say) {
         const parts = ["uncached", "written", "read", "output"].map((k) => `${k} ${grouped(h.ledger[k])} of ${grouped(h.host[k])} (${signed(h.difference[k])})`);
         say(`  host totals, session ${short(h.session)} (the last the host saved for ${h.cwd}, every branch): ${parts.join(", ")}`);
     }
+    if (restart?.unavailable === "branch-scope") {
+        say("  restart: comparison unavailable — the latest session's main request is outside this branch's owned scope");
+        return;
+    }
+    if (restart?.unavailable === "usage") {
+        say("  restart: comparison unavailable — input usage counters are invalid or incomplete");
+        return;
+    }
     if (restart === null || restart.threshold === undefined) {
         say(unjudged(priced));
         return;
@@ -740,7 +824,9 @@ export function print(report, say) {
     say(
         `  restart: session ${short(restart.session)} is at ${grouped(restart.context)} tokens and ` +
             `${restart.context >= restart.threshold ? "has reached" : "is below"} its threshold of ${grouped(restart.threshold)} = ` +
-            `${grouped(restart.fresh)} × (1 + ${m.write} / (${restart.horizon} × ${m.read})); ${describeMultipliers(m)}`,
+            `${grouped(restart.fresh)} × (1 + ${m.write} / (${restart.horizon} × ${m.read})) + ${restart.resume ?? 0} / (${restart.horizon} × ${m.read}); ${describeMultipliers(m)}; ` +
+            `horizon ${restart.horizon} requests remaining (${restart.horizonDeclared ? "declared" : "default"}); ` +
+            `${restart.resume === null ? "resume cost unknown: threshold is a lower bound" : `resume expense ${restart.resume} input-equivalent tokens; estimated saving ${restart.saving}`}`,
     );
 }
 

package/cli/librarian.mjs

@@ -22,6 +22,8 @@ import { pathToFileURL } from "node:url";
 
 import { inspect as inspectIndex, IndexError, recordType, dateOf, isInside } from "./index.mjs";
 import { parseProvenance } from "./doctor.mjs";
+import { alwaysTier, declaredContext, ESTIMATED_BYTES_PER_TOKEN, tokensOf, TOP_CONTRIBUTORS, treeOf } from "./context.mjs";
+import { BOOT_CARD_UNIT, ENGINE_LINE, GATES_LINE, guidanceDeclaration, guidanceEdits, GUIDANCE_RULES_DIR, LEADS_LINE, parseUnit, resolveWorkspace, RULES_MARKER } from "./compile.mjs";
 
 /** Raised when the pass cannot run, or cannot report honestly. Always exit 2. */
 export class LibrarianError extends Error {
@@ -31,7 +33,7 @@ export class LibrarianError extends Error {
     }
 }
 
-const KNOWN_SPECS = new Set(["2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13"]);
+const KNOWN_SPECS = new Set(["2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13", "2.14", "2.15", "2.16"]);
 
 const NOT_A_RECORD = new Set(["README.md"]);
 
@@ -89,22 +91,32 @@ export function retireWhen(source) {
         .trim();
 }
 
-/** Whether a proposal still waits on the human gate: anything short of a stated verdict does, as this feeds a nag, never a gate. */
+/** Explicit leading outcomes only; this classifies a report, never grants consent. */
 export function proposalPending(source) {
-    const lines = source.split("\n");
-    const parts = [];
-    for (let i = 0; i < lines.length; i += 1) {
-        if (!/^\s*\*\*(decision|status)\b/i.test(lines[i])) continue;
-        let end = i;
-        while (end + 1 < lines.length && lines[end + 1].trim() !== "") end += 1;
-        parts.push(lines.slice(i, end + 1).join(" "));
-        i = end;
-    }
-    if (!parts.length) return true;
-    const text = parts.join(" ").replace(/[*_`]/g, "");
-    if (/\bpending\b/i.test(text)) return true;
-    if (/[{}]|\|/.test(text)) return true; // an unfilled template line is not a decision
-    return !/\b(accepted|rejected|revised|applied|withdrawn|superseded)\b/i.test(text);
+    const words = "accepted|rejected|revised|applied|withdrawn|superseded|ruled";
+    const outcome = new RegExp(`^(${words})\\b`, "i");
+    const outcomeWord = new RegExp(`\\b(${words}|pending)\\b`, "i");
+    let settled = false;
+    for (const line of source.split("\n")) {
+        const marker = line.match(/^\s*\*\*(decision|status)[.:]/i);
+        if (!marker) continue;
+        const declaration = line.replace(/[*_]/g, "").replace(/^\s*(decision|status)[.:]\s*/i, "").split(/\bbecause\b/i)[0].trim();
+        const ownerForm = marker[1].toLowerCase() === "decision" ? declaration.match(/^[^—{}|<>\n]{1,160}—\s*(.*)$/) : null;
+        const leading = outcome.test(declaration) ? declaration : ownerForm?.[1] ?? declaration;
+        const match = leading.match(outcome);
+        if (!match) {
+            if (outcomeWord.test(declaration) || /[{}|<>]/.test(declaration)) return true;
+            if (ownerForm && !/^\d{4}-\d{2}-\d{2}\b/.test(leading)) return true;
+            continue;
+        }
+        const header = leading.split(/—|\bbecause\b/i)[0];
+        if (/[{}|<>?]/.test(header)) return true;
+        const rest = header.slice(match[0].length);
+        const alternative = rest.match(/\/|\bor\b|\bversus\b|\bvs\b|\b(?:and|but)\s+not\b/i);
+        if (alternative && outcomeWord.test(rest.slice(alternative.index))) return true;
+        settled = true;
+    }
+    return !settled;
 }
 
 // ---------------------------------------------------------------- Reading history
@@ -173,6 +185,58 @@ const listMarkdown = (dir) => {
     return names.filter((n) => n.endsWith(".md") && !NOT_A_RECORD.has(n)).sort();
 };
 
+function contextHeadroom(dir, workspace) {
+    try {
+        const declared = declaredContext(workspace);
+        const tree = treeOf(dir, workspace);
+        const base = { budget: declared.budget, ratio: declared.ratio ?? ESTIMATED_BYTES_PER_TOKEN, calibratedBy: declared.calibratedBy, drafts: [] };
+        if (tree === null) return { ...base, state: "unmeasured", bytes: null, tokens: null, remaining: null, reason: "no tree is declared" };
+        const root = fs.realpathSync(tree);
+        const measured = alwaysTier(root);
+        const bytes = measured.entries.reduce((sum, entry) => sum + entry.bytes, 0);
+        const tokens = tokensOf(bytes, base.ratio);
+        const result = { ...base, state: "measured", bytes, tokens, remaining: base.budget === null ? null : base.budget - tokens,
+            exclusions: { missing: measured.missing, outside: measured.outside, tooDeep: measured.tooDeep, scoped: measured.scoped, unlisted: measured.unlisted } };
+        if (base.budget === null) return result;
+        const realDir = fs.realpathSync(dir);
+        const declaration = guidanceDeclaration(root, path.relative(root, realDir) || ".");
+        if (declaration === null) return result;
+        const realContext = fs.realpathSync(declaration.dir);
+        if (!isInside(realDir, realContext) || realContext === realDir) throw new LibrarianError("slots.context resolves outside its workspace");
+        const loaded = new Map(measured.entries.filter(entry => entry.label === "rule").map(entry => [path.resolve(entry.file), entry]));
+        for (const file of listMarkdown(declaration.dir)) {
+            const source = path.join(declaration.dir, file);
+            if (fs.realpathSync(source) !== path.resolve(source)) continue;
+            if (measured.entries.some(entry => fs.realpathSync(entry.file) === source)) continue;
+            const unit = parseUnit(path.basename(file, ".md"), fs.readFileSync(source, "utf8"), file);
+            if (unit.tier !== "always" || unit.name === BOOT_CARD_UNIT || unit.body.includes("@")) continue;
+            if (unit.body.split("\n").some(line => [ENGINE_LINE, GATES_LINE, LEADS_LINE].some(pattern => pattern.test(line)))) continue;
+            const target = path.join(root, GUIDANCE_RULES_DIR, file);
+            const entry = loaded.get(target);
+            if (!entry || fs.realpathSync(target) !== path.resolve(target)) continue;
+            result.drafts.push({ source: path.relative(realDir, source).split(path.sep).join("/"), target: path.relative(root, target).split(path.sep).join("/"),
+                from: "always", to: "on-read", bytes: entry.bytes, tokens: tokensOf(entry.bytes, base.ratio) });
+        }
+        if (result.drafts.length) {
+            const plan = guidanceEdits(realDir);
+            if (fs.realpathSync(plan.root) !== root) throw new LibrarianError("the compiler ownership plan does not cover the measured tree; no demotions can be drafted");
+            const resolved = resolveWorkspace(realDir);
+            if (fs.realpathSync(path.resolve(resolved.workspaceRoot, resolved.workspaceDir)) !== realDir) throw new LibrarianError("the compiler ownership plan does not cover the measured workspace; no demotions can be drafted");
+            const repairs = new Set([...plan.edits.map(edit => edit.file), ...plan.left]);
+            if (repairs.has(`${GUIDANCE_RULES_DIR}/${RULES_MARKER}`)) {
+                result.drafts = [];
+                result.draftNote = "Compiler ownership needs regeneration; recompile before drafting demotions.";
+            } else result.drafts = result.drafts.filter(draft => !repairs.has(draft.target));
+        }
+        result.drafts.sort((a, b) => b.bytes - a.bytes || (a.source < b.source ? -1 : a.source > b.source ? 1 : 0));
+        result.drafts = result.drafts.slice(0, TOP_CONTRIBUTORS);
+        return result;
+    } catch (cause) {
+        if (cause instanceof LibrarianError) throw cause;
+        throw new LibrarianError(`the always tier could not be measured or drafted — ${cause.message}`);
+    }
+}
+
 /** One workspace's pass, which never writes: `run` does, after it. */
 export function passWorkspace(dir, { asOf, reviews, since } = {}) {
     parseDate(asOf, "--as-of");
@@ -385,6 +449,7 @@ export function passWorkspace(dir, { asOf, reviews, since } = {}) {
         handoffs: series,
         mining,
         consolidation,
+        context: contextHeadroom(dir, workspace),
     };
 }
 
@@ -509,8 +574,8 @@ export function renderReport(results, { asOf }) {
         "",
         `**Date:** ${asOf} · Filed by \`cli/librarian.mjs\` on a cron.`,
         "",
-        "**State.** Every figure below is **as of " + asOf + "**, read from git history rather than from the",
-        "filesystem, and nothing here is a decision. This pass drafts; the maintainer disposes.",
+        `**State.** Ages are read from git history as of ${asOf}; sizes and context headroom describe the tree on arrival, before any index regeneration.`,
+        "Nothing here is a decision. This pass drafts; the maintainer disposes.",
         "",
     ];
 
@@ -521,6 +586,25 @@ export function renderReport(results, { asOf }) {
         }
         const t = r.thresholds;
         out.push(`## ${r.name}`, "");
+        const context = r.context;
+        if (context) {
+            const cap = context.budget === null ? "budget undeclared; headroom unjudged" : `budget ${context.budget} tokens`;
+            if (context.state === "unmeasured") out.push(`**Always tier — Claude Code project.** Not measured: ${context.reason}; ${cap}.`, "");
+            else {
+                const headroom = context.remaining === null ? cap : `${cap}; ~${context.remaining} tokens headroom`;
+                out.push(`**Always tier — Claude Code project.** ${context.bytes} B, ~${context.tokens} tokens at ${context.ratio} bytes per token (${context.calibratedBy ?? "unconfigured estimate"}); ${headroom}.`, "");
+                const e = context.exclusions;
+                out.push(`**Measurement limits.** ${e.missing.length} missing imports; ${e.outside.length} outside imports or links; ${e.tooDeep.length} depth-limited imports; ${e.scoped} path-scoped rules; ${e.unlisted} descriptions unavailable. Personal/parent instructions, auto memory, system/tool prompts and plugin descriptions are outside this project measurement.`, "");
+                for (const [label, values] of [["Missing", e.missing], ["Outside", e.outside], ["Depth-limited", e.tooDeep]]) {
+                    if (values.length) out.push(`${label}: ${values.map(value => `\`${value}\``).join(", ")}.`, "");
+                }
+            }
+            out.push(`**Context demotion drafts.** ${context.drafts.length} conditional candidate(s); nothing applied. Pure, loaded, compiler-owned, matching always units only; boot cards, at-sign text, imported sources, expansions, links and stale targets are not drafted.`, "");
+            if (context.draftNote) out.push(context.draftNote, "");
+            for (const draft of context.drafts) {
+                out.push(`- **Draft: \`${draft.source}\`, \`${draft.from}\` → \`${draft.to}\`.** \`${draft.target}\` currently contributes ${draft.bytes} B (~${draft.tokens} tokens). If the maintainer decides this guidance can wait for an explicit read, change its tier, add a one-line \`description\`, preserve its body, recompile, and record before/after measurements. This is not a measured savings claim.`, "");
+            }
+        }
         out.push(
             `**Store.** ${plural(r.counts.records, "record")}, ${plural(r.counts.rules, "rule")}, ` +
                 `${(r.counts.bytes / 1024).toFixed(1)} KB` +
@@ -543,7 +627,7 @@ export function renderReport(results, { asOf }) {
                     `${(r.handoffs.bytes / 1024).toFixed(1)} KB, oldest ${r.handoffs.oldest ? `\`${r.handoffs.oldest.file}\` at ${plural(r.handoffs.oldest.days, "day")}` : "none — the series is empty"}. ` +
                     "Index: " +
                     indexState(r.index.series.handoffs) +
-                    ". No threshold reaches this series and no demotion is drafted against it: it is " +
+                    ". No aggregate size or staleness threshold reaches this series and no staleness demotion is drafted against it: it is " +
                     "append-only, so the only repair a staleness draft could recommend is deleting the " +
                     "record the series exists to keep.",
                 "",