toolroll 0.9.60 → 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,
@@ -564,7 +602,10 @@ const REGISTERED_AT_FILING = "again, as it was filed";
 // (decision.superseded_reason: its task's scope changed, or the task was cancelled).
 // 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).
-export const SCHEMA_VERSION = 120;
+// 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. */
@@ -688,9 +729,10 @@ const V115_DROPPED_REFERENCES = /\s+REFERENCES (?:contestant|contest|tournament_
  * 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). v120 only adds
- * three nullable task_steer columns (the running build's steering folder), checked the same way.
+ * 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, 120]);
+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" } },
@@ -710,6 +752,32 @@ export const V120_ADDED_COLUMNS = Object.freeze({
         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)
@@ -3440,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);
@@ -3465,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);
@@ -3514,6 +3589,13 @@ function initializeStore(db, file) {
         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
@@ -11765,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);
@@ -12080,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);
@@ -12837,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) {
@@ -13014,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
@@ -13071,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 }));
         });
     }
     /**
@@ -13135,9 +13232,12 @@ export class Store {
      * 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 = ?
+            .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(), noteId);
+            .run(runId, now.toISOString(), runId, runId, runId, noteId);
         return Number(changes) > 0;
     }
     /**
@@ -13156,6 +13256,201 @@ export class Store {
             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
@@ -17442,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
@@ -17464,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
@@ -17741,6 +18055,27 @@ function readSteerNote(row) {
         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

@@ -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 for the task's agent — a running build reads it when it next checks for notes, otherwise the next attempt does; 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-quarantine.d.ts

@@ -0,0 +1,28 @@
+export declare const QUARANTINE_NOTE = ".toolroll-sweep.json";
+type Journal<T> = {
+    version: 1;
+    name: string;
+    data: T;
+    deleting: boolean;
+    pid: number;
+    host: string;
+    bootId: string | null;
+};
+export type Quarantine<T> = {
+    path: string;
+    original: string;
+    journal: Journal<T>;
+};
+export declare function quarantineEntries<T>(root: string): Quarantine<T>[];
+/** A small marker closes discovery before the atomic rename. It is never published half-written. */
+export declare function quarantine<T>(original: string, data: T): Quarantine<T> | null;
+/** Returns null if another sweep owns it (or won recovery). */
+export declare function claimQuarantine<T>(entry: Quarantine<T>): Quarantine<T> | null;
+export declare function releaseQuarantine<T>(entry: Quarantine<T>): void;
+/** A partially deleted tree must never become discoverable again. */
+export declare function restoreQuarantine<T>(entry: Quarantine<T>): boolean;
+/** Keep the journal until all potentially large removals succeeded. Recovery never guesses at a half-deleted tree. */
+export declare function deleteQuarantine<T>(entry: Quarantine<T>, remove: (path: string) => void | Promise<void>): Promise<void>;
+/** Staged pruning is also called synchronously by update/deploy. */
+export declare function deleteQuarantineSync<T>(entry: Quarantine<T>, remove: (path: string) => void): void;
+export {};