toolroll 0.5.0

package/dist/browser-workspace.js

@@ -0,0 +1,47 @@
+import { browserCrewFromIndex } from './browser-crew.js';
+export { browserCrewFromIndex, browserWorkActionHref } from './browser-crew.js';
+import { workIndexPage } from './work-index.js';
+/** Safe inside a script[type=application/json] element. JSON escaping alone
+ * does not stop the HTML parser from closing that element at </script>. */
+export function serializeBrowserWorkspace(workspace) {
+    return JSON.stringify(workspace).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+}
+export const BROWSER_CREW_LIMIT = 40;
+/** A bounded recent family list. The caller supplies its already admitted
+ * access; an optional project can only narrow it. Admission and family grouping
+ * happen before the SQL limit and before reading questions or saved evidence. */
+export function browserCrewOf(store, now, access, options = {}) {
+    const project = options.project ?? null;
+    if (project !== null && access.repos !== null && !access.repos.includes(project))
+        return { crew: [], crewTruncated: false };
+    const limit = Number.isFinite(options.limit)
+        ? Math.max(1, Math.min(BROWSER_CREW_LIMIT, Math.floor(options.limit))) : BROWSER_CREW_LIMIT;
+    const page = workIndexPage(store, now, access, { limit, project });
+    return browserCrewFromIndex(page);
+}
+/** Navigation input must already be admitted by the caller. No extra project
+ * discovery belongs in a browser projection. Keep exact paths in every link. */
+export function browserProjectsOf(projects) {
+    const seen = new Set();
+    return projects.flatMap(project => {
+        if (seen.has(project.path))
+            return [];
+        seen.add(project.path);
+        return [{ name: project.name, path: project.path, href: `/work?project=${encodeURIComponent(project.path)}`,
+                knowledgeHref: `/settings/knowledge?repo=${encodeURIComponent(project.path)}` }];
+    });
+}
+export function browserNavigationOf(path, project = null, needsYou = 0) {
+    const pathname = path.split('?')[0].split('#')[0];
+    const knowledge = pathname === '/settings/knowledge' || pathname.startsWith('/settings/knowledge/');
+    return [
+        { label: 'Chat', href: '/chat', active: pathname === '/chat' },
+        { label: 'Tasks', href: `/work${project === null ? '' : `?project=${encodeURIComponent(project)}`}`,
+            active: pathname === '/work' || pathname === '/tasks' || pathname.startsWith('/t/') || pathname.startsWith('/r/'),
+            ...(needsYou > 0 ? { count: needsYou } : {}) },
+        { label: 'Flows', href: '/flows', active: pathname === '/flows' || pathname.startsWith('/flows/') },
+        { label: 'Projects', href: '/projects', active: pathname === '/projects' },
+        { label: 'Knowledge', href: `/settings/knowledge${project === null ? '' : `?repo=${encodeURIComponent(project)}`}`, active: knowledge },
+        { label: 'Settings', href: '/settings', active: !knowledge && (pathname === '/settings' || pathname.startsWith('/settings/')) },
+    ];
+}

package/dist/budget-alerts.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Budget alerts (v105): at 50, 80 and 100 % of a monthly budget, once each a
+ * month, a notification goes out (to everyone's usual places; a person's
+ * budget to that person) and the ledger keeps it. Only the highest mark newly
+ * reached is sent: a budget that jumps past three marks at once says so once.
+ * Budgets are dollars: only work billed to an API key counts (a subscription
+ * costs nothing extra).
+ */
+import type { Store } from "./store.js";
+import { type BudgetState } from "./spend.js";
+export declare function budgetAlertPass(store: Store, now: Date): {
+    sent: {
+        budget: number;
+        mark: number;
+    }[];
+};
+/** The loop beside the console: a pass a minute. */
+export declare function startBudgetAlerts(store: Store, everyMs?: number): () => void;
+export type { BudgetState };

package/dist/budget-alerts.js

