toolroll 0.9.59 → 0.9.61

package/dist/store.js

@@ -11,6 +11,7 @@ import { trackWorkspaceWrites } from "./workspace-revision.js";
 import { parseStoreColumn, readStoreColumn, readStoreStringifiedList, readStoreTextList } from "./contracts/store-json.js";
 import { assessmentFromSavedEvidence, verificationEvidence } from "./verification-evidence.js";
 import { LEARNING_SCHEMA, queueLearning } from "./project-learning.js";
+import { AGENT_BOARD_SCHEMA, AGENT_NOW_COLUMNS, closeRunQuestions, mintAttemptKey, watchedPing } from "./agent-board.js";
 import { SKILLS_SCHEMA } from "./project-skills.js";
 import { KNOWLEDGE_SCHEMA } from "./project-knowledge.js";
 import { MEMORY_SCHEMA } from "./project-memory.js";
@@ -50,7 +51,7 @@ import { hashSecret, mintLeadToken, parseCredential, secretMatches, tokenPurpose
  * are deferred until after M4, and a column that exists to serve a feature
  * nobody has designed yet is a column that will be wrong when they do.
  */
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, statSync, unlinkSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname } from "node:path";
@@ -83,7 +84,7 @@ import { REQUEST_BUDGET_SCHEMA } from "./request-budget.js";
 import { REVIEW_SCHEMA, reviewSwitchWords } from "./review-switch.js";
 import { SPEND_SCHEMA, billingOf, budgetStates, canPrice, claudeMachineBilling, countsToward, filersOf, monthOf, priceWork, seenBilling as seenBillingOf, spendItems, subagentFilers, usd } from "./spend.js";
 import { DEFAULT_PERIODS, RETENTION_SCHEMA, periodWords, widenRetentionSchema } from "./retention.js";
-import { CHECKOUT_CLEANUP_SCHEMA, STORAGE_SWEEP_SCHEMA, DEFAULT_CLEANUP, cleanupWords } from "./storage.js";
+import { CHECKOUT_CLEANUP_SCHEMA, LANDED_CLEANUP_SCHEMA, STORAGE_SWEEP_SCHEMA, DEFAULT_CLEANUP, cleanupWords } from "./storage.js";
 import { IN_RANGE, LEDGER_CHAIN_SCHEMA, safeWhole, sealLedger, verifyLedgerChain } from "./ledger-chain.js";
 import { NO_RULES, filerFor, isProtectedWork, protectedChanges, rulesWords } from "./approval-policy.js";
 import { configBase, envValue, namedPath } from "./names.js";
