toolroll 0.5.0

package/dist/policy-ui.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Settings → Policy (sprint 8): the organisation policy — allowed providers,
+ * models and tools, and the permission ceiling — and its history from the
+ * action ledger. Anyone signed in reads it; an instance operator changes it
+ * with their password.
+ */
+import type { LedgerEntry } from "./action-ledger.js";
+import { type SavedPolicy } from "./policy.js";
+export declare const POLICY_CSS: string;
+export type PolicyView = {
+    policy: SavedPolicy;
+    history: LedgerEntry[];
+    canChange: boolean;
+    /** The project tools here, as a hint for the tools list. */
+    toolNames: string[];
+};
+export declare function policyHtml(view: PolicyView, csrf: string, notice: {
+    said?: string | null;
+    problem?: string | null;
+}): string;

package/dist/policy-ui.js

@@ -0,0 +1,41 @@
+import { LEVEL_HINTS, LEVEL_NAMES, PERMISSION_LEVELS, POLICY_PROVIDERS, PROVIDER_NAMES, policyParts } from "./policy.js";
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+export const POLICY_CSS = `.policy{max-width:720px;min-width:0}.policy dl{display:grid;grid-template-columns:max-content minmax(0,1fr);gap:6px 16px;margin:12px 0 0;font-size:.875rem}` +
+    `.policy dt{color:var(--muted-foreground)}.policy dd{margin:0;overflow-wrap:anywhere}.policy fieldset{border:0;padding:0;margin:20px 0 0;min-width:0}` +
+    `.policy legend{font-weight:600;font-size:.875rem;margin-bottom:8px}.policy legend{padding:0}.policy .providers{display:grid;grid-template-columns:repeat(auto-fill,minmax(132px,1fr));gap:0 16px}.policy .providers label{display:flex;gap:8px;align-items:center;min-height:44px;margin:0;padding:0;font-weight:400}` +
+    `.policy .choice{display:grid;grid-template-columns:auto minmax(0,1fr);gap:10px;align-items:start;margin:0 0 10px;font-weight:400}.policy .choice input{margin:.2rem 0 0}` +
+    `.policy .choice strong{display:block;font-size:.875rem;font-weight:500}.policy .choice small,.policy .hint{display:block;color:var(--muted-foreground);font-size:.8125rem;margin-top:2px}` +
+    `.policy textarea{width:100%;min-height:72px;font-family:var(--font-mono);font-size:.8125rem;box-sizing:border-box}.policy .step-up{margin-top:18px}.policy button[type=submit]{margin-top:14px}` +
+    `.policy details{margin-top:28px}.policy summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600;font-size:.875rem}` +
+    `.policy ol{list-style:none;padding:0;margin:0}.policy li{padding:10px 0;border-bottom:1px solid var(--border);font-size:.8125rem;overflow-wrap:anywhere}.policy li .what{display:block;font-size:.875rem}`;
+/** A ledger entry as one line of history: when, who, what, before → after. */
+function historyItem(entry) {
+    const what = entry.action.replace(/^organisation policy: /, "");
+    const [before, after] = (entry.detail ?? "").split(" → ");
+    return `<li><span class="what">${e(what.charAt(0).toUpperCase() + what.slice(1))}: ${e(before ?? "")} → <strong>${e(after ?? "")}</strong></span>` +
+        `<span class="meta">${e(entry.actor)} · <time datetime="${e(entry.at)}">${e(entry.at.slice(0, 16).replace("T", " "))} UTC</time></span></li>`;
+}
+export function policyHtml(view, csrf, notice) {
+    const note = notice.problem ? `<p class="problem" role="alert">${e(notice.problem)}</p>` : notice.said ? `<p role="status">${e(notice.said)}</p>` : "";
+    const parts = policyParts(view.policy);
+    const changed = view.policy.updatedBy === null ? "" : `<p class="meta">Changed by ${e(view.policy.updatedBy)} on ${e((view.policy.updatedAt ?? "").slice(0, 10))}.</p>`;
+    const current = `<dl><dt>Providers</dt><dd>${e(parts.providers === "any" ? "Any" : parts.providers)}</dd><dt>Models</dt><dd>${e(parts.models === "any" ? "Any" : parts.models)}</dd>` +
+        `<dt>Tools</dt><dd>${e(parts.tools === "any" ? "Any" : parts.tools)}</dd><dt>Ceiling</dt><dd>${e(parts.ceiling)}</dd></dl>${changed}`;
+    const history = view.history.length === 0 ? "" : `<details><summary>History (${view.history.length})</summary><ol>${view.history.map(historyItem).join("")}</ol></details>`;
+    if (!view.canChange)
+        return `<section class="policy">${note}${current}<p class="meta">An instance operator sets the policy.</p>${history}</section>`;
+    const providers = POLICY_PROVIDERS.map(one => `<label><input type="checkbox" name="provider" value="${one}"${view.policy.providers === null || view.policy.providers.includes(one) ? " checked" : ""}> ${PROVIDER_NAMES[one]}</label>`).join("");
+    const levels = [...PERMISSION_LEVELS].reverse().map(level => `<label class="choice"><input type="radio" name="ceiling" value="${level}"${view.policy.ceiling === level ? " checked" : ""}>` +
+        `<span><strong>${LEVEL_NAMES[level]}</strong><small>${e(LEVEL_HINTS[level])}</small></span></label>`).join("");
+    const toolHint = view.toolNames.length === 0 ? "" : ` Tools here: ${view.toolNames.slice(0, 12).join(", ")}${view.toolNames.length > 12 ? "…" : ""}.`;
+    return `<section class="policy">${note}${changed}` +
+        `<form method="post" action="/settings/policy"><input type="hidden" name="csrf" value="${e(csrf)}">` +
+        `<fieldset><legend>Providers</legend><div class="providers">${providers}</div></fieldset>` +
+        `<fieldset><legend><label for="policy-models">Models</label></legend><textarea id="policy-models" name="models" spellcheck="false" placeholder="Any model" aria-describedby="policy-models-hint">${e((view.policy.models ?? []).join("\n"))}</textarea>` +
+        `<span class="hint" id="policy-models-hint">One per line; end with * to allow a family. Blank allows any.</span></fieldset>` +
+        `<fieldset><legend><label for="policy-tools">Project tools</label></legend><textarea id="policy-tools" name="tools" spellcheck="false" placeholder="Any tool" aria-describedby="policy-tools-hint">${e((view.policy.tools ?? []).join("\n"))}</textarea>` +
+        `<span class="hint" id="policy-tools-hint">One per line. Blank allows any.${e(toolHint)}</span></fieldset>` +
+        `<fieldset><legend>Permission ceiling</legend>${levels}</fieldset>` +
+        `<div class="step-up"><label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label></div>` +
+        `<button type="submit">Save policy</button></form>${history}</section>`;
+}

