toolroll 0.9.98 → 0.9.100

package/dist/chat-message-states.d.ts

@@ -0,0 +1,75 @@
+/**
+ * An incoming chat message (a `chat_event` row of kind 'message'): what its states mean, the result words it is
+ * settled with, and the one question "which replies have not reached the person yet".
+ *
+ * States (contracts/chat-tables.ts): queued, running, done, failed, dropped.
+ *
+ * What `done` means differs by app, and nothing should read more into it than this:
+ *  - Telegram: done after every planned part of the reply was sent (or dropped as moot, such as a card whose
+ *    proposal was already answered elsewhere). It is written by `ChatMessages.finishMessage`, only by the claim
+ *    holder and only from 'running'.
+ *  - Slack, Discord and Teams: done as soon as the reply is planned, before any of it is sent. `ChatState.plan`
+ *    writes the parts and then `ChatState.finish` marks the row done in the same transaction; the parts go out
+ *    later, part by part, through `chat_part`.
+ * So `done` means "the message needs no more work from the lead", never "the person has the reply". To ask whether
+ * a reply has reached the person, use `unsent()` / `unsentPart()` below, which look at the parts themselves and
+ * give the same answer on every app.
+ *
+ * `failed` is used by Telegram only. `dropped` means the chat was disconnected (or an app gave the event up) while
+ * it waited; Telegram rows read a dropped row as failed. Dropped is final: `ChatState.finish` never writes over it,
+ * and `ChatState.plan` saves no reply for it.
+ */
+import type { ResolvedLead } from "./chat-channel.js";
+import type { LeadFailure, LeadRefusal } from "./lead.js";
+/**
+ * Every fixed result word a message row can be written with. These are stored in `chat_event.result`, so each one
+ * must stay byte-identical: renaming one would change what older rows mean.
+ */
+export declare const CHAT_MESSAGE_OUTCOMES: readonly ["answered", "replayed", "typed-start", "busy", "backlog", "replayed:running", "registry-unavailable", "registry-unavailable:admitted", "delivering", "answered:sending", "unpaired", "unsent:no-session", "replayed:missing", "typed-start:not-counted", "revoked"];
+export type ChatMessageFixedOutcome = (typeof CHAT_MESSAGE_OUTCOMES)[number];
+/** Words a message is queued under while it waits for another attempt (telegram-lead.ts `requeue`). */
+export declare const CHAT_WAIT_OUTCOMES: readonly ["busy", "backlog", "replayed:running", "registry-unavailable", "registry-unavailable:admitted"];
+export type ChatWaitOutcome = (typeof CHAT_WAIT_OUTCOMES)[number];
+/** Waiting for the lead itself (it is answering, or earlier messages wait first): the two-hour bound applies. */
+export declare const CHAT_LEAD_WAITS: readonly ["busy", "backlog"];
+export type ChatLeadWait = (typeof CHAT_LEAD_WAITS)[number];
+/** Waiting on a turn that was already admitted: no age bound (the turn's own deadline ends it). */
+export declare const CHAT_ADMITTED_WAITS: readonly ["replayed:running", "registry-unavailable:admitted"];
+/** The words a row is marked done with (the reply was sent). */
+export type ChatDoneOutcome = "answered" | "replayed" | "typed-start";
+type RefusedReason = LeadRefusal | Extract<ResolvedLead, {
+    ok: false;
+}>["reason"];
+/**
+ * Every result word, including the forms that carry a detail after a prefix or a suffix. Build the detailed forms
+ * with `chatOutcome` below, never by joining strings at the call site.
+ */
+export type ChatMessageOutcome = ChatMessageFixedOutcome | `${ChatWaitOutcome}:gave-up` | `refused:${RefusedReason}` | `failed:${LeadFailure}` | `replayed:${string}` | `unsent:gave-up:${string}` | `unsent:${string}`;
+/** Builders for the result words that carry a detail. The stored text is exactly what the old string joins wrote. */
+export declare const chatOutcome: {
+    /** A wait that ran past its age bound. */
+    readonly gaveUp: <W extends ChatWaitOutcome>(wait: W) => `${W}:gave-up`;
+    /** The lead refused the turn, or no session could be resolved for it. */
+    readonly refused: <R extends RefusedReason>(reason: R) => `refused:${R}`;
+    /** The turn ran and failed. */
+    readonly failed: <R extends LeadFailure>(reason: R) => `failed:${R}`;
+    /** The recovered turn had ended without an answer: its failure reason as the turn row stores it ("failed" when none). */
+    readonly replayedFailed: (reason: string | null) => `replayed:${string}`;
+    /** The reply could not go out: the chat or its projects changed (the problem in words). */
+    readonly unsent: (problem: string) => `unsent:${string}`;
+    /** The reply was still unsent a day after it was planned (the last send error, or "unsent"). */
+    readonly unsentGaveUp: (error: string | null) => `unsent:gave-up:${string}`;
+};
+/** Is this word one of the waits for the lead itself (busy or backlog)? */
+export declare function isLeadWait(outcome: string | null): outcome is ChatLeadWait;
+/** Is this word a wait on a turn that was already admitted (no age bound)? */
+export declare function isAdmittedWait(outcome: string | null): boolean;
+/** SQL: this `chat_part` row (by its alias) has not reached the person: planned and neither sent nor dropped. */
+export declare function unsentPart(part: string): string;
+/**
+ * SQL: the `chat_event` row (by its alias or table name) has a reply part that has not reached the person yet.
+ * The one answer to "is anything of this reply unsent?" on every app; wrap it in NOT for "everything reached them
+ * or was dropped". `part` names the inner alias when the caller's query already uses the default.
+ */
+export declare function unsent(event: string, part?: string): string;
+export {};

