toolroll 0.5.0

package/dist/action-ledger.js

@@ -0,0 +1,75 @@
+/** v99: sign-ins (and refusals, lockouts, sign-outs) and policy changes are their own kinds of event. */
+export const LEDGER_SOURCES = ["work", "request", "access", "sign-in", "policy"];
+/** The table as v54 made it: the one earlier shape the v99 rebuild accepts. */
+export const LEDGER_V54_TABLE = (name) => `CREATE TABLE ${name} (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  at TEXT NOT NULL, actor TEXT NOT NULL, repo TEXT,
+  task_id TEXT, run_id INTEGER,
+  action TEXT NOT NULL, outcome TEXT NOT NULL,
+  source TEXT NOT NULL CHECK (source IN ('work','request','access'))
+)`;
+export const LEDGER_V54_COLUMNS = ["id", "at", "actor", "repo", "task_id", "run_id", "action", "outcome", "source"];
+export const LEDGER_TABLE = (name) => `CREATE TABLE ${name} (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  at TEXT NOT NULL, actor TEXT NOT NULL, repo TEXT,
+  task_id TEXT, run_id INTEGER,
+  action TEXT NOT NULL, outcome TEXT NOT NULL,
+  source TEXT NOT NULL CHECK (source IN ('work','request','access','sign-in','policy')),
+  detail TEXT
+)`;
+export const LEDGER_SCHEMA = `
+${LEDGER_TABLE("IF NOT EXISTS action_ledger")};
+CREATE INDEX IF NOT EXISTS action_ledger_project ON action_ledger(repo, id DESC);
+CREATE INDEX IF NOT EXISTS action_ledger_actor ON action_ledger(actor, id DESC);
+CREATE TRIGGER IF NOT EXISTS action_ledger_no_update BEFORE UPDATE ON action_ledger
+BEGIN SELECT RAISE(ABORT, 'action history is append-only'); END;
+CREATE TRIGGER IF NOT EXISTS action_ledger_no_delete BEFORE DELETE ON action_ledger
+BEGIN SELECT RAISE(ABORT, 'action history is append-only'); END;
+`;
+/** Installed after all table migrations. Work events commit with the work,
+ * including CLI and unattended workers; no prompts, tool arguments, tokens,
+ * decision text, or transcript content are copied into the ledger. */
+export function installLedgerTriggers(db) {
+    const repo = (ref) => `(SELECT repo FROM task_ref WHERE id = ${ref})`;
+    const task = (ref) => `(SELECT external_id FROM task_ref WHERE id = ${ref})`;
+    const runRef = `(SELECT task_ref FROM run WHERE id = NEW.run)`;
+    const event = (at, actor, project, taskId, runId, action, outcome) => `INSERT INTO action_ledger(at,actor,repo,task_id,run_id,action,outcome,source) VALUES (${at},${actor},${project},${taskId},${runId},'${action}',${outcome},'work');`;
+    db.exec(`
+CREATE TRIGGER IF NOT EXISTS ledger_run_started AFTER INSERT ON run BEGIN
+  ${event("NEW.started_at", "NEW.runner", repo("NEW.task_ref"), task("NEW.task_ref"), "NEW.id", "run started", "NEW.role")}
+END;
+CREATE TRIGGER IF NOT EXISTS ledger_run_finished AFTER UPDATE OF outcome ON run
+WHEN NEW.outcome IS NOT NULL AND OLD.outcome IS NOT NEW.outcome BEGIN
+  ${event("COALESCE(NEW.finished_at, NEW.started_at)", "NEW.runner", repo("NEW.task_ref"), task("NEW.task_ref"), "NEW.id", "run finished", "NEW.outcome")}
+END;
+CREATE TRIGGER IF NOT EXISTS ledger_decision_opened AFTER INSERT ON decision BEGIN
+  ${event("NEW.created_at", "'system'", repo(runRef), task(runRef), "NEW.run", "decision opened", "NEW.state")}
+END;
+CREATE TRIGGER IF NOT EXISTS ledger_decision_answered AFTER UPDATE OF answered_at ON decision
+WHEN NEW.answered_at IS NOT NULL AND OLD.answered_at IS NULL BEGIN
+  ${event("NEW.answered_at", "COALESCE(NEW.answered_by,'system')", repo(runRef), task(runRef), "NEW.run", "decision answered", "NEW.state")}
+END;
+CREATE TRIGGER IF NOT EXISTS ledger_scope_approved AFTER UPDATE OF approved_at, approved_digest ON task_scope
+WHEN NEW.approved_at IS NOT NULL AND (OLD.approved_at IS NOT NEW.approved_at OR OLD.approved_digest IS NOT NEW.approved_digest) BEGIN
+  ${event("NEW.approved_at", "COALESCE(NEW.approved_by,'system')", "(SELECT repo FROM task_ref WHERE backend = 'built-in' AND external_id = NEW.task_id)", "NEW.task_id", "NULL", "scope approved", "'approved'")}
+END;
+CREATE TRIGGER IF NOT EXISTS ledger_task_state AFTER UPDATE OF state ON task
+WHEN OLD.state IS NOT NEW.state BEGIN
+  ${event("NEW.updated_at", "'system'", "(SELECT repo FROM task_ref WHERE backend = 'built-in' AND external_id = NEW.id)", "NEW.id", "NULL", "task state changed", "NEW.state")}
+END;
+CREATE TRIGGER IF NOT EXISTS ledger_task_placed AFTER UPDATE OF repo ON task_ref
+WHEN OLD.repo IS NOT NEW.repo BEGIN
+  ${event("strftime('%Y-%m-%dT%H:%M:%fZ','now')", "'system'", "NEW.repo", "NEW.external_id", "NULL", "task placed", "'recorded'")}
+END;
+CREATE TRIGGER IF NOT EXISTS ledger_coordinator_minted AFTER INSERT ON coordinator_credential BEGIN
+  INSERT INTO action_ledger(at,actor,repo,task_id,run_id,action,outcome,source,detail) VALUES (NEW.created_at, NEW.created_by, NULL, NULL, NULL,
+    'coordinator minted: ' || NEW.name, 'minted', 'access', 'projects: ' || NEW.repos);
+END;
+CREATE TRIGGER IF NOT EXISTS ledger_task_registered AFTER INSERT ON task_ref BEGIN
+  ${event("strftime('%Y-%m-%dT%H:%M:%fZ','now')", "'system'", "NEW.repo", "NEW.external_id", "NULL", "task registered", "'recorded'")}
+END;
+CREATE TRIGGER IF NOT EXISTS ledger_steer AFTER INSERT ON task_steer BEGIN
+  ${event("NEW.created_at", "NEW.author", repo("NEW.task_ref"), task("NEW.task_ref"), "NEW.attached_run", "steering added", "NEW.authorship_state")}
+END;
+`);
+}

