toolroll 0.9.103 → 0.9.105

package/dist/planner.js

@@ -3,19 +3,6 @@ import { skillsContext } from "./project-skills.js";
 import { learningContext } from "./project-learning.js";
 import { deliverCodeMap } from "./code-map-admission.js";
 import { knowledgeContext } from "./project-knowledge.js";
-/**
- * The planner: an agent that reads the repository and negotiates a plan —
- * never a builder. It has no completion, no commit, and no publication
- * path; its only two legitimate endings are a parked question and a plan
- * handoff, and both are accepted only AFTER the workspace is proven
- * untouched (Codex planning review, finding 1: the builder ingests parks
- * before its moved-HEAD check, which is survivable for a role whose
- * completion re-checks — and exploitable for one whose session ends at a
- * question; here the proof comes first, always).
- *
- * This function assembles; the fenced finalizers in claim.ts seal. Same
- * division of labor as the builder.
- */
 import { createHash, randomUUID } from "node:crypto";
 import { unlinkSync } from "node:fs";
 import { homedir } from "node:os";
@@ -47,15 +34,7 @@ const AGENT_ENV_DENYLIST = [...TELEGRAM_TOKEN_ENVS];
 const DEFAULT_PLAN_TIMEOUT_MS = 20 * 60_000;
 const DEFAULT_PLAN_TURNS = CLAUDE_LIMITS.maxTurns;
 const DEFAULT_PULSE_MS = RUNNER_HEARTBEAT_MS;
-/**
- * One line of untrusted text made inert for the planner's brief (Codex
- * M5-M8 audit, IV-4): controls and separators collapse, protocol-shaped
- * prefixes break visibly, and length is bounded. Same posture as the
- * builder's fence — titles arrive from GitHub issues now, and a title is
- * data whoever wrote it.
- */
 function inert(text) {
-    // eslint-disable-next-line no-control-regex
     return text
         .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, " ")
         .replace(/STANDING-ORDERS/g, "STANDING[quoted]-ORDERS")
@@ -63,7 +42,6 @@ function inert(text) {
         .slice(0, 300)
         .trim();
 }
