toolroll 0.5.0

package/dist/dispatch.js

@@ -0,0 +1,311 @@
+/**
+ * One read-side answer to "will this task run?"
+ *
+ * The atomic claim remains the authority. This module owns the task-local
+ * predicates that claim re-proves under its write transaction, then layers
+ * fleet observations on top for people and agents reading the queue. A
+ * diagnosis can go stale; it can never grant a lease.
+ */
+import { isAlive } from "./runner.js";
+import { updateAdmissionPaused, UPDATE_PAUSED } from "./desktop-update-gate.js";
+import { approvalOf } from "./scope.js";
+import { plannerSourceProblemOf } from "./planner-source.js";
+import { REVIEW_TOKENS, resultStatusOf, reviewFactsOf } from "./workspace-ui.js";
+import { BUILT_IN, parseCapabilityKey } from "./store.js";
+export const DEFAULT_MAX_OPEN_DECISIONS = 5;
+/**
+ * Task state, active holds, and unfinished dependencies in the exact order
+ * acquireIfReady checks them. The claim path calls this while holding its
+ * write transaction; read surfaces call it only as a snapshot.
+ */
+export function taskReadinessBlocker(store, taskRef, now) {
+    const db = store.handle;
+    const stamp = now.toISOString();
+    const task = db
+        .prepare(`SELECT task.id, task.state FROM task
+       JOIN task_ref ON task_ref.external_id = task.id AND task_ref.backend = ?
+       WHERE task_ref.id = ?`)
+        .get(BUILT_IN, taskRef);
+    if (task === undefined)
+        return { code: "unknown-task", message: "no such task" };
+    const state = String(task["state"]);
+    if (state !== "queued")
+        return { code: "state", state, message: `state is ${state}, not queued` };
+    const hold = db
+        .prepare(`SELECT owner_kind, until, reason FROM hold
+       WHERE task_ref = ? AND (until IS NULL OR until > ?)
+       ORDER BY held_at, id LIMIT 1`)
+        .get(taskRef, stamp);
+    if (hold !== undefined) {
+        return {
+            code: "hold",
+            ownerKind: String(hold["owner_kind"]),
+            until: hold["until"] === null || hold["until"] === undefined ? null : String(hold["until"]),
+            message: `held: ${String(hold["reason"])}`,
+        };
+    }
+    const blocker = db
+        .prepare(`SELECT blocker.id, blocker.state FROM task_edge
+       JOIN task AS blocker ON blocker.id = task_edge.blocker
+       WHERE task_edge.blocked = ? AND blocker.state <> 'done'
+       ORDER BY blocker.id LIMIT 1`)
+        .get(String(task["id"]));
+    if (blocker !== undefined) {
+        const blockerId = String(blocker["id"]);
+        return {
+            code: "dependency",
+            blockerId,
+            blockerState: String(blocker["state"]),
+            message: `waiting on ${blockerId}`,
+        };
+    }
+    return null;
+}
+/** The exact live approval predicate used by both the scheduler survey and
+ * the atomic claim. Mode-backed approvals count only while their signer and
+ * mode still stand. */
+// Recovery reads this same live predicate; a completed run does not grandfather
+// a revoked signer or mode, and this query never creates dispatch authority.
+export function scopeApprovedForDispatch(store, taskRef, now) {
+    const row = store.handle
+        .prepare(`SELECT 1 AS hit FROM task_scope
+       JOIN task_ref ON task_ref.id = ? AND task_scope.task_id = task_ref.external_id
+       WHERE task_scope.approved_digest = task_scope.digest AND task_scope.approved_at IS NOT NULL
+         AND (COALESCE(task_scope.approval_basis, 'password') <> 'mode'
+           OR EXISTS (SELECT 1 FROM operating_mode om
+                      JOIN approver signer ON signer.name = om.signed_by
+                     WHERE om.repo = task_ref.repo AND om.revoked_at IS NULL
+                       AND om.absolute_expiry > ? AND om.digest = task_scope.mode_digest
+                       AND signer.revoked_at IS NULL AND signer.role = 'approver'))`)
+        .get(taskRef, now.toISOString());
+    return row !== undefined;
+}
+/** The phase the ordinary dispatch loop would choose before it resolves an
+ * agent. Attended authorization is deliberately outside this ordinary path. */
+export function dispatchRoleFor(store, taskRef, now) {
+    const ref = store.refForId(taskRef);
+    const approved = scopeApprovedForDispatch(store, taskRef, now);
+    if (ref?.plan === "requested" && !approved)
+        return "planner";
+    if (ref?.deliverable === "report" && approved)
+        return "scout";
+    return "builder";
+}
+/** The first requirement this task fails, in words, or null. */
+export function missingCapability(store, taskRef, dispatchRepo, now) {
+    const db = store.handle;
+    const row = db.prepare("SELECT repo, capability_requirements FROM task_ref WHERE id = ?").get(taskRef);
+    if (row === undefined)
+        return "no such task reference";
+    let keys;
+    try {
+        keys = JSON.parse(String(row["capability_requirements"] ?? "[]"));
+    }
+    catch {
+        keys = [];
+    }
+    if (keys.length === 0)
+        return null;
+    const repo = row["repo"] === null || row["repo"] === undefined ? dispatchRepo : String(row["repo"]);
+    if (repo === null)
+        return `requires ${keys[0]} but is placed in no repository`;
+    const stamp = now.toISOString();
+    for (const key of keys) {
+        const parsed = parseCapabilityKey(key);
+        if (parsed === null)
+            return `requirement \`${key}\` is not a capability key`;
+        const found = db.prepare("SELECT status, expires_at FROM capability WHERE repo = ? AND kind = ? AND name = ?").get(repo, parsed.kind, parsed.name);
+        if (found === undefined)
+            return `needs ${key} — unrecorded for ${repo}`;
+        if (String(found["status"]) !== "verified")
+            return `needs ${key} — not verified`;
+        const expires = found["expires_at"];
+        if (expires !== null && String(expires) <= stamp)
+            return `needs ${key} — verification expired`;
+    }
+    return null;
+}
+function answer(code, condition, summary, detail, options = {}) {
+    return {
+        condition,
+        code,
+        summary,
+        detail,
+        action: options.action ?? null,
+        nextAt: options.nextAt ?? null,
+        role: options.role ?? null,
+        blockerTaskId: options.blockerTaskId ?? null,
+        review: options.review ?? null,
+    };
+}
+/** The review projection, shaped for readers (v50). */
+function reviewViewOf(sourceRun, retry) {
+    const current = retry.live ?? (retry.state === "queued" ? null : retry.latest);
+    return {
+        sourceRun,
+        state: retry.state,
+        attempt: retry.state === "queued" ? retry.nextAttempt : current?.attempt ?? null,
+        cap: retry.cap,
+        retriesUsed: retry.retriesUsed,
+        retriesRemaining: retry.retriesRemaining,
+        latestRun: retry.latest?.runId ?? null,
+        latestReason: retry.latest?.reason ?? null,
+        interrupted: retry.latest !== null && (retry.latest.outcome === "interrupted" || retry.latest.reason === "interrupted"),
+        queued: retry.openRequest === null ? null : { requestedBy: retry.openRequest.requestedBy, origin: retry.openRequest.origin },
+    };
+}
+function approvedProfile(scope) {
+    if (scope === null || scope.approvalKind === "chain")
+        return null;
+    return scope.approvedProfile ?? scope.profile ?? null;
+}
+/** The read-side lifecycle answer. It changes nothing and grants nothing. */
+export function diagnoseTaskDispatch(store, taskId, now) {
+    const task = store.getTask(taskId);
+    const ref = store.lookupRef(taskId);
+    if (task === null || ref === null)
+        return null;
+    if (task.state === "done") {
+        const runs = store.runsFor(ref.id);
+        const result = runs.find(run => (run.role === "builder" || run.role === "scout") && (run.outcome === "built" || run.outcome === "no-change") && run.finishedAt !== null);
+        if (result?.role === "scout")
+            return answer("complete", "terminal", "Report ready", "The research report is ready to review.", { action: "open-result" });
+        const proof = result === undefined ? null : store.proofVerdictFor(result.id);
+        const accepted = result !== undefined && store.proofAcceptance(result.id) !== null;
+        // THE REVIEW STATUS (v50): read from the bounded retry projection — the
+        // open request and the NEWEST root attempt in ordinal order — so a
+        // queued retry is never hidden behind an older failed run, and every
+        // answer below names the attempt count and the one explicit next act.
+        const retry = result === undefined ? null : store.reviewRetryStateOf(result.id);
+        const review = result === undefined || retry === null || retry.state === "unrequested" ? null : reviewViewOf(result.id, retry);
+        // The words are the workspace's shared projection (package 1, review
+        // fixes): the same label and detail the Work rows, task page, focused
+        // chat, receipt, and review cockpit render for this exact result —
+        // a review in flight included. The codes stay the contract.
+        const reviewFacts = reviewFactsOf(retry, runner => {
+            const reviewer = store.getRunner(runner)?.runner;
+            return reviewer !== undefined && isAlive(reviewer, now);
+        });
+        // A no-change conclusion owes no proof beyond its handoff and sealed
+        // diff (the task page's own "attested floor"); with both on record it
+        // is complete, not verification-needed.
+        const noChangeRecord = result === undefined || result.outcome !== "no-change"
+            ? undefined
+            : (() => { const kinds = new Set(store.artifactsFor(result.id).map(one => one.kind)); return kinds.has("handoff") && kinds.has("terminal-diff"); })();
+        const status = resultStatusOf(result === undefined
+            ? null
+            : { runId: result.id, role: result.role, outcome: result.outcome, verdict: proof?.verdict ?? null, reasons: proof?.reasons ?? [], accepted, review: reviewFacts, ...(noChangeRecord === undefined ? {} : { recordComplete: noChangeRecord }) }, result === undefined ? null : store.publicationForRun(result.id));
+        if (REVIEW_TOKENS.has(status.token) && retry !== null && review !== null) {
+            const code = status.token;
+            return answer(code, code === "reviewing" ? "running" : "waiting", status.label, status.detail, { action: retry.state === "retryable" ? "retry-review" : "open-result", review });
+        }
+        if (!accepted && proof?.verdict === "refuted")
+            return answer("proof-refuted", "waiting", status.label, `${status.detail} Review the evidence to correct it, or record an explicit acceptance.`, { action: "open-result", review });
+        if (!accepted && proof?.verdict === "short")
+            return answer("needs-verification", "waiting", status.label, `${status.detail} Open the result for the exact criteria still needing verification.`, { action: "open-result", review });
+        if (!accepted && proof === null && noChangeRecord !== true)
+            return answer("needs-verification", "waiting", status.label, status.detail, { action: "open-result", review });
+        return answer("complete", "terminal", status.label, review?.state === "succeeded" && review.attempt !== null && review.attempt > 1
+            ? `${status.detail} Its independent review succeeded on attempt ${review.attempt} of ${review.cap}.`
+            : status.detail, { action: "open-result", review });
+    }
+    if (task.state === "cancelled")
+        return answer("cancelled", "terminal", "Cancelled", "Nothing else will run for this task.");
+    if (task.state === "failed")
+        return answer("failed", "terminal", "Needs a retry", "The last attempt stopped; review its incident, then retry it.", { action: "retry-task" });
+    if (store.hasLiveClaim(ref.id, now))
+        return answer("running", "running", "Running now", "A worker owns the current live claim.");
+    if (task.state === "running")
+        return answer("vanished-run", "waiting", "Build vanished", "The task says running, but no current claim owns it; reconcile it before retrying.", { action: "retry-task" });
+    if (updateAdmissionPaused(store.raw()))
+        return answer("updating", "waiting", "Waiting for app update", UPDATE_PAUSED);
+    const local = taskReadinessBlocker(store, ref.id, now);
+    if (local?.code === "hold") {
+        if (local.ownerKind === "backoff") {
+            return answer("retry-scheduled", "retrying", "Retry scheduled", local.until === null ? "The failed attempt is backing off before retrying." : `The next attempt is eligible at ${local.until}.`, { nextAt: local.until });
+        }
+        if (local.ownerKind === "decision")
+            return answer("waiting-decision", "waiting", "Waiting on your answer", "An agent parked a question; answering it resumes the task.", { action: "answer-decision" });
+        if (local.ownerKind === "incident")
+            return answer("waiting-incident", "waiting", "Needs a retry", "An unresolved incident holds the next attempt.", { action: "retry-task" });
+        if (local.ownerKind === "stop")
+            return answer("stopped", "waiting", "Paused", `${local.message.replace(/^held:\s*/, "")}. The attempt's work is preserved; resuming that exact attempt lifts this pause.`, { action: "resume-run" });
+        return answer("held", "waiting", "On hold", local.message.replace(/^held:\s*/, ""), { action: local.ownerKind === "operator" ? "unhold" : "inspect-hold" });
+    }
+    if (local?.code === "dependency") {
+        const terminal = local.blockerState === "failed" || local.blockerState === "cancelled";
+        return terminal
+            ? answer("terminal-dependency", "waiting", "A required task did not finish", `${local.blockerId} ${local.blockerState === "cancelled" ? "was cancelled" : "failed"} before it finished.`, { action: "repair-dependency", blockerTaskId: local.blockerId })
+            : answer("waiting-dependency", "waiting", "Waiting for another task", `${local.blockerId} must finish before this task can start.`, { blockerTaskId: local.blockerId });
+    }
+    const role = dispatchRoleFor(store, ref.id, now);
+    const scope = store.getScope(taskId);
+    if (ref.repo === null)
+        return answer("needs-project", "waiting", "Needs a project", "Place this task in a repository before a worker can claim it.", { action: "place-task", role });
+    if (role !== "planner") {
+        if (scope === null)
+            return answer("needs-scope", "waiting", "Needs a scope", "Write the success contract or ask the planner to draft it.", { action: "write-scope", role });
+        if (scope.profileState === "unresolved")
+            return answer("needs-agent-profile", "waiting", "Needs an agent profile", scope.unresolvedReason ?? "Choose an available provider and model.", { action: "select-agent", role });
+        if (!scopeApprovedForDispatch(store, ref.id, now) || !approvalOf(scope).approved) {
+            return answer("needs-approval", "waiting", "Needs your approval", "Review and sign the current scope before a worker can claim it.", { action: "approve-scope", role });
+        }
+    }
+    const gap = missingCapability(store, ref.id, ref.repo, now);
+    if (gap !== null)
+        return answer("missing-requirement", "waiting", "Missing a requirement", gap, { action: "repair-capability", role });
+    const all = store.listRunners().filter(one => one.retiredAt === null);
+    const bound = all.filter(one => one.repos.includes(ref.repo));
+    const eligible = ref.assignedRunner === null ? bound : bound.filter(one => one.name === ref.assignedRunner);
+    if (eligible.length === 0) {
+        const detail = ref.assignedRunner === null
+            ? all.length === 0
+                ? "This project has not been connected to a builder yet."
+                : "Your connected builders do not include this project yet."
+            : `This task is assigned to ${ref.assignedRunner}, but that builder is not connected to this project.`;
+        return answer("no-worker-registered", "waiting", "Builder not connected", detail, { action: "start-worker", role });
+    }
+    const alive = eligible.filter(one => isAlive(one, now));
+    if (alive.length === 0) {
+        return answer("no-worker-online", "waiting", "Builder disconnected", `${eligible.length === 1 ? "The builder for this project has" : "All builders for this project have"} stopped checking in. This task starts automatically when ${eligible.length === 1 ? "it reconnects" : "one reconnects"}.`, { action: "start-worker", role });
+    }
+    const available = alive.filter(one => store.liveClaimCount(one.name, now) < one.capacity);
+    if (available.length === 0)
+        return answer("worker-at-capacity", "retrying", "Waiting for worker capacity", "Every eligible worker is busy; this task starts when a slot is released.", { role });
+    const profile = approvedProfile(scope);
+    if (profile !== null) {
+        const exhausted = available.map(one => store.readQuotaState(one.name, profile.provider, profile.model, now)).filter(one => one?.state === "exhausted");
+        if (exhausted.length === available.length) {
+            const resets = exhausted.map(one => one?.resetAt ?? null).filter((one) => one !== null).sort();
+            const nextAt = resets[0] ?? null;
+            return answer("provider-quota", "retrying", "Provider quota exhausted", nextAt === null ? "The provider has not supplied a reset time; this needs operator attention." : `The next recorded reset is ${nextAt}.`, { action: nextAt === null ? "select-agent" : null, nextAt, role });
+        }
+    }
+    const openDecisions = store.countUnanswered();
+    if (openDecisions >= DEFAULT_MAX_OPEN_DECISIONS && (role === "planner" || ref.parkRate > 0)) {
+        return answer("waiting-decision", "waiting", "Decision queue is full", `${openDecisions} decisions already wait; answer some before this task may add another.`, { action: "answer-decision", role });
+    }
+    if (role === "planner") {
+        // The filed request's own gate (contract handoff, task 1): a request
+        // the planner could not be given whole is refused before spend, and
+        // this is where the task page says so.
+        const sourceProblem = plannerSourceProblemOf(store, taskId);
+        if (sourceProblem !== null)
+            return answer("planner-source", "waiting", "The filed request cannot be planned as filed", sourceProblem, { action: "write-scope", role });
+        return answer("planning-ready", "retrying", "Planner ready", "An eligible worker can draft the scope on the next pass.", { role });
+    }
+    if (role === "scout")
+        return answer("scouting-ready", "retrying", "Scout ready", "An eligible worker can produce the report on the next pass.", { role });
+    return answer("ready", "retrying", "Ready to run", "An eligible worker has capacity and every dispatch gate currently passes.", { role });
+}
+export function diagnosisIsDispatchable(diagnosis) {
+    return diagnosis?.code === "ready" || diagnosis?.code === "planning-ready" || diagnosis?.code === "scouting-ready";
+}
+/** Attach the same lifecycle answer to the bounded fleet snapshot used by
+ * both direct chat and the long-running mate. */
+export function withDispatchDiagnoses(store, snapshot, now) {
+    return {
+        ...snapshot,
+        tasks: snapshot.tasks.map(one => ({ ...one, dispatch: diagnoseTaskDispatch(store, one.id, now) })),
+    };
+}