package/dist/agent-fence.d.ts

@@ -0,0 +1,42 @@
+/** How a launch was fenced, as recorded on the run and said on the task. */
+export type FenceMethod = "codex-profile" | "macos-sandbox" | "linux-bubblewrap" | "claude-rules" | "none";
+/**
+ * Every path an agent must not reach: the Toolroll state folder
+ * beside the database (all of it, except the folder that holds this run's
+ * own worktree), the database itself with its journal files, and
+ * `~/.toolroll` or an older `~/.standing-orders` (provider keys and project tool secrets). When the
+ * database sits anywhere else (a shared folder), only the database and
+ * secret-looking entries there are fenced.
+ */
+export declare function agentFence(options: {
+    databaseFile: string | null;
+    worktree: string | null;
+    home?: string;
+    extra?: readonly string[];
+}): string[];
+/**
+ * Codex's own sandbox, fenced. Auto: the `:workspace` profile Codex's
+ * `--sandbox workspace-write` already gives (workspace and temp writes, no
+ * network). Full access: the same profile widened to write anywhere with
+ * network on, instead of no sandbox at all. Either way the fenced paths are
+ * denied, which in Codex outranks any write or read grant.
+ */
+export declare function codexFenceArgv(fence: readonly string[], fullAccess: boolean): string[];
+/** Claude's own file tools refuse the fenced paths in every mode (its shell is fenced by the macOS sandbox). */
+export declare function claudeFenceSettings(fence: readonly string[]): string;
+/** A Seatbelt profile that allows everything except reading or writing the fenced paths. */
+export declare function macosFenceProfile(fence: readonly string[]): string;
+export declare const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
+/** Whether this machine can run an agent inside the macOS fence. */
+export declare function macosFenceAvailable(platform?: NodeJS.Platform): boolean;
+/** The spawn that runs `file args` inside the macOS fence (same process: sandbox-exec replaces itself with the agent). */
+export declare function macosFenced(file: string, args: readonly string[], fence: readonly string[]): {
+    file: string;
+    args: string[];
+};
+export declare function linuxFenceAvailable(platform?: NodeJS.Platform, probe?: () => boolean): boolean;
+/** The spawn that runs `file args` inside the Linux fence: the whole filesystem as it is, except each fenced path masked. */
+export declare function linuxFenced(file: string, args: readonly string[], fence: readonly string[]): {
+    file: string;
+    args: string[];
+};

