toolroll 0.9.58 → 0.9.60

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.9.60 — 2026-10-11
+
+- **Steer a running build.** A note now reaches the agent while it works, and
+  shows when the agent has read it. Notes it misses go to the next attempt.
+- **One inbox for the lead.** Every update, including cancellations, reaches
+  the lead through one inbox.
+- **Lighter status work.** Status sweeps skip when nothing changed, and
+  `--version` and `--help` answer instantly.
+- **Signal tokens.** The console's colours and type come from the generated
+  Signal design tokens.
+
+## 0.9.59 — 2026-10-10
+
+- **Safer deploys.** A deploy that fails before the swap releases its own
+  lock. A stranded lock clears with one guided command.
+- **Planning restarts on a new scope.** Changing a task's scope restarts its
+  planning. Cancelling a task closes its open questions.
+
 ## 0.9.58 — 2026-10-09
 
 - **One token kind.** Personal, lead and coordinator tokens now live in one

package/README.md

@@ -100,9 +100,10 @@ separate model reviewer or automatic evidence resubmission loop. Deployment is
 reported separately and still requires the exact passing native machine check.
 
 Enable **Automatic crew updates** in a conversation, or use `toolroll chat
---follow`. Meaningful updates reach the same lead within its saved permissions
-and limits. Idle scanning uses no model. Restart recovery reuses saved responses;
-a failed response does not rerun a task. `--no-follow` pauses automatic responses.
+--follow`. Meaningful updates (a result, a question, completion or cancellation)
+reach the same lead within its saved permissions and limits, through the same
+acknowledged inbox an external coordinator reads. Idle scanning uses no model.
+Restart recovery reuses saved responses; a failed response does not rerun a task. `--no-follow` pauses automatic responses.
 This wakes Toolroll's own lead, not an unrelated external agent session.
 
 `toolroll brief` reads the local database. `knowledge search`, `knowledge
@@ -816,7 +817,7 @@ The console, the terminal, Telegram, Slack, Discord and Teams all talk to the
 same lead with the same tools. The lead reads the fleet
 and **only proposes**: file a task (or a scout), move one to the front,
 reserve it for a worker, hold it, rewrite a scope, retry/replace/unlink a
-terminal dependency, guide a task's next attempt, cancel, or suggest an answer to a parked decision. Every
+terminal dependency, send a task's agent guidance, cancel, or suggest an answer to a parked decision. Every
 proposal is a card you confirm, with
 every consequence and the builder's recommendation shown beside the
 lead's pick; a scope the lead wrote never seals under an operating mode.
@@ -843,8 +844,9 @@ Every task has an **Overview / Ask** switch. **Ask** opens a focused companion
 to that task without creating another conversation: Toolroll attaches
 the current task to each new message, keeps the live status beside the thread,
 and offers plain-language starters for status, scope revision, steering, and
-result inspection. Proposed guidance is inert until you confirm its card, then it
-reaches the next attempt without interrupting work already running.
+result inspection. Proposed guidance is inert until you confirm its card. A
+running build's agent then reads it when it next checks for notes; otherwise
+the next attempt does. Each note says whether the agent has read it.
 
 New work starts the same way: describe the outcome once in ordinary language.
 The lead infers a concise title, narrow scope, safe non-goals, and proof

package/dist/action-ledger.js