@@ -0,0 +1,46 @@
+import { budgetLabel, teammateNames, usd } from "./spend.js";
+const MARKS = [100, 80, 50];
+export function budgetAlertPass(store, now) {
+    const { month, budgets } = store.monthSpend(now);
+    const sent = [];
+    const names = teammateNames(store.handle);
+    for (const budget of budgets) {
+        const mark = MARKS.find(one => budget.percent >= one);
+        if (mark === undefined)
+            continue;
+        // Keyed by the limit too: a budget raised (or lowered) this month alerts afresh at its new marks.
+        const key = (one) => `budget:${budget.id}:${budget.limitMicrousd}:${month}:${one}`;
+        // A higher mark already sent this month covers this one.
+        if (MARKS.filter(one => one >= mark).some(one => store.handle.prepare("SELECT 1 AS hit FROM notification WHERE dedupe_key = ?").get(key(one)) !== undefined))
+            continue;
+        const label = budgetLabel(budget, budget.scope === "teammate" ? names.get(Number(budget.key)) : undefined);
+        const fresh = store.enqueueNotification({
+            dedupeKey: key(mark), kind: "budget-alert", pushClass: "attention", link: `/spend?month=${month}`,
+            subject: `${label} budget: ${mark}% used`,
+            body: `${usd(budget.spentMicrousd)} of ${usd(budget.limitMicrousd)} in ${month}.${mark >= 100 ? budget.hardStop ? " New API work waits until next month or a higher budget." : " It only alerts; work carries on." : ""}`,
+            source: budget.scope === "project" ? { project: budget.key } : { installation: true },
+            ...(budget.scope === "person" ? { recipient: budget.key } : {}),
+        }, now);
+        if (!fresh)
+            continue;
+        store.recordAction({ at: now.toISOString(), actor: "system", repo: budget.scope === "project" ? budget.key : null, taskId: null, runId: null,
+            action: `budget ${mark}% used: ${label.replace(/'s$/, "")}`, outcome: mark >= 100 && budget.hardStop ? "stopped" : "alerted", source: "policy",
+            detail: `${usd(budget.spentMicrousd)} of ${usd(budget.limitMicrousd)} in ${month}` });
+        sent.push({ budget: budget.id, mark });
+    }
+    return { sent };
+}
+/** The loop beside the console: a pass a minute. */
+export function startBudgetAlerts(store, everyMs = 60_000) {
+    let stopped = false;
+    const tick = () => { if (stopped)
+        return; try {
+        budgetAlertPass(store, new Date());
+    }
+    catch { /* the next pass tries again */ } };
+    const timer = setInterval(tick, everyMs);
+    timer.unref?.();
+    const first = setTimeout(tick, 5_000);
+    first.unref?.();
+    return () => { stopped = true; clearInterval(timer); clearTimeout(first); };
+}

package/dist/builder.d.ts