-/** The planner's brief: read, ask, propose — never change. */
 function plannerBrief(title, mailbox, planFile, answers, source, structured) {
     const answeredBlock = answers.length === 0
         ? ""
@@ -82,10 +60,6 @@ function plannerBrief(title, mailbox, planFile, answers, source, structured) {
         "files named below), stage, commit, or switch branches. The workspace",
         "is checked after you finish; any other change discards your session.",
         "",
-        // The filed request, whole and quoted (contract handoff, task 1): the
-        // operator's goal, exclusions, rubric, terms, and revision brief reach
-        // the planner as data — never as a title-derived guess, never as
-        // authorization. The rules for preserving or amending it ride with it.
         ...plannerSourceBlock(source),
         answeredBlock,
         "If you need the operator's judgement to plan well, write ONE decision",
@@ -152,20 +126,12 @@ function plannerBrief(title, mailbox, planFile, answers, source, structured) {
 }
 function decodeStructuredBytes(raw) {
     try {
-        // Buffer#toString silently inserts U+FFFD for malformed sequences,
-        // making the validator judge text the agent never actually authored.
         return { ok: true, text: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw) };
     }
     catch {
         return { ok: false };
     }
 }
-/**
- * Once a parseable first plan states every authority-bearing field, repair
- * may fix its non-authority document shape but may not silently rewrite its
- * contract. A plan whose authority cannot be frozen is not repairable: asking
- * the model to recreate missing scope would be replanning under a repair name.
- */
 function planAuthorityAnchor(raw) {
     try {
         const parsed = JSON.parse(normalizeStructuredJson(raw).text);
@@ -175,9 +141,6 @@ function planAuthorityAnchor(raw) {
         const fields = ["goal", "outOfScope", "touches", "acceptance"];
         if (!fields.every(field => Object.prototype.hasOwnProperty.call(body, field)))
             return null;
-        // canonicalJson is recursive. A byte-bounded but pathologically deep
-        // JSON value can still exhaust the JS stack; that means its authority
-        // cannot be frozen safely, so this output is not eligible for repair.
         return canonicalJsonUndefinedAsNull({
             goal: body["goal"],
             outOfScope: body["outOfScope"],
@@ -189,34 +152,15 @@ function planAuthorityAnchor(raw) {
         return null;
     }
 }
-/**
- * A structured correction may repair only the non-authority plan document.
- * The goal, out-of-scope boundary, touched paths, and acceptance rubric are
- * what the operator will sign. Merely being present is not enough to freeze
- * them: if any of those fields failed validation, preserving the bad value
- * makes repair impossible while changing it would silently re-plan scope.
- */
 function planProblemsAreDocumentOnly(problems) {
     return problems.every(problem => problem.reason === "missing-plan" ||
         problem.reason === "bad-plan" ||
-        // A silent amendment is repaired by SAYING the amendment (the frozen
-        // authority values stay exactly as the planner wrote them; the
-        // operator sees every change at approval) — never by re-planning.
         problem.reason === "silent-amendment" ||
         problem.reason === "bad-amendment" ||
         problem.reason.startsWith("amendment") ||
-        // A key the plan contract does not know carries no authority: the
-        // frozen goal, outOfScope, touches, and acceptance are read by name.
         problem.reason === "payload-unknown-key" ||
         problem.reason.startsWith("plan-"));
 }
-/**
- * The contract check (contract handoff, task 1): a plan drafted against
- * FILED terms either reproduces them exactly or states an amendment. A
- * plan that changes the filed goal, exclusions, touches, or rubric in
- * silence is malformed — the exact changes are the validation message,
- * so the correction knows what it must own up to.
- */
 function contractProblemsOf(plan, source) {
     const filed = source.contract.scope;
     if (filed === null)
@@ -232,20 +176,12 @@ function contractProblemsOf(plan, source) {
         },
     ];
 }
-/**
- * Claude's structured output under the plan schema (`--json-schema`), read as if it were the plan file: the same
- * byte cap, and the bytes the model returned.
- */
 function structuredPlanRead(structured) {
     const raw = Buffer.from(structured, "utf8");
     return raw.length > TEXT_LIMITS.planPayloadBytes
         ? { ok: false, problem: `the structured output is over ${TEXT_LIMITS.planPayloadBytes} bytes`, missing: false, bytesOriginal: raw.length }
         : { ok: true, raw };
 }
-/** Read both nonce-bound outputs so writing both can never win by priority.
- * The files stay the handoff. Claude's structured output (the plan schema)
- * is the plan only when neither file was written; a question always comes
- * through the mailbox, and then the structured output is not read. */
 function plannerPayload(worktree, mailbox, planFile, source, structured = null) {
     const decision = readMailbox(join(worktree, mailbox));
     const fromFile = readMailbox(join(worktree, planFile), TEXT_LIMITS.planPayloadBytes);
@@ -255,8 +191,6 @@ function plannerPayload(worktree, mailbox, planFile, source, structured = null)
     if (!hasDecision && !hasPlan)
         return { state: "missing" };
     if (hasDecision && hasPlan) {
-        // Keep both conclusions in one bounded audit artifact. Invalid UTF-8 is
-        // represented losslessly as base64 instead of replacement characters.
         const evidenceValue = (read) => {
             if (!read.ok)
                 return { unreadable: read.problem };
@@ -337,8 +271,6 @@ function plannerPayload(worktree, mailbox, planFile, source, structured = null)
         }
         const anchor = planAuthorityAnchor(decoded.text);
         const parsedShape = parsePlan(normalized.text);
-        // A well-formed plan that silently amends the filed contract is a
-        // malformed plan: the shape passed, the contract did not.
         const parsed = parsedShape.ok
             ? (() => {
                 const contractProblems = contractProblemsOf(parsedShape.plan, source);
@@ -362,9 +294,6 @@ function plannerPayload(worktree, mailbox, planFile, source, structured = null)
             };
     }
     catch (error) {
-        // Everything past readMailbox is agent-controlled. A resource-hostile
-        // JSON shape is a typed malformed protocol result, never an exception
-        // that escapes into the runner or an invitation to spend again.
         return {
             state: "malformed",
             kind,
@@ -419,9 +348,6 @@ function plannerRepairBrief(problems, mailbox, planFile, expectedKind, authority
         "Return valid JSON through the chosen nonce-bound file only.",
     ].join("\n");
 }
-/** Structured correction is not a second planning pass. Ambiguous intent
- * (both protocol files) and a plan whose authority cannot be mechanically
- * frozen stop at the original malformed result. */
 function plannerPayloadIsRepairable(payload) {
     if (!payload.repairable || payload.raw === null)
         return false;
@@ -450,7 +376,6 @@ function enforceRepairAuthority(payload, expectedKind, authorityAnchor, source)
             repairable: true,
         };
     }
-    // A repair that goes back to exactly the FILED terms adds no authority: it is what the operator filed.
     const filed = payload.state === "plan" && source.contract.scope !== null && contractChangesOf(source.contract.scope, payload.plan).length === 0;
     if (authorityAnchor !== null && !filed) {
         if (payload.state !== "plan" || payload.authorityAnchor !== authorityAnchor) {
@@ -495,16 +420,10 @@ function draftedOutcome(root, runId, plan, repairRunId = null) {
 }
 export async function plan(store, request) {
     const { taskId, taskRef, runner, worktree, branch, now, agent, git: givenGit = run, timeoutMs = DEFAULT_PLAN_TIMEOUT_MS, maxTurns = DEFAULT_PLAN_TURNS, } = request;
-    // The plane's git on the plan's checkout (agent-written, and its repository shared with every build) runs hardened, against
-    // a frozen view of the repository's config and info (teardown-git.ts checkoutGit); an injected runner is used as given.
     const git = givenGit === run ? checkoutGit(run, "build", { repo: store.getWorktree(worktree)?.repo ?? null }) : givenGit;
-    // An ACP agent works with full access inside the fence: it builds and repairs, and is never handed a plan (routing refuses it first).
     if (request.provider !== undefined && isAcpProvider(request.provider)) {
         return { ok: false, kind: "failure", reason: "provider-unsupported", message: `${ACP_AGENTS[request.provider].name} builds and repairs only — configure the planner to claude, codex or gemini` };
     }
-    // The same custody checks as a build: the claim is ours under exactly
-    // this lease, and the directory is a worktree this pool leased to us for
-    // this task. A planner in somebody else's checkout is not a planner.
     const claim = currentClaim(store, taskRef, now);
     if (claim === null || claim.runner !== runner || claim.leaseId !== request.leaseId) {
         return { ok: false, kind: "failure", reason: "not-yours", message: `${taskId} is not held under ${request.leaseId}` };
@@ -546,8 +465,6 @@ export async function plan(store, request) {
     const mailbox = mailboxName();
     const planFile = planFileName();
     quarantineMailboxes(worktree, root, request.runId);
-    // The "before" of the clean-tree proof (v4 review, finding 4 — shared
-    // with the scout): ignored paths the checkout already carried.
     const ignoredBefore = await snapshotIgnored(git, worktree);
     if (ignoredBefore === null) {
         return { ok: false, kind: "failure", reason: "git", message: `could not read the tree state in ${worktree}` };
@@ -567,8 +484,6 @@ export async function plan(store, request) {
         const beat = () => {
             try {
                 const answer = heartbeat(store, request.leaseId, clock());
-                // Credentialed when the caller carries the token (arc 2 finding
-                // 33): a takeover's rotation fences this session at its next beat.
                 if (request.runnerToken !== undefined) {
                     const alive = runnerHeartbeat(store, runner, request.runnerToken, clock());
                     if (!alive.ok)
@@ -589,16 +504,10 @@ export async function plan(store, request) {
         pulseTimer = setInterval(beat, pulseMs);
         pulseTimer.unref?.();
     }
-    // The live window (peek): the same transcript file the builder keeps,
-    // so `toolroll peek` and the run page can watch this session too.
     const liveLog = withRunActivity(openLiveLog(root, request.runId, liveLogContext(store, request.runId, taskRef, worktree, clock())), store, request.runId, clock);
-    // The durable run row, not a caller's duplicate options, is the route
-    // every correction inherits.
     const provider = logicalRun.provider;
     const model = logicalRun.model;
-    // Claude takes the plan schema as `--json-schema`; other harnesses read it in the brief and write the file.
     const structured = provider === "claude";
-    /** Every paid turn is followed by the same custody and untouched-tree proof. */
     const proveAfterInvocation = async () => {
         if (fencedMidPlan) {
             return { ok: false, kind: "failure", reason: "fenced", message: "the lease was superseded while the planner ran" };
@@ -629,7 +538,6 @@ export async function plan(store, request) {
             !workspaceLease.verified) {
             return { ok: false, kind: "failure", reason: "not-leased", message: `${worktree} is no longer this task's leased workspace` };
         }
-        // THE PROOF COMES FIRST: no output bytes are read before this succeeds.
         const after = await git(GIT, ["--no-optional-locks", "rev-parse", "--abbrev-ref", "HEAD"], { cwd: worktree });
         if (after.code !== 0 || after.stdout.trim() !== branch) {
             quarantineMailboxes(worktree, root, request.runId);
@@ -678,9 +586,6 @@ export async function plan(store, request) {
         problems: payload.problems,
     });
     const acceptDecision = (payload, repairedBy) => {
-        // Raw transport bytes are already sealed as structured-output. The
-        // decision-linked artifact stays strict JSON even when a transport BOM,
-        // fence, or double-encoded string was normalized away.
         const bytes = Buffer.from(JSON.stringify(payload.decision), "utf8");
         const payloadArtifact = storeEvidence(store, root, request.runId, "park-payload", "park-payload.json", bytes, repairedBy === null ? "planner mailbox (verified tree)" : `canonical validated planner decision repaired by run ${repairedBy}`, clock());
         return { ok: true, parked: { decision: payload.decision, artifactIds: [payloadArtifact], repairRunId: repairedBy } };
@@ -716,8 +621,6 @@ export async function plan(store, request) {
             phase: "plan",
             brief: projectSkillContext + knowledgeContext(store, request.runId, join(root, '..', 'repository-context'), undefined, clock()) + deliverCodeMap(store, request.runId, clock()) + learningContext(store, root, request.runId, "plan", clock()) + plannerBrief(request.taskTitle, mailbox, planFile, request.answers ?? [], request.source, structured),
             maxTurns,
-            // Claude's built-in `plan` permission mode diverts writes into its
-            // own ~/.claude/plans file and refuses the nonce-bound handoff file.
             permissionMode: request.permissionMode ?? "acceptEdits",
             skipPermissions: false,
             resumeSession: null,
@@ -782,10 +685,6 @@ export async function plan(store, request) {
             return { ok: false, kind: "failure", reason: "agent", message: `agent exit ${result.code}` };
         }
         if (result.sessionId !== null) {
-            // Buffered test/custom transports may only expose identity in their
-            // terminal envelope rather than through the streaming callback. Seal
-            // it on the root before any correction child is opened so the final
-            // transaction can prove one exact session end to end.
             store.stampRun(request.runId, { sessionId: result.sessionId });
         }
         if (payload.state === "missing") {
@@ -834,15 +733,11 @@ export async function plan(store, request) {
                     branch,
                     worktree,
                     ...(model === null ? {} : { model }),
-                    // This is still planner work: it can only correct the planner's
-                    // nonce-bound protocol file and must never appear as a code repair.
                     role: "planner",
                     provider,
                     parentRun: repairParentRun,
                     sessionId,
                     now: clock(),
-                    // The correction presents its parent's route provenance (v48):
-                    // the same plan leg, proved again inside this admission.
                     ...(parentStamp === null ? {} : { route: parentStamp }),
                 });
                 store.stampRun(repairRun, { baseRevision });
@@ -853,7 +748,6 @@ export async function plan(store, request) {
                         store.finishRun(repairRun, { outcome: "failed", reason: "repair-admission", now: clock() });
                     }
                     catch {
-                        // The original database failure is the useful diagnosis.
                     }
                 }
                 return {
@@ -863,7 +757,6 @@ export async function plan(store, request) {
                     message: `the structured repair run could not be recorded: ${error instanceof Error ? error.message : String(error)}`,
                 };
             }
-            // The success arm above assigned it; the catch always returned.
             const correctionRun = repairRun;
             let repaired;
             try {
@@ -875,7 +768,6 @@ export async function plan(store, request) {
                     skipPermissions: false,
                     resumeSession: sessionId,
                     ...(request.maxBudgetUsd === undefined ? {} : { maxBudgetUsd: request.maxBudgetUsd }),
-                    // A plan's correction is held to the same schema; a question's is not.
                     ...(structured && expectedKind === "plan" ? { jsonSchema: PLAN_MODEL_SCHEMA } : {}),
                 }, {
                     cwd: worktree,
@@ -931,14 +823,6 @@ export async function plan(store, request) {
                 store.finishRun(correctionRun, { outcome: "failed", reason: "evidence", now: clock() });
                 return correctionEvidenceProblem;
             }
-            // A RESUME the harness refused by its own protocol, or never came up
-            // for, is a doomed turn (v48 authority repair): the exact session on record is not one
-            // anybody can continue, so the attempt ends here with its typed
-            // reason — never a second resume of the same identity. The planning
-            // strike's backoff then retries the task as a FRESH planner root in
-            // a fresh session (every root starts one; nothing resumes across
-            // attempts), and the whole custody of this attempt — root, rejected
-            // reply, doomed correction — stays sealed as evidence.
             if (repaired.kind === "refused") {
                 store.finishRun(correctionRun, { outcome: "refused", reason: repaired.reason, now: clock() });
                 return {
@@ -1017,7 +901,6 @@ function cleanup(worktree, names) {
             unlinkSync(join(worktree, name));
         }
         catch {
-            // Missing is fine; unremovable is caught by the next quarantine sweep.
         }
     }
 }

package/dist/policy-ui.js

@@ -1,17 +1,9 @@
-/**
- * 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 { html, joinHtml } from "./html.js";
 import { whenUtc } from "./when-html.js";
 import { LEVEL_HINTS, LEVEL_NAMES, PERMISSION_LEVELS, POLICY_PROVIDERS, PROVIDER_NAMES, policyParts } from "./policy.js";
 import { disclose, facts, formRow, infoLine, note, notice, radios, settingsRecord, settingsSection, textarea } from "./server/kit.js";
 import { kitSectionForm } from "./settings-kit.js";
-/** The old look; the page is built from the kit now. Kept for chrome.ts, which still concatenates it. */
 export const POLICY_CSS = "";
-/** A ledger entry as one record of history: what, before → after; who; when. */
 function historyItem(entry) {
     const what = entry.action.replace(/^organisation policy: /, "");
     const [before, after] = (entry.detail ?? "").split(" → ");

package/dist/policy.js

@@ -1,27 +1,7 @@
-/**
- * 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), the lead and project chats, subagents and flow steps.
- */
 import { isAcpProfile } from "./acp-agents.js";
 export const PERMISSION_LEVELS = ["safe", "standard", "escalated"];
 export const POLICY_PROVIDERS = ["claude", "codex", "gemini", "openrouter", "opencode", "cursor", "cline", "qwen", "goose"];
 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),
@@ -44,7 +24,6 @@ const listOf = (value) => {
         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 {
@@ -65,7 +44,6 @@ export function readPolicy(db) {
         updatedAt: row["updated_at"] == null ? null : String(row["updated_at"]),
     };
 }
-// ---- words -------------------------------------------------------------------------------
 export const PROVIDER_NAMES = { claude: "Claude", codex: "Codex", gemini: "Gemini", openrouter: "OpenRouter", opencode: "OpenCode", cursor: "Cursor", cline: "Cline", qwen: "Qwen Code", goose: "Goose" };
 export const LEVEL_NAMES = { safe: "Safe", standard: "Standard", escalated: "Escalated" };
 export const LEVEL_HINTS = {
@@ -73,9 +51,7 @@ export const LEVEL_HINTS = {
     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;
@@ -85,7 +61,6 @@ const providerName = (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),
@@ -97,14 +72,10 @@ export function policyParts(policy) {
 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))) {
@@ -119,25 +90,20 @@ export function agentRefusal(policy, provider, model) {
     }
     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";
-    // An ACP agent runs any tool it chooses inside the OS fence: full access, and nothing lower exists.
     if (isAcpProfile(profile))
         return "escalated";
     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" };
@@ -147,7 +113,6 @@ function profileAt(profile, level) {
         return level === "escalated" ? profile : null;
     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";
@@ -157,7 +122,6 @@ export function levelWords(profile) {
         return "full access inside the OS fence";
     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))
@@ -173,9 +137,6 @@ export function underCeiling(policy, 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";
@@ -183,7 +144,6 @@ export function sessionCeilingRefusal(policy, provider, what) {
         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)
@@ -193,7 +153,6 @@ export function profileVerdict(policy, profile) {
         return { ok: false, message: `Its repairs: ${repair.charAt(0).toLowerCase()}${repair.slice(1)}` };
     return underCeiling(policy, profile);
 }
-/** 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);
@@ -210,13 +169,10 @@ export function approvalRefusal(policy, profiles, legs = []) {
     }
     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." };
@@ -248,13 +204,10 @@ export function checkPolicy(input) {
         return { ok: false, problem: tools.problem };
     return { ok: true, policy: { providers, models, tools, ceiling: input.ceiling } };
 }
-/** Every provider the policy knows, in plain names: "Claude, Codex, … and Goose". */
 function providerChoices() {
     const names = POLICY_PROVIDERS.map(one => PROVIDER_NAMES[one]);
     return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
 }
-/** The providers ticked on the policy form: every provider the policy knows ticked (and nothing unknown) means "any"
- * (null), so a provider added later is allowed too; anything else is the list as ticked, for checkPolicy to check. */
 export function chosenProviders(chosen) {
     const known = new Set(chosen.map(one => policyProvider(one.toLowerCase())));
     if (known.has(null))

package/dist/prepared-evidence.js

@@ -1,4 +1,3 @@
-/** Committed image inventory, never claimed checks, completion, or approval. */
 import { noLazyFetch, viewedGitSync } from './teardown-git.js';
 import { createHash } from 'node:crypto';
 import { lstatSync, writeFileSync } from 'node:fs';
@@ -6,18 +5,15 @@ 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';
-/** Read flags: --no-lazy-fetch where git has it; a partial clone is refused where it doesn't (teardown-git.ts). */
 export const preparedEvidenceGit = () => ['--literal-pathspecs', ...noLazyFetch(), '-c', 'protocol.allow=never', '--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 {
-            // Every git version through a frozen read view, bounded (eval-harness review 1, finding 7).
             const ran = viewedGitSync(repo, [...preparedEvidenceGit(), ...args], { timeoutMs: 10_000, maxBuffer: cap, buffer: true });
             if (ran.status !== 0)
                 throw new Error('git failed');
@@ -84,7 +80,6 @@ export function readPreparedEvidence(repo, candidate, required = false) {
 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('/');

package/dist/principal.js

@@ -1,27 +1,8 @@
-/**
- * The branded approver principal (mate arc, ruling 3).
- *
- * Every act the lead proposes and every confirmation an operator taps
- * runs under a principal that PROVES it was authenticated — a password
- * ceremony, or a cookie session the edge already proved (csrf, role,
- * generation) and this module re-proves against the approver row. The
- * maker is module-private and the brand is RUNTIME (slice-1 review,
- * finding 3): a principal is frozen at mint and remembered in a private
- * set, so a structural look-alike, a mutated copy, or a repos list edited
- * after the fact is refused by `isVerifiedApprover` and `reproveApprover`.
- * The ceiling rides on it — the admitted repos and their digest — so a
- * principal minted on one surface can never read or confirm on another's
- * wider or narrower view.
- */
 import { createHash } from "node:crypto";
 import { authenticateAccount } from "./scope.js";
-/** The lead's ceiling digest: the admitted repos IN ORDER, hashed — `rN`
- * is an index, so two surfaces naming the same repos in a different order
- * hold different ceilings (slice-2 review, finding 3). */
 export function ceilingDigestOf(repos) {
     return createHash("sha256").update(repos.join("\n")).digest("hex");
 }
-/** Every principal this process minted. Membership IS the brand at runtime. */
 const minted = new WeakSet();
 function verified(row) {
     const who = Object.freeze({
@@ -33,11 +14,9 @@ function verified(row) {
     minted.add(who);
     return who;
 }
-/** True only for an object this module minted — never for a structural copy. */
 export function isVerifiedApprover(value) {
     return typeof value === "object" && value !== null && minted.has(value);
 }
-/** The password road: the CLI, and any ceremony that retypes it. */
 export function verifyApproverByPassword(store, name, token, repos) {
     const account = authenticateAccount(store, name, token);
     if (!account.ok)
@@ -46,13 +25,6 @@ export function verifyApproverByPassword(store, name, token, repos) {
         return { ok: false, reason: "not-an-approver" };
     return { ok: true, who: verified({ name, generation: account.generation, repos }) };
 }
-/**
- * The session road: the edge has already proved the cookie, csrf, and the
- * origin, and holds the generation the session was opened under. This
- * re-proves the ROW — present, an approver, not revoked, SAME generation —
- * so a name alone mints nothing, and a credential rotation since the
- * session opened ends the principal.
- */
 export function verifyApproverStanding(store, name, generation, repos) {
     const account = store.accountOf(name);
     if (account === null)
@@ -65,7 +37,6 @@ export function verifyApproverStanding(store, name, generation, repos) {
         return { ok: false, reason: "generation" };
     return { ok: true, who: verified({ name, generation: account.generation, repos }) };
 }
-/** Re-prove a principal minted earlier: minted here, intact, same row, same generation, still an approver. */
 export function reproveApprover(store, who) {
     if (!isVerifiedApprover(who) || ceilingDigestOf(who.repos) !== who.ceilingDigest)
         return { ok: false, reason: "forged" };