@@ -36,6 +36,11 @@ export function installLedgerTriggers(db) {
     const task = (ref) => `(SELECT external_id FROM task_ref WHERE id = ${ref})`;
     const runRef = `(SELECT task_ref FROM run WHERE id = NEW.run)`;
     const event = (at, actor, project, taskId, runId, action, outcome) => `INSERT INTO action_ledger(at,actor,repo,task_id,run_id,action,outcome,source) VALUES (${at},${actor},${project},${taskId},${runId},'${action}',${outcome},'work');`;
+    // v119: closing a question without an answer is its own event. Replace only the old trigger's future behavior;
+    // every ledger entry already recorded, and its seal, stays unchanged.
+    const answeredTrigger = db.prepare("SELECT sql FROM sqlite_master WHERE type = 'trigger' AND name = 'ledger_decision_answered'").get();
+    if (answeredTrigger !== undefined && !String(answeredTrigger["sql"]).includes("superseded_reason"))
+        db.exec("DROP TRIGGER ledger_decision_answered");
     db.exec(`
 CREATE TRIGGER IF NOT EXISTS ledger_run_started AFTER INSERT ON run BEGIN
   ${event("NEW.started_at", "NEW.runner", repo("NEW.task_ref"), task("NEW.task_ref"), "NEW.id", "run started", "NEW.role")}
@@ -48,9 +53,13 @@ CREATE TRIGGER IF NOT EXISTS ledger_decision_opened AFTER INSERT ON decision BEG
   ${event("NEW.created_at", "'system'", repo(runRef), task(runRef), "NEW.run", "decision opened", "NEW.state")}
 END;
 CREATE TRIGGER IF NOT EXISTS ledger_decision_answered AFTER UPDATE OF answered_at ON decision
-WHEN NEW.answered_at IS NOT NULL AND OLD.answered_at IS NULL BEGIN
+WHEN NEW.answered_at IS NOT NULL AND OLD.answered_at IS NULL AND NEW.superseded_reason IS NULL BEGIN
   ${event("NEW.answered_at", "COALESCE(NEW.answered_by,'system')", repo(runRef), task(runRef), "NEW.run", "decision answered", "NEW.state")}
 END;
+CREATE TRIGGER IF NOT EXISTS ledger_decision_closed AFTER UPDATE OF answered_at ON decision
+WHEN NEW.answered_at IS NOT NULL AND OLD.answered_at IS NULL AND NEW.superseded_reason IS NOT NULL BEGIN
+  ${event("NEW.answered_at", "COALESCE(NEW.answered_by,'system')", repo(runRef), task(runRef), "NEW.run", "decision closed", "NEW.superseded_reason")}
+END;
 CREATE TRIGGER IF NOT EXISTS ledger_scope_approved AFTER UPDATE OF approved_at, approved_digest ON task_scope
 WHEN NEW.approved_at IS NOT NULL AND (OLD.approved_at IS NOT NEW.approved_at OR OLD.approved_digest IS NOT NEW.approved_digest) BEGIN
   ${event("NEW.approved_at", "COALESCE(NEW.approved_by,'system')", "(SELECT repo FROM task_ref WHERE backend = 'built-in' AND external_id = NEW.task_id)", "NEW.task_id", "NULL", "scope approved", "'approved'")}

package/dist/assignment-adapters.d.ts

@@ -18,7 +18,7 @@ export declare const ASSIGNMENT_TOOLS: readonly [{
 }, {
     readonly name: "list_assignment_updates";
     readonly operation: "updates";
-    readonly description: "Read durable assignment updates in your projects after a cursor. Save nextCursor after processing; repeated reads do not acknowledge or deliver anything.";
+    readonly description: "Read the history of assignment handoffs sent to people in your projects, after a cursor. History only: it delivers and acknowledges nothing. To receive your updates, use get_assignment_inbox.";
 }, {
     readonly name: "claim_assignment";
     readonly operation: "claim";

package/dist/assignment-adapters.js

@@ -16,7 +16,7 @@ const failure = (reason, message) => ({ ok: false, reason, message });
  * (src/contracts/gateway-tools.ts), which `toolroll assignment` reads its flags with too. */
 export const ASSIGNMENT_TOOLS = [
     { name: "get_assignment", operation: "show", description: "Read one assignment's root, current execution, owner, exact result and handoff receipt. Approval, proof and deployment remain separate facts." },
-    { name: "list_assignment_updates", operation: "updates", description: "Read durable assignment updates in your projects after a cursor. Save nextCursor after processing; repeated reads do not acknowledge or deliver anything." },
+    { name: "list_assignment_updates", operation: "updates", description: "Read the history of assignment handoffs sent to people in your projects, after a cursor. History only: it delivers and acknowledges nothing. To receive your updates, use get_assignment_inbox." },
     { name: "claim_assignment", operation: "claim", description: "Record yourself as this assignment's lead. Repeating your claim is safe; another active owner cannot be replaced. This grants no approval or execution authority." },
     { name: "acknowledge_assignment", operation: "check", description: "Acknowledge the exact ready-to-check receipt as its lead, using the current receipt digest. This does not accept failed proof, answer decisions, approve work, publish or deploy." },
     { name: "get_assignment_brief", operation: "brief", description: "Catch up from the local database: current work, decisions, saved results and project knowledge. Bounded read only; no model call or task mutation." },

package/dist/assignment-delivery.d.ts

@@ -47,10 +47,26 @@ export declare function assignmentInbox(store: Store, owner: AssignmentOwner, qu
     consumer: string;
     limit?: number;
 }, now: Date): AssignmentInboxResult;
+/** The built-in lead's inbox: the same page, replay and acknowledgment as a coordinator's, over its follow grant. */
+export declare function leadFollowInbox(store: Store, grant: {
+    id: number;
+    repos: readonly string[];
+}, query: {
+    consumer: string;
+    limit?: number;
+}, now: Date): AssignmentInboxResult;
 /** ACK advances only the exact issued page, atomically. Replaying any prior
  * ACK is harmless, including while a newer page awaits acknowledgment. */
 export declare function acknowledgeAssignmentDelivery(store: Store, owner: AssignmentOwner, query: {
     consumer: string;
     batchId: string;
 }, now: Date): AssignmentDeliveryAckResult;
+/** The built-in lead acknowledges its own page the same way, once it has handled it. */
+export declare function acknowledgeLeadFollowDelivery(store: Store, grant: {
+    id: number;
+    repos: readonly string[];
+}, query: {
+    consumer: string;
+    batchId: string;
+}, now: Date): AssignmentDeliveryAckResult;
 export {};

package/dist/assignment-delivery.js

@@ -1,16 +1,28 @@
 /** Durable, explicitly acknowledged delivery of assignment status events.
  * Callers authenticate the raw coordinator credential inside the same Store
- * transaction. Delivery receipts never complete tasks or grant authority. */
+ * transaction. Delivery receipts never complete tasks or grant authority.
+ * This is the one way results reach a lead: an external coordinator reads its
+ * owned assignments' events, and the built-in lead reads its follow grant's
+ * (lead-follow.ts) through the same saved pages, replay and acknowledgment. */
 import { createHash, randomBytes } from "node:crypto";
-import { ASSIGNMENT_STATUS_ACTION, parseAssignmentStatusEvent } from "./assignment-status.js";
+import { ASSIGNMENT_STATUS_ACTION, followActor, parseAssignmentStatusEvent } from "./assignment-status.js";
 const MAX_PAGE_BYTES = 64 * 1024;
 const fail = (reason, message) => ({ ok: false, reason, message });
-const actor = (owner) => `coordinator:${owner.id}`;
-const keyFor = (owner, consumer) => createHash("sha256").update(JSON.stringify([owner.id, consumer])).digest("hex");
 const validConsumer = (value) => typeof value === "string" && /^[a-z0-9][a-z0-9-]{0,63}$/.test(value);
 const ownerSql = `COALESCE((SELECT 'lead:'||o.lead FROM team_task_owner o WHERE o.task_ref=t.id),(SELECT a.actor FROM action_ledger a WHERE a.task_id = t.external_id
   AND a.action = 'assignment claimed' AND a.source = 'work' ORDER BY a.id DESC LIMIT 1),
   'coordinator:' || t.coordinator_cid)`;
+function coordinatorReader(store, owner) {
+    const actor = `coordinator:${owner.id}`;
+    return { actor, key: consumer => createHash("sha256").update(JSON.stringify([owner.id, consumer])).digest("hex"),
+        repos: () => admittedRepos(store, owner), admits: { sql: `${ownerSql} = ?`, params: [actor] },
+        receives: event => event.assignment.owner?.id === owner.id, gone: "The coordinator is no longer active." };
+}
+/** The built-in lead's follow grant (lead-follow.ts), which its caller has already proved, with the projects it covers. */
+function followReader(grant) {
+    return { actor: followActor(grant.id), key: consumer => createHash("sha256").update(JSON.stringify(["follow", grant.id, consumer])).digest("hex"),
+        repos: () => [...grant.repos], admits: { sql: "1 = 1", params: [] }, receives: () => true, gone: "Automatic crew updates are off." };
+}
 function admittedRepos(store, owner) {
     if (owner.kind !== "coordinator" || typeof owner.id !== "string" || owner.id.length === 0)
         return null;
@@ -25,28 +37,28 @@ function admittedRepos(store, owner) {
         return null;
     }
 }
-function exposedBatch(store, owner, repos, batch) {
+function exposedBatch(store, reader, repos, batch) {
     return { ...batch, events: batch.events.map(event => {
             const admitted = repos.includes(event.project) && store.handle.prepare(`SELECT 1 FROM task_ref t
-      WHERE t.backend = 'built-in' AND t.external_id = ? AND t.repo = ? AND t.revision_of IS NULL AND ${ownerSql} = ?`)
-                .get(event.rootId, event.project, actor(owner)) !== undefined;
+      WHERE t.backend = 'built-in' AND t.external_id = ? AND t.repo = ? AND t.revision_of IS NULL AND ${reader.admits.sql}`)
+                .get(event.rootId, event.project, ...reader.admits.params) !== undefined;
             return admitted ? event : { id: event.id, unavailable: true };
         }) };
 }
