toolroll 0.9.58 → 0.9.60

package/dist/store.js

@@ -559,7 +559,12 @@ const REGISTERED_AT_FILING = "again, as it was filed";
 // v118 (D7) keeps every machine credential in one table, `credential`: a person's API tokens (so_…), the lead's tokens
 // (lt_…) and coordinators, each with its kind, read/act access, project limit, expiry, revocation and generation. Every
 // row moves with its id, hash and dates; the references to coordinators and API tokens point at it.
-export const SCHEMA_VERSION = 118;
+// 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).
+// 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;
 /** 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. */
@@ -680,9 +685,31 @@ const V115_DROPPED_REFERENCES = /\s+REFERENCES (?:contestant|contest|tournament_
  * teammates' to its subagents' (SQLite's RENAME, every row, id and link carried), renames their teammate column, and rewrites four internal kinds from 'teammate' to 'subagent' in place; the rehearsal checks
  * each renamed table's rows arrived under its new name. v118 (D7) is checked the same way: every row of api_token,
  * 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.
+ * 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.
  */
-export const UPDATE_SAFE_MIGRATIONS = Object.freeze([108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118]);
+export const UPDATE_SAFE_MIGRATIONS = Object.freeze([108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120]);
+/** 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" } },
+    run: { planning_generation: { definition: "INTEGER NOT NULL DEFAULT 0", saved: "0" } },
+    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" },
+    },
+});
 /** 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)
@@ -2878,6 +2905,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,
@@ -3474,6 +3504,16 @@ function initializeStore(db, file) {
     // v115: the task each standing-order firing filed, kept on the firing itself (a card's task changes as it moves).
     addColumn(db, "flow_trigger_event", "task", "TEXT");
     db.exec(PLAN_AUTO_SCHEMA);
+    // v119: planning generations, and why a question closed unanswered (additive only; saved rows read the defaults).
+    for (const [table, columns] of Object.entries(V119_ADDED_COLUMNS)) {
+        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);
+    }
     installLedgerTriggers(db);
     // Attention/history indexes come AFTER migration: on a database whose
     // constrained tables still carry a pre-rebuild shape, creating a partial
@@ -4796,6 +4836,10 @@ export class Store {
         // just the state verb's.
         if (ref !== undefined)
             this.supersedeSteerNotes(Number(ref["id"]), now);
+        // Its open questions close the same way (v119), typed 'cancelled', with their holds and pages: a question about
+        // work that will never run must leave every decision queue. Answered ones stay exactly as they were.
+        if (ref !== undefined)
+            this.closeQuestionsLocked(Number(ref["id"]), "cancelled", now);
         // The reason is part of the transition, not decoration: a
         // coordinator-filed task's dismissal writes its durable event IN THIS
         // transaction — operator text and typed machine codes alike (MCP spec
@@ -9942,6 +9986,66 @@ export class Store {
             return { ok: true };
         });
     }
+    /**
+     * A rewritten scope starts planning again (v119), in one transaction: the task's planning generation advances, a
+     * requested or drafted plan becomes requested with no strikes, and what the old goal produced leaves the active
+     * planning context — its open questions close (typed 'scope-changed', never a fake answer, their holds and pages
+     * with them) and a revision still waiting for a person is rejected with its hold. The old runs, plans, revisions,
+     * answers and ledger rows all stay: generation-bound reads simply stop offering them to the next planner. Only a
+     * task already planning restarts; false (nothing changed) for any other.
+     */
+    restartPlanning(taskRef, now) {
+        return this.transact(() => {
+            const moved = this.db
+                .prepare("UPDATE task_ref SET planning_generation = planning_generation + 1, plan = 'requested', plan_strikes = 0 WHERE id = ? AND plan IN ('requested','drafted')")
+                .run(taskRef);
+            if (Number(moved.changes) === 0)
+                return false;
+            const ref = this.db.prepare("SELECT external_id, repo, planning_generation FROM task_ref WHERE id = ?").get(taskRef);
+            const generation = Number(ref["planning_generation"]);
+            this.closeQuestionsLocked(taskRef, "scope-changed", now, generation);
+            const blocked = this.db
+                .prepare("SELECT id FROM plan_revision WHERE task_ref = ? AND status = 'blocked' AND planning_generation < ?")
+                .all(taskRef, generation)
+                .map(row => Number(row["id"]));
+            for (const id of blocked) {
+                this.resolvePlanRevision(id, "rejected", "toolroll", now);
+                this.releaseOwnedHold("revision", String(id));
+            }
+            this.recordAction({
+                at: now.toISOString(), actor: currentActor() === null ? "system" : actorLabel(currentActor()), repo: ref["repo"] === null ? null : String(ref["repo"]),
+                taskId: String(ref["external_id"]), runId: null, action: "planning restarted", outcome: "scope changed", source: "work",
+            });
+            this.bumpWake();
+            return true;
+        });
+    }
+    /**
+     * Close a task's open and expired questions without answering them (v119): typed with why, no choice, their
+     * holds lifted and their pages resolved, so they leave every decision queue. Answered questions are never touched.
+     * `belowGeneration` limits it to questions asked in earlier planning generations. Caller holds the transaction.
+     */
+    closeQuestionsLocked(taskRef, reason, now, belowGeneration) {
+        const ids = this.db
+            .prepare(`SELECT decision.id FROM decision JOIN run ON run.id = decision.run
+          WHERE run.task_ref = ? AND decision.state IN ('open','expired') AND (? IS NULL OR run.planning_generation < ?)
+          ORDER BY decision.id`)
+            .all(taskRef, belowGeneration ?? null, belowGeneration ?? null)
+            .map(row => Number(row["id"]));
+        const close = this.db.prepare("UPDATE decision SET state = 'answered', answered_at = ?, answered_by = 'toolroll', superseded_reason = ? WHERE id = ? AND state IN ('open','expired')");
+        for (const id of ids) {
+            close.run(now.toISOString(), reason, id);
+            this.releaseOwnedHold("decision", String(id));
+            this.resolveEpisode(`decision:${id}`, now);
+        }
+        return ids;
+    }
+    /** The number the next plan revision of a task takes: one past every revision it ever had, in any planning
+     * generation, so a restarted plan's revisions never collide with the history they follow. */
+    nextPlanRevisionNumber(taskRef) {
+        const row = this.db.prepare("SELECT coalesce(max(revision), 0) AS n FROM plan_revision WHERE task_ref = ?").get(taskRef);
+        return Number(row?.["n"] ?? 0) + 1;
+    }
     /** Move the planning state; null clears it. Caller owns the transaction story. */
     setPlanState(taskRef, state) {
         this.db.prepare("UPDATE task_ref SET plan = ? WHERE id = ?").run(state, taskRef);
@@ -11653,8 +11757,8 @@ export class Store {
             })();
         const inserted = this.db
             .prepare(`INSERT INTO run (task_ref, lease_id, runner, branch, worktree, model, role, provider, parent_run, session_id, quality_mode,
-                          started_at, review_attempt)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                          started_at, review_attempt, planning_generation)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, (SELECT planning_generation FROM task_ref WHERE id = ?1))`)
             .run(run.taskRef, run.leaseId, run.runner, run.branch ?? null, run.worktree ?? null, model, role, provider ?? "claude", run.parentRun ?? null, run.sessionId ?? null, qualityMode, run.now.toISOString(), 
         // The root reviewer's ordinal (v50) rides the insert: a root and
         // its attempt number are one fact, and the ordinal index refuses a
@@ -12599,12 +12703,14 @@ export class Store {
      * reads in the order the questions arrived. "unanswered" is open + expired:
      * expiry makes a decision louder, never gone.
      */
-    /** The newest planner run's plan document for a task, when one exists. */
+    /** The newest planner run's plan document for a task, when one exists in its current planning generation (v119:
+     * a plan drafted for a scope since rewritten is history, read by its artifact id). */
     latestPlanArtifact(taskRef) {
         const row = this.db
             .prepare(`SELECT artifact.* FROM artifact
          JOIN run ON run.id = artifact.run
          WHERE run.task_ref = ? AND run.role = 'planner' AND artifact.kind = 'plan'
+           AND run.planning_generation = (SELECT planning_generation FROM task_ref WHERE id = run.task_ref)
          ORDER BY artifact.id DESC LIMIT 1`)
             .get(taskRef);
         return row === undefined ? null : readArtifact(row);
@@ -12619,6 +12725,7 @@ export class Store {
          JOIN run ON run.id = artifact.run
          WHERE run.task_ref = ? AND run.role = 'planner' AND artifact.kind = 'plan-contract'
            AND artifact.key LIKE '%/plan-contract.json'
+           AND run.planning_generation = (SELECT planning_generation FROM task_ref WHERE id = run.task_ref)
          ORDER BY artifact.id DESC LIMIT 1`)
             .get(taskRef);
         return row === undefined ? null : readArtifact(row);
@@ -12646,16 +12753,17 @@ export class Store {
         const inserted = this.db
             .prepare(`INSERT INTO plan_revision
            (task_ref, revision, artifact, parent_hash, reason, evidence_link, author, origin_run,
-            kind, authority_kind, authority_digest, changed_fields, status, created_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            kind, authority_kind, authority_digest, changed_fields, status, created_at, planning_generation)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, (SELECT planning_generation FROM task_ref WHERE id = ?1))`)
             .run(revision.taskRef, revision.revision, revision.artifact, revision.parentHash, revision.reason, revision.evidenceLink, revision.author, revision.originRun, revision.kind, revision.authorityKind, revision.authorityDigest, JSON.stringify(revision.changedFields), revision.status, now.toISOString());
         return Number(inserted.lastInsertRowid);
     }
-    /** Every revision for a task, newest first — the immutable history a
-     * reader can show without a second table. */
+    /** Every revision for a task in its current planning generation, newest
+     * first — the immutable history a reader can show without a second table
+     * (v119: an earlier generation's rows stay, read by id). */
     listPlanRevisions(taskRef) {
         return this.db
-            .prepare("SELECT * FROM plan_revision WHERE task_ref = ? ORDER BY revision DESC")
+            .prepare("SELECT * FROM plan_revision WHERE task_ref = ? AND planning_generation = (SELECT planning_generation FROM task_ref WHERE id = plan_revision.task_ref) ORDER BY revision DESC")
             .all(taskRef)
             .map(readPlanRevision);
     }
@@ -12666,7 +12774,7 @@ export class Store {
      * `latestPlanArtifact`'s synthetic revision 1 in both cases. */
     currentPlanRevision(taskRef) {
         const row = this.db
-            .prepare("SELECT * FROM plan_revision WHERE task_ref = ? AND status = 'applied' ORDER BY revision DESC LIMIT 1")
+            .prepare("SELECT * FROM plan_revision WHERE task_ref = ? AND planning_generation = (SELECT planning_generation FROM task_ref WHERE id = plan_revision.task_ref) AND status = 'applied' ORDER BY revision DESC LIMIT 1")
             .get(taskRef);
         return row === undefined ? null : readPlanRevision(row);
     }
@@ -12674,7 +12782,7 @@ export class Store {
      * 'blocked' awaiting an operator's decision — what a reader shows
      * alongside the current one to render a pending proposal at all. */
     latestPlanRevision(taskRef) {
-        const row = this.db.prepare("SELECT * FROM plan_revision WHERE task_ref = ? ORDER BY revision DESC LIMIT 1").get(taskRef);
+        const row = this.db.prepare("SELECT * FROM plan_revision WHERE task_ref = ? AND planning_generation = (SELECT planning_generation FROM task_ref WHERE id = plan_revision.task_ref) ORDER BY revision DESC LIMIT 1").get(taskRef);
         return row === undefined ? null : readPlanRevision(row);
     }
     getPlanRevision(id) {
@@ -12762,7 +12870,8 @@ export class Store {
             .get(taskRef);
         return row === undefined ? null : readArtifact(row);
     }
-    /** Answered questions for one task, newest first — the planner's memory. */
+    /** Answered questions for one task, newest first — the planner's memory. Only real answers from its current
+     * planning generation (v119): a question closed unanswered, or asked about a scope since rewritten, is history. */
     answeredDecisionsFor(taskId, limit = 5) {
         return this.db
             .prepare(`SELECT decision.question, decision.choice, decision.note
@@ -12770,7 +12879,8 @@ export class Store {
          JOIN run ON run.id = decision.run
          JOIN task_ref ON task_ref.id = run.task_ref
          WHERE task_ref.backend = ? AND task_ref.external_id = ?
-           AND decision.answered_at IS NOT NULL
+           AND decision.answered_at IS NOT NULL AND decision.superseded_reason IS NULL
+           AND run.planning_generation = task_ref.planning_generation
          ORDER BY decision.answered_at DESC, decision.id DESC LIMIT ?`)
             .all(BUILT_IN, taskId, Math.max(1, Math.min(Math.floor(limit), 20)))
             .map(row => ({
@@ -12869,6 +12979,9 @@ export class Store {
          JOIN task_ref ON task_ref.id = run.task_ref
          WHERE run.task_ref = ? AND decision.state = 'answered'
            AND decision.contestant IS NULL
+           -- v119: a question closed unanswered carries no answer, and one asked about a rewritten scope is history.
+           AND decision.superseded_reason IS NULL
+           AND run.planning_generation = task_ref.planning_generation
            AND NOT EXISTS (
              SELECT 1 FROM run_decision
              JOIN run AS delivered ON delivered.id = run_decision.run
@@ -12977,6 +13090,72 @@ 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 = ?
+          WHERE id = ? AND delivered_at IS NULL AND superseded_at IS NULL`)
+            .run(runId, now.toISOString(), 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;
+    }
     /** A finished task's pending notes settle superseded — shown, typed, done. */
     supersedeSteerNotes(taskRef, now) {
         const { changes } = this.db
@@ -13022,6 +13201,9 @@ export class Store {
         const existing = this.getDecision(answer.id);
         if (existing === null)
             return { ok: false, reason: "unknown-decision" };
+        // A question closed without an answer (v119) stays closed: its task's scope changed or the task was cancelled.
+        if (existing.supersededReason !== null)
+            return { ok: false, reason: "closed" };
         if (!existing.options.some(option => option.id === answer.choice)) {
             return { ok: false, reason: "bad-option" };
         }
@@ -17443,6 +17625,7 @@ function readRun(row) {
         taskRef: Number(row["task_ref"]),
         leaseId: String(row["lease_id"]),
         runner: String(row["runner"]),
+        planningGeneration: Number(row["planning_generation"] ?? 0),
         watchIncarnation: row["watch_incarnation"] == null ? null : String(row["watch_incarnation"]),
         reviewAttempt: wholeNumber(row["review_attempt"]),
         role: String(row["role"] ?? "builder"),
@@ -17555,6 +17738,9 @@ 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"]),
     };
 }
 function readDecision(row) {
@@ -17575,6 +17761,7 @@ function readDecision(row) {
         answeredVia: row["answered_via"] === null ? null : String(row["answered_via"]),
         choice: row["choice"] === null ? null : String(row["choice"]),
         note: row["note"] === null ? null : String(row["note"]),
+        supersededReason: row["superseded_reason"] === "scope-changed" || row["superseded_reason"] === "cancelled" ? row["superseded_reason"] : null,
     };
 }
 function readArtifact(row) {
@@ -17762,6 +17949,7 @@ function readTaskRef(row) {
             ? null
             : String(row["plan"]),
         planStrikes: Number(row["plan_strikes"] ?? 0),
+        planningGeneration: Number(row["planning_generation"] ?? 0),
         deliverable: row["deliverable"] === "report" ? "report" : "branch",
         strikes: Number(row["strikes"] ?? 0),
         agentProvider: row["agent_provider"] === null || row["agent_provider"] === undefined

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,7 @@ 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 build reads it when it next checks for notes, otherwise the next attempt does; steering speaks with the operator's voice"),
     { 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,

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;

package/dist/sweep-gate.js

@@ -0,0 +1,18 @@
+export const SWEEP_FALLBACK_MS = 60_000;
+const cycles = new WeakMap();
+/** Runs `sweep` unless the cycle under `cursorKey` would see what its last start saw. Returns whether it ran. */
+export function sweepIfMoved(store, cursorKey, now, sweep) {
+    const seq = store.wakeSeq();
+    const startsCycle = store.serviceCursor(cursorKey) === 0;
+    const seen = cycles.get(store) ?? new Map();
+    cycles.set(store, seen);
+    const last = seen.get(cursorKey);
+    const elapsed = last === undefined ? Infinity : now.getTime() - last.at;
+    if (startsCycle && last?.seq === seq && elapsed >= 0 && elapsed < SWEEP_FALLBACK_MS)
+        return false;
+    sweep();
+    // Recorded only once the pass returns: a pass that threw is retried next time.
+    if (startsCycle)
+        seen.set(cursorKey, { seq, at: now.getTime() });
+    return true;
+}

package/dist/task-status.js

@@ -261,7 +261,9 @@ export const taskStatusOf = statusOf;
  * wait on a person stay Needs you; everything else waits in the queue. */
 const CODE_STAGE = {
     queued: ["queued"], ready: ["queued"], "worker-at-capacity": ["queued"], "retry-scheduled": ["queued"], updating: ["queued"],
-    "waiting-dependency": ["queued"], "scouting-ready": ["queued"], "planning-ready": ["queued"], "provider-quota": ["queued"], "planner-source": ["queued"],
+    "waiting-dependency": ["queued"], "scouting-ready": ["queued"], "planning-ready": ["queued"], "provider-quota": ["queued"],
+    // A request the planner cannot be given (too long to hand back, say) waits on a person to shorten it.
+    "planner-source": ["needs-you", "fix-request"],
     running: ["building"], reviewing: ["reviewing"], "review-pending": ["building"],
     "signed-out": ["needs-you", "sign-in"],
     "needs-approval": ["needs-you", "approval"],

package/dist/team-updates.js

@@ -1,5 +1,5 @@
 import { TeamLeads } from './team-leads.js';
-import { ASSIGNMENT_STATUS_ACTION, parseAssignmentStatusEvent } from './assignment-status.js';
+import { ASSIGNMENT_STATUS_ACTION, LEAD_WAKE_STATES, parseAssignmentStatusEvent } from './assignment-status.js';
 export const teamUpdateCursor = (conversation) => `team-updates:${conversation}`;
 export function startTeamUpdates(store, conversation, now) {
     // Enabling updates starts here. Past events remain available in task history.
@@ -33,10 +33,10 @@ export function deliverTeamUpdates(store, domain, authorized, now) {
             for (const row of rows) {
                 const event = parseAssignmentStatusEvent(String(row['outcome']));
                 // Keep an unreadable row pending instead of silently losing delivery.
-                if (!event || event.assignment.rootId !== row['task_id'] || event.assignment.owner.kind !== 'lead' || event.assignment.owner.id !== current.lead.id)
+                if (!event || event.assignment.rootId !== row['task_id'] || event.assignment.owner?.kind !== 'lead' || event.assignment.owner.id !== current.lead.id)
                     break;
                 through = Number(row['id']);
-                if (!['ready-to-check', 'needs-decision', 'complete', 'cancelled'].includes(event.assignment.state))
+                if (!LEAD_WAKE_STATES.includes(event.assignment.state))
                     continue;
                 changes.push(`${event.assignment.rootId}: ${event.assignment.title.slice(0, 100)} — ${event.assignment.state}. ${event.assignment.detail.slice(0, 180)}`);
                 if (changes.length === 4)

package/dist/telegram-lead.js

@@ -204,6 +204,12 @@ export function applyProposalTap(store, binding, token, message, repos, options,
     const who = verified.who;
     const preview = proposalPreview(store, proposal, actionRepos, "telegram");
     const origin = options.phoneOrigin?.() ?? null;
+    if (preview.closed) {
+        store.consumeTelegramProposalActions(proposal.id, now);
+        ack("This question is closed.");
+        edit(preview.text, []);
+        return { effects, confirmed: false, ignored: true };
+    }
     if (action.phase === "dismiss") {
         if (!store.consumeTelegramProposalAction(token, now)) {
             ack("that button was already used");

package/dist/telegram.js

@@ -25,7 +25,7 @@ import { resultImageFileName, resultTaskLabel, verifyResultImage } from "./chat-
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { chmodSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { validateNote } from "./decision.js";
+import { closedQuestionWords, validateNote } from "./decision.js";
 import { isShotsKind, resultShotsFor } from "./result-shots.js";
 import { isLifecycleNotification, isTelegramProgressNotification, RESULT_SHOTS_KIND, TELEGRAM_HOLD_REASONS } from "./store.js";
 import { telegramProgressCard } from "./telegram-progress.js";
@@ -1998,7 +1998,7 @@ function applyNote(context, update, effects) {
         return;
     }
     if (decision.state === "answered") {
-        say(`already answered: ${decision.choice ?? "?"} — this note did not travel`);
+        say(`${decision.supersededReason !== null ? closedQuestionWords(decision.supersededReason) : `already answered: ${decision.choice ?? "?"}`} — this note did not travel`);
         report.ignored++;
         return;
     }
@@ -2344,8 +2344,8 @@ function applyCallback(context, update, effects) {
     }
     if (decision.state === "answered") {
         store.consumeTelegramAction(token, clock());
-        ack(`already answered: ${decision.choice ?? "?"}`);
-        editText(answeredText(store, decision));
+        ack(decision.supersededReason !== null ? closedQuestionWords(decision.supersededReason) : `already answered: ${decision.choice ?? "?"}`);
+        editText(answeredText(store, decision), []);
         return;
     }
     if (action.phase === "choose") {
@@ -2451,13 +2451,13 @@ function answerNow(context, decision, choice, binding, ack, editText) {
         editText(answeredText(store, answered.decision));
         return;
     }
-    if (answered.reason === "already-answered") {
+    if (answered.reason === "already-answered" || answered.reason === "closed") {
         if (draft !== null)
             store.setNoteDraftState(draft.id, "discarded");
         const settled = store.getDecision(decision.id);
-        ack(`already answered: ${settled?.choice ?? "?"}${draft === null ? "" : " — your note did NOT travel"}`);
+        ack(`${settled?.supersededReason != null ? closedQuestionWords(settled.supersededReason) : `already answered: ${settled?.choice ?? "?"}`}${draft === null ? "" : " — your note did NOT travel"}`);
         if (settled !== null)
-            editText(answeredText(store, settled));
+            editText(answeredText(store, settled), []);
         return;
     }
     ack(`could not answer: ${answered.reason}`);
@@ -2479,6 +2479,8 @@ function armedDecisionText(option, note) {
     ].join("\n");
 }
 function answeredText(store, decision) {
+    if (decision.supersededReason !== null)
+        return [closedQuestionWords(decision.supersededReason), taskOf(store, decision)].join("\n");
     const chosen = decision.options.find(one => one.id === decision.choice)?.label ?? decision.choice ?? "?";
     return [
         `✓ Answered: ${chosen}`,

package/dist/toolroll-update.js

@@ -35,7 +35,7 @@ import { processMayBeAlive } from "./process-liveness.js";
 import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists, releaseStaleCodingOwner, removeCodingUpdateGate } from "./coding-update.js";
 import { installLaunchdService, launchdPlist, stopLaunchdService, writeFileDurably } from "./daemon.js";
 import { NAME } from "./names.js";
-import { orphanKey, updateSafeSchema, V117_RENAMED_COLUMNS, V117_RENAMED_TABLES, V118_MERGED_TABLES } from "./store.js";
+import { orphanKey, updateSafeSchema, V117_RENAMED_COLUMNS, V117_RENAMED_TABLES, V118_MERGED_TABLES, V119_ADDED_COLUMNS, V120_ADDED_COLUMNS } from "./store.js";
 import { isNewer, REGISTRY } from "./releases.js";
 import { markNeverIndex } from "./never-index.js";
 import { readRuntimeUpdateJournal, RUNTIME_PHASES, RUNTIME_UPDATE_STEPS, stagedStartedAt, updaterStartingOf } from "./contracts/update-journal.js";
@@ -363,6 +363,16 @@ export const CHAT_MOVES = {
     ...Object.fromEntries(Object.entries(TELEGRAM_MOVES).map(([table, move]) => [table, { ...move, where: `provider = 'telegram' AND (${move.where})` }])),
     ...Object.fromEntries(["slack", "discord", "teams"].flatMap(app => APP_TABLES.map(suffix => [`${app}_${suffix}`, { into: `chat_${suffix}`, where: `provider = '${app}'` }]))),
 };
+/** Each table's added columns across versions, merged: a table two versions both extend keeps every column. */
+function addedColumns(...versions) {
+    const rules = {};
+    for (const version of versions) {
+        for (const [table, columns] of Object.entries(version)) {
+            rules[table] = { added: { ...rules[table]?.added, ...Object.fromEntries(Object.entries(columns).map(([column, { saved }]) => [column, saved])) } };
+        }
+    }
+    return rules;
+}
 const HISTORY_RULES = {
     ...Object.fromEntries(Object.entries(CHAT_MOVES).map(([table, moved]) => [table, { moved }])),
     action_ledger: { appendOnly: true }, ledger_seal: { appendOnly: true }, ledger_checkpoint: { appendOnly: true },
@@ -384,6 +394,11 @@ const HISTORY_RULES = {
     ...Object.fromEntries(V117_RENAMED_COLUMNS.filter(([table]) => !Object.values(V117_RENAMED_TABLES).includes(table)).map(([table, from, to]) => [table, { renamed: { [from]: to } }])),
     // v118 (D7): every API token, coordinator and lead token arrives in the one credential table under its kind.
     ...Object.fromEntries(Object.entries(V118_MERGED_TABLES).map(([table, kind]) => [table, { moved: { into: "credential", where: `kind = '${kind}'` } }])),
+    // v119: planning generations and a question's closure reason are new columns; every row saved before them reads
+    // the declared value (generation 0, no closure reason).
+    // v120: a steering note's mailing and acknowledgement, and a run's steering folder, are new columns; every row
+    // saved before them reads none.
+    ...addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS),
 };
 /** The tables a migration may remove whole (v115's removed features). */
 export const RETIRED_TABLES = Object.freeze(Object.keys(HISTORY_RULES).filter(name => HISTORY_RULES[name].retired));
@@ -537,6 +552,10 @@ export function changedHistory(db, before) {
         if (t.columns.some(c => !kept(c) && (!rule?.dropped?.includes(c) || (t.nonNull?.[c] !== 0 && !accounted(rule, t)))))
             return true;
         const columns = t.columns.filter(c => present.has(c));
+        // A declared new column: every row saved before it reads its declared value.
+        const added = Object.entries(rule?.added ?? {}).filter(([c]) => !t.columns.includes(c) && present.has(c));
+        if (t.rowid && added.some(([c, saved]) => Number(db.prepare("SELECT count(*) AS n FROM " + quote(t.name) + " WHERE rowid <= ? AND " + quote(c) + " IS NOT " + saved).get(t.last)["n"]) > 0))
+            return true;
         if (!t.rowid) {
             const after = rowsHash(db, t.name, columns);
             return after.count !== t.count || after.hash !== t.hash;