package/dist/dispose.d.ts

@@ -0,0 +1,161 @@
+import { type FailureClass } from "./claim.js";
+import type { BuildResult } from "./builder.js";
+import type { Store } from "./store.js";
+import { type ProofVerdict } from "./proof.js";
+/**
+ * Which road is disposing. 'tick' = the unattended loop: full task
+ * completion, strikes, quota, publication. 'standalone' = the one-off
+ * `build` command: run records only — no task state, no strikes, no
+ * publication (its historical shape). The held road reuses 'tick' —
+ * an attended session is still the task's real attempt.
+ */
+export type DisposePolicy = "tick" | "standalone" | "continuation";
+export type DisposeContext = {
+    store: Store;
+    policy: DisposePolicy;
+    /** The lease this attempt ran under; undefined only on the standalone road. */
+    leaseId: string | undefined;
+    runId: number;
+    taskId: string;
+    taskRef: number;
+    runner: string;
+    /** The canonical repo, for the publication grant lookup (tick policy). */
+    repo: string;
+    branch: string;
+    /** task_ref.origin — the publication selector consults it. */
+    origin: string;
+    provider: string;
+    model: string | null;
+    /** Where the attempt's tree lives — failure records name it. */
+    worktreePath: string;
+    /** The same evidence root the builder used. */
+    evidenceRoot?: string;
+    clock: () => Date;
+};
+export type Disposition = {
+    kind: "parked";
+    decisionId: number;
+} | {
+    kind: "park-fenced";
+} | {
+    kind: "disowned";
+} | {
+    kind: "built";
+    committed: boolean;
+    noChange: boolean;
+} | {
+    kind: "built-fenced";
+} | {
+    kind: "skipped";
+    reason: "unapproved" | "scope-changed";
+} | {
+    kind: "fenced";
+} | {
+    kind: "malformed";
+    sealed: boolean;
+} | {
+    kind: "failed";
+    failureClass: FailureClass;
+    disposition: string | null;
+    strikes: number | null;
+    sealed: boolean;
+}
+/** The standalone road's simple record: outcome written, nothing else. */
+ | {
+    kind: "recorded";
+    outcome: "failed" | "refused";
+}
+/** v52: an operator's stop won before terminal settlement — the attempt
+ * is sealed as interrupted with its work preserved, its own stop
+ * settled, no strike and no retry. `stopRun` names the exact stopped
+ * run (this one, or the owning ancestor whose stop it inherited). */
+ | {
+    kind: "stopped";
+    stopRun: number;
+    requeued: boolean;
+} | {
+    kind: "invariant";
+    reason: string;
+};
+/** Compatibility for historical integrations: finished work is handed to the
+ * lead. No model review is requested and no signed history is rewritten. */
+export declare function maybeRequestAutoReview(_store: Store, _repo: string, _runId: number, _committed: boolean, _noChange: boolean, _now: Date): void;
+export declare function disposeBuildOutcome(context: DisposeContext, result: BuildResult): Disposition;
+/**
+ * The stale-approval HOLD, shared by the post-build disposition above and
+ * the tick's pre-admission refusal (v48 integrity): a pre-routing row
+ * whose sealed profile no longer matches what would resolve is refused
+ * BEFORE any run row exists — held under the backoff the approval door
+ * lifts, paged once per approval — so the fail-closed admission never
+ * turns into a refusal every pass.
+ */
+export declare function holdStaleApproval(store: Store, args: {
+    taskRef: number;
+    taskId: string;
+    message: string;
+}, now: Date): void;
+/** The public, envelope-documented name for each stop — distinct from the
+ * store's own short `repair_chain.outcome` word (the DB enum is a
+ * different namespace; these are the CLI/console-facing reason tokens,
+ * registered in envelope.ts's DOCUMENTED_REASONS). */
+export type RepairStopReason = "repair-attempts-spent" | "repair-no-progress" | "repair-refused-integrity";
+/**
+ * The chain's happy exit (v40): the instant one of its own attempts
+ * reaches `verified` or `attested`, the chain is done. Checked at every
+ * completed build's own verdict-save point — not only after a review —
+ * since a review can never UPGRADE a verdict past what `adjudicate`
+ * already found (foldReview's monotonicity), so only the structural save
+ * can ever produce one of these two words.
+ */
+export declare function maybeSettleRepairChain(store: Store, taskId: string, verdict: ProofVerdict, now: Date): void;
+/**
+ * Run the approved gate again on the SAME commit (v70): a new attempt whose
+ * prepared candidate is the last attempt's head. The machine checks the
+ * commit out (no agent), seals a fresh diff, receipt and proof, and the
+ * ordinary review follows. Used by `task regate` (an operator's yes) and by
+ * the automatic single rerun after a failure the change did not cause.
+ */
+export type RegateRefusal = "no-task" | "no-attempt" | "accepted-result" | "published" | "claimed" | "not-approved" | "not-rejected";
+export declare function regateTask(store: Store, taskId: string, now: Date, approval: {
+    kind: "operator";
+    name: string;
+    token: string;
+} | {
+    kind: "mode";
+    name: string;
+    modeDigest: string;
+}): {
+    ok: true;
+    run: number;
+    head: string;
+} | {
+    ok: false;
+    reason: RegateRefusal;
+    message: string;
+};
+export type RepairTrigger = {
+    kind: "drafted";
+    draftTaskId: string;
+    attempt: number;
+    approved: boolean;
+} | {
+    kind: "stopped";
+    reason: RepairStopReason;
+} | {
+    kind: "none";
+};
+/**
+ * An explicitly requested repair from saved check or historical review findings.
+ * Automatic calls are retired. Composes at
+ * most one durable revision draft naming exactly the unmet criterion ids,
+ * inheriting the source scope and rubric verbatim — or settles the chain
+ * at one of its four independent stops (integrity, no-progress, attempts
+ * cap; the fourth — existing spend/run rails — is the ordinary tick's own
+ * job once a mode-approved draft dispatches as a normal builder run).
+ *
+ * Never dispatches anything itself: a mode-authorized draft is
+ * auto-APPROVED here, but still builds through the ordinary tick, under
+ * the ordinary rails and strikes — this function only ever composes a
+ * task and, at most, one scope approval.
+ */
+export declare function maybeTriggerRepair(store: Store, repo: string, evidenceRoot: string, sourceRunId: number, verdict: ProofVerdict, now: Date, cause?: "review" | "verification", automatic?: boolean): RepairTrigger;