-function eventFromRow(row, owner) {
+function eventFromRow(row, reader) {
     const parsed = parseAssignmentStatusEvent(String(row["outcome"]));
-    if (parsed === null || parsed.assignment.rootId !== row["task_id"] || parsed.assignment.owner?.id !== owner.id)
+    if (parsed === null || parsed.assignment.rootId !== row["task_id"] || !reader.receives(parsed))
         return null;
     return { id: Number(row["id"]), createdAt: String(row["at"]), rootId: String(row["task_id"]),
         project: String(row["repo"]), kind: "assignment-status", digest: parsed.digest, assignment: parsed.assignment };
 }
-function pendingBatch(store, owner, key) {
+function pendingBatch(store, reader, key) {
     const id = store.serviceCursor(`assignment-inbox:${key}:pending`);
     if (id === 0)
         return null;
     const invalid = () => fail("unavailable", "The saved delivery page is invalid; its cursor has not advanced.");
     const row = store.handle.prepare("SELECT outcome FROM action_ledger WHERE id = ? AND actor = ? AND action = ? AND source = 'work'")
-        .get(id, actor(owner), `assignment delivery batch:${key}`);
+        .get(id, reader.actor, `assignment delivery batch:${key}`);
     if (!row || Buffer.byteLength(String(row["outcome"])) > MAX_PAGE_BYTES)
         return invalid();
     let parsed;
@@ -69,8 +81,8 @@ function pendingBatch(store, owner, key) {
         if (!event || !Number.isSafeInteger(event.id) || event.id <= previous)
             return invalid();
         const source = store.handle.prepare("SELECT id,at,task_id,repo,outcome FROM action_ledger WHERE id = ? AND actor = ? AND action = ? AND source = 'work'")
-            .get(event.id, actor(owner), ASSIGNMENT_STATUS_ACTION);
-        const original = source === undefined ? null : eventFromRow(source, owner);
+            .get(event.id, reader.actor, ASSIGNMENT_STATUS_ACTION);
+        const original = source === undefined ? null : eventFromRow(source, reader);
         if (original === null || JSON.stringify(original) !== JSON.stringify(event))
             return invalid();
         previous = event.id;
@@ -83,31 +95,38 @@ function pendingBatch(store, owner, key) {
  * tombstone; it does not prevent acknowledgment of that already issued page.
  * Consumer names identify independent inboxes. */
 export function assignmentInbox(store, owner, query, now) {
+    return inbox(store, coordinatorReader(store, owner), query, now);
+}
+/** The built-in lead's inbox: the same page, replay and acknowledgment as a coordinator's, over its follow grant. */
+export function leadFollowInbox(store, grant, query, now) {
+    return inbox(store, followReader(grant), query, now);
+}
+function inbox(store, reader, query, now) {
     if (!validConsumer(query.consumer) || (query.limit !== undefined && (!Number.isInteger(query.limit) || query.limit < 1 || query.limit > 100)))
         return fail("invalid-input", "Use a consumer name of 1–64 characters and a page size of 1–100.");
     return store.transact(() => store.savepoint(() => {
-        const repos = admittedRepos(store, owner);
+        const repos = reader.repos();
         if (repos === null)
-            return fail("unavailable", "The coordinator is no longer active.");
-        const key = keyFor(owner, query.consumer), cursorKey = `assignment-inbox:${key}:acked`;
-        const after = store.serviceCursor(cursorKey), pending = pendingBatch(store, owner, key);
+            return fail("unavailable", reader.gone);
+        const key = reader.key(query.consumer), cursorKey = `assignment-inbox:${key}:acked`;
+        const after = store.serviceCursor(cursorKey), pending = pendingBatch(store, reader, key);
         if (pending !== null) {
             if ("ok" in pending)
                 return pending;
             if (pending.consumer !== query.consumer || pending.after !== after)
                 return fail("unavailable", "The saved delivery page does not match its cursor.");
-            return { ok: true, batch: exposedBatch(store, owner, repos, pending), replayed: true };
+            return { ok: true, batch: exposedBatch(store, reader, repos, pending), replayed: true };
         }
         const limit = query.limit ?? 10;
         const rows = store.handle.prepare(`SELECT n.id,n.at,n.task_id,n.repo,n.outcome
       FROM action_ledger n JOIN task_ref t ON t.backend = 'built-in'
         AND t.external_id = n.task_id AND t.repo = n.repo AND t.revision_of IS NULL
       WHERE n.id > ? AND n.action = ? AND n.source = 'work' AND n.actor = ?
-        AND n.repo IN (SELECT value FROM json_each(?)) AND ${ownerSql} = ?
-      ORDER BY n.id LIMIT ?`).all(after, ASSIGNMENT_STATUS_ACTION, actor(owner), JSON.stringify(repos), actor(owner), limit + 1);
+        AND n.repo IN (SELECT value FROM json_each(?)) AND ${reader.admits.sql}
+      ORDER BY n.id LIMIT ?`).all(after, ASSIGNMENT_STATUS_ACTION, reader.actor, JSON.stringify(repos), ...reader.admits.params, limit + 1);
         const batch = { version: 1, id: null, consumer: query.consumer, after, nextCursor: after, hasMore: rows.length > limit, events: [] };
         for (const row of rows.slice(0, limit)) {
-            const event = eventFromRow(row, owner);
+            const event = eventFromRow(row, reader);
             if (event === null)
                 return fail("unavailable", "The next saved assignment event is invalid; no event was skipped.");
             batch.events.push(event);
@@ -123,7 +142,7 @@ export function assignmentInbox(store, owner, query, now) {
         if (batch.events.length === 0)
             return { ok: true, batch, replayed: false };
         batch.id = randomBytes(16).toString("hex");
-        const id = store.recordAction({ at: now.toISOString(), actor: actor(owner), repo: null, taskId: null, runId: null,
+        const id = store.recordAction({ at: now.toISOString(), actor: reader.actor, repo: null, taskId: null, runId: null,
             action: `assignment delivery batch:${key}`, outcome: JSON.stringify(batch), source: "work" });
         store.setServiceCursor(`assignment-inbox:${key}:pending`, id, now);
         return { ok: true, batch, replayed: false };
@@ -132,26 +151,33 @@ export function assignmentInbox(store, owner, query, now) {
 /** ACK advances only the exact issued page, atomically. Replaying any prior
  * ACK is harmless, including while a newer page awaits acknowledgment. */
 export function acknowledgeAssignmentDelivery(store, owner, query, now) {
+    return acknowledge(store, coordinatorReader(store, owner), query, now);
+}
+/** The built-in lead acknowledges its own page the same way, once it has handled it. */
+export function acknowledgeLeadFollowDelivery(store, grant, query, now) {
+    return acknowledge(store, followReader(grant), query, now);
+}
+function acknowledge(store, reader, query, now) {
     if (!validConsumer(query.consumer) || typeof query.batchId !== "string" || !/^[a-f0-9]{32}$/.test(query.batchId))
         return fail("invalid-input", "Use the exact consumer and batch ID returned by the inbox.");
     return store.transact(() => store.savepoint(() => {
-        const repos = admittedRepos(store, owner);
+        const repos = reader.repos();
         if (repos === null)
-            return fail("unavailable", "The coordinator is no longer active.");
-        const key = keyFor(owner, query.consumer), cursorKey = `assignment-inbox:${key}:acked`;
+            return fail("unavailable", reader.gone);
+        const key = reader.key(query.consumer), cursorKey = `assignment-inbox:${key}:acked`;
         const cursor = store.serviceCursor(cursorKey), action = `assignment delivery acknowledged:${key}`;
         const acknowledged = store.handle.prepare(`SELECT 1 FROM action_ledger WHERE actor = ? AND action = ? AND source = 'work'
-      AND json_extract(outcome, '$.batchId') = ? LIMIT 1`).get(actor(owner), action, query.batchId);
+      AND json_extract(outcome, '$.batchId') = ? LIMIT 1`).get(reader.actor, action, query.batchId);
         if (acknowledged)
             return { ok: true, alreadyAcknowledged: true, cursor };
-        const pending = pendingBatch(store, owner, key);
+        const pending = pendingBatch(store, reader, key);
         if (pending !== null && "ok" in pending)
             return pending;
         if (pending === null || pending.id !== query.batchId || pending.consumer !== query.consumer || pending.after !== cursor)
             return fail("stale-batch", "This batch was not issued to this inbox; its cursor has not advanced.");
         // Access loss redacts replayed events; the exact issued page remains
         // acknowledgeable so its inaccessible entries cannot wedge this inbox.
-        store.recordAction({ at: now.toISOString(), actor: actor(owner), repo: null, taskId: null, runId: null,
+        store.recordAction({ at: now.toISOString(), actor: reader.actor, repo: null, taskId: null, runId: null,
             action, outcome: JSON.stringify({ batchId: pending.id, after: pending.after, cursor: pending.nextCursor }), source: "work" });
         store.setServiceCursor(cursorKey, pending.nextCursor, now);
         store.setServiceCursor(`assignment-inbox:${key}:pending`, 0, now);

package/dist/assignment-status.d.ts

@@ -1,7 +1,13 @@
 import type { Store } from "./store.js";
 import { type AssignmentSnapshot } from "./assignment.js";
 export declare const ASSIGNMENT_STATUS_ACTION = "assignment status observed";
+/** A reader's first sight of a task that is not news: the state later events are compared to, never delivered. */
+export declare const ASSIGNMENT_STATUS_BASELINE = "assignment status baseline";
 export declare const ASSIGNMENT_STATUS_SOURCE: "work";
+/** The states that wake a lead: a result to check, a question, completion, or cancellation. */
+export declare const LEAD_WAKE_STATES: readonly AssignmentSnapshot["state"][];
+/** The built-in lead's events, one stream per follow grant. */
+export declare const followActor: (grant: number) => string;
 /** No saved artifact contents, credential bytes, or polling timestamps. Exact
  * IDs and digests identify the full read; display text is deliberately bounded. */
 export declare function assignmentStatusBrief(assignment: AssignmentSnapshot): {
@@ -42,13 +48,12 @@ export declare function assignmentStatusBrief(assignment: AssignmentSnapshot): {
         remoteState: string | null;
     } | null;
 };
+/** An owner's events always name it; the built-in lead's follow events name whatever owner the task has, or none. */
 export type AssignmentStatusEvent = {
     version: 1;
     digest: string;
     stateDigest: string;
-    assignment: ReturnType<typeof assignmentStatusBrief> & {
-        owner: NonNullable<ReturnType<typeof assignmentStatusBrief>["owner"]>;
-    };
+    assignment: ReturnType<typeof assignmentStatusBrief>;
 };
 /** An unreadable ledger event is an explicit consumer error, not a cursor that
  * may silently skip the row. This validates the bounded data, not authority. */
@@ -57,6 +62,10 @@ export declare function parseAssignmentStatusEvent(value: string): AssignmentSta
  * for worker reconciliation. The latest event, not a permanent digest set,
  * deduplicates retries so Working → Needs decision → Working is retained. */
 export declare function noteAssignmentStatus(store: Store, snapshot: AssignmentSnapshot, now: Date): number | null;
+/** The built-in lead's crew update (lead-follow.ts): the same event, under its follow grant. The
+ * caller has already proved the grant and its projects; the root must still be a placed task. */
+export declare function noteFollowStatus(store: Store, grant: number, snapshot: AssignmentSnapshot, now: Date, action?: typeof ASSIGNMENT_STATUS_ACTION | typeof ASSIGNMENT_STATUS_BASELINE): number | null;
 /** At most fifty roots per pass; the cursor survives process restarts. A full
- * pass cycles back, so changes below the cursor are eventually observed too. */
+ * pass cycles back, so changes below the cursor are eventually observed too.
+ * A pass is skipped when nothing moved since the cycle began (sweep-gate.ts). */
 export declare function syncAssignmentStatuses(store: Store, now: Date, repos: readonly string[], root?: string): void;

package/dist/assignment-status.js

@@ -1,11 +1,22 @@
 /** Private lead catch-up, separate from human notification delivery. These are
  * observed assignment transitions, not a promise to capture every intermediate
- * state between scans. Recording or reading them never dispatches agent work. */
+ * state between scans. Recording or reading them never dispatches agent work.
+ * One stream serves every lead: a coordinator's or team lead's events are
+ * recorded under its owner, and the built-in lead's crew updates under its
+ * follow grant (`follow:<grant>`, lead-follow.ts); each reads its own through
+ * the delivery inbox (assignment-delivery.ts). */
 import { createHash } from "node:crypto";
 import { assignmentOf } from "./assignment.js";
 import { publicChatText } from "./chat-display.js";
+import { sweepIfMoved } from "./sweep-gate.js";
 export const ASSIGNMENT_STATUS_ACTION = "assignment status observed";
+/** A reader's first sight of a task that is not news: the state later events are compared to, never delivered. */
+export const ASSIGNMENT_STATUS_BASELINE = "assignment status baseline";
 export const ASSIGNMENT_STATUS_SOURCE = "work";
+/** The states that wake a lead: a result to check, a question, completion, or cancellation. */
+export const LEAD_WAKE_STATES = ["ready-to-check", "needs-decision", "complete", "cancelled"];
+/** The built-in lead's events, one stream per follow grant. */
+export const followActor = (grant) => `follow:${grant}`;
 const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
 const text = publicChatText;
 /** No saved artifact contents, credential bytes, or polling timestamps. Exact
@@ -51,7 +62,7 @@ export function parseAssignmentStatusEvent(value) {
             !Array.isArray(a["attention"]) || a["attention"].length > 8 || !a["attention"].every(one => string(one, 500)))
             return null;
         const owner = a["owner"], action = a["primaryAction"], result = a["result"], completion = a["completion"], publication = a["publication"];
-        if (!object(owner) || !keys(owner, ["kind", "id", "label"]) || !["coordinator", "lead"].includes(String(owner["kind"])) || !string(owner["id"], 128) || !string(owner["label"], 100))
+        if (owner !== null && (!object(owner) || !keys(owner, ["kind", "id", "label"]) || !["coordinator", "lead"].includes(String(owner["kind"])) || !string(owner["id"], 128) || !string(owner["label"], 100)))
             return null;
         if (action !== null && (!object(action) || !keys(action, ["code", "label", "target"]) || !string(action["code"], 80) || !string(action["label"], 160) ||
             !object(action["target"]) || !keys(action["target"], ["taskId", "runId", "decisionId"]) || !string(action["target"]["taskId"], 64) || !id(action["target"]["runId"]) || !id(action["target"]["decisionId"])))
@@ -103,50 +114,70 @@ export function noteAssignmentStatus(store, snapshot, now) {
             if (!Array.isArray(repos) || !repos.includes(snapshot.repo))
                 return null;
         }
-        const assignment = assignmentStatusBrief(snapshot);
-        if (assignment.owner === null)
+        if (assignmentStatusBrief(snapshot).owner === null)
             return null;
-        const stateDigest = hash(assignment);
-        const previous = store.handle.prepare("SELECT id,outcome FROM action_ledger WHERE task_id=? AND action=? AND source=? ORDER BY id DESC LIMIT 1")
-            .get(snapshot.rootId, ASSIGNMENT_STATUS_ACTION, ASSIGNMENT_STATUS_SOURCE);
-        if (previous !== undefined) {
-            try {
-                if (JSON.parse(String(previous["outcome"]))?.stateDigest === stateDigest)
-                    return null;
-            }
-            catch { /* Preserve an unreadable older event; append the current observation. */ }
-        }
-        const digest = hash({ rootRef: ref.id, owner: owner.id, previous: previous === undefined ? null : Number(previous["id"]), stateDigest });
-        const event = { version: 1, digest, stateDigest, assignment: { ...assignment, owner: assignment.owner } };
-        return store.recordAction({ at: now.toISOString(), actor: `${owner.kind}:${owner.id}`, repo: snapshot.repo,
-            taskId: snapshot.rootId, runId: assignment.runId, action: ASSIGNMENT_STATUS_ACTION,
-            outcome: JSON.stringify(event), source: ASSIGNMENT_STATUS_SOURCE });
+        return appendStatusEvent(store, `${owner.kind}:${owner.id}`, owner.id, ref.id, snapshot, now);
     });
 }
+/** The built-in lead's crew update (lead-follow.ts): the same event, under its follow grant. The
+ * caller has already proved the grant and its projects; the root must still be a placed task. */
+export function noteFollowStatus(store, grant, snapshot, now, action = ASSIGNMENT_STATUS_ACTION) {
+    if (snapshot.repo === null)
+        return null;
+    return store.transact(() => {
+        const ref = store.lookupRef(snapshot.rootId);
+        if (!ref || ref.repo !== snapshot.repo || ref.revisionOf !== null)
+            return null;
+        return appendStatusEvent(store, followActor(grant), followActor(grant), ref.id, snapshot, now, action);
+    });
+}
+/** Each reader's latest event or baseline, not a permanent digest set, deduplicates its retries, so Working → Needs
+ * decision → Working is retained. One reader's events never suppress or duplicate another's. */
+function appendStatusEvent(store, actor, ownerId, rootRef, snapshot, now, action = ASSIGNMENT_STATUS_ACTION) {
+    const assignment = assignmentStatusBrief(snapshot);
+    const stateDigest = hash(assignment);
+    const previous = store.handle.prepare("SELECT id,outcome FROM action_ledger WHERE task_id=? AND action IN (?,?) AND source=? AND actor=? ORDER BY id DESC LIMIT 1")
+        .get(snapshot.rootId, ASSIGNMENT_STATUS_ACTION, ASSIGNMENT_STATUS_BASELINE, ASSIGNMENT_STATUS_SOURCE, actor);
+    if (previous !== undefined) {
+        try {
+            if (JSON.parse(String(previous["outcome"]))?.stateDigest === stateDigest)
+                return null;
+        }
+        catch { /* Preserve an unreadable older event; append the current observation. */ }
+    }
+    const digest = hash({ rootRef, owner: ownerId, previous: previous === undefined ? null : Number(previous["id"]), stateDigest });
+    const event = { version: 1, digest, stateDigest, assignment };
+    return store.recordAction({ at: now.toISOString(), actor, repo: snapshot.repo,
+        taskId: snapshot.rootId, runId: assignment.runId, action,
+        outcome: JSON.stringify(event), source: ASSIGNMENT_STATUS_SOURCE });
+}
 /** At most fifty roots per pass; the cursor survives process restarts. A full
- * pass cycles back, so changes below the cursor are eventually observed too. */
+ * pass cycles back, so changes below the cursor are eventually observed too.
+ * A pass is skipped when nothing moved since the cycle began (sweep-gate.ts). */
 export function syncAssignmentStatuses(store, now, repos, root) {
     if (repos.length === 0)
         return;
     const allowed = [...new Set(repos)].sort();
     const key = `assignment-status:${hash(allowed)}`;
-    const rows = store.handle.prepare(`SELECT t.id,t.external_id FROM task_ref t
-    WHERE t.backend='built-in' AND t.revision_of IS NULL
-    AND t.repo IN (SELECT value FROM json_each(?)) AND t.id>?
-    AND (t.coordinator_cid IS NOT NULL OR EXISTS(SELECT 1 FROM team_task_owner o WHERE o.task_ref=t.id) OR EXISTS
-      (SELECT 1 FROM action_ledger a WHERE a.task_id=t.external_id AND a.action='assignment claimed' AND a.source='work'))
-    ORDER BY t.id LIMIT 50`).all(JSON.stringify(allowed), store.serviceCursor(key));
-    // Release the writer between families. Each observation and its durable
-    // position still commit together; an interrupted sweep resumes after the
-    // last committed family instead of holding every heartbeat behind a batch.
-    if (rows.length === 0)
-        store.setServiceCursor(key, 0, now);
-    for (const [index, row] of rows.entries()) {
-        store.transact(() => {
-            const snapshot = assignmentOf(store, String(row['external_id']), now, { principal: 'coordinator', repos: allowed }, root);
-            if (snapshot !== null)
-                noteAssignmentStatus(store, snapshot, now);
-            store.setServiceCursor(key, index === rows.length - 1 && rows.length < 50 ? 0 : Number(row['id']), now);
-        });
-    }
+    sweepIfMoved(store, key, now, () => {
+        const rows = store.handle.prepare(`SELECT t.id,t.external_id FROM task_ref t
+      WHERE t.backend='built-in' AND t.revision_of IS NULL
+      AND t.repo IN (SELECT value FROM json_each(?)) AND t.id>?
+      AND (t.coordinator_cid IS NOT NULL OR EXISTS(SELECT 1 FROM team_task_owner o WHERE o.task_ref=t.id) OR EXISTS
+        (SELECT 1 FROM action_ledger a WHERE a.task_id=t.external_id AND a.action='assignment claimed' AND a.source='work'))
+      ORDER BY t.id LIMIT 50`).all(JSON.stringify(allowed), store.serviceCursor(key));
+        // Release the writer between families. Each observation and its durable
+        // position still commit together; an interrupted sweep resumes after the
+        // last committed family instead of holding every heartbeat behind a batch.
+        if (rows.length === 0)
+            store.setServiceCursor(key, 0, now);
+        for (const [index, row] of rows.entries()) {
+            store.transact(() => {
+                const snapshot = assignmentOf(store, String(row['external_id']), now, { principal: 'coordinator', repos: allowed }, root);
+                if (snapshot !== null)
+                    noteAssignmentStatus(store, snapshot, now);
+                store.setServiceCursor(key, index === rows.length - 1 && rows.length < 50 ? 0 : Number(row['id']), now);
+            });
+        }
+    });
 }

package/dist/assignment.d.ts

@@ -233,9 +233,13 @@ export declare function acceptAndCompleteAsOperator(store: Store, taskId: string
     receiptDigest: string;
     note: string | null;
 }, who: VerifiedApprover, now: Date, root?: string, finish?: (digest: string) => Finished): Finished;
-/** The ordinary worker reconciles at most 50 owned roots per pass. A lost
- * wakeup is recovered after restart; immutable notification keys dedupe it. */
+/** The ordinary worker reconciles at most 50 owned roots per pass, and skips a
+ * pass when nothing moved (sweep-gate.ts). A lost wakeup is recovered after
+ * restart; immutable notification keys dedupe it. */
 export declare function syncAssignmentHandoffs(store: Store, now: Date, repos: readonly string[], root?: string): void;
+/** The history of assignment handoffs sent to people (the `assignment-handoff` notifications), read by cursor. It is
+ * not a delivery path: nothing is saved, replayed or acknowledged here. Leads receive their updates through the
+ * assignment inbox (assignment-delivery.ts), the one road results take to a lead. */
 export declare function assignmentUpdates(store: Store, now: Date, access: AssignmentAccess, query: {
     after: number;
     limit: number;

package/dist/assignment.js

@@ -9,7 +9,8 @@ import { homedir } from "node:os";
 import { readSchemaVersion, stopFactOf } from "./store.js";
 import { approvalOf } from "./scope.js";
 import { openWorkDecisionOf, taskWorkSummaryOf, workDecisionAction } from "./work-summary.js";
-import { evidenceRoot, readVerifiedArtifact, readVerifiedReport } from "./evidence.js";
+import { evidenceRoot, readVerifiedArtifact, readVerifiedReport, verifyArtifact } from "./evidence.js";
+import { sweepIfMoved } from "./sweep-gate.js";
 import { verificationEvidence } from "./verification-evidence.js";
 import { reproveApprover } from "./principal.js";
 import { noteAssignmentStatus } from "./assignment-status.js";
@@ -163,7 +164,7 @@ export function assignmentOf(store, taskId, now, access, root, memo) {
     });
     const artifacts = result === null ? [] : store.artifactsFor(result.id);
     const reports = artifacts.filter(a => a.kind === "report");
-    const unavailable = family.versions.flatMap(version => store.runsFor(version.refId).flatMap(run => store.artifactsFor(run.id).filter(artifact => root === undefined || !readVerifiedArtifact(root, artifact).ok)
+    const unavailable = family.versions.flatMap(version => store.runsFor(version.refId).flatMap(run => store.artifactsFor(run.id).filter(artifact => root === undefined || !verifyArtifact(root, artifact).ok)
         .map(artifact => `Saved ${artifact.kind} #${artifact.id} (run ${run.id}) is unavailable or changed.`)));
     const ownChecks = result === null ? null : assignmentChecksForRun(store, root, result.id, now);
     // Checks Off: a passing full release check that contains this commit covers it, read now from the existing receipts.
@@ -418,7 +419,7 @@ export function assignmentEvidenceIntact(store, root, receipt) {
     try {
         const family = store.taskFamilyOf(receipt.taskId, null, true);
         if (family === null || family.problem !== null || family.root.id !== receipt.rootId ||
-            !family.versions.every(version => store.runsFor(version.refId).every(run => store.artifactsFor(run.id).every(artifact => readVerifiedArtifact(root, artifact).ok))))
+            !family.versions.every(version => store.runsFor(version.refId).every(run => store.artifactsFor(run.id).every(artifact => verifyArtifact(root, artifact).ok))))
             return false;
         if (receipt.completionKind === "research-report") {
             const report = readVerifiedReport(store, root, store.lookupRef(receipt.taskId).id);
@@ -567,13 +568,14 @@ function noteAssignmentHandoff(store, assignment, now) {
         kind: "assignment-handoff", source: { taskRef: ref.id }, subject: assignment.state === "cancelled" ? "Assignment cancelled" : assignment.state === "ready-to-check" ? "Ready" : "Assignment needs a decision",
         body: assignment.detail, link: `/t/${encodeURIComponent(assignment.rootId)}` }, now);
 }
-/** The ordinary worker reconciles at most 50 owned roots per pass. A lost
- * wakeup is recovered after restart; immutable notification keys dedupe it. */
+/** The ordinary worker reconciles at most 50 owned roots per pass, and skips a
+ * pass when nothing moved (sweep-gate.ts). A lost wakeup is recovered after
+ * restart; immutable notification keys dedupe it. */
 export function syncAssignmentHandoffs(store, now, repos, root) {
     if (repos.length === 0)
         return;
-    store.transact(() => {
-        const key = `assignment-handoff:${digest([...new Set(repos)].sort())}`;
+    const key = `assignment-handoff:${digest([...new Set(repos)].sort())}`;
+    sweepIfMoved(store, key, now, () => store.transact(() => {
         const cursor = store.serviceCursor(key);
         const rows = store.handle.prepare(`SELECT t.id,t.external_id FROM task_ref t WHERE t.backend = 'built-in' AND t.revision_of IS NULL
     AND t.repo IN (SELECT value FROM json_each(?)) AND t.id > ?
@@ -587,8 +589,11 @@ export function syncAssignmentHandoffs(store, now, repos, root) {
             }
         }
         store.setServiceCursor(key, rows.length < 50 ? 0 : Number(rows.at(-1)["id"]), now);
-    });
+    }));
 }
+/** The history of assignment handoffs sent to people (the `assignment-handoff` notifications), read by cursor. It is
+ * not a delivery path: nothing is saved, replayed or acknowledged here. Leads receive their updates through the
+ * assignment inbox (assignment-delivery.ts), the one road results take to a lead. */
 export function assignmentUpdates(store, now, access, query, root) {
     const after = Number.isSafeInteger(query.after) && query.after >= 0 ? query.after : 0;
     const limit = Math.max(1, Math.min(100, Math.floor(query.limit) || 50));

package/dist/bin.js

@@ -17,6 +17,15 @@ if (major < 22 || (major === 22 && minor < 13)) {
     process.stderr.write(`Toolroll needs Node 22.13 or newer (this is ${versions.node}) — it uses node:sqlite.\n`);
     process.exit(2);
 }
-const { runCliProcess } = await import("./cli.js");
-await runCliProcess(process.argv.slice(2));
+// --version and the top-level usage answer here, before the CLI and its command families load.
+const argv = process.argv.slice(2);
+const { quickAnswer } = await import("./cli-fast.js");
+const quick = quickAnswer(argv);
+if (quick !== null) {
+    console.log(quick);
+}
+else {
+    const { runCliProcess } = await import("./cli.js");
+    await runCliProcess(argv);
+}
 export {};

package/dist/brief-fence.d.ts

@@ -0,0 +1,9 @@
+/**
+ * One line, prefixed, with nothing that can end the block or start a new rule.
+ *
+ * Scope text is written by whoever filed the task. A goal containing a newline
+ * and a bullet would otherwise read to the agent as another rule in the list,
+ * which is how "add a guard" becomes "add a guard, and ignore the rules below".
+ * The same quoting wraps a steering note the agent reads from its mailbox.
+ */
+export declare function fence(text: string): string;