package/dist/chat-message-states.js

@@ -0,0 +1,74 @@
+/**
+ * Every fixed result word a message row can be written with. These are stored in `chat_event.result`, so each one
+ * must stay byte-identical: renaming one would change what older rows mean.
+ */
+export const CHAT_MESSAGE_OUTCOMES = [
+    // done: the reply was sent (Telegram)
+    "answered", // a fresh turn's reply
+    "replayed", // the reply of a turn found again after a restart, or sent on a later pass
+    "typed-start", // Toolroll's own reply to a typed yes on a Start card
+    // queued: waiting for the lead, with no age bound or the bounds in telegram-lead.ts
+    "busy", // the lead is answering something else
+    "backlog", // the person's own earlier messages wait first
+    "replayed:running", // a turn was already admitted for it and is still working
+    "registry-unavailable", // the project records could not be read
+    "registry-unavailable:admitted", // the same, but a turn already took the message
+    // queued: the reply is planned and only sending remains
+    "delivering",
+    "answered:sending", // a fresh turn's reply, handed to the bridge's cycle to send
+    // failed
+    "unpaired", // the chat's pairing changed before the turn
+    "unsent:no-session", // the session ended before the reply went out
+    "replayed:missing", // the turn its receipt names is gone
+    "typed-start:not-counted", // a typed yes whose card's turn is gone
+    // dropped: the chat was disconnected while the message waited (chat-core.ts)
+    "revoked",
+];
+/** Words a message is queued under while it waits for another attempt (telegram-lead.ts `requeue`). */
+export const CHAT_WAIT_OUTCOMES = ["busy", "backlog", "replayed:running", "registry-unavailable", "registry-unavailable:admitted"];
+/** Waiting for the lead itself (it is answering, or earlier messages wait first): the two-hour bound applies. */
+export const CHAT_LEAD_WAITS = ["busy", "backlog"];
+/** Waiting on a turn that was already admitted: no age bound (the turn's own deadline ends it). */
+export const CHAT_ADMITTED_WAITS = ["replayed:running", "registry-unavailable:admitted"];
+/** Builders for the result words that carry a detail. The stored text is exactly what the old string joins wrote. */
+export const chatOutcome = {
+    /** A wait that ran past its age bound. */
+    gaveUp: (wait) => `${wait}:gave-up`,
+    /** The lead refused the turn, or no session could be resolved for it. */
+    refused: (reason) => `refused:${reason}`,
+    /** The turn ran and failed. */
+    failed: (reason) => `failed:${reason}`,
+    /** The recovered turn had ended without an answer: its failure reason as the turn row stores it ("failed" when none). */
+    replayedFailed: (reason) => `replayed:${reason ?? "failed"}`,
+    /** The reply could not go out: the chat or its projects changed (the problem in words). */
+    unsent: (problem) => `unsent:${problem}`,
+    /** The reply was still unsent a day after it was planned (the last send error, or "unsent"). */
+    unsentGaveUp: (error) => `unsent:gave-up:${error ?? "unsent"}`,
+};
+/** Is this word one of the waits for the lead itself (busy or backlog)? */
+export function isLeadWait(outcome) {
+    return CHAT_LEAD_WAITS.includes(outcome ?? "");
+}
+/** Is this word a wait on a turn that was already admitted (no age bound)? */
+export function isAdmittedWait(outcome) {
+    return CHAT_ADMITTED_WAITS.includes(outcome ?? "");
+}
+const SQL_ALIAS = /^[a-z_][a-z0-9_]*$/;
+function alias(name) {
+    if (!SQL_ALIAS.test(name))
+        throw new Error(`not a table alias: ${name}`);
+    return name;
+}
+/** SQL: this `chat_part` row (by its alias) has not reached the person: planned and neither sent nor dropped. */
+export function unsentPart(part) {
+    return `${alias(part)}.state = 'pending'`;
+}
+/**
+ * SQL: the `chat_event` row (by its alias or table name) has a reply part that has not reached the person yet.
+ * The one answer to "is anything of this reply unsent?" on every app; wrap it in NOT for "everything reached them
+ * or was dropped". `part` names the inner alias when the caller's query already uses the default.
+ */
+export function unsent(event, part = "unsent_part") {
+    const e = alias(event), p = alias(part);
+    return `EXISTS (SELECT 1 FROM chat_part ${p} WHERE ${p}.provider = ${e}.provider AND ${p}.event = ${e}.id AND ${unsentPart(p)})`;
+}