package/dist/policy.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Organisation policy (sprint 8): one policy for the whole installation, set
+ * by an instance operator on Settings → Policy or with `toolroll policy
+ * set`. It says which providers and models may run, which project tools
+ * (MCP servers) agents may use, and the highest permission level any task,
+ * project or mode may run with.
+ *
+ * Nothing set means nothing restricted: no row is the open policy. The
+ * permission levels, lowest first:
+ *   safe       edits only: Claude accepts edits (acceptEdits), Gemini auto_edit;
+ *              Codex and OpenRouter have no setting this low
+ *   standard   routine commands: Claude auto, Codex's workspace sandbox
+ *   escalated  full access: Claude bypassPermissions, Codex danger-full-access, Gemini yolo
+ * Work above the ceiling runs at the highest level beneath it its provider has
+ * (lowered), or, when there is none, doesn't run (refused); the words say which.
+ *
+ * Every road that admits work asks here: scope approval, the tick before a
+ * run starts (and build() as the last look), fallback entries, race lanes,
+ * attended sessions, the lead and project chats, teammates and flow steps.
+ */
+import type { Database } from "./store.js";
+import type { ExecutionProfile } from "./scope.js";
+export type PermissionLevel = "safe" | "standard" | "escalated";
+export declare const PERMISSION_LEVELS: readonly PermissionLevel[];
+export declare const POLICY_PROVIDERS: readonly ["claude", "codex", "gemini", "openrouter"];
+export type PolicyProvider = (typeof POLICY_PROVIDERS)[number];
+/** The policy as saved: null lists allow everything of their kind. */
+export type OrgPolicy = {
+    providers: PolicyProvider[] | null;
+    models: string[] | null;
+    tools: string[] | null;
+    ceiling: PermissionLevel;
+};
+export type SavedPolicy = OrgPolicy & {
+    updatedBy: string | null;
+    updatedAt: string | null;
+};
+export declare const OPEN_POLICY: OrgPolicy;
+/** v105 keeps its version: the policy is a table of its own, made beside the spend tables. One row, or none. */
+export declare const POLICY_SCHEMA = "\nCREATE TABLE IF NOT EXISTS org_policy (\n  id             INTEGER PRIMARY KEY CHECK (id = 1),\n  providers_json TEXT,\n  models_json    TEXT,\n  tools_json     TEXT,\n  ceiling        TEXT NOT NULL DEFAULT 'escalated' CHECK (ceiling IN ('safe', 'standard', 'escalated')),\n  updated_by     TEXT NOT NULL,\n  updated_at     TEXT NOT NULL\n);\n";
+/** The policy in force. A missing table (a database not yet opened by this build) reads as open. */
+export declare function readPolicy(db: Database): SavedPolicy;
+export declare const PROVIDER_NAMES: Record<PolicyProvider, string>;
+export declare const LEVEL_NAMES: Record<PermissionLevel, string>;
+export declare const LEVEL_HINTS: Record<PermissionLevel, string>;
+/** Where a refusal sends people. */
+export declare const WHERE = "An instance operator can change it in Settings \u2192 Policy.";
+/** A provider id as the policy knows it: chat and key variants count as their provider. */
+export declare function policyProvider(provider: string): PolicyProvider | null;
+/** Each rule in words, for the page, the command and the ledger. */
+export declare function policyParts(policy: OrgPolicy): {
+    providers: string;
+    models: string;
+    tools: string;
+    ceiling: string;
+};
+export declare function isOpen(policy: OrgPolicy): boolean;
+/** Whether a model id matches an entry: the same id (any case), or a prefix ending in `*`. */
+export declare function modelMatches(entry: string, model: string): boolean;
+/** Why the policy stops an agent on this provider and model, or null. A default model ("default", or none) can't be
+ * checked against a model list, so a list stops it. */
+export declare function agentRefusal(policy: OrgPolicy, provider: string, model: string | null): string | null;
+/** Why the policy stops agents using a project tool, or null. */
+export declare function toolRefusal(policy: OrgPolicy, tool: string): string | null;
+export declare const levelAbove: (level: PermissionLevel, ceiling: PermissionLevel) => boolean;
+/** The level a profile runs at. */
+export declare function levelOfProfile(profile: ExecutionProfile): PermissionLevel;
+/** A level's words for one provider: "Full access", "Auto", "Accept edits". */
+export declare function levelWords(profile: ExecutionProfile): string;
+export type CeilingVerdict = {
+    ok: true;
+    profile: ExecutionProfile;
+    lowered: null;
+} | {
+    ok: true;
+    profile: ExecutionProfile;
+    lowered: string;
+} | {
+    ok: false;
+    message: string;
+};
+/** Hold a profile to the ceiling: as it is, lowered (and the words say so), or refused (and the words say why). */
+export declare function underCeiling(policy: OrgPolicy, profile: ExecutionProfile): CeilingVerdict;
+/** Why the ceiling stops a planner, scout or native coding session on this provider, or null. They carry no sealed
+ * profile to lower: on Claude and Gemini they edit only (Safe); on Codex and OpenRouter they run in the workspace
+ * sandbox (Standard), those providers' lowest. */
+export declare function sessionCeilingRefusal(policy: OrgPolicy, provider: string, what: string): string | null;
+/** Everything the policy says about a profile before it runs: refused (words), or what runs and any lowering. */
+export declare function profileVerdict(policy: OrgPolicy, profile: ExecutionProfile): CeilingVerdict;
+/** An attended session runs at exactly what the person signed, so nothing is lowered: it runs as signed, or is refused. */
+export declare function attendedRefusal(policy: OrgPolicy, profile: ExecutionProfile): string | null;
+/** At approval, a person signs exact terms: anything above the ceiling is refused with words (a new filing is lowered). */
+export declare function approvalRefusal(policy: OrgPolicy, profiles: readonly ExecutionProfile[], legs?: readonly {
+    provider: string;
+    model: string | null;
+}[]): string | null;
+/** Read a list typed by a person: commas or new lines, trimmed, no repeats; blank is "any". */
+export declare function parseList(text: string | null | undefined): string[] | null;
+/** Check a policy before it's saved. */
+export declare function checkPolicy(input: {
+    providers: readonly string[] | null;
+    models: readonly string[] | null;
+    tools: readonly string[] | null;
+    ceiling: string;
+}): {
+    ok: true;
+    policy: OrgPolicy;
+} | {
+    ok: false;
+    problem: string;
+};