@@ -0,0 +1,370 @@
+import { type PreparedEvidence } from "./prepared-evidence.js";
+import { type ExecResult, type RunOptions } from "./exec.js";
+import type { Decision, Store } from "./store.js";
+import { type ExecutionProfile, type Scope } from "./scope.js";
+import { type ParsedDecision, type Problem } from "./decision.js";
+import { type AgentOutcome } from "./invoke.js";
+import { type DiffStatFacts } from "./proof.js";
+import { type AuthoritySnapshot, type MilestoneState } from "./plan.js";
+export type Runner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
+/**
+ * The native shell for an operator-approved repository command. There are
+ * exactly two consumers: dependency setup before an agent starts, and the
+ * verification command after it commits. Keeping the choice here prevents a
+ * Windows worker from trying to spawn `/bin/sh` while leaving the approved
+ * command itself byte-for-byte unchanged.
+ */
+export declare function approvedCommandShell(command: string, platform?: NodeJS.Platform, windowsShell?: string): {
+    file: string;
+    args: string[];
+    display: string;
+};
+/**
+ * Whether an approved project check failed at its launch boundary because a
+ * local executable was unavailable. The numeric shell codes are the primary
+ * signal. Windows `cmd.exe` can instead return 1 with one exact diagnostic,
+ * so that spelling is admitted only on Windows. Free-form test output such as
+ * `MODULE_NOT_FOUND` is deliberately not enough: assertions are untrusted and
+ * must not turn an ordinary product failure into environment recovery.
+ */
+export declare function verificationExecutableMissing(result: ExecResult, platform?: NodeJS.Platform): boolean;
+/** The attended dispatch (Parity II Phase 2): the authorization is the
+ * authority, the coordinator takes ownership at the spawn point, and the
+ * builder returns `held` without settling. */
+export type AttendedDispatch = {
+    authorization: import("./store.js").AttendedAuthorization;
+    coordinator: import("./held.js").HeldSessionCoordinator;
+    upIncarnation: string;
+    socketDir: string;
+    releaseWorktree: (path: string) => Promise<unknown>;
+    dispose: {
+        repo: string;
+        origin: string;
+        provider: string;
+        model: string | null;
+        policy?: import("./dispose.js").DisposePolicy;
+    };
+    starter?: import("./exec.js").HeldSessionStart extends never ? never : typeof import("./exec.js").startClaudeHeldSession;
+    graceMs?: number;
+    /** v28: the operator's session cap, enforced in the custody transaction. */
+    maxHeldSessions?: number;
+    onDisposed?: import("./held.js").HeldLaunchArgs["onDisposed"];
+};
+export type BuildRequest = {
+    attended?: AttendedDispatch;
+    taskId: string;
+    taskRef: number;
+    runner: string;
+    /**
+     * The exact lease this attempt was dispatched under. Optional for a person
+     * driving `build` by hand; an unattended pass always sets it, because the
+     * runner-name check alone cannot tell a live attempt from a superseded one
+     * the same runner started earlier.
+     */
+    leaseId?: string;
+    /**
+     * The runner's own credential, for the CREDENTIALED pulse (arc 2 finding
+     * 33): with it, every mid-build beat re-proves the token against the
+     * current hash, and a takeover's rotation fences this attempt at its
+     * next beat. Absent (a person driving `build` by hand), the beat falls
+     * back to the unauthenticated touch, exactly as before.
+     */
+    runnerToken?: string;
+    /** A tournament contestant's OWN approved profile (v24): under the joint
+     * race approval, this — not the scope's single snapshot — is what the
+     * dispatch proof holds the invocation to. */
+    contestProfile?: ExecutionProfile;
+    /**
+     * Real time, read repeatedly. `now` is one instant and a build is not: a
+     * lease heartbeated with the timestamp the build started at is a lease that
+     * stopped being extended the moment it began.
+     */
+    clock?: () => Date;
+    /** How often the pulse beats while the agent runs. 0 disables it. */
+    pulseMs?: number;
+    worktree: string;
+    branch: string;
+    now: Date;
+    /**
+     * The open run record this attempt writes its facts to. Required: nothing
+     * spends without a record that will outlive it, and the invocation
+     * gateway refuses a paid call whose run is missing or already finished.
+     */
+    runId: number;
+    /** Claude's native dollar cap for this attempt (tournaments): the
+     * harness stops itself at this figure. Absent = uncapped, as today. */
+    maxBudgetUsd?: number;
+    /** Fires with the provider's process-group id the moment it exists —
+     * the worker-process ledger records it (v14). */
+    onProviderSpawn?: (pid: number) => void;
+    /** Where evidence files live. Defaults to ~/.toolroll/evidence (or an older ~/.standing-orders/evidence). */
+    evidenceRoot?: string;
+    /** A draft preserved from an interrupted predecessor. The fresh attempt
+     * still reviews it and writes its own nonce-bound handoff. */
+    recoveredDraftRun?: number;
+    recoveredDraftKind?: "completed" | "partial";
+    /** Defaults to the safe one; see the note on permissions above. */
+    permissionMode?: "acceptEdits" | "auto" | "plan";
+    /** Named honestly, never the default, and only ever set by a person. */
+    skipPermissions?: boolean;
+    /** The harness this build runs on. Repair ALWAYS inherits it — a session
+     * resumed across providers is not a session (Codex provider review, Q3). */
+    provider?: "claude" | "codex" | "openrouter" | "gemini";
+    model?: string;
+    /**
+     * The model repair turns run on. Repair is a few-k, one-job resumption —
+     * the §9 economics argument in miniature — so it may run cheaper than the
+     * builder. Defaults to the builder's model.
+     */
+    repairModel?: string;
+    maxTurns?: number;
+    timeoutMs?: number;
+    agent?: Runner;
+    git?: Runner;
+    /** Runs the approved worktree setup command (M5.7). Tests inject; production uses exec. */
+    setup?: Runner;
+    /** Runs the repository's approved verification command (Priority 2), after
+     * commit. Tests inject; production uses exec. */
+    verify?: Runner;
+    /**
+     * The stop fence (audit IV-1, completed): re-proved AFTER the agent and
+     * BEFORE the commit. A stop that lands while the agent runs preserves
+     * the work uncommitted for the successor — late output cannot commit.
+     */
+    shouldStop?: () => boolean;
+};
+/**
+ * What the agent handed over when it parked: the validated decision and the
+ * evidence rows already written for it. The caller seals it with
+ * `finalizeParkFenced` — nothing here has touched the claim or the task.
+ */
+export type ParkPackage = {
+    decision: ParsedDecision;
+    artifactIds: number[];
+};
+export type BuildResult = {
+    ok: true;
+    parked?: undefined;
+    committed: boolean;
+    /** The agent said no-change and the tree proves it: done, nothing to publish. */
+    noChange?: boolean;
+    /** The session is HELD (attended road): the coordinator owns run,
+     * lease, and worktree from here — the caller settles NOTHING. */
+    held?: true;
+    branch: string;
+    summary: string;
+} | {
+    ok: true;
+    parked: ParkPackage;
+    branch: string;
+} | {
+    ok: false;
+    reason: BuildRefusal;
+    message: string;
+    problems?: Problem[];
+};
+export type BuildRefusal = "skills-unavailable"
+/** Sprint 8: the organisation policy stops this provider, model or permission level. */
+ | "policy" | "unapproved" | "scope-changed" | "stale-approval" | "mode-ended" | "stale-authorization" | "attended-only" | "session-cap" | "attended-held" | "attended-unsupported" | "run-held" | "spawn-failed" | "capability" | "no-claim" | "not-yours" | "not-leased" | "protected-branch" | "wrong-branch" | "moved-branch" | "fenced" | "agent" | "agent-reported" | "no-op" | "moved-head" | "timeout" | "git" | "commit-failure" | "malformed-decision" | "provider-init" | "setup" | "revision-brief" | "external" | "stopped" | "plan-revised" | "plan-revision-blocked" | "provider-unattested" | "provider-protocol" | "chain-credential" | "chain-custody" | "runner-custody" | "auth-mode" | "route-authority" | "containment";
+/** Long enough for real work; short enough that a stuck build ends the same night. */
+export declare const DEFAULT_BUILD_TIMEOUT_MS: number;
+export declare const DEFAULT_MAX_TURNS = 40;
+/**
+ * Bounded repair (§6): a malformed park gets the same session back, twice,
+ * with a compact error naming exactly what failed — then it is an incident.
+ * The turns are short and narrow because the job is narrow: re-emit one
+ * file. Sandcastle's mechanism, sized to sandcastle's numbers.
+ */
+export declare const REPAIR_TURNS = 2;
+export declare const REPAIR_MAX_TURNS = 4;
+export declare const REPAIR_TIMEOUT_MS: number;
+/**
+ * How often a running build says "still here" — extending its lease and its
+ * runner's liveness in one beat. A minute against a three-minute liveness
+ * window means two beats can be lost to load before anything looks dead.
+ */
+export declare const DEFAULT_PULSE_MS = 60000;
+/** Branches an unattended agent may never commit to, whatever it was asked. */
+export declare const PROTECTED: Set<string>;
+/**
+ * Setup shells run under an ALLOWLIST, not the operator's shell minus two
+ * names (audit IV-5, completed): the deterministic basics a package
+ * manager needs and nothing that could carry a credential. A setup that
+ * needs more exports it inside its own approved command text — visibly,
+ * on the approval screen.
+ */
+export declare const SETUP_ENV_ALLOWLIST: readonly string[];
+/** Belt over the allowlist's suspenders: even if these ever appear in `env`, they die here. */
+export declare const SETUP_ENV_DENYLIST: readonly string[];
+/**
+ * A bounded, redacted diagnostic from untrusted tool output (audit IV-5):
+ * assignments and URL userinfo that look credential-shaped are blanked
+ * before a byte reaches SQLite, a page, or a webhook. Coarse on purpose —
+ * over-redacting a diagnostic costs a glance at the real log; under-
+ * redacting costs a secret.
+ */
+export declare function redactSecretText(text: string): string;
+/** The same blanking with no length cap, for a log that keeps its length (a flow script's output). */
+export declare function redactSecretAssignments(text: string): string;
+export declare function proveApprovedProfile(scope: Scope | null, contestProfile: ExecutionProfile | null, given: {
+    provider: string;
+    model: string | undefined;
+    maxTurns: number | undefined;
+    timeoutMs: number | undefined;
+    skipPermissions: boolean;
+}): {
+    ok: true;
+    effective: {
+        model: string;
+        maxTurns: number | undefined;
+        timeoutMs: number;
+        skipPermissions: boolean;
+        profile: ExecutionProfile;
+    };
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Build one task, if everything says it may.
+ *
+ * The gates are re-checked here rather than assumed from the caller, because
+ * this is the last point before somebody's repository changes, and a caller
+ * that forgot one is exactly the caller this is protecting against.
+ */
+export declare function build(store: Store, request: BuildRequest): Promise<BuildResult>;
+/**
+ * Everything the post-provider settlement closes over (Parity II Phase 2,
+ * v4 Q2 / v6 W8): an explicit record, so the held road's coordinator can
+ * run THE SAME settlement the one-shot road runs — one state machine,
+ * never a paraphrase. `fenced()` reads the pulse's live flag: settlement
+ * decisions are about NOW, not about the moment of capture.
+ */
+/** The prepared candidate must be a commit this repository holds and must
+ * descend from the task's base (the first attempt's base once one exists,
+ * otherwise the current HEAD). Plain words on refusal, nothing touched. */
+export declare function proveCandidate(git: Runner, worktree: string, candidate: string, pinnedBase: string | null): Promise<string | null>;
+/** Make the worktree's tracked tree EXACTLY the candidate commit's tree —
+ * renames, deletions and additions included — without moving HEAD, so the
+ * result is uncommitted work on the task branch, as an agent would leave it.
+ * Untracked files (the protocol mailbox among them) are not touched. */
+export declare function bringWorktreeTo(git: Runner, worktree: string, candidate: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+}>;
+export type CapturedBuild = {
+    store: Store;
+    request: BuildRequest;
+    agent: BuildRequest["agent"];
+    git: Runner;
+    worktree: string;
+    branch: string;
+    baseRevision: string;
+    taskId: string;
+    taskRef: number;
+    runner: string;
+    provider: string;
+    scope: Scope | null;
+    effective: {
+        model: string;
+        maxTurns: number | undefined;
+        timeoutMs: number;
+        skipPermissions: boolean;
+        profile: ExecutionProfile;
+    };
+    answers: {
+        decision: Decision & {
+            taskId: string;
+        };
+        choice: string;
+        note: string | null;
+    }[];
+    timeoutMs: number;
+    root: string;
+    mailbox: string;
+    done: string;
+    /** The proof manifest's nonce-bound filename (Priority 2) — optional for
+     * the agent to write, read the same way as the handoff once it finishes. */
+    proof: string;
+    preparedEvidence?: PreparedEvidence;
+    rubric?: string;
+    clock: () => Date;
+    fenced: () => boolean;
+    /** The adaptive-execution-plan binding, when this attempt received a plan
+     * with milestones. Optional: a build with no plan (or an older free-form
+     * one) settles exactly as it always has, and a caller assembling a
+     * capture by hand need not know this protocol exists. */
+    plan?: PlanBinding;
+};
+/** What settlement needs to know about the plan this attempt built against. */
+export type PlanBinding = {
+    /** This attempt's terminal revision-proposal file, worktree-relative. */
+    proposal: string;
+    /** The revision number the brief named — what a page and a page's
+     * notification say out loud. */
+    revision: number;
+    /** The signed scope and publication authority as they stood when the
+     * build STARTED. A revision auto-applies only if both still match. */
+    authority: AuthoritySnapshot;
+    /** The checkpoint reader's live state, shared with the pulse: settlement
+     * makes one more pass with it, so a final checkpoint that raced the last
+     * beat is not lost, and one the beat already ingested is not doubled. */
+    progress: ProgressIngestState;
+};
+/**
+ * Everything the milestone-checkpoint reader carries between passes. Two
+ * callers share one instance — the pulse's `beat()` and the single
+ * settlement pass — which is exactly why the dedupe state lives here rather
+ * than in either of them: the last beat and the final read routinely see
+ * the same bytes, and a checkpoint written twice would read as progress
+ * twice.
+ */
+export type ProgressIngestState = {
+    runId: number;
+    taskRef: number;
+    /** Null when this task has no ledger row to attach a checkpoint to —
+     * `run_checkpoint.plan_revision` is NOT NULL, so nothing is recorded. */
+    planRevisionId: number | null;
+    expectedRevisionHash: string | null;
+    knownIds: readonly string[];
+    progressPath: string;
+    /** The exact bytes last ingested — a cheap `Buffer.equals` against the
+     * file skips the parse entirely on an unchanged checkpoint. */
+    lastRaw: Buffer | null;
+    /** The furthest state each milestone has reached, for the regression
+     * check. Not a full snapshot: only the states matter. */
+    lastStates: Map<string, MilestoneState>;
+};
+export declare function settleProviderOutcome(captured: CapturedBuild, result: AgentOutcome): Promise<BuildResult>;
+/**
+ * Read the agent's optional proof, re-run the repository's approved
+ * verification command if one is configured, and save the machine's one
+ * verdict — computed once, here, and never re-inferred at render. Runs
+ * strictly after commit and terminal-diff capture; every branch below
+ * ends in `store.saveProofVerdict`, never in a thrown error that could
+ * reach the caller and be mistaken for a build failure.
+ */
+/** The sealed diff-stat artifact restated as facts: whether it captured
+ * and verified, whether its file list was cut, the paths it names, and the
+ * old name of every rename git paired (provenance, never a path). Anything
+ * missing, failed, tampered or unparseable reads as not captured. */
+export declare function sealedDiffStatFacts(store: Store, root: string, statArtifactId: number): DiffStatFacts | null;
+/**
+ * What a non-zero agent exit means, in words a person can act on: the
+ * harness's own result line names the ending (a turn ceiling, an error
+ * during execution) and how many turns it took; only when it said nothing
+ * do stderr or the bare exit code stand in. Two attempts died at exactly
+ * the ceiling on 2026-09-04 and the ledger said "unknown" — the fact was
+ * in the stream all along.
+ */
+export declare function agentExitWords(outcome: {
+    code: number;
+    stderr: string;
+    finalMessage: string | null;
+    ending?: {
+        subtype: string | null;
+        turns: number | null;
+    } | null;
+}): string;