package/dist/agent-fence.js

@@ -0,0 +1,183 @@
+/**
+ * The agent fence: what no build, plan, scout or repair agent may read or
+ * write, whatever its permission mode. Agents run as the operator's own OS
+ * user, so without it an agent could read the approver's remembered login
+ * (`up-login.txt`), runner and coordinator tokens, provider keys, project
+ * tool secrets, other runs' evidence, or the live database — and use them
+ * to approve its own work. The fence closes that at the operating system,
+ * not in the model's instructions:
+ *
+ * - Codex (every platform): a permission profile that extends its own
+ *   `:workspace` sandbox (Auto keeps it exactly: workspace writes, no
+ *   network) or widens it to write anywhere with network on (Full access,
+ *   which used to mean no sandbox at all), and denies every fenced path.
+ * - Claude and Gemini on macOS: the whole agent process runs inside a
+ *   Seatbelt profile that allows everything except the fenced paths.
+ * - Claude and Gemini on Linux (v88): the agent runs under bubblewrap, in its
+ *   own mount namespace where every fenced folder is an empty one and every
+ *   fenced file is /dev/null. Used when `bwrap` is installed and works here.
+ * - Claude everywhere also gets Read/Edit deny rules for its own file tools.
+ *
+ * Checked against codex-cli 0.156 and Claude Code 2.1.281 with a canary
+ * file read by an obfuscated script: "Operation not permitted".
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { readMonitoring } from "./monitoring-settings.js";
+import { existingFolders } from "./names.js";
+/** Names that are secrets wherever the database lives (used when its folder is shared with other things). */
+const SENSITIVE_NAME = /(^up-login\.txt$|token|secret|login|password|credential|vapid|keys?\b|\.pem$|\.key$|^backups$|^evidence$|^remote$|^sign-in\.json$|^monitoring\.json$)/i;
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+function inside(child, parent) {
+    const rel = relative(parent, child);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+ * Every path an agent must not reach: the Toolroll state folder
+ * beside the database (all of it, except the folder that holds this run's
+ * own worktree), the database itself with its journal files, and
+ * `~/.toolroll` or an older `~/.standing-orders` (provider keys and project tool secrets). When the
+ * database sits anywhere else (a shared folder), only the database and
+ * secret-looking entries there are fenced.
+ */
+export function agentFence(options) {
+    const fence = new Set();
+    const home = real(options.home ?? homedir());
+    const worktree = options.worktree === null ? null : real(options.worktree);
+    if (options.databaseFile !== null && options.databaseFile !== "" && options.databaseFile !== ":memory:") {
+        const database = real(options.databaseFile);
+        const state = dirname(database);
+        for (const suffix of ["", "-wal", "-shm", "-journal"])
+            if (existsSync(database + suffix))
+                fence.add(database + suffix);
+        // Only a folder that is Toolroll's own (~/.config/toolroll or an older name,
+        // the desktop app's "Toolroll") is fenced whole: a database kept
+        // in a shared folder (a projects folder, a test's temp folder) must not
+        // fence its neighbours, the repositories agents build among them.
+        const dedicated = state !== home && state !== sep && !existsSync(join(state, ".git")) && /standing[\s_-]?orders|toolroll|nightorders/i.test(basename(state));
+        // The entries this run's worktree needs stay reachable: the one it lives
+        // under, and the repository its git metadata belongs to.
+        const keep = new Set();
+        for (const needed of [worktree, worktree === null ? null : mainRepositoryOf(worktree)]) {
+            if (needed !== null && inside(needed, state))
+                keep.add(relative(state, needed).split(sep)[0]);
+        }
+        let entries = [];
+        try {
+            entries = readdirSync(state);
+        }
+        catch {
+            entries = [];
+        }
+        for (const entry of entries) {
+            // A repository is work, never a secret.
+            if (keep.has(entry) || existsSync(join(state, entry, ".git")))
+                continue;
+            if (dedicated || SENSITIVE_NAME.test(entry))
+                fence.add(join(state, entry));
+        }
+    }
+    for (const secrets of existingFolders(home, { dot: true }))
+        fence.add(secrets);
+    // v104: the folder the audit stream writes to holds the whole instance's history.
+    if (options.databaseFile !== null && options.databaseFile !== "" && options.databaseFile !== ":memory:") {
+        const stream = readMonitoring(dirname(real(options.databaseFile))).folder?.path;
+        if (stream !== undefined && existsSync(stream))
+            fence.add(real(stream));
+    }
+    for (const path of options.extra ?? [])
+        if (existsSync(path))
+            fence.add(real(path));
+    // Never fence the run's own worktree or anything above it.
+    return [...fence].filter(path => worktree === null || (path !== worktree && !inside(worktree, path))).sort();
+}
+/** The repository a git worktree belongs to (its `.git` file names the main repository's git folder). */
+function mainRepositoryOf(worktree) {
+    try {
+        const pointer = /^gitdir:\s*(.+)$/m.exec(readFileSync(join(worktree, ".git"), "utf8"))?.[1]?.trim();
+        if (pointer === undefined)
+            return null;
+        const gitdir = real(isAbsolute(pointer) ? pointer : join(worktree, pointer));
+        // <repo>/.git/worktrees/<name> → <repo>
+        const marker = `${sep}.git${sep}worktrees${sep}`;
+        const at = gitdir.lastIndexOf(marker);
+        return at < 0 ? null : gitdir.slice(0, at);
+    }
+    catch {
+        return null;
+    }
+}
+const toml = (value) => `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+/**
+ * Codex's own sandbox, fenced. Auto: the `:workspace` profile Codex's
+ * `--sandbox workspace-write` already gives (workspace and temp writes, no
+ * network). Full access: the same profile widened to write anywhere with
+ * network on, instead of no sandbox at all. Either way the fenced paths are
+ * denied, which in Codex outranks any write or read grant.
+ */
+export function codexFenceArgv(fence, fullAccess) {
+    const filesystem = [...(fullAccess ? ['"/"="write"'] : []), ...fence.map(path => `${toml(path)}="deny"`)];
+    return [
+        "-c", 'default_permissions="standing-orders"',
+        "-c", 'permissions.standing-orders.extends=":workspace"',
+        "-c", `permissions.standing-orders.filesystem={${filesystem.join(",")}}`,
+        ...(fullAccess ? ["-c", "permissions.standing-orders.network.enabled=true", "-c", 'approval_policy="never"'] : []),
+    ];
+}
+/** Claude's own file tools refuse the fenced paths in every mode (its shell is fenced by the macOS sandbox). */
+export function claudeFenceSettings(fence) {
+    const rules = fence.flatMap(path => [`Read(/${path})`, `Read(/${path}/**)`, `Edit(/${path})`, `Edit(/${path}/**)`]);
+    return JSON.stringify({ permissions: { deny: rules } });
+}
+const seatbelt = (path) => `"${path.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+/** A Seatbelt profile that allows everything except reading or writing the fenced paths. */
+export function macosFenceProfile(fence) {
+    return ["(version 1)", "(allow default)", `(deny file-read* file-write* ${fence.map(path => `(subpath ${seatbelt(path)})`).join(" ")})`].join("\n");
+}
+export const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
+/** Whether this machine can run an agent inside the macOS fence. */
+export function macosFenceAvailable(platform = process.platform) {
+    return platform === "darwin" && existsSync(SANDBOX_EXEC);
+}
+/** The spawn that runs `file args` inside the macOS fence (same process: sandbox-exec replaces itself with the agent). */
+export function macosFenced(file, args, fence) {
+    return { file: SANDBOX_EXEC, args: ["-p", macosFenceProfile(fence), file, ...args] };
+}
+/** Whether bubblewrap runs here (checked once): installed, and allowed to make its namespace. */
+let bubblewrapWorks = null;
+export function linuxFenceAvailable(platform = process.platform, probe = () => spawnSync("bwrap", ["--dev-bind", "/", "/", "--", "true"], { timeout: 5_000, stdio: "ignore" }).status === 0) {
+    if (platform !== "linux")
+        return false;
+    if (bubblewrapWorks === null) {
+        try {
+            bubblewrapWorks = probe();
+        }
+        catch {
+            bubblewrapWorks = false;
+        }
+    }
+    return bubblewrapWorks;
+}
+/** The spawn that runs `file args` inside the Linux fence: the whole filesystem as it is, except each fenced path masked. */
+export function linuxFenced(file, args, fence) {
+    const masks = fence.flatMap(path => {
+        let folder = true;
+        try {
+            folder = statSync(path).isDirectory();
+        }
+        catch {
+            folder = true;
+        }
+        return folder ? ["--tmpfs", path] : ["--ro-bind", "/dev/null", path];
+    });
+    return { file: "bwrap", args: ["--dev-bind", "/", "/", ...masks, "--die-with-parent", "--", file, ...args] };
+}

package/dist/agentconfig.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Phase-agent resolution: which provider and model a phase runs on, layer
+ * by layer, with the layers written down (Codex provider review, Q8).
+ *
+ *   pinned task agent  — stamped by a fire transaction; NOTHING overrides it
+ *   explicit flags     — this pass's operator, per field
+ *   project override   — phase_config row scoped to the canonical repo
+ *   installation       — phase_config row scoped 'installation'
+ *   review inheritance — when review is unset, the planner's complete pair
+ *   default            — claude, harness default model
+ *
+ * Config rows are COMPLETE pairs (provider required, model optional), so a
+ * partial override cannot marry a codex model to an inherited claude
+ * provider. Flags are per-field with one stated rule: `--model` alone
+ * rides whatever provider resolves; `--provider` alone runs that
+ * provider's default model — a lower layer's model never crosses onto a
+ * flag-chosen provider it was not written for.
+ *
+ * The resolved pair is validated before anything is claimed or spent, and
+ * the caller snapshots it into the run row.
+ */
+import { type AgentSpec, type Phase } from "./provider.js";
+import { type Store, type TaskRef } from "./store.js";
+import { type ChainEntry, type ExecutionProfile, type UnattendedPermissionMode } from "./scope.js";
+import { type ExactSpec, type PhaseRoute, type RouteCandidates } from "./phase-routing.js";
+import type { AcceptanceCriterion } from "./scope.js";
+export declare const INSTALLATION_SCOPE = "installation";
+export type PhaseFlags = {
+    provider?: string | undefined;
+    model?: string | undefined;
+};
+export type Resolution = {
+    ok: true;
+    spec: AgentSpec;
+    source: "pinned" | "flag" | "project" | "installation" | "default";
+} | {
+    ok: false;
+    problem: string;
+};
+export declare function resolvePhaseAgent(store: Store, phase: Phase, repo: string | null, flags: PhaseFlags, 
+/** The task being dispatched, when one is — its pin is authoritative. */
+ref?: Pick<TaskRef, "agentProvider" | "agentModel">): Resolution;
+/**
+ * The FILING resolver (foundations findings 13/15/19): the execution
+ * profile a scope stores, resolved once, exactly, at filing. The model is
+ * the exact string the argv will carry — the harness-default road refuses
+ * here rather than floating (ruling 10). Repair precedence: the
+ * --repair-model flag, else the repair phase-config row's MODEL (its
+ * provider must equal the build provider — cross-provider repair does not
+ * exist), else the literal "inherit". Callers that file scopes SAVE an
+ * unresolved state on refusal (finding 19) — this function only says why.
+ */
+export type ProfileResolution = {
+    ok: true;
+    profile: ExecutionProfile;
+    provenance: {
+        resolvedFrom: string;
+        repairFrom: string;
+    };
+} | {
+    ok: false;
+    reason: "unknown-provider" | "no-model" | "repair-provider-mismatch";
+    problem: string;
+};
+export declare function resolveScopeProfile(store: Store, repo: string | null, ref: Pick<TaskRef, "agentProvider" | "agentModel"> | undefined, flags: PhaseFlags & {
+    repairModel?: string | undefined;
+    permissionMode?: UnattendedPermissionMode | undefined;
+}): ProfileResolution;
+export type ChainResolution = {
+    ok: true;
+    chain: ChainEntry[];
+    kind: "profile" | "chain";
+} | {
+    ok: false;
+    reason: "base-unresolved" | "bad-fallback" | "duplicate";
+    problem: string;
+};
+/**
+ * Resolve the full EXECUTION CHAIN a scope files under (v30): the base
+ * (entry 0) is the ordinary single-profile resolution wearing the base
+ * provider's auth mode; the fallbacks are the scope's configured entries,
+ * each resolved to a WHOLE ExecutionProfile (repair per entry). With no
+ * fallbacks configured, the result is `kind: "profile"` — a single-profile
+ * approval, byte-identical to today (NOT an explicit chain). With
+ * fallbacks, it is `kind: "chain"` and the approval binds the whole thing.
+ * The base auth mode is passed in (the caller reads it from the managed
+ * key store) so resolution stays pure and testable.
+ */
+export declare function resolveScopeChain(store: Store, repo: string | null, ref: Pick<TaskRef, "agentProvider" | "agentModel"> | undefined, flags: PhaseFlags & {
+    repairModel?: string | undefined;
+    permissionMode?: UnattendedPermissionMode | undefined;
+}, baseAuthMode: "subscription" | "api-key"): ChainResolution;
+/**
+ * The two candidate tiers the routing policy chooses between, per phase,
+ * read from configuration ONLY — never inferred from a model's name:
+ *
+ *   routine — the ordinary resolution above (project > installation,
+ *             review inheriting the planner's pair), i.e. exactly the
+ *             agent every pre-v47 scope resolved to — but EXACT: a phase
+ *             whose resolution has no model id cannot be a candidate,
+ *             because an approval binds exact routing. Repair is the one
+ *             phase with no routine candidate of its own when nothing is
+ *             configured: it inherits the build leg (repairs resume the
+ *             builder's session), and the policy says so.
+ *   strong  — the operator's named strong row (`config set <phase> --tier
+ *             strong …`), project over installation, review inheriting the
+ *             plan's strong row when it has none of its own; null when
+ *             nothing is configured, and the route then SAYS so.
+ *
+ * A misconfigured row — unknown provider, missing model, argv-unsafe
+ * model — REFUSES with the words to fix it; the caller files the scope
+ * unresolved with them. Nothing is skipped or guessed.
+ */
+export type CandidatesResolution = {
+    ok: true;
+    candidates: RouteCandidates;
+} | {
+    ok: false;
+    phase: Phase;
+    problem: string;
+};
+export declare function resolveRouteCandidates(store: Store, repo: string | null, pins?: {
+    plan?: ExactSpec | null;
+    build?: ExactSpec | null;
+}): CandidatesResolution;
+/** A task's pinned pair as an EXACT spec, or the words for why it cannot
+ * route: a pin with no model id binds nothing exact. */
+export declare function exactPinOf(provider: string | null, model: string | null, phase: "plan" | "build"): {
+    ok: true;
+    pin: ExactSpec | null;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * THE ROUTE A TASK RUNS UNDER, for dispatch and every surface:
+ *
+ *   approved   — the sealed route when the approval stands (authoritative;
+ *                mutable configuration never rewrites it);
+ *   proposed   — the WORKING proposed route the next approval would seal;
+ *   live       — no scope yet (a plan request): a live recommendation from
+ *                the task's own risk, overrides, and pins over today's
+ *                configuration;
+ *   legacy     — a row PROVEN to predate v47 (no route era): its sealed
+ *                profile alone governs the build; plan and review resolve
+ *                from configuration at run time, and the surfaces say so;
+ *   unreadable — a routed row whose route data is missing, malformed, or
+ *                does not verify against its approval, or a task whose
+ *                configuration cannot make an exact route: FAIL CLOSED,
+ *                with the words. Nothing dispatches on it.
+ *
+ * `source` says which, so a surface never presents a live recommendation
+ * as a sealed term and a runner never runs a legacy road on a routed row.
+ */
+export type TaskRoute = {
+    kind: "route";
+    route: PhaseRoute;
+    source: "approved" | "proposed" | "live";
+} | {
+    kind: "legacy";
+    profile: ExecutionProfile;
+    approved: boolean;
+} | {
+    kind: "unreadable";
+    problem: string;
+};
+export declare function routeOfTask(store: Store, taskId: string, ref: TaskRef | null, now: Date): TaskRoute | null;
+/**
+ * THE ROUTINE'S FROZEN AUTHORITY, resolved once at filing: the four-role
+ * route a routine's firings will run under, and the execution profile that
+ * restates its build and repair legs exactly. Routine tasks declare routine
+ * risk; the rubric's evidence needs, the installation's quality default,
+ * and the repository's publication authority are the other signed inputs.
+ * A configuration that cannot make an exact, runnable route answers with
+ * the words — the routine files unresolved and cannot be approved until
+ * it is filed again under a configuration that can.
+ */
+export type RoutineAuthority = {
+    ok: true;
+    route: PhaseRoute;
+    profile: ExecutionProfile;
+} | {
+    ok: false;
+    problem: string;
+};
+export declare function resolveRoutineAuthority(store: Store, repo: string, acceptance: readonly AcceptanceCriterion[], now: Date): RoutineAuthority;
+/** One agent a surface shows for one role: an exact pair, where it comes
+ * from, whether it is the role's current leg, and whether it can be
+ * CHOSEN — only a pair the active configuration names for this role is
+ * selectable; a current leg the configuration no longer names is shown
+ * for what runs today and nothing more. */
+export type AgentChoice = ExactSpec & {
+    source: string;
+    current: boolean;
+    selectable: boolean;
+};
+/**
+ * THE ROLE'S CONFIGURED CHOICES (v48), simple and role-specific: for each
+ * role, exactly the exact pairs the active configuration names FOR THAT
+ * ROLE — its everyday agent and its strong agent — and nothing borrowed
+ * from another role. Repair runs only the build leg's provider (repairs
+ * resume the builder's session): its choices are the configured repair
+ * rows on that provider plus the build role's own configured agents on
+ * it, so an operator can keep repairs on the builder without naming a
+ * repair row. Gemini never reviews. Nothing is typed free-hand and
+ * nothing unconfigured is selectable: an approval binds an exact agent
+ * the operator named once, in configuration.
+ *
+ * The role's CURRENT leg rides along marked `current`; when the
+ * configuration no longer names it (a stale override, a routine's pin)
+ * it is display-only — `selectable: false` — so a surface can say what
+ * runs today without offering to re-pick it. Empty when the
+ * configuration cannot make exact candidates at all; the surface then
+ * says so instead of guessing.
+ */
+export declare function agentChoicesFor(store: Store, repo: string | null, route: PhaseRoute | null): Record<Phase, AgentChoice[]>;