package/dist/policy.js

@@ -0,0 +1,231 @@
+export const PERMISSION_LEVELS = ["safe", "standard", "escalated"];
+export const POLICY_PROVIDERS = ["claude", "codex", "gemini", "openrouter"];
+export const OPEN_POLICY = { providers: null, models: null, tools: null, ceiling: "escalated" };
+/** v105 keeps its version: the policy is a table of its own, made beside the spend tables. One row, or none. */
+export const POLICY_SCHEMA = `
+CREATE TABLE IF NOT EXISTS org_policy (
+  id             INTEGER PRIMARY KEY CHECK (id = 1),
+  providers_json TEXT,
+  models_json    TEXT,
+  tools_json     TEXT,
+  ceiling        TEXT NOT NULL DEFAULT 'escalated' CHECK (ceiling IN ('safe', 'standard', 'escalated')),
+  updated_by     TEXT NOT NULL,
+  updated_at     TEXT NOT NULL
+);
+`;
+const listOf = (value) => {
+    if (value === null || value === undefined)
+        return null;
+    try {
+        const parsed = JSON.parse(String(value));
+        return Array.isArray(parsed) ? parsed.map(one => String(one)) : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** The policy in force. A missing table (a database not yet opened by this build) reads as open. */
+export function readPolicy(db) {
+    let row;
+    try {
+        row = db.prepare("SELECT * FROM org_policy WHERE id = 1").get();
+    }
+    catch {
+        row = undefined;
+    }
+    if (row === undefined)
+        return { ...OPEN_POLICY, updatedBy: null, updatedAt: null };
+    const ceiling = PERMISSION_LEVELS.includes(row["ceiling"]) ? row["ceiling"] : "escalated";
+    return {
+        providers: listOf(row["providers_json"])?.filter((one) => POLICY_PROVIDERS.includes(one)) ?? null,
+        models: listOf(row["models_json"]),
+        tools: listOf(row["tools_json"]),
+        ceiling,
+        updatedBy: row["updated_by"] == null ? null : String(row["updated_by"]),
+        updatedAt: row["updated_at"] == null ? null : String(row["updated_at"]),
+    };
+}
+// ---- words -------------------------------------------------------------------------------
+export const PROVIDER_NAMES = { claude: "Claude", codex: "Codex", gemini: "Gemini", openrouter: "OpenRouter" };
+export const LEVEL_NAMES = { safe: "Safe", standard: "Standard", escalated: "Escalated" };
+export const LEVEL_HINTS = {
+    safe: "Edits in the project only. Codex and OpenRouter can't run this low.",
+    standard: "Edits and routine commands. Full access is lowered to this.",
+    escalated: "Anything a task, project or mode was approved for, full access included.",
+};
+/** Where a refusal sends people. */
+export const WHERE = "An instance operator can change it in Settings → Policy.";
+/** A provider id as the policy knows it: chat and key variants count as their provider. */
+export function policyProvider(provider) {
+    const base = provider === "anthropic-api" ? "claude" : provider.replace(/-(subscription|api)$/, "");
+    return POLICY_PROVIDERS.includes(base) ? base : null;
+}
+const providerName = (provider) => {
+    const known = policyProvider(provider);
+    return known === null ? provider : PROVIDER_NAMES[known];
+};
+const listWords = (list, names = one => one) => list === null ? "any" : list.length === 0 ? "none" : list.map(names).join(", ");
+/** Each rule in words, for the page, the command and the ledger. */
+export function policyParts(policy) {
+    return {
+        providers: listWords(policy.providers, one => PROVIDER_NAMES[one] ?? one),
+        models: listWords(policy.models),
+        tools: listWords(policy.tools),
+        ceiling: LEVEL_NAMES[policy.ceiling],
+    };
+}
+export function isOpen(policy) {
+    return policy.providers === null && policy.models === null && policy.tools === null && policy.ceiling === "escalated";
+}
+// ---- providers, models and tools -----------------------------------------------------------
+/** Whether a model id matches an entry: the same id (any case), or a prefix ending in `*`. */
+export function modelMatches(entry, model) {
+    const want = entry.trim().toLowerCase(), have = model.trim().toLowerCase();
+    return want.endsWith("*") ? have.startsWith(want.slice(0, -1)) : want === have;
+}
+/** Why the policy stops an agent on this provider and model, or null. A default model ("default", or none) can't be
+ * checked against a model list, so a list stops it. */
+export function agentRefusal(policy, provider, model) {
+    const family = policyProvider(provider);
+    if (policy.providers !== null && (family === null || !policy.providers.includes(family))) {
+        return `The organisation policy doesn't allow ${providerName(provider)}. ${WHERE}`;
+    }
+    if (policy.models !== null) {
+        if (model === null || model === "" || model === "default") {
+            return `The organisation policy allows only listed models, and this uses ${providerName(provider)}'s default model. Choose a listed model, or ${WHERE.charAt(0).toLowerCase()}${WHERE.slice(1)}`;
+        }
+        if (!policy.models.some(entry => modelMatches(entry, model)))
+            return `The organisation policy doesn't allow the model ${model}. ${WHERE}`;
+    }
+    return null;
+}
+/** Why the policy stops agents using a project tool, or null. */
+export function toolRefusal(policy, tool) {
+    return policy.tools === null || policy.tools.includes(tool) ? null : `The organisation policy doesn't allow the tool ${tool}. ${WHERE}`;
+}
+// ---- the permission ceiling ------------------------------------------------------------------
+const RANK = { safe: 0, standard: 1, escalated: 2 };
+export const levelAbove = (level, ceiling) => RANK[level] > RANK[ceiling];
+/** The level a profile runs at. */
+export function levelOfProfile(profile) {
+    if (profile.provider === "claude")
+        return profile.permissionArgv === "bypassPermissions" ? "escalated" : profile.permissionArgv === "auto" ? "standard" : "safe";
+    if (profile.provider === "gemini")
+        return profile.approvalArgv === "yolo" ? "escalated" : "safe";
+    return profile.sandboxMode === "danger-full-access" ? "escalated" : "standard";
+}
+/** The same profile at a level, or null when its provider has no setting that low. */
+function profileAt(profile, level) {
+    if (profile.provider === "claude")
+        return { ...profile, permissionArgv: level === "escalated" ? "bypassPermissions" : level === "standard" ? "auto" : "acceptEdits" };
+    if (profile.provider === "gemini")
+        return { ...profile, approvalArgv: level === "escalated" ? "yolo" : "auto_edit" };
+    return level === "safe" ? null : { ...profile, sandboxMode: level === "escalated" ? "danger-full-access" : "workspace-write" };
+}
+/** A level's words for one provider: "Full access", "Auto", "Accept edits". */
+export function levelWords(profile) {
+    if (profile.provider === "claude")
+        return profile.permissionArgv === "bypassPermissions" ? "full access" : profile.permissionArgv === "auto" ? "auto" : "accept edits";
+    if (profile.provider === "gemini")
+        return profile.approvalArgv === "yolo" ? "full access" : "auto edit";
+    return profile.sandboxMode === "danger-full-access" ? "full access" : "the workspace sandbox";
+}
+/** Hold a profile to the ceiling: as it is, lowered (and the words say so), or refused (and the words say why). */
+export function underCeiling(policy, profile) {
+    const level = levelOfProfile(profile);
+    if (!levelAbove(level, policy.ceiling))
+        return { ok: true, profile, lowered: null };
+    const ceiling = LEVEL_NAMES[policy.ceiling];
+    for (const below of [...PERMISSION_LEVELS].reverse()) {
+        if (levelAbove(below, policy.ceiling) || !levelAbove(level, below))
+            continue;
+        const lower = profileAt(profile, below);
+        if (lower === null)
+            continue;
+        return { ok: true, profile: lower, lowered: `The organisation policy's permission ceiling is ${ceiling}, so this runs with ${levelWords(lower)} instead of ${levelWords(profile)}.` };
+    }
+    return { ok: false, message: `The organisation policy's permission ceiling is ${ceiling}, and ${providerName(profile.provider)} can't run that low. ${WHERE}` };
+}
+/** Why the ceiling stops a planner, scout or native coding session on this provider, or null. They carry no sealed
+ * profile to lower: on Claude and Gemini they edit only (Safe); on Codex and OpenRouter they run in the workspace
+ * sandbox (Standard), those providers' lowest. */
+export function sessionCeilingRefusal(policy, provider, what) {
+    const known = policyProvider(provider);
+    const level = known === "claude" || known === "gemini" ? "safe" : "standard";
+    if (!levelAbove(level, policy.ceiling))
+        return null;
+    return `The organisation policy's permission ceiling is ${LEVEL_NAMES[policy.ceiling]}, and ${providerName(provider)} ${what} can't run that low. ${WHERE}`;
+}
+/** Everything the policy says about a profile before it runs: refused (words), or what runs and any lowering. */
+export function profileVerdict(policy, profile) {
+    const agent = agentRefusal(policy, profile.provider, profile.model);
+    if (agent !== null)
+        return { ok: false, message: agent };
+    const repair = profile.repairModel === "inherit" || profile.repairModel === profile.model ? null : agentRefusal(policy, profile.provider, profile.repairModel);
+    if (repair !== null)
+        return { ok: false, message: `Its repairs: ${repair.charAt(0).toLowerCase()}${repair.slice(1)}` };
+    return underCeiling(policy, profile);
+}
+/** An attended session runs at exactly what the person signed, so nothing is lowered: it runs as signed, or is refused. */
+export function attendedRefusal(policy, profile) {
+    const verdict = profileVerdict(policy, profile);
+    if (!verdict.ok)
+        return verdict.message;
+    return verdict.lowered === null ? null
+        : `This session asks for ${levelWords(profile)}, above the organisation policy's permission ceiling (${LEVEL_NAMES[policy.ceiling]}). Authorise it again with a lower permission, or ${WHERE.charAt(0).toLowerCase()}${WHERE.slice(1)}`;
+}
+/** At approval, a person signs exact terms: anything above the ceiling is refused with words (a new filing is lowered). */
+export function approvalRefusal(policy, profiles, legs = []) {
+    for (const profile of profiles) {
+        const verdict = profileVerdict(policy, profile);
+        if (!verdict.ok)
+            return verdict.message;
+        if (verdict.lowered !== null) {
+            return `This asks for ${levelWords(profile)}, above the organisation policy's permission ceiling (${LEVEL_NAMES[policy.ceiling]}). File it again to run it within the ceiling, or ${WHERE.charAt(0).toLowerCase()}${WHERE.slice(1)}`;
+        }
+    }
+    for (const leg of legs) {
+        const refused = agentRefusal(policy, leg.provider, leg.model);
+        if (refused !== null)
+            return refused;
+    }
+    return null;
+}
+// ---- changes ---------------------------------------------------------------------------------
+/** Read a list typed by a person: commas or new lines, trimmed, no repeats; blank is "any". */
+export function parseList(text) {
+    const items = [...new Set(String(text ?? "").split(/[,\n]/).map(one => one.trim()).filter(one => one !== ""))];
+    return items.length === 0 ? null : items;
+}
+/** Check a policy before it's saved. */
+export function checkPolicy(input) {
+    if (!PERMISSION_LEVELS.includes(input.ceiling))
+        return { ok: false, problem: "Choose a permission ceiling: safe, standard or escalated." };
+    let providers = null;
+    if (input.providers !== null) {
+        const unknown = input.providers.filter(one => policyProvider(one.toLowerCase()) === null);
+        if (unknown.length > 0)
+            return { ok: false, problem: `${unknown.join(", ")} isn't a provider here. Choose from Claude, Codex, Gemini and OpenRouter.` };
+        providers = POLICY_PROVIDERS.filter(one => input.providers.some(given => policyProvider(given.toLowerCase()) === one));
+        if (providers.length === 0)
+            return { ok: false, problem: "Allow at least one provider, or allow any." };
+    }
+    const clean = (list, what, limit) => {
+        if (list === null)
+            return null;
+        const items = [...new Set(list.map(one => one.trim()).filter(one => one !== ""))];
+        if (items.length > limit)
+            return { problem: `List at most ${limit} ${what}.` };
+        const bad = items.find(one => one.length > 120 || !/^[A-Za-z0-9._:/@~*+-]+$/.test(one));
+        if (bad !== undefined)
+            return { problem: `${bad.slice(0, 40)} isn't a ${what.replace(/s$/, "")} name. Use letters, numbers and . _ - : / @ ~ * only.` };
+        return items.length === 0 ? null : items;
+    };
+    const models = clean(input.models, "models", 100);
+    if (models !== null && !Array.isArray(models))
+        return { ok: false, problem: models.problem };
+    const tools = clean(input.tools, "tools", 100);
+    if (tools !== null && !Array.isArray(tools))
+        return { ok: false, problem: tools.problem };
+    return { ok: true, policy: { providers, models, tools, ceiling: input.ceiling } };
+}

package/dist/prepared-evidence.d.ts

@@ -0,0 +1,16 @@
+import { type ParsedProof } from './proof.js';
+export declare const PREPARED_EVIDENCE_FILE = "standing-orders.evidence.json";
+export declare const PREPARED_EVIDENCE_GIT: readonly ['--literal-pathspecs', '--no-lazy-fetch', '--no-replace-objects', '--no-optional-locks'];
+export type PreparedEvidence = {
+    proof: ParsedProof;
+    files: {
+        path: string;
+        sha256: string;
+        cap: number;
+    }[];
+};
+/** Reads immutable Git objects; local/untracked files cannot fill a missing entry. */
+export declare function readPreparedEvidence(repo: string, candidate: string, required?: boolean): PreparedEvidence | null;
+export declare function preparedScreenshotMatches(inventory: PreparedEvidence, path: string, bytes: Buffer): boolean;
+/** After checkout/setup, read without following links and mint this worker's receipt. */
+export declare function writePreparedEvidence(worktree: string, nonceFile: string, inventory: PreparedEvidence): void;

package/dist/prepared-evidence.js

@@ -0,0 +1,96 @@
+/** Committed image inventory, never claimed checks, completion, or approval. */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { lstatSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { imageDimensions, looksLikeProtocolFile, readMailbox, SCREENSHOT_BYTE_CAP, validateScreenshotBytes } from './evidence.js';
+import { parseProof, PROOF_LIMITS, SCREENSHOT_EVIDENCE_MIN_BYTES, SCREENSHOT_EVIDENCE_MIN_HEIGHT, SCREENSHOT_EVIDENCE_MIN_WIDTH, serializeProof } from './proof.js';
+export const PREPARED_EVIDENCE_FILE = 'standing-orders.evidence.json';
+export const PREPARED_EVIDENCE_GIT = ['--literal-pathspecs', '--no-lazy-fetch', '--no-replace-objects', '--no-optional-locks'];
+const nextAction = 'Ask Codex to prepare review screenshots and commit them with standing-orders.evidence.json, then review the new result.';
+const fail = (detail) => { throw Error(`Review screenshots are not ready. ${nextAction} ${detail}`); };
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+/** Reads immutable Git objects; local/untracked files cannot fill a missing entry. */
+export function readPreparedEvidence(repo, candidate, required = false) {
+    if (!/^[a-f0-9]{40}$/.test(candidate))
+        fail('The saved commit is invalid.');
+    const git = (args, cap) => {
+        try {
+            return execFileSync('git', [...PREPARED_EVIDENCE_GIT, '-C', repo, ...args], { stdio: ['ignore', 'pipe', 'pipe'], timeout: 10_000, maxBuffer: cap });
+        }
+        catch {
+            return fail('The committed screenshot inventory could not be read.');
+        }
+    };
+    const blob = (path, cap) => {
+        const entries = git(['ls-tree', '-z', '-l', candidate, '--', path], 2048).toString('utf8').split('\0').filter(Boolean);
+        if (!entries.length)
+            return null;
+        const match = /^(100644|100755) blob ([a-f0-9]{40}) +([0-9]+)\t([\s\S]+)$/.exec(entries[0]);
+        if (entries.length !== 1 || !match || match[4] !== path)
+            fail(`${path} must be a committed regular file.`);
+        const size = Number(match[3]);
+        if (!Number.isSafeInteger(size) || size > cap)
+            fail(`${path} exceeds the supported evidence size.`);
+        const bytes = git(['cat-file', 'blob', match[2]], cap);
+        if (bytes.length !== size || createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex') !== match[2])
+            fail(`${path} could not be read completely or its Git identity changed.`);
+        return bytes;
+    };
+    const raw = blob(PREPARED_EVIDENCE_FILE, PROOF_LIMITS.payload);
+    if (raw === null) {
+        if (required)
+            fail('No committed screenshot inventory was found.');
+        return null;
+    }
+    let body;
+    try {
+        body = JSON.parse(raw.toString('utf8'));
+    }
+    catch {
+        return fail('The screenshot inventory must be valid JSON.');
+    }
+    if (!body || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).some(key => !['version', 'screenshots'].includes(key)) ||
+        !Array.isArray(body['screenshots']) || body['screenshots'].some(shot => !shot || typeof shot !== 'object' || Array.isArray(shot) || Object.keys(shot).some(key => !['path', 'caption'].includes(key)))) {
+        fail('The inventory may contain only version 1 and screenshots with path and caption.');
+    }
+    const parsed = parseProof(raw.toString('utf8'));
+    if (!parsed.ok)
+        return fail(parsed.problems.map(problem => problem.message).join('; '));
+    if (required && parsed.proof.screenshots.length === 0)
+        fail('The committed inventory has no screenshots.');
+    const files = [{ path: PREPARED_EVIDENCE_FILE, sha256: digest(raw), cap: PROOF_LIMITS.payload }];
+    for (const shot of parsed.proof.screenshots) {
+        if (shot.path.split('/').some(part => /^\.git$/i.test(part) || looksLikeProtocolFile(part)))
+            fail('A screenshot cannot name Git metadata or a prior attempt’s protocol file.');
+        const bytes = blob(shot.path, SCREENSHOT_BYTE_CAP);
+        if (bytes === null)
+            fail(`${shot.path} is not committed in this result.`);
+        const image = validateScreenshotBytes(bytes);
+        if (!image.ok)
+            return fail(`${shot.path}: ${image.problem}`);
+        const dims = imageDimensions(bytes, image.kind);
+        if (bytes.length < SCREENSHOT_EVIDENCE_MIN_BYTES || !dims || dims.width < SCREENSHOT_EVIDENCE_MIN_WIDTH || dims.height < SCREENSHOT_EVIDENCE_MIN_HEIGHT)
+            fail(`${shot.path} needs a readable screenshot of at least ${SCREENSHOT_EVIDENCE_MIN_BYTES} bytes and ${SCREENSHOT_EVIDENCE_MIN_WIDTH}×${SCREENSHOT_EVIDENCE_MIN_HEIGHT} pixels.`);
+        files.push({ path: shot.path, sha256: digest(bytes), cap: SCREENSHOT_BYTE_CAP });
+    }
+    return { proof: parsed.proof, files };
+}
+export function preparedScreenshotMatches(inventory, path, bytes) {
+    return inventory.files.some(file => file.path === path && file.sha256 === digest(bytes));
+}
+/** After checkout/setup, read without following links and mint this worker's receipt. */
+export function writePreparedEvidence(worktree, nonceFile, inventory) {
+    for (const file of inventory.files) {
+        const parts = file.path.split('/');
+        for (let count = 1; count < parts.length; count++) {
+            const parent = lstatSync(join(worktree, ...parts.slice(0, count)));
+            if (!parent.isDirectory() || parent.isSymbolicLink())
+                fail(`${file.path} has a linked or missing parent directory.`);
+        }
+        const read = readMailbox(join(worktree, file.path), file.cap);
+        if (!read.ok || !preparedScreenshotMatches(inventory, file.path, read.raw))
+            fail(`${file.path} no longer matches the saved commit.`);
+    }
+    writeFileSync(join(worktree, nonceFile), serializeProof(inventory.proof), { flag: 'wx', mode: 0o600 });
+}

package/dist/pricing.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pinned build-model prices (tournament design v3, stage 1; the round-3
+ * findings are the spec). Integer micro-dollars per SINGLE token, rounded
+ * UP from list prices, with the cache token classes priced separately —
+ * finding 24: a "one call" tail computed from rates alone bounds nothing;
+ * quantity must be pinned too, so every model row carries its context
+ * window and maximum output, and the tail is the worst legal call:
+ * every context token at the DEAREST input class plus every output token.
+ *
+ * Conservative by construction: reservations overcharge, never under.
+ * PRICE_VERSION is stamped into approved tournament terms — a price table
+ * edit never silently reprices an existing approval.
+ */
+export declare const BUILD_PRICE_VERSION = 1;
+export type BuildModelPrice = {
+    /** Micro-dollars per token, ceil'd from list. */
+    inMicrousd: number;
+    outMicrousd: number;
+    cacheWriteMicrousd: number;
+    cacheReadMicrousd: number;
+    /** The pinned request envelope's quantity bounds (finding 24). */
+    contextTokens: number;
+    maxOutputTokens: number;
+};
+export declare function buildPriceOf(model: string): BuildModelPrice | null;
+export declare const PRICED_BUILD_MODELS: readonly string[];
+/**
+ * The non-spendable overrun reserve: the worst one API call the pinned
+ * envelope permits. Claude's native cap checks the budget AFTER each
+ * call, so the true maximum is budget + one full call — this is that
+ * call, priced at the dearest input class (finding 24's arithmetic).
+ * Held apart from the spendable budget and NEVER granted to a later
+ * invocation: each lineage invocation's native cap derives from
+ * max(spendable − accounted, 0) alone.
+ */
+export declare function oneCallTailMicrousd(model: string): number | null;
+/** Settlement at pinned rates from a usage report that itemizes cache
+ * classes; absent classes count as zero, absent totals fail closed by
+ * returning null (the caller latches unknown spend, never guesses). */
+export declare function settleBuildMicrousd(model: string, usage: {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheWriteTokens?: number;
+    cacheReadTokens?: number;
+}): number | null;

package/dist/pricing.js

@@ -0,0 +1,77 @@
+/**
+ * Pinned build-model prices (tournament design v3, stage 1; the round-3
+ * findings are the spec). Integer micro-dollars per SINGLE token, rounded
+ * UP from list prices, with the cache token classes priced separately —
+ * finding 24: a "one call" tail computed from rates alone bounds nothing;
+ * quantity must be pinned too, so every model row carries its context
+ * window and maximum output, and the tail is the worst legal call:
+ * every context token at the DEAREST input class plus every output token.
+ *
+ * Conservative by construction: reservations overcharge, never under.
+ * PRICE_VERSION is stamped into approved tournament terms — a price table
+ * edit never silently reprices an existing approval.
+ */
+export const BUILD_PRICE_VERSION = 1;
+const PRICES = {
+    "claude-sonnet-5": {
+        inMicrousd: 3,
+        outMicrousd: 15,
+        cacheWriteMicrousd: 4, // 1.25x input, ceil'd
+        cacheReadMicrousd: 1, // 0.1x input, ceil'd up
+        contextTokens: 200_000,
+        maxOutputTokens: 64_000,
+    },
+    "claude-opus-5": {
+        inMicrousd: 15,
+        outMicrousd: 75,
+        cacheWriteMicrousd: 19,
+        cacheReadMicrousd: 2,
+        contextTokens: 200_000,
+        maxOutputTokens: 32_000,
+    },
+    "claude-haiku-4-5": {
+        inMicrousd: 1,
+        outMicrousd: 5,
+        cacheWriteMicrousd: 2,
+        cacheReadMicrousd: 1,
+        contextTokens: 200_000,
+        maxOutputTokens: 64_000,
+    },
+};
+export function buildPriceOf(model) {
+    return PRICES[model] ?? null;
+}
+export const PRICED_BUILD_MODELS = Object.keys(PRICES);
+/**
+ * The non-spendable overrun reserve: the worst one API call the pinned
+ * envelope permits. Claude's native cap checks the budget AFTER each
+ * call, so the true maximum is budget + one full call — this is that
+ * call, priced at the dearest input class (finding 24's arithmetic).
+ * Held apart from the spendable budget and NEVER granted to a later
+ * invocation: each lineage invocation's native cap derives from
+ * max(spendable − accounted, 0) alone.
+ */
+export function oneCallTailMicrousd(model) {
+    const price = buildPriceOf(model);
+    if (price === null)
+        return null;
+    const dearestInput = Math.max(price.inMicrousd, price.cacheWriteMicrousd, price.cacheReadMicrousd);
+    return price.contextTokens * dearestInput + price.maxOutputTokens * price.outMicrousd;
+}
+/** Settlement at pinned rates from a usage report that itemizes cache
+ * classes; absent classes count as zero, absent totals fail closed by
+ * returning null (the caller latches unknown spend, never guesses). */
+export function settleBuildMicrousd(model, usage) {
+    const price = buildPriceOf(model);
+    if (price === null)
+        return null;
+    const { inputTokens, outputTokens } = usage;
+    if (inputTokens === undefined || outputTokens === undefined)
+        return null;
+    if (!Number.isFinite(inputTokens) || !Number.isFinite(outputTokens) || inputTokens < 0 || outputTokens < 0)
+        return null;
+    return (inputTokens * price.inMicrousd +
+        outputTokens * price.outMicrousd +
+        (usage.cacheWriteTokens ?? 0) * price.cacheWriteMicrousd +
+        (usage.cacheReadTokens ?? 0) * price.cacheReadMicrousd);
+}