@@ -354,6 +355,43 @@ CREATE TABLE IF NOT EXISTS run_activity (
   at   TEXT NOT NULL
 );
 `;
+/** Pausing a running Claude build (live steering, v121: additive only). A person's Pause asks the build to
+ * stop its current turn and keep its session: one row per request, bound to the exact run it was asked of, under the
+ * request id the asker chose (a repeated request is the same request). `note` is the steering note a Pause and steer
+ * sends right after the interrupt. The builder's dispatcher stamps sent_at when the interrupt is written, paused_at when
+ * the turn stopped, resumed_at when a later note continued the session, and ended_at when the run stopped taking input
+ * first. Never a stop: nothing here ends, holds or reclaims an attempt (run_stop does that). A person's Resume (run_resume)
+ * continues a paused build with a short continue frame and no note: one row per request, bound to the exact paused run;
+ * sent_at when the frame was written, ended_at when the run was no longer paused to take it. */
+export const LIVE_STEER_SCHEMA = `
+CREATE TABLE IF NOT EXISTS run_pause (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  run           INTEGER NOT NULL REFERENCES run(id) ON DELETE CASCADE,
+  task_ref      INTEGER NOT NULL REFERENCES task_ref(id) ON DELETE CASCADE,
+  request_id    TEXT NOT NULL UNIQUE,
+  requested_by  TEXT NOT NULL,
+  requested_via TEXT NOT NULL CHECK (requested_via IN ('cli','web','chat')),
+  requested_at  TEXT NOT NULL,
+  note          INTEGER REFERENCES task_steer(id) ON DELETE SET NULL,
+  sent_at       TEXT,
+  paused_at     TEXT,
+  resumed_at    TEXT,
+  ended_at      TEXT
+);
+CREATE INDEX IF NOT EXISTS run_pause_by_run ON run_pause (run, id);
+CREATE TABLE IF NOT EXISTS run_resume (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  run           INTEGER NOT NULL REFERENCES run(id) ON DELETE CASCADE,
+  task_ref      INTEGER NOT NULL REFERENCES task_ref(id) ON DELETE CASCADE,
+  request_id    TEXT NOT NULL UNIQUE,
+  requested_by  TEXT NOT NULL,
+  requested_via TEXT NOT NULL CHECK (requested_via IN ('cli','web','chat')),
+  requested_at  TEXT NOT NULL,
+  sent_at       TEXT,
+  ended_at      TEXT
+);
+CREATE INDEX IF NOT EXISTS run_resume_by_run ON run_resume (run, id);
+`;
 export const CHAT_APPROVAL_SCHEMA = `
 CREATE TABLE IF NOT EXISTS chat_approval_setting (
   approver             TEXT NOT NULL,
@@ -562,7 +600,12 @@ const REGISTERED_AT_FILING = "again, as it was filed";
 // v119 keeps planning generations: a rewritten scope starts a clean planning context (task_ref, run and plan_revision
 // carry planning_generation, 0 for all earlier history), and a question closed without an answer says why
 // (decision.superseded_reason: its task's scope changed, or the task was cancelled).
-export const SCHEMA_VERSION = 119;
+// v120 lets a running build read steering: a note the pulse put in the build's steering folder (task_steer.mailed_run,
+// mailed_at) and the moment the agent moved it to handled/ (acked_at).
+// v121 adds, and changes no saved row: the Agents board (run.attempt_key; agent_turn, agent_now, agent_question,
+// agent_seen, agent_view), live steering (a note's live identity and sends, a run's stdin session; run_pause and
+// run_resume) and landed work's teardown journal (landed_cleanup, landed_cleanup_item).
+export const SCHEMA_VERSION = 121;
 /** v118: the tables merged into `credential`, in the order they move (a person's API tokens keep their ids first). */
 export const V118_MERGED_TABLES = Object.freeze({ api_token: "person", coordinator_credential: "coordinator", lead_credential: "lead" });
 /** The foreign keys that named a merged table, exactly as their DDL wrote them; each names `credential(id)` instead. */
@@ -685,9 +728,11 @@ const V115_DROPPED_REFERENCES = /\s+REFERENCES (?:contestant|contest|tournament_
  * coordinator_credential and lead_credential moves into credential under its kind in one transaction that counts them
  * before the old tables drop, and the references that named them name credential in place, their rows untouched. v119 only adds four columns
  * (planning_generation on task_ref, run and plan_revision, defaulting to 0, and decision.superseded_reason, null);
- * the rehearsal checks every saved row reads the declared default (HISTORY_RULES' added columns).
+ * the rehearsal checks every saved row reads the declared default (HISTORY_RULES' added columns). v120 only adds
+ * three nullable task_steer columns (the running build's steering folder), checked the same way. v121 only adds
+ * new tables and the columns in V121_ADDED_COLUMNS (null, or no sends), checked the same way.
  */
-export const UPDATE_SAFE_MIGRATIONS = Object.freeze([108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119]);
+export const UPDATE_SAFE_MIGRATIONS = Object.freeze([108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121]);
 /** v119: the columns it adds, by table, with the value every row saved before it reads (toolroll-update's HISTORY_RULES). */
 export const V119_ADDED_COLUMNS = Object.freeze({
     task_ref: { planning_generation: { definition: "INTEGER NOT NULL DEFAULT 0", saved: "0" } },
@@ -695,6 +740,44 @@ export const V119_ADDED_COLUMNS = Object.freeze({
     plan_revision: { planning_generation: { definition: "INTEGER NOT NULL DEFAULT 0", saved: "0" } },
     decision: { superseded_reason: { definition: "TEXT CHECK (superseded_reason IN ('scope-changed','cancelled'))", saved: "NULL" } },
 });
+/** v120: the columns it adds, by table, with the value every row saved before it reads. */
+export const V120_ADDED_COLUMNS = Object.freeze({
+    task_steer: {
+        mailed_run: { definition: "INTEGER REFERENCES run(id)", saved: "NULL" },
+        mailed_at: { definition: "TEXT", saved: "NULL" },
+        acked_at: { definition: "TEXT", saved: "NULL" },
+    },
+    run: {
+        steer_opened_at: { definition: "TEXT", saved: "NULL" },
+        steer_closed_at: { definition: "TEXT", saved: "NULL" },
+    },
+});
+/**
+ * Live steering's added columns (v121), with the value every row saved before them reads. A note carries the identity
+ * its stdin copy is sent under (live_uuid, minted when it is filed), how many times it was sent to the running build
+ * and when last, and when it was given up on as not picked up.
+ * A run says when its stdin session opened and closed: only then can a note reach it in seconds, or a Pause stop a turn;
+ * and how long a paused session may wait before it ends (the idle limit; none under a wall-clock limit).
+ */
+export const LIVE_STEER_COLUMNS = Object.freeze({
+    task_steer: {
+        live_uuid: { definition: "TEXT", saved: "NULL" },
+        live_sends: { definition: "INTEGER NOT NULL DEFAULT 0", saved: "0" },
+        live_sent_at: { definition: "TEXT", saved: "NULL" },
+        live_missed_at: { definition: "TEXT", saved: "NULL" },
+    },
+    run: {
+        live_input_opened_at: { definition: "TEXT", saved: "NULL" },
+        live_input_closed_at: { definition: "TEXT", saved: "NULL" },
+        live_pause_limit_ms: { definition: "INTEGER", saved: "NULL" },
+    },
+});
+/** v121: the columns it adds, by table, with the value every row saved before it reads: live steering's, and a run's
+ * attempt key (the Agents board; runs admitted before it read none). Its new tables carry no saved rows. */
+export const V121_ADDED_COLUMNS = Object.freeze({
+    task_steer: LIVE_STEER_COLUMNS.task_steer,
+    run: { ...LIVE_STEER_COLUMNS.run, attempt_key: { definition: "TEXT", saved: "NULL" } },
+});
 /** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
 export function updateSafeSchema(version) {
     if (version === null || !Number.isSafeInteger(version) || version <= 0 || version > SCHEMA_VERSION)
@@ -2890,6 +2973,9 @@ CREATE TABLE IF NOT EXISTS review_request (
 -- rode toward; delivered_at settles only on the stream's own receipt (the
 -- agent's first words, or a successful completion). At-least-once, honestly
 -- labeled. Superseded means the task ended with the note still pending.
+-- v120 adds mailed_run, mailed_at and acked_at (V120_ADDED_COLUMNS): a note
+-- filed while a build runs is written into its steering folder, and is read
+-- (and delivered) only when that agent moves it to handled/.
 CREATE TABLE IF NOT EXISTS task_steer (
   id            INTEGER PRIMARY KEY AUTOINCREMENT,
   task_ref      INTEGER NOT NULL REFERENCES task_ref(id) ON DELETE CASCADE,
@@ -3422,6 +3508,11 @@ function initializeStore(db, file) {
     db.exec(CHAT_APPROVAL_SCHEMA);
     // What a running agent did last (no version bump: additive only; absent means no word yet).
     db.exec(RUN_ACTIVITY_SCHEMA);
+    // v121: the Agents board: each run's attempt key (V121_ADDED_COLUMNS, below), its turn history and current snapshot,
+    // the agent's open questions, who has seen a finished run and who is watching one now. Older runs read null keys.
+    db.exec(AGENT_BOARD_SCHEMA);
+    for (const [column, definition] of AGENT_NOW_COLUMNS)
+        addColumn(db, "agent_now", column, definition);
     // A flow's "Send to me" and "Person chooses" zones (no version bump: additive only).
     db.exec(FLOW_SEND_SCHEMA);
     db.exec(SPEND_SCHEMA);
@@ -3447,6 +3538,8 @@ function initializeStore(db, file) {
     db.exec(CHECKOUT_CLEANUP_SCHEMA);
     // The daily storage sweep's record (no version bump: a new table, nothing carried over).
     db.exec(STORAGE_SWEEP_SCHEMA);
+    // v121: landed work's teardown journal (landed-cleanup.ts): new tables.
+    db.exec(LANDED_CLEANUP_SCHEMA);
     db.exec(BACKUP_SCHEMA);
     // Sprint 8: the organisation policy (one row, or none: nothing restricted).
     db.exec(POLICY_SCHEMA);
@@ -3491,6 +3584,18 @@ function initializeStore(db, file) {
         for (const [column, { definition }] of Object.entries(columns))
             addColumn(db, table, column, definition);
     }
+    // v120: a running build's steering folder (additive only; saved notes read as never mailed).
+    for (const [table, columns] of Object.entries(V120_ADDED_COLUMNS)) {
+        for (const [column, { definition }] of Object.entries(columns))
+            addColumn(db, table, column, definition);
+    }
+    // v121: live steering and the Agents board's attempt key (additive only; saved notes read as never sent, saved runs as
+    // never taking input and keyless), and the pause and resume requests.
+    for (const [table, columns] of Object.entries(V121_ADDED_COLUMNS)) {
+        for (const [column, { definition }] of Object.entries(columns))
+            addColumn(db, table, column, definition);
+    }
+    db.exec(LIVE_STEER_SCHEMA);
     installLedgerTriggers(db);
     // Attention/history indexes come AFTER migration: on a database whose
     // constrained tables still carry a pre-rebuild shape, creating a partial
@@ -11742,6 +11847,8 @@ export class Store {
         // duplicate before any request is consumed.
         reviewAttempt);
         const id = Number(inserted.lastInsertRowid);
+        // The attempt key (Agents board): opaque, minted with the row, and the only key its stream state is recorded under.
+        this.db.prepare("UPDATE run SET attempt_key = ? WHERE id = ?").run(mintAttemptKey(), id);
         // The provenance row lands in the same transaction as the run row —
         // proved above, written here; a run and its route are one fact.
         this.writeRunRoute(id, stamp, run.now);
@@ -12057,6 +12164,8 @@ export class Store {
             // retained witnesses and every owned run; recovery revisits a pending
             // stop after an orphan finishes shutdown.
             this.recordRunProcessExits(id, result.now);
+            // An ended attempt's open questions close unanswered: a reply would reach no one.
+            closeRunQuestions(this, id, result.now);
             // Use the existing reconciliation proof now, while exits are fresh. In
             // particular, a returned --candidate check need not await the next scan.
             this.settleUnspawnedWitnesses(result.now, id);
@@ -12814,8 +12923,12 @@ export class Store {
     }
     /** What the agent did last on this run (live tasks): one fixed kind and when, replacing the last. */
     recordRunActivity(run, kind, now) {
-        this.db.prepare("INSERT INTO run_activity (run, kind, at) VALUES (?, ?, ?) ON CONFLICT (run) DO UPDATE SET kind = excluded.kind, at = excluded.at")
-            .run(run, kind, now.toISOString());
+        this.transact(() => {
+            this.db.prepare("INSERT INTO run_activity (run, kind, at) VALUES (?, ?, ?) ON CONFLICT (run) DO UPDATE SET kind = excluded.kind, at = excluded.at")
+                .run(run, kind, now.toISOString());
+            // Fresh activity is not Stuck: an open board hears the mark clear with this same write (agent-board.ts).
+            this.db.prepare("UPDATE agent_now SET stuck_at = NULL WHERE run = ? AND stuck_at IS NOT NULL").run(run);
+        });
     }
     /** A run's last recorded activity and its newest progress checkpoint's time, in one read. */
     runActivity(run) {
@@ -12991,13 +13104,19 @@ export class Store {
             const state = String(task["state"]);
             if (state === "done" || state === "cancelled")
                 return { ok: false, reason: "task-finished" };
-            const inserted = this.db
-                .prepare("INSERT INTO task_steer (task_ref, author, note, created_at, authorship_state) VALUES (?, ?, ?, ?, 'verified')")
-                .run(Number(ref["id"]), author, valid.note, now.toISOString());
+            const id = this.insertSteerNote(Number(ref["id"]), author, valid.note, now);
             this.bumpWake();
-            return { ok: true, id: Number(inserted.lastInsertRowid) };
+            return { ok: true, id };
         }), result => result.ok);
     }
+    /** One verified note, with the identity a running build's stdin copy is sent under: filing it is also what queues
+     * its live delivery, in the same transaction (the builder's dispatcher sends whatever is filed and unsent). */
+    insertSteerNote(taskRef, author, note, now) {
+        const inserted = this.db
+            .prepare("INSERT INTO task_steer (task_ref, author, note, created_at, authorship_state, live_uuid) VALUES (?, ?, ?, ?, 'verified', ?)")
+            .run(taskRef, author, note, now.toISOString(), randomUUID());
+        return Number(inserted.lastInsertRowid);
+    }
     /** Every steering note of a task, filing order, delivery state included. */
     listSteerNotes(taskRef) {
         return this.db
@@ -13048,11 +13167,12 @@ export class Store {
                 .all(taskRef, runId, live, live);
             const stamp = now.toISOString();
             for (const row of rows) {
+                // A brief that quotes it starts its live delivery over: an earlier build's sends and give-up are not this one's.
                 this.db
-                    .prepare("UPDATE task_steer SET attached_run = ?, attached_at = ? WHERE id = ?")
+                    .prepare("UPDATE task_steer SET attached_run = ?, attached_at = ?, live_sends = 0, live_sent_at = NULL, live_missed_at = NULL WHERE id = ?")
                     .run(runId, stamp, Number(row["id"]));
             }
-            return rows.map(row => readSteerNote({ ...row, attached_run: runId, attached_at: stamp }));
+            return rows.map(row => readSteerNote({ ...row, attached_run: runId, attached_at: stamp, live_sends: 0, live_sent_at: null, live_missed_at: null }));
         });
     }
     /**
@@ -13067,6 +13187,270 @@ export class Store {
             .run(now.toISOString(), runId);
         return Number(changes);
     }
+    /**
+     * The task's build whose agent is running right now and reads its steering
+     * folder (v120): the current live lease's open builder run, in its
+     * agent-running phase, whose steering folder is open. Null otherwise — a
+     * note then waits for the next attempt. Display state, never evidence.
+     */
+    steeringLiveBuild(taskRef, now) {
+        const live = this.currentLiveLease(taskRef, now);
+        if (live === null)
+            return null;
+        const row = this.db
+            .prepare(`SELECT id FROM run WHERE task_ref = ? AND lease_id = ? AND role = 'builder'
+            AND outcome IS NULL AND phase = 'agent-running' AND steer_opened_at IS NOT NULL AND steer_closed_at IS NULL
+          ORDER BY id DESC LIMIT 1`)
+            .get(taskRef, live);
+        return row === undefined ? null : Number(row["id"]);
+    }
+    /** This run made its steering folder (v120): its agent can read a note filed now. */
+    markSteerFolderOpened(runId, now) {
+        this.db.prepare("UPDATE run SET steer_opened_at = ? WHERE id = ? AND outcome IS NULL AND steer_opened_at IS NULL").run(now.toISOString(), runId);
+    }
+    /** This run's steering folder is gone (v120): a note filed now reaches the next attempt. */
+    markSteerFolderClosed(runId, now) {
+        this.db.prepare("UPDATE run SET steer_closed_at = ? WHERE id = ? AND steer_opened_at IS NOT NULL AND steer_closed_at IS NULL").run(now.toISOString(), runId);
+    }
+    /**
+     * The notes a RUNNING build may still read (v120): verified, pending, not
+     * already quoted in this run's brief, and not already in its folder. The
+     * pulse mails exactly these, in filing order.
+     */
+    mailableSteerNotes(taskRef, runId) {
+        return this.db
+            .prepare(`SELECT * FROM task_steer
+          WHERE task_ref = ? AND authorship_state = 'verified'
+            AND delivered_at IS NULL AND superseded_at IS NULL
+            AND (attached_run IS NULL OR attached_run <> ?)
+            AND (mailed_run IS NULL OR mailed_run <> ?)
+          ORDER BY id`)
+            .all(taskRef, runId, runId)
+            .map(readSteerNote);
+    }
+    /** The pulse wrote this note into the run's steering folder. Mailing is not
+     * reading: delivery settles only on the agent's own acknowledgement. */
+    markSteerMailed(noteId, runId, now) {
+        const { changes } = this.db
+            .prepare(`UPDATE task_steer SET mailed_run = ?, mailed_at = ?,
+            live_sends = CASE WHEN mailed_run IS ? THEN live_sends ELSE 0 END,
+            live_sent_at = CASE WHEN mailed_run IS ? THEN live_sent_at ELSE NULL END,
+            live_missed_at = CASE WHEN mailed_run IS ? THEN live_missed_at ELSE NULL END
+          WHERE id = ? AND delivered_at IS NULL AND superseded_at IS NULL`)
+            .run(runId, now.toISOString(), runId, runId, runId, noteId);
+        return Number(changes) > 0;
+    }
+    /**
+     * The agent moved this note to handled/ (v120): it was read, by THIS run.
+     * Acknowledgement is the only road from mailed to delivered — a hook firing
+     * or a file written proves nothing. First acknowledgement wins; a note the
+     * task already ended, or mailed to another run since, is left alone.
+     */
+    ackSteerNote(noteId, runId, now) {
+        const stamp = now.toISOString();
+        const { changes } = this.db
+            .prepare(`UPDATE task_steer SET acked_at = ?, delivered_at = ?, attached_run = ?, attached_at = COALESCE(mailed_at, ?)
+          WHERE id = ? AND mailed_run = ? AND acked_at IS NULL AND delivered_at IS NULL AND superseded_at IS NULL`)
+            .run(stamp, stamp, runId, stamp, noteId, runId);
+        if (Number(changes) > 0)
+            this.bumpWake();
+        return Number(changes) > 0;
+    }
+    /**
+     * The task's build that takes live input right now (live steering): the steering build (steeringLiveBuild) whose
+     * Claude session reads stdin. Only this run can take a note in seconds, or a Pause. Null otherwise.
+     */
+    liveInputRun(taskRef, now) {
+        const run = this.steeringLiveBuild(taskRef, now);
+        if (run === null)
+            return null;
+        const row = this.db.prepare("SELECT 1 FROM run WHERE id = ? AND live_input_opened_at IS NOT NULL AND live_input_closed_at IS NULL").get(run);
+        return row === undefined ? null : run;
+    }
+    /** This run's Claude session reads stdin now (live steering), and how long a paused session may wait (null: no idle limit). */
+    markLiveInputOpened(runId, now, pauseLimitMs = null) {
+        this.db.prepare("UPDATE run SET live_input_opened_at = ?, live_pause_limit_ms = ? WHERE id = ? AND outcome IS NULL AND live_input_opened_at IS NULL")
+            .run(now.toISOString(), pauseLimitMs === null || !Number.isSafeInteger(pauseLimitMs) || pauseLimitMs <= 0 ? null : pauseLimitMs, runId);
+    }
+    /** This run's stdin is closed (live steering): notes reach it only through its folder, and a Pause is over. */
+    markLiveInputClosed(runId, now) {
+        const stamp = now.toISOString();
+        this.transact(() => {
+            this.db.prepare("UPDATE run SET live_input_closed_at = ? WHERE id = ? AND live_input_opened_at IS NOT NULL AND live_input_closed_at IS NULL").run(stamp, runId);
+            this.db.prepare("UPDATE run_pause SET ended_at = ? WHERE run = ? AND ended_at IS NULL AND resumed_at IS NULL").run(stamp, runId);
+            this.db.prepare("UPDATE run_resume SET ended_at = ? WHERE run = ? AND sent_at IS NULL AND ended_at IS NULL").run(stamp, runId);
+        });
+    }
+    /** One steering note by id. */
+    steerNote(noteId) {
+        const row = this.db.prepare("SELECT * FROM task_steer WHERE id = ?").get(noteId);
+        return row === undefined ? null : readSteerNote(row);
+    }
+    /**
+     * The note's copy was written to this run's stdin (live steering): one more send, stamped. Sending is not reading —
+     * only the agent moving its file to handled/ is (ackSteerNote). Refused once the note is read, ended, given up on,
+     * or mailed to another run.
+     */
+    recordLiveSend(noteId, runId, now) {
+        const { changes } = this.db
+            .prepare(`UPDATE task_steer SET live_sends = live_sends + 1, live_sent_at = ?
+          WHERE id = ? AND mailed_run = ? AND delivered_at IS NULL AND superseded_at IS NULL AND live_missed_at IS NULL`)
+            .run(now.toISOString(), noteId, runId);
+        return Number(changes) > 0;
+    }
+    /** The running build was sent this note every time it is owed and never moved it to handled/: Not picked up. A later
+     * acknowledgement still reads it (ackSteerNote ignores this), and an attempt that ends returns it to the next brief. */
+    markLiveMissed(noteId, runId, now) {
+        const { changes } = this.db
+            .prepare("UPDATE task_steer SET live_missed_at = ? WHERE id = ? AND mailed_run = ? AND delivered_at IS NULL AND superseded_at IS NULL AND live_missed_at IS NULL")
+            .run(now.toISOString(), noteId, runId);
+        if (Number(changes) > 0)
+            this.bumpWake();
+        return Number(changes) > 0;
+    }
+    /**
+     * Pause a running Claude build, or Pause and steer it (live steering): asked of the exact run the person saw, under
+     * their request id. In one transaction the note (when there is one) is filed — Ruling 11's verified author — and the
+     * pause is queued ahead of it, so the dispatcher writes the interrupt before the note. A repeated request id is the
+     * same request; a run that no longer takes live input is stale. Pause never stops, holds or reclaims the attempt.
+     */
+    requestPause(request, now) {
+        return this.transact(() => {
+            const requestId = request.requestId.trim();
+            if (!/^[A-Za-z0-9._:-]{8,100}$/.test(requestId))
+                return { ok: false, reason: "invalid-request", detail: "the request id is 8 to 100 letters, digits or . _ : -" };
+            const seen = this.db.prepare("SELECT * FROM run_pause WHERE request_id = ?").get(requestId);
+            if (seen !== undefined) {
+                const pause = readPause(seen);
+                if (pause.run !== request.runId)
+                    return { ok: false, reason: "duplicate", detail: "that request id was already used for another attempt" };
+                return { ok: true, pause: pause.id, note: pause.note, duplicate: true };
+            }
+            const task = this.db.prepare("SELECT state FROM task WHERE id = ?").get(request.taskId);
+            const ref = this.db.prepare("SELECT id FROM task_ref WHERE backend = ? AND external_id = ?").get(BUILT_IN, request.taskId);
+            if (task === undefined || ref === undefined)
+                return { ok: false, reason: "unknown-task", detail: "no such task" };
+            const state = String(task["state"]);
+            if (state === "done" || state === "cancelled")
+                return { ok: false, reason: "task-finished", detail: "this task is finished" };
+            const taskRef = Number(ref["id"]);
+            if (this.liveInputRun(taskRef, now) !== request.runId) {
+                return { ok: false, reason: "stale", detail: `build #${request.runId} isn't taking live input now — reload and decide against the current attempt` };
+            }
+            let noteId = null;
+            if (request.note !== undefined) {
+                const valid = validateNote(request.note);
+                if (!valid.ok)
+                    return { ok: false, reason: "invalid-note", detail: valid.problem };
+                noteId = this.insertSteerNote(taskRef, request.by, valid.note, now);
+            }
+            const inserted = this.db
+                .prepare("INSERT INTO run_pause (run, task_ref, request_id, requested_by, requested_via, requested_at, note) VALUES (?, ?, ?, ?, ?, ?, ?)")
+                .run(request.runId, taskRef, requestId, request.by, request.via, now.toISOString(), noteId);
+            this.bumpWake();
+            return { ok: true, pause: Number(inserted.lastInsertRowid), note: noteId, duplicate: false };
+        });
+    }
+    /** The pauses this run has not yet written to stdin, in request order (the dispatcher writes these first). */
+    unsentPauses(runId) {
+        return this.db.prepare("SELECT * FROM run_pause WHERE run = ? AND sent_at IS NULL AND ended_at IS NULL ORDER BY id").all(runId).map(readPause);
+    }
+    /** The interrupt for this pause was written to the run's stdin. */
+    markPauseSent(pauseId, now) {
+        this.db.prepare("UPDATE run_pause SET sent_at = ? WHERE id = ? AND sent_at IS NULL AND ended_at IS NULL").run(now.toISOString(), pauseId);
+    }
+    /** The run's current turn stopped: every pause sent and still waiting reads paused. */
+    markRunPaused(runId, now) {
+        const changed = this.db.prepare("UPDATE run_pause SET paused_at = ? WHERE run = ? AND sent_at IS NOT NULL AND paused_at IS NULL AND resumed_at IS NULL AND ended_at IS NULL").run(now.toISOString(), runId);
+        if (Number(changed.changes) > 0)
+            this.bumpWake();
+    }
+    /** A note continued the paused session: its pauses are over. */
+    markRunResumed(runId, now) {
+        this.db.prepare("UPDATE run_pause SET resumed_at = ? WHERE run = ? AND sent_at IS NOT NULL AND resumed_at IS NULL AND ended_at IS NULL").run(now.toISOString(), runId);
+    }
+    /** The run could not take this pause (its stdin closed first). */
+    endPause(pauseId, now) {
+        this.db.prepare("UPDATE run_pause SET ended_at = ? WHERE id = ? AND ended_at IS NULL").run(now.toISOString(), pauseId);
+    }
+    /** Where this run's latest pause stands: asked and not yet stopped (pausing), stopped (paused), or none. */
+    pauseStateOf(runId) {
+        return this.livePauseOf(runId)?.state ?? null;
+    }
+    /** This run's latest pause, when it paused, and how long a paused build may wait before it ends; null with none. */
+    livePauseOf(runId) {
+        const row = this.db.prepare(`SELECT p.paused_at, r.live_pause_limit_ms FROM run_pause p JOIN run r ON r.id = p.run
+        WHERE p.run = ? AND p.resumed_at IS NULL AND p.ended_at IS NULL ORDER BY p.id DESC LIMIT 1`).get(runId);
+        if (row === undefined)
+            return null;
+        const pausedAt = row["paused_at"] === null ? null : String(row["paused_at"]);
+        const limit = row["live_pause_limit_ms"] === null || row["live_pause_limit_ms"] === undefined ? null : Number(row["live_pause_limit_ms"]);
+        return { state: pausedAt === null ? "pausing" : "paused", pausedAt, limitMs: limit };
+    }
+    /**
+     * Resume a paused Claude build (live steering): asked of the exact run the person saw, under their request id, and
+     * only while that run is paused. The dispatcher sends a short continue frame — never a note, so nothing is filed.
+     * A repeated request id is the same request; a run that no longer takes live input is stale.
+     */
+    requestResume(request, now) {
+        return this.transact(() => {
+            const requestId = request.requestId.trim();
+            if (!/^[A-Za-z0-9._:-]{8,100}$/.test(requestId))
+                return { ok: false, reason: "invalid-request", detail: "the request id is 8 to 100 letters, digits or . _ : -" };
+            const seen = this.db.prepare("SELECT id, run FROM run_resume WHERE request_id = ?").get(requestId);
+            if (seen !== undefined) {
+                if (Number(seen["run"]) !== request.runId)
+                    return { ok: false, reason: "duplicate", detail: "that request id was already used for another attempt" };
+                return { ok: true, resume: Number(seen["id"]), duplicate: true };
+            }
+            const task = this.db.prepare("SELECT state FROM task WHERE id = ?").get(request.taskId);
+            const ref = this.db.prepare("SELECT id FROM task_ref WHERE backend = ? AND external_id = ?").get(BUILT_IN, request.taskId);
+            if (task === undefined || ref === undefined)
+                return { ok: false, reason: "unknown-task", detail: "no such task" };
+            const state = String(task["state"]);
+            if (state === "done" || state === "cancelled")
+                return { ok: false, reason: "task-finished", detail: "this task is finished" };
+            const taskRef = Number(ref["id"]);
+            if (this.liveInputRun(taskRef, now) !== request.runId) {
+                return { ok: false, reason: "stale", detail: `build #${request.runId} isn't taking live input now — reload and decide against the current attempt` };
+            }
+            if (this.pauseStateOf(request.runId) !== "paused")
+                return { ok: false, reason: "not-paused", detail: `build #${request.runId} isn't paused` };
+            const inserted = this.db
+                .prepare("INSERT INTO run_resume (run, task_ref, request_id, requested_by, requested_via, requested_at) VALUES (?, ?, ?, ?, ?, ?)")
+                .run(request.runId, taskRef, requestId, request.by, request.via, now.toISOString());
+            this.bumpWake();
+            return { ok: true, resume: Number(inserted.lastInsertRowid), duplicate: false };
+        });
+    }
+    /** The resumes this run has not yet sent, in request order. */
+    unsentResumes(runId) {
+        return this.db.prepare("SELECT id, request_id FROM run_resume WHERE run = ? AND sent_at IS NULL AND ended_at IS NULL ORDER BY id").all(runId)
+            .map(row => ({ id: Number(row["id"]), requestId: String(row["request_id"]) }));
+    }
+    /** The continue frame was written: the resume is sent, and the run's pauses are over. */
+    markResumeSent(resumeId, runId, now) {
+        this.transact(() => {
+            this.db.prepare("UPDATE run_resume SET sent_at = ? WHERE id = ? AND sent_at IS NULL AND ended_at IS NULL").run(now.toISOString(), resumeId);
+            this.markRunResumed(runId, now);
+        });
+        this.bumpWake();
+    }
+    /** The run was no longer paused (a note continued it first) or stopped taking input: nothing to send. */
+    endResume(resumeId, now) {
+        this.db.prepare("UPDATE run_resume SET ended_at = ? WHERE id = ? AND sent_at IS NULL AND ended_at IS NULL").run(now.toISOString(), resumeId);
+    }
+    /** Every resume of a task, newest first (history and tests). */
+    resumesForTask(taskRef) {
+        return this.db.prepare("SELECT * FROM run_resume WHERE task_ref = ? ORDER BY id DESC").all(taskRef).map(row => ({
+            id: Number(row["id"]), run: Number(row["run"]), requestId: String(row["request_id"]), requestedVia: String(row["requested_via"]),
+            sentAt: row["sent_at"] === null ? null : String(row["sent_at"]), endedAt: row["ended_at"] === null ? null : String(row["ended_at"]),
+        }));
+    }
+    /** Every pause of a task, newest first (history and tests). */
+    pausesForTask(taskRef) {
+        return this.db.prepare("SELECT * FROM run_pause WHERE task_ref = ? ORDER BY id DESC").all(taskRef).map(readPause);
+    }
     /** A finished task's pending notes settle superseded — shown, typed, done. */
     supersedeSteerNotes(taskRef, now) {
         const { changes } = this.db
@@ -17353,10 +17737,24 @@ export class Store {
                     this.db.prepare("UPDATE push_delivery SET state = 'retired', last_error = ? WHERE id = ? AND state = 'pending'")
                         .run(elsewhere ? TELEGRAM_SKIPPED_OTHER_CHAT : "quiet", Number(raw["pair"]));
                 }
+                else
+                    this.settleWatchedPush(Number(raw["pair"]), readNotification(raw), String(raw["approver"]), now);
             }
         }
         return Number(changes);
     }
+    /** A pending pair about a run its person is watching waits for the watch to lapse; one about a finished run they have
+     * since seen retires unsent (agent-board.ts watchedPing). False when the pair must not be sent now. */
+    settleWatchedPush(pair, row, approver, now) {
+        const decided = watchedPing(this, row, approver, now);
+        if (decided === "send")
+            return true;
+        if (decided === "skip")
+            this.db.prepare("UPDATE push_delivery SET state = 'retired', last_error = 'seen' WHERE id = ? AND state = 'pending'").run(pair);
+        else
+            this.db.prepare("UPDATE push_delivery SET next_attempt_at = ? WHERE id = ? AND state = 'pending'").run(decided.hold, pair);
+        return false;
+    }
     /**
      * Claim due pairs: pending (respecting next_attempt_at) or claimed-but-
      * expired (reclaim bumps the generation — the old owner loses every
@@ -17375,6 +17773,11 @@ export class Store {
                 .map(row => Number(row["id"]));
             const taken = [];
             for (const id of due) {
+                // A ping held while its person watched the run is decided again now: held on, retired, or sent.
+                const watched = this.db.prepare(`SELECT n.*, s.approver AS approver FROM push_delivery p JOIN push_subscription s ON s.id = p.subscription
+          JOIN notification n ON n.id = p.notification WHERE p.id = ? AND p.state = 'pending'`).get(id);
+                if (watched !== undefined && !this.settleWatchedPush(id, readNotification(watched), String(watched["approver"]), now))
+                    continue;
                 const { changes } = this.db
                     .prepare(`UPDATE push_delivery SET state = 'claimed', claim_owner = ?, claim_expires_at = ?,
                                       claim_generation = claim_generation + 1
@@ -17649,6 +18052,30 @@ function readSteerNote(row) {
         supersededAt: row["superseded_at"] === null ? null : String(row["superseded_at"]),
         authorshipState: row["authorship_state"] === "verified" ? "verified" : "unverified-legacy",
         supersededReason: row["superseded_reason"] === null || row["superseded_reason"] === undefined ? null : String(row["superseded_reason"]),
+        mailedRun: row["mailed_run"] === null || row["mailed_run"] === undefined ? null : Number(row["mailed_run"]),
+        mailedAt: row["mailed_at"] === null || row["mailed_at"] === undefined ? null : String(row["mailed_at"]),
+        ackedAt: row["acked_at"] === null || row["acked_at"] === undefined ? null : String(row["acked_at"]),
+        liveUuid: row["live_uuid"] === null || row["live_uuid"] === undefined ? null : String(row["live_uuid"]),
+        liveSends: Number(row["live_sends"] ?? 0),
+        liveSentAt: row["live_sent_at"] === null || row["live_sent_at"] === undefined ? null : String(row["live_sent_at"]),
+        liveMissedAt: row["live_missed_at"] === null || row["live_missed_at"] === undefined ? null : String(row["live_missed_at"]),
+    };
+}
+function readPause(row) {
+    const text = (key) => row[key] === null || row[key] === undefined ? null : String(row[key]);
+    return {
+        id: Number(row["id"]),
+        run: Number(row["run"]),
+        taskRef: Number(row["task_ref"]),
+        requestId: String(row["request_id"]),
+        requestedBy: String(row["requested_by"]),
+        requestedVia: String(row["requested_via"]),
+        requestedAt: String(row["requested_at"]),
+        note: row["note"] === null || row["note"] === undefined ? null : Number(row["note"]),
+        sentAt: text("sent_at"),
+        pausedAt: text("paused_at"),
+        resumedAt: text("resumed_at"),
+        endedAt: text("ended_at"),
     };
 }
 function readDecision(row) {

package/dist/surface.js

@@ -201,7 +201,7 @@ const GUIDE_ROWS = [
     ...["show", "updates", "claim", "check", "brief", "inbox", "ack"].map(action => ({
         invocation: `assignment ${action}`,
         synopsis: action === "show" ? "read the root, current work, owner and exact receipt"
-            : action === "updates" ? "read durable updates after a cursor; save nextCursor after processing"
+            : action === "updates" ? "read the history of handoffs sent to people after a cursor; delivers nothing — receive updates with assignment inbox"
                 : action === "claim" ? "record lead ownership; with the lead token the task reads \"<the lead's name> is on it\" and leaves Needs you until done, handed over, or 2 hours idle; grants no approval or execution authority"
                     : action === "brief" ? "catch up from current assignments and project knowledge in the local database"
                         : action === "inbox" ? "receive or replay a saved batch of lead status updates"
@@ -242,7 +242,9 @@ const GUIDE_ROWS = [
         positionals: [{ name: "id", required: true, meaning: "the task" }],
         flags: [jsonFlag, dbFlag, keyFlag, { name: "undo", takesValue: false, meaning: "back to filing order" }],
         notableReasons: ["unknown-task", "claimed"] },
-    operator("task steer", "one credentialed note read before the task's next attempt — steering speaks with the operator's voice"),
+    operator("task steer", "one credentialed note for the task's agent — a running Claude build gets it in seconds, another running build reads it when it next checks for notes, otherwise the next attempt does; --now pauses the running Claude build first; steering speaks with the operator's voice"),
+    operator("task pause", "stop a running Claude build's current turn and keep the build (--run <id> names the attempt): its next note continues it; never a stop"),
+    operator("task continue", "resume a paused Claude build where it stopped, without a note (--run <id> names the attempt)"),
     { invocation: "task assign", synopsis: "reserve a task for one worker, or return it to the shared queue", audience: "agent", agentMayInvoke: true, mutation: "keyed",
         positionals: [{ name: "id", required: true, meaning: "the task" }],
         flags: [jsonFlag, dbFlag, keyFlag,
@@ -449,7 +451,7 @@ const REMOTE_STEP_UP = [
 const REMOTE_YES = [
     "status", "integrations", "ready", "gaps", "grants", "sync", "audit",
     "task add", "task ask", "task checks", "task add-tests", "task list", "task show", "check-progress", "task wait", "task complete", "task revise",
-    "task state", "task block", "task unblock", "task next", "task steer", "task assign", "task scope", "task plan", "task hold", "task unhold", "task require",
+    "task state", "task block", "task unblock", "task next", "task steer", "task pause", "task continue", "task assign", "task scope", "task plan", "task hold", "task unhold", "task require",
     "task requeue", "task review", "task repair", "task route", "task reopen", "task stop", "task resume",
     "runner list", "coordinator list", "cap list", "cap add", "outbox list", "incident list", "incident resolve",
     "config show", "verify show", "intake show", "intake run", "intake preview", "intake pr-comments", "template list", "template show",

package/dist/sweep-gate.d.ts

@@ -0,0 +1,10 @@
+/** Assignment sweeps re-project every owned root on each pass. A pass is
+ * skipped when nothing has moved since the last full cycle began: the store's
+ * wake sequence is unchanged and that cycle started under a minute ago. The
+ * minute covers changes that don't bump wake (time-based lease expiry, some
+ * ledger-only writes). A cycle in progress (its cursor past 0) always goes on,
+ * and a restarted process sweeps at once. */
+import type { Store } from "./store.js";
+export declare const SWEEP_FALLBACK_MS = 60000;
+/** Runs `sweep` unless the cycle under `cursorKey` would see what its last start saw. Returns whether it ran. */
+export declare function sweepIfMoved(store: Store, cursorKey: string, now: Date, sweep: () => void): boolean;