toolroll 0.9.98 → 0.9.100

package/dist/store.d.ts

@@ -3,6 +3,7 @@ import { type WritesMode } from "./writes-mode.js";
 import { type CheckAccess } from "./check-access.js";
 import { type ProjectSandbox } from "./project-sandbox.js";
 import type { FencePolicy } from "./agent-fence.js";
+import type { ChatMessageOutcome } from "./chat-message-states.js";
 import { type NetworkProfile, type ProjectNetwork, type RunNetworkRecord } from "./egress.js";
 import { type AcpLaunch } from "./acp-attest.js";
 import { type CheckStamp, type StampReading } from "./check-stamp.js";
@@ -1805,8 +1806,8 @@ export type TelegramConversation = {
     nextAttemptAt: string | null;
     session: number | null;
     turn: number | null;
-    /** A short outcome word: answered, replayed, refused:<reason>, failed:<reason>, revoked, … */
-    outcome: string | null;
+    /** Its result word (chat-message-states.ts); a row written by an older version may hold a word no longer listed. */
+    outcome: ChatMessageOutcome | null;
     replyMessageId: string | null;
     createdAt: string;
     startedAt: string | null;
@@ -8552,3 +8553,61 @@ export declare function setLeadTurnRoute(store: Store, turn: number, generation:
  * reply asked one, less than LEAD_ASK_TTL_MS ago. Conservative on purpose: the quick-answer router (§8) keeps such a
  * message on the main model. */
 export declare function leadAskAwaitsAnswer(store: Store, thread: number, now: Date): boolean;
+/** When an invite can still be used: not revoked, not consumed, not expired, and fewer than ten admitted attempts.
+ * One bound parameter: the current time as an ISO string. Every read and write that asks "is this invite usable" uses
+ * this fragment, so the join page, the attempt counter, the join terms and the open-invites list agree. */
+export declare const INVITE_USABLE_SQL = "revoked_at IS NULL AND consumed_at IS NULL AND expires_at > ? AND attempts < 10";
+/** How long a confirm step stays open: the Yes and Cancel buttons shown after a first tap, in every chat app. */
+export declare const CONFIRM_TTL_MS: number;
+/**
+ * Withdraw task approvals: the one statement every withdrawal runs. It always clears approved_at, approved_by,
+ * approved_digest and approved_profile_json, and sets approval_basis to `basisAfter`. The callers differ in what else
+ * they clear, so that stays theirs to say: `clearRoute` clears approved_route_json, `clearModeDigest` clears
+ * mode_digest. `where` is the caller's own WHERE clause (starting with WHERE) with its bound values; it is always a
+ * fixed string in our code, never built from input. The check and the write are one statement. Returns the rows changed.
+ */
+export declare function withdrawApproval(store: Store, rows: {
+    where: string;
+    args: readonly (string | number | null)[];
+}, writes: {
+    basisAfter: "password" | null;
+    clearRoute: boolean;
+    clearModeDigest: boolean;
+}): number;
+/**
+ * Whether `requeueTask` would run this task again, read without writing anything: the same checks in the same order,
+ * so the requeue itself and every sentence that offers it agree. Read inside the caller's transaction.
+ */
+export declare function requeueEligibility(store: Store, taskId: string, now: Date): {
+    ok: true;
+    taskRef: number;
+    incidents: number[];
+    state: string;
+    rejectedRun: number | null;
+} | {
+    ok: false;
+    reason: "unknown-task" | "not-stalled" | "claimed" | "accepted-result" | "published" | "archived";
+};
+/** The three closed states (docs/plans/closed-task-claims.md). */
+export type ClosedState = Extract<TaskState, "done" | "failed" | "cancelled">;
+export declare function isClosedState(state: string): state is ClosedState;
+/**
+ * What this database knows about the task behind a reference, for a claim: a built-in task's row and state, a
+ * built-in reference with no task row, or a task of another backend (its state lives in that tracker, not here).
+ * Read inside the caller's transaction, so the answer holds until it commits.
+ */
+export declare function taskStateForClaim(store: Store, taskRef: number): {
+    kind: "built-in";
+    state: TaskState;
+} | {
+    kind: "missing";
+} | {
+    kind: "outside";
+};
+/**
+ * Check cleanup's proof (acp-check.ts settleChecks, claim.ts acquireForCheckCleanup): the task reference of check
+ * `checkId` when that check belongs to `runner`, has finished (passed or failed) and is not yet settled, is held right
+ * now by exactly this cleanup `attempt`, and is bound to the built-in task named from the check row's own id. Null
+ * otherwise. Every fact comes from rows only code writes; read inside the caller's transaction.
+ */
+export declare function checkCleanupTaskOf(store: Store, checkId: number, runner: string, attempt: string, now: Date): number | null;

package/dist/store.js

@@ -129,8 +129,10 @@ import { configBase, envValue, namedPath } from "./names.js";
 import { PULL_REQUEST_SCHEMA } from "./pull-request-schema.js";
 import { chatTurnAmountOf, combineReportedModels, providerTurnsOf, reportedCostUsdOf, reportedModelOf, runAmountOf } from "./reported-usage.js";
 import { usageOf } from "./run-efficiency.js";
+import { endedInterrupted, wasInterrupted } from "./run-ending.js";
 import { YOUIYOUX_FILED_VIA } from "./contracts/youiyoux-request.js";
 import { cardShowsScope, cardTermsDigest, shownTermsDigest } from "./chat-terms.js";
+import { markedRunningSql, moveTask } from "./task-moves.js";
 // PR #263 follow-up: the built-ins the Store money seal uses, captured as this module is evaluated, so code that later
 // replaces `Object.defineProperty` and the like can't fool the seal or the lock (lockStoreMoneyMethods refuses when
 // they've been replaced). The four sealed method references are recorded once, at the seal, in SEALED_MONEY_METHODS.
@@ -6768,10 +6770,7 @@ export class Store {
                     return { ok: true };
                 }
                 const prior = this.db.prepare("SELECT state FROM task WHERE id = ?").get(id);
-                const { changes } = this.db
-                    .prepare("UPDATE task SET state = ?, updated_at = ? WHERE id = ?")
-                    .run(state, now.toISOString(), id);
-                if (Number(changes) === 0)
+                if (!moveTask(this.db, id, "set", now, state))
                     return { ok: false, reason: "unknown-task" };
                 if (state === "done" && prior?.["state"] !== "done") {
                     const done = this.lookupRef(id);
@@ -7588,9 +7587,7 @@ export class Store {
                 .prepare(`UPDATE external_mirror SET dispatch_ok = 1, close_generation = NULL, reopened_by = ?, reopened_at = ?
             WHERE local_task_id = ?`)
                 .run(by, now.toISOString(), localTaskId);
-            this.db
-                .prepare("UPDATE task SET state = 'queued', updated_at = ? WHERE id = ?")
-                .run(now.toISOString(), localTaskId);
+            moveTask(this.db, localTaskId, "reopen", now);
             this.noteLifecycle({ taskRef, kind: "task-queued", identity: `t${taskRef}`, subject: "Back in the queue", body: "The tracker item is open again; another attempt can start.", link: chatControlHref("task", localTaskId) }, now);
             this.bumpWake();
             return { ok: true };
@@ -8514,10 +8511,7 @@ export class Store {
                              WHERE tr.backend = 'built-in' AND tr.external_id = task_scope.task_id
                                AND claim.released_at IS NULL AND claim.expires_at > ?)`;
         const demoted = this.db.prepare(`SELECT task_id FROM task_scope ${demotable}`).all(digest, now.toISOString()).map(row => String(row["task_id"]));
-        this.db
-            .prepare(`UPDATE task_scope SET approved_at = NULL, approved_by = NULL, approved_digest = NULL,
-                approved_profile_json = NULL, approval_basis = 'password', mode_digest = NULL ${demotable}`)
-            .run(digest, now.toISOString());
+        withdrawApproval(this, { where: demotable, args: [digest, now.toISOString()] }, { basisAfter: "password", clearRoute: false, clearModeDigest: true });
         this.db.prepare("DELETE FROM plan_authorization WHERE basis = 'grant' AND mode_digest = ?").run(digest);
         for (const taskId of demoted) {
             const ref = this.lookupRef(taskId);
@@ -8562,12 +8556,7 @@ export class Store {
             .prepare(`SELECT task_id FROM task_scope ${demotable}`)
             .all(...demotableArgs)
             .map(row => String(row["task_id"]));
-        this.db
-            .prepare(`UPDATE task_scope
-            SET approved_at = NULL, approved_by = NULL, approved_digest = NULL,
-                approved_profile_json = NULL, approval_basis = 'password', mode_digest = NULL
-          ${demotable}`)
-            .run(...demotableArgs);
+        withdrawApproval(this, { where: demotable, args: demotableArgs }, { basisAfter: "password", clearRoute: false, clearModeDigest: true });
         for (const taskId of demoted) {
             const ref = this.lookupRef(taskId);
             if (ref === null)
@@ -9263,7 +9252,7 @@ export class Store {
      * false: the disclosure boundary is one indistinguishable page (D6). */
     inviteIsLive(tokenValue, now) {
         const row = this.db
-            .prepare("SELECT 1 AS hit FROM invite WHERE token_hash = ? AND revoked_at IS NULL AND consumed_at IS NULL AND expires_at > ? AND attempts < 10")
+            .prepare(`SELECT 1 AS hit FROM invite WHERE token_hash = ? AND ${INVITE_USABLE_SQL}`)
             .get(createHash("sha256").update(tokenValue, "utf8").digest("hex"), now.toISOString());
         return row !== undefined;
     }
@@ -9276,7 +9265,7 @@ export class Store {
     admitInviteAttempt(tokenValue, now) {
         const row = this.db
             .prepare(`UPDATE invite SET attempts = attempts + 1
-          WHERE token_hash = ? AND revoked_at IS NULL AND consumed_at IS NULL AND expires_at > ? AND attempts < 10
+          WHERE token_hash = ? AND ${INVITE_USABLE_SQL}
           RETURNING role, minted_by`)
             .get(createHash("sha256").update(tokenValue, "utf8").digest("hex"), now.toISOString());
         return row === undefined
@@ -9297,6 +9286,8 @@ export class Store {
             // concurrent join must read as 'gone' — the indistinguishable dead
             // shape — never as a name collision that discloses the winner.
             const hash = createHash("sha256").update(args.tokenValue, "utf8").digest("hex");
+            // Not INVITE_USABLE_SQL on purpose: admitInviteAttempt has already counted this submission, so the tenth
+            // admitted attempt arrives here with attempts = 10 and must still be able to join.
             const live = this.db
                 .prepare("SELECT 1 AS hit FROM invite WHERE token_hash = ? AND revoked_at IS NULL AND consumed_at IS NULL AND expires_at > ?")
                 .get(hash, now.toISOString());
@@ -9609,7 +9600,7 @@ export class Store {
      * never leave the store; an invite is named by its row id. */
     openInvites(now) {
         return this.db
-            .prepare("SELECT id, role, minted_by, minted_at, expires_at, attempts, projects_json FROM invite WHERE revoked_at IS NULL AND consumed_at IS NULL AND expires_at > ? ORDER BY id")
+            .prepare(`SELECT id, role, minted_by, minted_at, expires_at, attempts, projects_json FROM invite WHERE ${INVITE_USABLE_SQL} ORDER BY id`)
             .all(now.toISOString())
             .map(row => ({
             id: Number(row["id"]),
@@ -11930,53 +11921,11 @@ export class Store {
      * is still the one just approved, read inside this transaction ("moved" otherwise). */
     expect) {
         return this.transact(() => {
-            const ref = this.db
-                .prepare("SELECT id FROM task_ref WHERE backend = ? AND external_id = ?")
-                .get(BUILT_IN, taskId);
-            if (ref === undefined)
-                return { ok: false, reason: "unknown-task" };
-            const taskRef = Number(ref["id"]);
-            // A put-away task (v145) is restored before it runs again.
-            if (refArchived(this, taskRef))
-                return { ok: false, reason: "archived" };
-            const stamp = now.toISOString();
-            if (this.hasLiveClaim(taskRef, now))
-                return { ok: false, reason: "claimed" };
-            const incidents = this.db
-                .prepare(`SELECT incident.id FROM incident
-           JOIN run ON run.id = incident.run
-           WHERE run.task_ref = ? AND incident.resolved_at IS NULL`)
-                .all(taskRef)
-                .map(row => Number(row["id"]));
-            const state = String(this.db.prepare("SELECT state FROM task WHERE id = ?").get(taskId)?.["state"]);
-            // A finished task whose last result was rejected — a failed gate, a
-            // contradicting review, a refuted proof — runs again on the SAME
-            // filing: the branch keeps the earlier attempt, the sealed diff still
-            // spans from the original base, and a corrected candidate needs a
-            // re-scope, not a new task. An accepted or published result is final
-            // here; it is revised through a revision or its pull request.
-            let rejectedRun = null;
-            if (state === "done") {
-                // The guards hold whether or not an incident is open: a finished
-                // task's last result decides, and an accepted or published one is
-                // never reopened by resolving an incident beside it.
-                const last = this.db
-                    .prepare("SELECT id FROM run WHERE task_ref = ? AND role = 'builder' AND finished_at IS NOT NULL ORDER BY id DESC LIMIT 1")
-                    .get(taskRef);
-                if (last === undefined) {
-                    if (incidents.length === 0)
-                        return { ok: false, reason: "not-stalled" };
-                }
-                else {
-                    rejectedRun = Number(last["id"]);
-                    const final = this.finalResultReason(rejectedRun);
-                    if (final !== null)
-                        return { ok: false, reason: final };
-                }
-            }
-            else if (incidents.length === 0 && state !== "failed") {
-                return { ok: false, reason: "not-stalled" };
-            }
+            // Who may run again is one read, shared with the claim refusal's words (requeueEligibility, end of file).
+            const eligible = requeueEligibility(this, taskId, now);
+            if (!eligible.ok)
+                return eligible;
+            const { taskRef, incidents, state, rejectedRun } = eligible;
             if (expect !== undefined) {
                 const scope = this.db.prepare("SELECT digest, approved_digest FROM task_scope WHERE task_id = ?").get(taskId);
                 if (state !== "done" || rejectedRun !== expect.run || scope === undefined || String(scope["digest"]) !== expect.scopeDigest ||
@@ -11990,9 +11939,7 @@ export class Store {
             // A person's Retry is a new person act: a fast start gets a new start window. A machine's never does.
             if (!machineActing())
                 this.db.prepare("UPDATE task_ref SET fast_start_until = ? WHERE id = ? AND fast_start_until IS NOT NULL").run(new Date(now.getTime() + 30 * 60_000).toISOString(), taskRef);
-            this.db
-                .prepare("UPDATE task SET state = 'queued', updated_at = ? WHERE id = ? AND state IN ('failed','queued','done')")
-                .run(stamp, taskId);
+            moveTask(this.db, taskId, "retry", now);
             // The stall's page is answered by the act itself.
             this.resolveEpisode(`stalled:${taskRef}`, now);
             this.noteLifecycle({
@@ -13511,7 +13458,7 @@ export class Store {
         if (taskId === null)
             return;
         const role = String(prior["role"]);
-        const stopped = result.outcome === "failed" && result.reason === "interrupted" && this.stopOf(id) !== null;
+        const stopped = wasInterrupted(result) && this.stopOf(id) !== null;
         if (role === "builder") {
             if (stopped) {
                 this.noteLifecycle({ taskRef, run: id, kind: "run-stopped", identity: `r${id}`, subject: `Build #${id} stopped`, body: "Its work is preserved. Resume this attempt from the task page when ready.", link: chatControlHref("recovery", taskId) }, now);
@@ -14079,7 +14026,7 @@ export class Store {
             return `run #${parent.id} left its draft in ${parent.worktree ?? "no worktree"} on ${parent.branch ?? "no branch"}, not ${run.worktree} on ${run.branch}`;
         // An attempt that stopped before its handoff (run 2085) left its work in
         // place for exactly this: the retry inherits it, like an interrupted one's.
-        const interrupted = parent.outcome === null || (parent.outcome === "failed" && (parent.reason === "interrupted" || parent.reason === "no-handoff"));
+        const interrupted = parent.outcome === null || endedInterrupted(parent) || (parent.outcome === "failed" && parent.reason === "no-handoff");
         if (!interrupted)
             return `run #${parent.id} ended as ${parent.outcome}${parent.reason === null ? "" : ` (${parent.reason})`} — only an interrupted attempt's draft is recovered`;
         if (parent.outcome === null && this.liveClaimByLease(parent.leaseId, now) !== null)
@@ -18731,7 +18678,7 @@ export class Store {
         const q = this.db
             .prepare(`SELECT
            SUM(CASE WHEN task.state = 'queued' THEN 1 ELSE 0 END) AS queued,
-           SUM(CASE WHEN task.state = 'running' THEN 1 ELSE 0 END) AS running
+           SUM(CASE WHEN ${markedRunningSql} THEN 1 ELSE 0 END) AS running
            FROM task JOIN task_ref ON task_ref.backend = 'built-in' AND task_ref.external_id = task.id
           WHERE task_ref.repo = ? AND NOT EXISTS (SELECT 1 FROM task_archive WHERE task_archive.task_ref = task_ref.id)`)
             .get(repo);
@@ -21761,7 +21708,7 @@ export function serializeReleaseTerms(terms) {
 }
 // ---- one approval per release: the authority record (release-once.md, part 1) --------------------------------------
 export { LIVE_RELEASE_STATES, belongsToRelease, newestReleaseGeneration, outstandingReleaseOperations, releaseAuthority, releaseAuthorityOfTask, releaseCarries, releaseCarryTo, releaseOperation, releaseOperations, releaseSealProblem, } from "./release-authority.js";
-import { LIVE_RELEASE_STATES, autoEvidenceOf, belongsToRelease, newestReleaseGeneration, outstandingReleaseOperations, releaseAuthority, releaseCarryTo, releaseOperation, releaseSealProblem, } from "./release-authority.js";
+import { LIVE_RELEASE_STATES, autoEvidenceOf, belongsToRelease, releaseExpiredAt, newestReleaseGeneration, outstandingReleaseOperations, releaseAuthority, releaseCarryTo, releaseOperation, releaseSealProblem, } from "./release-authority.js";
 /**
  * Open a release's authority for a person's seal of its terms (inside the seal's transaction): the next generation,
  * superseding the live one. False when it can't (releaseSealProblem), which refuses the seal.
@@ -21836,7 +21783,7 @@ export function reserveRelease(store, input) {
             return { ok: false, why: "This release still waits for GitHub CI. Resume it with `toolroll release`." };
         const at = input.now.toISOString();
         // Expiry stops every live state; an operation already reserved settles only through reconciliation.
-        if (a.expiresAt <= at)
+        if (releaseExpiredAt(a, input.now))
             return { ok: false, why: "The release approval expired." };
         if (a.tipTask !== input.taskId || a.tipSha !== input.candidate)
             return { ok: false, why: `Task ${input.taskId} is not the release's current commit.` };
@@ -21882,7 +21829,7 @@ export function runReleaseOperation(store, id, epoch, now, issuer = currentRelea
         if (releaseCiRunningOf(store, op.taskId) !== null)
             return false;
         // Past the expiry nothing new starts; the reserved operation is settled by reconciliation instead.
-        if (a.expiresAt <= now.toISOString())
+        if (releaseExpiredAt(a, now))
             return false;
         // The lease that reserved it still holds (a person's direct deploy: still no coordinator holding the release), and
         // the live-release predicate still accepts it, at this moment (review round 1).
@@ -22644,7 +22591,7 @@ export function restoreTaskFamily(store, taskId, by, now, guard) {
  */
 export function liveInviteTerms(store, tokenValue, now) {
     const row = store.handle
-        .prepare("SELECT role, minted_by, expires_at, projects_json FROM invite WHERE token_hash = ? AND revoked_at IS NULL AND consumed_at IS NULL AND expires_at > ? AND attempts < 10")
+        .prepare(`SELECT role, minted_by, expires_at, projects_json FROM invite WHERE token_hash = ? AND ${INVITE_USABLE_SQL}`)
         .get(createHash("sha256").update(tokenValue, "utf8").digest("hex"), now.toISOString());
     if (row === undefined)
         return null;
@@ -23249,3 +23196,106 @@ export function leadAskAwaitsAnswer(store, thread, now) {
       WHERE m.id = (SELECT MAX(id) FROM lead_message WHERE thread = ? AND role = 'assistant') AND t.state = 'answered'`).get(thread);
     return row !== undefined && Date.parse(String(row["at"])) + LEAD_ASK_TTL_MS > now.getTime();
 }
+/** When an invite can still be used: not revoked, not consumed, not expired, and fewer than ten admitted attempts.
+ * One bound parameter: the current time as an ISO string. Every read and write that asks "is this invite usable" uses
+ * this fragment, so the join page, the attempt counter, the join terms and the open-invites list agree. */
+export const INVITE_USABLE_SQL = "revoked_at IS NULL AND consumed_at IS NULL AND expires_at > ? AND attempts < 10";
+/** How long a confirm step stays open: the Yes and Cancel buttons shown after a first tap, in every chat app. */
+export const CONFIRM_TTL_MS = 10 * 60_000;
+/**
+ * Withdraw task approvals: the one statement every withdrawal runs. It always clears approved_at, approved_by,
+ * approved_digest and approved_profile_json, and sets approval_basis to `basisAfter`. The callers differ in what else
+ * they clear, so that stays theirs to say: `clearRoute` clears approved_route_json, `clearModeDigest` clears
+ * mode_digest. `where` is the caller's own WHERE clause (starting with WHERE) with its bound values; it is always a
+ * fixed string in our code, never built from input. The check and the write are one statement. Returns the rows changed.
+ */
+export function withdrawApproval(store, rows, writes) {
+    const set = ["approved_at = NULL", "approved_by = NULL", "approved_digest = NULL", "approved_profile_json = NULL",
+        ...(writes.clearRoute ? ["approved_route_json = NULL"] : []), "approval_basis = ?", ...(writes.clearModeDigest ? ["mode_digest = NULL"] : [])];
+    return Number(store.handle.prepare(`UPDATE task_scope SET ${set.join(", ")} ${rows.where}`).run(writes.basisAfter, ...rows.args).changes);
+}
+/**
+ * Whether `requeueTask` would run this task again, read without writing anything: the same checks in the same order,
+ * so the requeue itself and every sentence that offers it agree. Read inside the caller's transaction.
+ */
+export function requeueEligibility(store, taskId, now) {
+    const db = store.handle;
+    const ref = db.prepare("SELECT id FROM task_ref WHERE backend = ? AND external_id = ?").get(BUILT_IN, taskId);
+    if (ref === undefined)
+        return { ok: false, reason: "unknown-task" };
+    const taskRef = Number(ref["id"]);
+    // A put-away task (v145) is restored before it runs again.
+    if (refArchived(store, taskRef))
+        return { ok: false, reason: "archived" };
+    if (store.hasLiveClaim(taskRef, now))
+        return { ok: false, reason: "claimed" };
+    const incidents = db
+        .prepare(`SELECT incident.id FROM incident
+       JOIN run ON run.id = incident.run
+       WHERE run.task_ref = ? AND incident.resolved_at IS NULL`)
+        .all(taskRef)
+        .map(row => Number(row["id"]));
+    const state = String(db.prepare("SELECT state FROM task WHERE id = ?").get(taskId)?.["state"]);
+    // A finished task whose last result was rejected — a failed gate, a
+    // contradicting review, a refuted proof — runs again on the SAME
+    // filing: the branch keeps the earlier attempt, the sealed diff still
+    // spans from the original base, and a corrected candidate needs a
+    // re-scope, not a new task. An accepted or published result is final
+    // here; it is revised through a revision or its pull request.
+    let rejectedRun = null;
+    if (state === "done") {
+        // The guards hold whether or not an incident is open: a finished
+        // task's last result decides, and an accepted or published one is
+        // never reopened by resolving an incident beside it.
+        const last = db
+            .prepare("SELECT id FROM run WHERE task_ref = ? AND role = 'builder' AND finished_at IS NOT NULL ORDER BY id DESC LIMIT 1")
+            .get(taskRef);
+        if (last === undefined) {
+            if (incidents.length === 0)
+                return { ok: false, reason: "not-stalled" };
+        }
+        else {
+            rejectedRun = Number(last["id"]);
+            const final = store.finalResultReason(rejectedRun);
+            if (final !== null)
+                return { ok: false, reason: final };
+        }
+    }
+    else if (incidents.length === 0 && state !== "failed") {
+        return { ok: false, reason: "not-stalled" };
+    }
+    return { ok: true, taskRef, incidents, state, rejectedRun };
+}
+export function isClosedState(state) {
+    return state === "done" || state === "failed" || state === "cancelled";
+}
+/**
+ * What this database knows about the task behind a reference, for a claim: a built-in task's row and state, a
+ * built-in reference with no task row, or a task of another backend (its state lives in that tracker, not here).
+ * Read inside the caller's transaction, so the answer holds until it commits.
+ */
+export function taskStateForClaim(store, taskRef) {
+    const row = store.handle.prepare(`SELECT task_ref.backend AS backend, task.state AS state FROM task_ref
+    LEFT JOIN task ON task.id = task_ref.external_id AND task_ref.backend = ?
+    WHERE task_ref.id = ?`).get(BUILT_IN, taskRef);
+    if (row === undefined)
+        return { kind: "missing" };
+    if (String(row["backend"]) !== BUILT_IN)
+        return { kind: "outside" };
+    if (row["state"] === null || row["state"] === undefined)
+        return { kind: "missing" };
+    return { kind: "built-in", state: String(row["state"]) };
+}
+/**
+ * Check cleanup's proof (acp-check.ts settleChecks, claim.ts acquireForCheckCleanup): the task reference of check
+ * `checkId` when that check belongs to `runner`, has finished (passed or failed) and is not yet settled, is held right
+ * now by exactly this cleanup `attempt`, and is bound to the built-in task named from the check row's own id. Null
+ * otherwise. Every fact comes from rows only code writes; read inside the caller's transaction.
+ */
+export function checkCleanupTaskOf(store, checkId, runner, attempt, now) {
+    const row = store.handle.prepare(`SELECT r.task_ref AS ref FROM acp_check_request r
+    JOIN task_ref t ON t.id = r.task_ref AND t.backend = ? AND t.external_id = 'agent-check-' || r.id
+    WHERE r.id = ? AND r.runner = ? AND r.state IN ('passed','failed') AND r.settled_at IS NULL
+      AND r.settle_by = ? AND r.settle_until > ?`).get(BUILT_IN, checkId, runner, attempt, now.toISOString());
+    return row === undefined ? null : Number(row["ref"]);
+}

package/dist/subagent-question.js

@@ -11,7 +11,7 @@
  * the person it was asked of. Answered anywhere, every button retires.
  */
 import { randomBytes } from "node:crypto";
-import { partContent, savedChatPart } from "./chat-delivery-state.js";
+import { partContent } from "./chat-delivery-state.js";
 import { answerSubagentQuestion } from "./subagent-work.js";
 import { labelOf } from "./subagent-admin.js";
 import { telegramButton } from "./contracts/telegram-callback.js";
@@ -97,12 +97,14 @@ export function chatQuestionButtons(state, part, now) {
     return state.prepare("SELECT token,choice FROM chat_question_action WHERE provider=:provider AND part=? AND consumed IS NULL AND expires>? ORDER BY rowid").all(part, now.toISOString())
         .map(one => ({ token: String(one.token), label: (labels.get(one.choice ?? "") ?? IN_WORDS).slice(0, 75), words: one.choice === null }));
 }
-/** Show the tapped notice again with the answer, and without its buttons. */
-function repaint(state, part, event, line) {
+/** Show the tapped notice again with the answer, and without its buttons. A notice that was dropped isn't brought back:
+ * the line goes as a new message. */
+function repaint(state, part, event, line, now) {
     const row = state.prepare("SELECT payload FROM chat_part WHERE provider=:provider AND id=?").get(part);
     const before = row === undefined ? { text: "" } : partContent(String(row["payload"]));
     const content = { text: `${before.text}\n\n${line}`.slice(0, 3400), edit: event.ts, ...(before.link === undefined ? {} : { link: before.link }), ...(before.channel === undefined ? {} : { channel: before.channel }) };
-    state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE provider=:provider AND id=?").run(savedChatPart(content), part);
+    if (!state.repaint(part, content))
+        state.plan(event.id, [{ text: line }], now);
 }
 /** A tapped question button, inside the action's transaction; false when the token isn't one. */
 export function applyChatQuestionTap(options, event, binding, token, now) {
@@ -120,7 +122,7 @@ export function applyChatQuestionTap(options, event, binding, token, now) {
     const question = store.subagentQuestion(questionId);
     if (action["consumed"] !== null || String(action["expires"]) <= now.toISOString() || question === null || question.state !== "open") {
         retireEverywhere(store, questionId, now, state);
-        repaint(state, part, event, "This was already answered.");
+        repaint(state, part, event, "This was already answered.", now);
         state.finish(event.id);
         return true;
     }
@@ -139,7 +141,7 @@ export function applyChatQuestionTap(options, event, binding, token, now) {
     }
     retireEverywhere(store, questionId, now, state);
     const label = question.options.find(one => one.id === action["choice"])?.label ?? String(action["choice"]);
-    repaint(state, part, event, `✅ You answered: ${label}. ${answered.said}`);
+    repaint(state, part, event, `✅ You answered: ${label}. ${answered.said}`, now);
     state.finish(event.id);
     return true;
 }

package/dist/surface.js

@@ -366,10 +366,10 @@ const GUIDE_ROWS = [
             { name: "runner", takesValue: true, meaning: "your registered worker name" },
             { name: "token", takesValue: true, meaning: "the worker's token" },
             { name: "ttl", takesValue: true, meaning: "lease seconds" }],
-        notableReasons: ["held", "fenced", "unapproved", "reserved", "external", "claimed", "not-ready"] },
+        notableReasons: ["held", "fenced", "unapproved", "reserved", "external", "claimed", "not-ready", "closed"] },
     { invocation: "heartbeat", synopsis: "still working; extends the lease", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
         positionals: [{ name: "lease", required: true, meaning: "the lease id" }],
-        flags: [jsonFlag, dbFlag], notableReasons: ["not-leased", "fenced"] },
+        flags: [jsonFlag, dbFlag], notableReasons: ["not-leased", "fenced", "closed"] },
     { invocation: "worker release", synopsis: "done with it; fenced if superseded", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
         positionals: [{ name: "lease", required: true, meaning: "the lease id" }],
         flags: [jsonFlag, dbFlag], notableReasons: ["not-leased", "fenced"] },

package/dist/task-moves.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The one door for writing a task's state (docs/plans/task-state-moves.md).
+ *
+ * A task is in one of five states: queued, running, done, failed, cancelled. TASK_MOVES lists every way code moves
+ * a task between them today: the state it writes and the states it may move from. moveTask writes one move as ONE
+ * statement, so the from-check and the write happen together inside whatever transaction the caller is in.
+ *
+ * Each from-list is copied from the statement it replaced, so this table records current behaviour exactly, except
+ * where docs/plans/closed-task-claims.md changed it (exhaust narrowed, claim added). The two moves marked
+ * `from: "any"` (complete, set) have no from-check and callers rely on that; making them narrower is a behaviour
+ * change with its own plan.
+ *
+ * Cancellation is not a move here: it has its own door, Store.applyCancellation, which also records why and who.
+ * Task creation (INSERT ... 'queued') is not a move either.
+ *
+ * This file imports nothing from store.ts at runtime (store.ts calls it), only types.
+ */
+import type { TaskState } from "./store.js";
+export declare const TASK_MOVES: {
+    /** Back to the queue from a running attempt that ended without finishing (stop, service stop, sign-in expired,
+     * vanished builder, move to a fallback agent). */
+    readonly requeue: {
+        readonly to: "queued";
+        readonly from: readonly ["running"];
+    };
+    /** An unfinished task that cannot go on (retries stopped, fallback agent signed out). */
+    readonly giveUp: {
+        readonly to: "failed";
+        readonly from: readonly ["queued", "running"];
+    };
+    /** A person's Retry. */
+    readonly retry: {
+        readonly to: "queued";
+        readonly from: readonly ["failed", "queued", "done"];
+    };
+    /** The tracker item was opened again. */
+    readonly reopen: {
+        readonly to: "queued";
+        readonly from: readonly ["cancelled", "failed", "queued"];
+    };
+    /** The fenced completion of an attempt. Wide today: a late result still writes over a closed task. */
+    readonly complete: {
+        readonly to: readonly ["done", "failed"];
+        readonly from: "any";
+    };
+    /** Strikes used up (build and scouting). Only an open task: one a person already closed keeps its state
+     * (docs/plans/closed-task-claims.md, decision B). */
+    readonly exhaust: {
+        readonly to: "failed";
+        readonly from: readonly ["queued", "running"];
+    };
+    /** The CLI `claim`: taking a task makes it running, in the grant's own transaction. `running` is listed because
+     * taking over an expired claim on a task a CLI runner left running keeps it running. */
+    readonly claim: {
+        readonly to: "running";
+        readonly from: readonly ["queued", "running"];
+    };
+    /** Store.setTaskState (the state verb, backend.setState, release and others). Wide by design: it is the
+     * general-purpose write; cancelled goes through applyCancellation instead. */
+    readonly set: {
+        readonly to: readonly ["queued", "running", "done", "failed"];
+        readonly from: "any";
+    };
+};
+export type TaskMoveName = keyof typeof TASK_MOVES;
+/** The smallest database handle moveTask needs (Store.handle fits). */
+export type MoveDatabase = {
+    prepare(sql: string): {
+        run(...params: unknown[]): {
+            changes: number | bigint;
+        };
+    };
+};
+/**
+ * Move one task. One statement: the from-check and the write together. True when the row changed (false when the
+ * task does not exist or is not in one of the move's from-states). `to` is required for complete and set, and
+ * refused for every other move.
+ */
+export declare function moveTask(db: MoveDatabase, id: string, move: TaskMoveName, now: Date, to?: TaskState): boolean;
+/**
+ * SQL condition, true while a runner holds a live claim on the task: the claim is not released, has not expired, and
+ * is the newest generation for its task. It needs the `claim` table in scope under that name, and binds one
+ * parameter: the current time as an ISO string. This is ownership, not proof that a process is alive.
+ */
+export declare const claimedNowSql = "claim.released_at IS NULL AND claim.expires_at > ? AND claim.lease_generation = (SELECT MAX(newest.lease_generation) FROM claim AS newest WHERE newest.task_ref = claim.task_ref)";
+/**
+ * SQL condition, true when the task's stored state is running (the `task` table in scope under that name). A task
+ * can be marked running with no live claim (see claimedNowSql), so the two can count differently.
+ */
+export declare const markedRunningSql = "task.state = 'running'";

package/dist/task-moves.js

@@ -0,0 +1,68 @@
+const ALL_BUT_CANCELLED = ["queued", "running", "done", "failed"];
+export const TASK_MOVES = {
+    /** Back to the queue from a running attempt that ended without finishing (stop, service stop, sign-in expired,
+     * vanished builder, move to a fallback agent). */
+    requeue: { to: "queued", from: ["running"] },
+    /** An unfinished task that cannot go on (retries stopped, fallback agent signed out). */
+    giveUp: { to: "failed", from: ["queued", "running"] },
+    /** A person's Retry. */
+    retry: { to: "queued", from: ["failed", "queued", "done"] },
+    /** The tracker item was opened again. */
+    reopen: { to: "queued", from: ["cancelled", "failed", "queued"] },
+    /** The fenced completion of an attempt. Wide today: a late result still writes over a closed task. */
+    complete: { to: ["done", "failed"], from: "any" },
+    /** Strikes used up (build and scouting). Only an open task: one a person already closed keeps its state
+     * (docs/plans/closed-task-claims.md, decision B). */
+    exhaust: { to: "failed", from: ["queued", "running"] },
+    /** The CLI `claim`: taking a task makes it running, in the grant's own transaction. `running` is listed because
+     * taking over an expired claim on a task a CLI runner left running keeps it running. */
+    claim: { to: "running", from: ["queued", "running"] },
+    /** Store.setTaskState (the state verb, backend.setState, release and others). Wide by design: it is the
+     * general-purpose write; cancelled goes through applyCancellation instead. */
+    set: { to: ALL_BUT_CANCELLED, from: "any" },
+};
+/** The SQL for one move: the guard is built from the table's own constants, never from caller input. */
+function moveSql(rule) {
+    const base = "UPDATE task SET state = ?, updated_at = ? WHERE id = ?";
+    if (rule.from === "any")
+        return base;
+    return `${base} AND state IN (${rule.from.map(state => `'${state}'`).join(", ")})`;
+}
+/** The state a move writes; throws on a call that does not fit the table (a programming error, not a refusal). */
+function targetOf(name, rule, to) {
+    if (to === "cancelled")
+        throw new Error("moveTask never writes cancelled: use applyCancellation");
+    if (typeof rule.to === "string") {
+        if (to !== undefined)
+            throw new Error(`the ${name} move always writes ${rule.to}; do not pass a target`);
+        return rule.to;
+    }
+    if (to === undefined)
+        throw new Error(`the ${name} move needs a target (${rule.to.join(" or ")})`);
+    if (!rule.to.includes(to))
+        throw new Error(`the ${name} move cannot write ${to}`);
+    return to;
+}
+/**
+ * Move one task. One statement: the from-check and the write together. True when the row changed (false when the
+ * task does not exist or is not in one of the move's from-states). `to` is required for complete and set, and
+ * refused for every other move.
+ */
+export function moveTask(db, id, move, now, to) {
+    const rule = Object.hasOwn(TASK_MOVES, move) ? TASK_MOVES[move] : undefined;
+    if (rule === undefined)
+        throw new Error(`unknown task move: ${String(move)}`);
+    const state = targetOf(move, rule, to);
+    return Number(db.prepare(moveSql(rule)).run(state, now.toISOString(), id).changes) > 0;
+}
+/**
+ * SQL condition, true while a runner holds a live claim on the task: the claim is not released, has not expired, and
+ * is the newest generation for its task. It needs the `claim` table in scope under that name, and binds one
+ * parameter: the current time as an ISO string. This is ownership, not proof that a process is alive.
+ */
+export const claimedNowSql = "claim.released_at IS NULL AND claim.expires_at > ? AND claim.lease_generation = (SELECT MAX(newest.lease_generation) FROM claim AS newest WHERE newest.task_ref = claim.task_ref)";
+/**
+ * SQL condition, true when the task's stored state is running (the `task` table in scope under that name). A task
+ * can be marked running with no live claim (see claimedNowSql), so the two can count differently.
+ */
+export const markedRunningSql = "task.state = 'running'";