package/dist/chat-messages.d.ts

@@ -1,4 +1,5 @@
 import { ChatCore } from "./chat-core.js";
+import { type ChatMessageOutcome } from "./chat-message-states.js";
 import type { Notification, NotificationReceipt, Run, TelegramAction, TelegramBinding, TelegramConversation, TelegramConversationPart, TelegramConversationPartPlan, TelegramDelivery, TelegramDigest, TelegramFlowAction, TelegramFlowChoice, TelegramFlowPrompt, TelegramProposalAction } from "./store.js";
 /** v83: a notification for another person, settled for this destination without sending. */
 export declare const TELEGRAM_SKIPPED_ELSEWHERE = "skipped:for-another-person";
@@ -32,6 +33,8 @@ export declare const TELEGRAM_HOLD_REASONS: Readonly<{
     order: "Earlier task notification is still undelivered";
     disabled: "Telegram delivery is disabled";
 }>;
+/** A note draft's states: `pending` and `armed` are live; the other three are final. */
+export type NoteDraftState = "pending" | "armed" | "superseded" | "consumed" | "discarded";
 export declare class ChatMessages extends ChatCore {
     createDecisionAction(action: {
         token: string;
@@ -72,8 +75,9 @@ export declare class ChatMessages extends ChatCore {
         replyTo: string;
         note: string;
     }, now: Date, ttlMs?: number): boolean;
-    /** Move a draft between states; the caller owns the transaction story. */
-    setNoteDraftState(id: number, state: "pending" | "armed" | "superseded" | "consumed" | "discarded"): void;
+    /** Move a draft to `to`, only from one of the states in `from` (the check and the write are one statement). True when
+     * it moved; false when the draft was in none of them. The caller owns the transaction story. */
+    setNoteDraftState(id: number, from: readonly NoteDraftState[], to: NoteDraftState): boolean;
     createFlowActions(at: {
         binding: number;
         chatId: string;
@@ -202,14 +206,16 @@ export declare class ChatMessages extends ChatCore {
      * Settle a claimed row: done or failed with its outcome word, or back to
      * queued for a later attempt (a busy engine). Only the claim holder may;
      * a lapsed claim settles nothing, so a reclaimer's outcome stands.
+     * Telegram writes done here only once every part of the reply was sent
+     * or dropped; what done means on each app is in chat-message-states.ts.
      */
     finishMessage(id: number, owner: string, result: {
         state: "done" | "failed";
-        outcome: string;
+        outcome: ChatMessageOutcome;
         replyMessageId?: string | null;
     } | {
         state: "queued";
-        outcome: string;
+        outcome: ChatMessageOutcome;
         nextAttemptAt: string;
     }, now: Date): boolean;
     /**

package/dist/chat-messages.js

@@ -10,6 +10,7 @@
  */
 import { neverHeld, watchedPing } from "./agent-board.js";
 import { ChatCore } from "./chat-core.js";
+import { unsentPart, unsent } from "./chat-message-states.js";
 import { readChatMessageBody, readChatPart, savedChatEventBody, savedChatPart } from "./contracts/chat-content.js";
 import { isTelegramProgressNotification, proposalTaskOf, readNotification, readNotificationReceipt } from "./notification-rows.js";
 /** v83: a notification for another person, settled for this destination without sending. */
@@ -195,7 +196,7 @@ export class ChatMessages extends ChatCore {
             if (live !== undefined) {
                 if (Number(live["event"]) >= draft.updateId)
                     return false;
-                chat.prepare("UPDATE chat_note_draft SET state = 'superseded' WHERE provider = :provider AND id = ?").run(live["id"]);
+                chat.setNoteDraftState(Number(live["id"]), ["pending", "armed"], "superseded");
             }
             chat
                 .prepare(`INSERT INTO chat_note_draft (provider, id, binding, decision, event, message, reply_to, note, state, created, expires)
@@ -204,9 +205,11 @@ export class ChatMessages extends ChatCore {
             return true;
         });
     }
-    /** Move a draft between states; the caller owns the transaction story. */
-    setNoteDraftState(id, state) {
-        this.prepare("UPDATE chat_note_draft SET state = ? WHERE provider = :provider AND id = ?").run(state, id);
+    /** Move a draft to `to`, only from one of the states in `from` (the check and the write are one statement). True when
+     * it moved; false when the draft was in none of them. The caller owns the transaction story. */
+    setNoteDraftState(id, from, to) {
+        return Number(this.prepare("UPDATE chat_note_draft SET state = ? WHERE provider = :provider AND id = ? AND state IN (SELECT value FROM json_each(?))")
+            .run(to, id, JSON.stringify(from)).changes) === 1;
     }
     createFlowActions(at, actions, now, days = 7) {
         const stamp = now.toISOString(), expires = new Date(now.getTime() + days * 86_400_000).toISOString();
@@ -454,6 +457,8 @@ export class ChatMessages extends ChatCore {
      * Settle a claimed row: done or failed with its outcome word, or back to
      * queued for a later attempt (a busy engine). Only the claim holder may;
      * a lapsed claim settles nothing, so a reclaimer's outcome stands.
+     * Telegram writes done here only once every part of the reply was sent
+     * or dropped; what done means on each app is in chat-message-states.ts.
      */
     finishMessage(id, owner, result, now) {
         const stamp = now.toISOString(), chat = this;
@@ -478,9 +483,9 @@ export class ChatMessages extends ChatCore {
     unsentReplies(botId, approver, since) {
         return this
             .prepare(`SELECT c.id, b.approver, MIN(p.created) AS since,
-           (SELECT q.problem FROM chat_part q WHERE q.provider = c.provider AND q.event = c.id AND q.state = 'pending' ORDER BY q.ordinal LIMIT 1) AS error
+           (SELECT q.problem FROM chat_part q WHERE q.provider = c.provider AND q.event = c.id AND ${unsentPart("q")} ORDER BY q.ordinal LIMIT 1) AS error
           FROM chat_event c JOIN chat_binding b ON b.provider = c.provider AND b.id = c.binding
-          JOIN chat_part p ON p.provider = c.provider AND p.event = c.id AND p.state = 'pending'
+          JOIN chat_part p ON p.provider = c.provider AND p.event = c.id AND ${unsentPart("p")}
          WHERE c.provider = :provider AND c.kind = 'message' AND c.state IN ('queued','running') AND (? IS NULL OR c.installation = ?) AND (? IS NULL OR b.approver = ?)
          GROUP BY c.id HAVING MIN(p.created) <= ? ORDER BY ${TELEGRAM_CONVERSATION_ORDER.replaceAll("e.", "c.")}`)
             .all(botId, botId, approver, approver, since.toISOString())
@@ -492,7 +497,7 @@ export class ChatMessages extends ChatCore {
             .prepare(`UPDATE chat_event SET next_at = ?
           WHERE provider = :provider AND kind = 'message' AND state = 'queued'
             AND (? IS NULL OR binding IN (SELECT id FROM chat_binding WHERE provider = :provider AND approver = ?))
-            AND EXISTS (SELECT 1 FROM chat_part p WHERE p.provider = chat_event.provider AND p.event = chat_event.id AND p.state = 'pending')`)
+            AND ${unsent("chat_event")}`)
             .run(now.toISOString(), approver, approver);
         return Number(changes);
     }

package/dist/check-failure.js

@@ -27,6 +27,7 @@ import { INFRA_RERUNS_PER_CANDIDATE, INFRA_RERUNS_PER_INCIDENT } from "./release
 import { releaseCheckScope } from "./scope.js";
 import { isVerificationReceipt, verificationEvidence } from "./verification-evidence.js";
 import { checkAttemptOf } from "./store.js";
+import { endedInterrupted } from "./run-ending.js";
 /** The plane's limits for confirmed infrastructure failures (one rerun per incident, two per candidate). */
 export { INFRA_RERUNS_PER_CANDIDATE, INFRA_RERUNS_PER_INCIDENT };
 /** The ledger action that records each rerun the release asked for, and why. */
@@ -208,7 +209,7 @@ export function setupReplayWords(first) {
  * got as far as its check keeps every rule below.
  */
 export function ranNoCheck(store, row) {
-    if (row.outcome !== "failed" || (row.reason !== "interrupted" && row.reason !== "no-op") || row.head !== null || row.checkRow !== null)
+    if (!(endedInterrupted(row) || (row.outcome === "failed" && row.reason === "no-op")) || row.head !== null || row.checkRow !== null)
         return false;
     if (checkAttemptOf(store, row.id) !== null)
         return false;

package/dist/check-report.js

@@ -36,7 +36,7 @@ export const CHECK_ARTIFACT_CAP = CHECK_REPORT_MAX_BYTES;
 /** The release check's harness, named: the orchestrator, its runners and helpers, Vitest's configuration and setup, and
  * the reporter. These never carry (release-carry.ts). The execution context digests far more (inHarnessDigest). */
 export const HARNESS_FILES = Object.freeze([
-    "scripts/release-check.mjs", "scripts/release-check-ci.mjs", "scripts/suite-lifecycle.mjs", "scripts/provider-gate.mjs",
+    "scripts/release-check.mjs", "scripts/release-check-ci.mjs", "scripts/upgrade-rule.mjs", "scripts/suite-lifecycle.mjs", "scripts/provider-gate.mjs",
     "scripts/e2e-parallel.mjs", "scripts/e2e-kit.mjs", "scripts/upgrade-path.mjs", "scripts/check-results.mjs",
     "vitest.config.ts", "test/attacks/vitest.config.ts",
     "test/setup-state.ts", "test/fresh-store.ts", "test/temp-root.ts", "test/ensure-build.ts", "test/release-reporter.ts",

package/dist/checkout-cleanup.js

@@ -27,6 +27,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
+import { isDeployed } from "./deploy-phase.js";
 import { taskBranches } from "./names.js";
 import { COMPLETION_ACTION } from "./result-completion.js";
 import { CLEANUP_CHOICES, IDLE_CHOICES, bytesWords, diskBytes, diskBytesAsync } from "./storage.js";
@@ -59,7 +60,7 @@ export function deployedRelease(stateDir) {
         catch {
             continue;
         }
-        if (journal["phase"] !== "deployed")
+        if (!isDeployed(journal["phase"]))
             continue;
         const at = typeof journal["deployedAt"] === "string" ? journal["deployedAt"] : typeof journal["updatedAt"] === "string" ? journal["updatedAt"] : "";
         if (newest !== null && newest.at >= at)

package/dist/claim.d.ts

@@ -27,7 +27,7 @@
  * untestable, and a lease is exactly the kind of thing that has to be provable
  * rather than probable.
  */
-import { type Store, type Mutation, type TaskState } from "./store.js";
+import { type Store, type Mutation, type TaskState, type ClosedState } from "./store.js";
 import type { ParsedDecision, Problem } from "./decision.js";
 import type { ParsedPlan } from "./plan.js";
 import { type PlannerSource } from "./planner-source.js";
@@ -115,6 +115,18 @@ export type AcquireResult = {
     ok: false;
     reason: "draining";
     until: string;
+}
+/** The task is done, failed or cancelled (docs/plans/closed-task-claims.md): nothing claims a closed task, except
+ * check cleanup's own door (acquireForCheckCleanup). */
+ | {
+    ok: false;
+    reason: "closed";
+    state: ClosedState;
+}
+/** A built-in reference with no task row behind it: nothing to claim. */
+ | {
+    ok: false;
+    reason: "no-task";
 };
 /** `fenced` means the lease was superseded; `unknown` means it never existed. */
 export type FenceResult = {
@@ -125,6 +137,12 @@ export type FenceResult = {
     ok: false;
     reason: "fenced" | "unknown" | "stopped";
 };
+/** A heartbeat's answer: the fence, or `closed` when an expired claim's task was closed meanwhile (it is not renewed). */
+export type HeartbeatResult = FenceResult | {
+    ok: false;
+    reason: "closed";
+    state: ClosedState;
+};
 /**
  * Completion's OWN result (external dispatch, finding 33): `completed` is
  * today's world — the task is done/failed as asked; `disowned` means the
@@ -225,7 +243,7 @@ export declare function acquireIfReady(store: Store, taskRef: number, runner: st
  * has been superseded — which is the cheapest moment for it to find out, well
  * before it has finished work nobody will accept.
  */
-export declare function heartbeat(store: Store, leaseId: string, now: Date, ttlMs?: number): FenceResult;
+export declare function heartbeat(store: Store, leaseId: string, now: Date, ttlMs?: number): HeartbeatResult;
 /**
  * Hand the task back.
  *
@@ -354,6 +372,13 @@ export type FailureDisposition = {
     ok: true;
     disposition: "fallback";
     provider: string;
+}
+/** Strikes used up on a task a person had already closed: its state is kept, and no incident, hold or page. */
+ | {
+    ok: true;
+    disposition: "closed";
+    strikes: number;
+    state: ClosedState;
 } | {
     ok: false;
     reason: "fenced" | "unknown" | "stopped";
@@ -557,6 +582,11 @@ export type ScoutFailureDisposition = {
     disposition: "stalled";
     incidentId: number;
     strikes: number;
+} | {
+    ok: true;
+    disposition: "closed";
+    strikes: number;
+    state: ClosedState;
 } | {
     ok: true;
     disposition: "auth-expired";
@@ -587,3 +617,11 @@ export declare function currentClaim(store: Store, taskRef: number, now: Date):
  * that recovers and a system that appears to have lost the work.
  */
 export declare function reap(store: Store, now: Date): Claim[];
+/**
+ * Check cleanup's claim (acp-check.ts settleChecks): the one road that may claim a closed task. Only the task bound to
+ * check `checkId`, when that check is this runner's, finished and unsettled, held right now by this cleanup `attempt`,
+ * and its task is the built-in one named from the check row's own id (store.ts checkCleanupTaskOf) — proved here, in
+ * the same transaction as the grant. Every other gate of the claim still applies. When the proof fails, the claim
+ * answers exactly as an ordinary one would: never wider.
+ */
+export declare function acquireForCheckCleanup(store: Store, checkId: number, attempt: string, runner: string, options: AcquireOptions): AcquireResult;

package/dist/claim.js

@@ -31,7 +31,7 @@ import { randomUUID } from "node:crypto";
 import { authenticate, drainOf } from "./runner.js";
 import { pauseForAuth } from "./provider-auth.js";
 import { DEFAULT_MAX_OPEN_DECISIONS, missingCapability, scopeApprovedForDispatch, taskReadinessBlocker, } from "./dispatch.js";
-import { BUILT_IN, refArchived, } from "./store.js";
+import { BUILT_IN, checkCleanupTaskOf, isClosedState, refArchived, taskStateForClaim, } from "./store.js";
 import { digestOf } from "./scope.js";
 import { parseExecutionPlanDocument } from "./plan.js";
 import { sealUnchangedPlanUnderMode } from "./plan-auto.js";
@@ -39,6 +39,7 @@ import { routeFromJson } from "./phase-routing.js";
 import { contractChangesOf, decodePlannerSource, encodePlannerSource, canonicalContractJson, PLANNER_SOURCE_LIMITS, describeContractChanges, encodePlanContractRecord, plannerContractOf, plannerSourceDigest, } from "./planner-source.js";
 import { storeEvidence, readVerifiedArtifact, EVIDENCE_CAPS } from "./evidence.js";
 import { moveOnIfExhausted } from "./fallback.js";
+import { moveTask } from "./task-moves.js";
 /** How stale a mirror's last complete sync may be before admission refuses. */
 export const SYNC_MAX_AGE_MS = 15 * 60_000;
 /**
@@ -60,7 +61,7 @@ export function acquire(store, taskRef, runner, options) {
     // copy, so a second replay cannot double-stamp, and Store.replay's T→T
     // contract holds for every other user.
     const replayed = store.hasMutationRecord(options.mutation ?? {});
-    const result = inTransaction(store, () => acquireLocked(store, taskRef, runner, options));
+    const result = inTransaction(store, () => acquireLocked(store, taskRef, runner, options, "refuse"));
     return replayed && result.ok ? { ...result, replayed: true } : result;
 }
 /**
@@ -68,7 +69,10 @@ export function acquire(store, taskRef, runner, options) {
  * `acquireIfReady` needs its readiness check and the CAS to be one atomic
  * step, and SQLite does not nest transactions.
  */
-function acquireLocked(store, taskRef, runner, options) {
+function acquireLocked(store, taskRef, runner, options, 
+/** Not an AcquireOptions field, so no options object (CLI flag, HTTP body, chat, MCP) can carry it. Only
+ * acquireForCheckCleanup passes "check-cleanup", after proving its check row in this transaction. */
+closed) {
     const { now, ttlMs = DEFAULT_LEASE_MS, newLeaseId = randomUUID, mutation = {} } = options;
     const db = store.handle;
     // Idempotency wraps the CAS, not the other way round: a retried
@@ -158,6 +162,18 @@ function acquireLocked(store, taskRef, runner, options) {
                 until: String(existing["expires_at"]),
             };
         }
+        // A CLOSED TASK claims for nobody (docs/plans/closed-task-claims.md, decision A), read here in the same write
+        // transaction as the insert below. Placed after every older refusal, so each of those answers as before; this
+        // only replaces what would have been a grant. A built-in reference with no task row has nothing to claim. A
+        // task of another backend keeps today's answer: its state is in that tracker, not in this database.
+        if (placedRef !== null && placedRef.backend === BUILT_IN) {
+            const known = taskStateForClaim(store, taskRef);
+            if (known.kind === "missing")
+                return { ok: false, reason: "no-task" };
+            if (known.kind === "built-in" && isClosedState(known.state) && closed === "refuse") {
+                return { ok: false, reason: "closed", state: known.state };
+            }
+        }
         const generation = existing === undefined ? 1 : Number(existing["lease_generation"]) + 1;
         const claim = {
             taskRef,
@@ -227,7 +243,7 @@ export function acquireForCheck(store, taskRef, runner, options) {
         if (registered !== null && store.liveClaimCount(runner, options.now) >= registered.runner.capacity) {
             return { ok: false, reason: "capacity", message: `${runner} has no free slot for a check` };
         }
-        return acquireLocked(store, taskRef, runner, options);
+        return acquireLocked(store, taskRef, runner, options, "refuse");
     });
 }
 export function acquireIfReady(store, taskRef, runner, options) {
@@ -344,7 +360,7 @@ export function acquireIfReady(store, taskRef, runner, options) {
                 };
             }
         }
-        const taken = acquireLocked(store, taskRef, runner, options);
+        const taken = acquireLocked(store, taskRef, runner, options, "refuse");
         // The half-open probe slot is consumed only WITH the claim it admits —
         // an attention refusal or a lost CAS must not re-arm the quota as
         // exhausted with no probe in flight (finding 3). Same transaction, so
@@ -364,6 +380,12 @@ export function heartbeat(store, leaseId, now, ttlMs = DEFAULT_LEASE_MS) {
     const db = store.handle;
     const expiresAt = new Date(now.getTime() + ttlMs).toISOString();
     return inTransaction(store, () => {
+        // An expired claim is not brought back on a task closed meanwhile (closed-task-claims.md, finding 1): that would
+        // be a new claim on a closed task by another road. A live claim, and an expired one on an open task, renew as
+        // always. Read in this write transaction, before the renewal.
+        const closedNow = expiredOnClosedTask(store, leaseId, now);
+        if (closedNow !== null)
+            return { ok: false, reason: "closed", state: closedNow };
         const { changes } = db
             .prepare(`UPDATE claim SET heartbeat_at = ?, expires_at = ?
           WHERE lease_id = ? AND released_at IS NULL AND ${NOT_SUPERSEDED}`)
@@ -582,7 +604,7 @@ function sealComplete(store, leaseId, args) {
                 store.applyCancellation(String(taskId["external_id"]), { kind: "machine", code: "disowned-completion" }, now, null);
             }
             else {
-                db.prepare("UPDATE task SET state = ?, updated_at = ? WHERE id = ?").run(state, now.toISOString(), String(taskId["external_id"]));
+                moveTask(db, String(taskId["external_id"]), "complete", now, state);
             }
             return true;
         });
@@ -789,11 +811,9 @@ function sealInterrupted(store, leaseId, args) {
         return { ok: true, stopRun, requeued: false, fenced: true };
     // Back to the queue, where the stop's hold keeps it — a paused task
     // reads as queued-and-held, exactly like an operator pause.
-    const requeued = db
-        .prepare("UPDATE task SET state = 'queued', updated_at = ? WHERE id = ? AND state = 'running'")
-        .run(now.toISOString(), taskId);
+    const requeued = moveTask(db, taskId, "requeue", now);
     store.bumpWake();
-    return { ok: true, stopRun, requeued: Number(requeued.changes) > 0, fenced: false };
+    return { ok: true, stopRun, requeued, fenced: false };
 }
 /**
  * Hand an attempt back because the SERVICE stopped (its builder is
@@ -824,11 +844,9 @@ function sealHandBack(store, leaseId, args) {
     store.finishRun(runId, { outcome: "failed", reason: "interrupted", now });
     if (fenced)
         return { ok: true, requeued: false, fenced: true };
-    const requeued = db
-        .prepare("UPDATE task SET state = 'queued', updated_at = ? WHERE id = ? AND state = 'running'")
-        .run(now.toISOString(), taskId);
+    const requeued = moveTask(db, taskId, "requeue", now);
     store.bumpWake();
-    return { ok: true, requeued: Number(requeued.changes) > 0, fenced: false };
+    return { ok: true, requeued, fenced: false };
 }
 /**
  * THE STOP FENCE at settlement (v52): when a stop applies to the run —
@@ -868,7 +886,6 @@ export function interruptIfStopped(store, args) {
  */
 function sealFailure(store, leaseId, args) {
     const { runId, taskId, failureClass, message, now } = args;
-    const db = store.handle;
     const run = openAttempt(store, leaseId, runId, "a failure", "builder");
     const stopped = interruptIfStopped(store, { leaseId, runId, taskId, now });
     if (stopped !== null)
@@ -916,6 +933,11 @@ function sealFailure(store, leaseId, args) {
     }
     const strikes = store.addStrike(run.taskRef);
     if (strikes >= MAX_STRIKES) {
+        // The state first: a task a person already closed keeps its state, and then no incident, hold or page is
+        // written either (closed-task-claims.md, decision B). The run's outcome, the release and the strike stand.
+        const closedState = exhaustUnlessClosed(store, run, taskId, now);
+        if (closedState !== null)
+            return { ok: true, disposition: "closed", strikes, state: closedState };
         const incidentId = store.createIncident({ run: runId, kind: "attempts-exhausted" }, now);
         store.holdOwned({
             taskRef: run.taskRef,
@@ -924,7 +946,6 @@ function sealFailure(store, leaseId, args) {
             reason: `attempts-exhausted — ${strikes} consecutive failures, last: ${failureClass}`,
             until: null,
         }, now);
-        db.prepare("UPDATE task SET state = 'failed', updated_at = ? WHERE id = ?").run(now.toISOString(), taskId);
         store.enqueueNotification({
             source: { run: runId },
             dedupeKey: `stalled:${run.taskRef}`,
@@ -970,7 +991,7 @@ function sealFailure(store, leaseId, args) {
  */
 function sealAuthExpired(store, run, taskId, now) {
     store.finishRun(run.id, { outcome: "failed", reason: "auth-expired", now });
-    store.handle.prepare("UPDATE task SET state = 'queued', updated_at = ? WHERE id = ? AND state = 'running'").run(now.toISOString(), taskId);
+    moveTask(store.handle, taskId, "requeue", now);
     pauseForAuth(store, { provider: run.provider, authMode: run.authMode ?? null, runId: run.id, taskRef: run.taskRef, now });
     store.bumpWake();
     return { disposition: "auth-expired", provider: run.provider };
@@ -1385,7 +1406,6 @@ function sealScout(store, leaseId, args) {
  */
 function sealScoutFailure(store, leaseId, args) {
     const { runId, taskId, failure: kind, message, now } = args;
-    const db = store.handle;
     const run = openAttempt(store, leaseId, runId, "a failure", "scout");
     const stopped = interruptIfStopped(store, { leaseId, runId, taskId, now });
     if (stopped !== null)
@@ -1419,6 +1439,10 @@ function sealScoutFailure(store, leaseId, args) {
     }
     const strikes = store.addStrike(run.taskRef);
     if (strikes >= MAX_STRIKES) {
+        // Same as the build: a task a person already closed keeps its state, with no incident, hold or page.
+        const closedState = exhaustUnlessClosed(store, run, taskId, now);
+        if (closedState !== null)
+            return { ok: true, disposition: "closed", strikes, state: closedState };
         const incidentId = store.createIncident({ run: runId, kind: "attempts-exhausted" }, now);
         store.holdOwned({
             taskRef: run.taskRef,
@@ -1427,7 +1451,6 @@ function sealScoutFailure(store, leaseId, args) {
             reason: `attempts-exhausted — ${strikes} consecutive scouting failures`,
             until: null,
         }, now);
-        db.prepare("UPDATE task SET state = 'failed', updated_at = ? WHERE id = ?").run(now.toISOString(), taskId);
         store.enqueueNotification({
             source: { run: runId },
             dedupeKey: `stalled:${run.taskRef}`,
@@ -1512,3 +1535,53 @@ function inTransaction(store, body) {
     // intent) joins one transaction instead of dying on a nested BEGIN.
     return store.transact(body);
 }
+/**
+ * Whether `leaseId` is an expired claim, still unreleased and the newest for its task, on a built-in task that is now
+ * done, failed or cancelled: that closed state, else null. heartbeat refuses to renew exactly this case.
+ */
+function expiredOnClosedTask(store, leaseId, now) {
+    const row = store.handle
+        .prepare(`SELECT task_ref FROM claim WHERE lease_id = ? AND released_at IS NULL AND expires_at <= ? AND ${NOT_SUPERSEDED}`)
+        .get(leaseId, now.toISOString());
+    if (row === undefined)
+        return null;
+    const known = taskStateForClaim(store, Number(row["task_ref"]));
+    return known.kind === "built-in" && isClosedState(known.state) ? known.state : null;
+}
+/**
+ * The stall's state write (build and scouting), inside finalize's transaction. The task is the run's own: a supplied
+ * id that names another task is a caller defect, thrown like openAttempt's. An open built-in task is marked failed
+ * (null back, the stall goes on as before). One a person already closed keeps its state: that state comes back and
+ * the caller writes no incident, hold or page. A reference with no built-in task row behind it (a missing row, or a
+ * task of another backend) writes no state and answers null, so the stall goes on as it did before.
+ */
+function exhaustUnlessClosed(store, run, taskId, now) {
+    const ref = store.refForId(run.taskRef);
+    if (ref === null || ref.externalId !== taskId) {
+        throw new Error(`run ${run.id} belongs to task reference ${run.taskRef}, not ${taskId} — a stall is sealed on the run's own task`);
+    }
+    if (ref.backend !== BUILT_IN)
+        return null;
+    if (moveTask(store.handle, taskId, "exhaust", now))
+        return null;
+    const state = store.getTask(taskId)?.state;
+    return state !== undefined && isClosedState(state) ? state : null;
+}
+/**
+ * Check cleanup's claim (acp-check.ts settleChecks): the one road that may claim a closed task. Only the task bound to
+ * check `checkId`, when that check is this runner's, finished and unsettled, held right now by this cleanup `attempt`,
+ * and its task is the built-in one named from the check row's own id (store.ts checkCleanupTaskOf) — proved here, in
+ * the same transaction as the grant. Every other gate of the claim still applies. When the proof fails, the claim
+ * answers exactly as an ordinary one would: never wider.
+ */
+export function acquireForCheckCleanup(store, checkId, attempt, runner, options) {
+    return inTransaction(store, () => {
+        const proved = checkCleanupTaskOf(store, checkId, runner, attempt, options.now);
+        if (proved !== null)
+            return acquireLocked(store, proved, runner, options, "check-cleanup");
+        const bound = store.acpCheck(checkId)?.taskRef ?? null;
+        if (bound === null)
+            return { ok: false, reason: "no-task" };
+        return acquireLocked(store, bound, runner, options, "refuse");
+    });
+}

package/dist/contracts/chat-tables.js

@@ -26,6 +26,9 @@ CREATE TABLE IF NOT EXISTS chat_pair (
 );
 -- Everything an app sent us, once each (the key is the idempotency). kind 'update' is an applied (or pushed and
 -- waiting) Telegram update; 'message' is a message the lead answers, queued to running to done or failed.
+-- done means "no more work for the lead", not "the person has the reply": Telegram writes it once every part is sent,
+-- Slack, Discord and Teams when the reply is planned. result is a word from chat-message-states.ts; whether a reply
+-- reached the person is answered there by unsent(), from chat_part.
 -- session: the lead session its turn was dispatched under, a pointer to its receipt (never an authority).
 CREATE TABLE IF NOT EXISTS chat_event (
  ${PROVIDER}, id TEXT NOT NULL, installation TEXT NOT NULL, binding INTEGER,