toolroll 0.9.59 → 0.9.61

package/dist/agents-board.js

@@ -0,0 +1,225 @@
+/**
+ * The Agents board's projection (one place to check on running agents): each
+ * task's newest build attempt from the last day, in the viewer's admitted
+ * projects, grouped Needs you, Working, Stuck, Done (not viewed yet), Idle.
+ * A protocol repair never takes the row: while one runs, its parent's row says
+ * "Fixing the handoff" and keeps the parent's transcript, changes and link.
+ * Saved facts only (agent-board.ts, the run, its activity and its sealed diff
+ * stats); nothing here verifies evidence or grants an action.
+ */
+import { quietSince, stuckSince } from "./agent-board.js";
+import { activityLine } from "./activity-line.js";
+import { readVerifiedArtifact } from "./evidence.js";
+import { failedAttemptSentence } from "./needs-you.js";
+import { projectName } from "./project.js";
+import { providerName } from "./provider-auth.js";
+import { runActivityOf } from "./task-activity.js";
+export const AGENT_GROUPS = [
+    { key: "needs-you", label: "Needs you" },
+    { key: "working", label: "Working" },
+    { key: "stuck", label: "Stuck" },
+    { key: "done", label: "Done" },
+    { key: "idle", label: "Idle" },
+];
+/** Finished attempts stay on the board this long; unread Done and Needs you stay three days. */
+const RECENT_MS = 24 * 60 * 60_000;
+const KEPT_MS = 3 * RECENT_MS;
+const BOARD_LIMIT = 80;
+const str = (row, key) => row[key] == null ? null : String(row[key]);
+const FACTS = `SELECT r.id, r.task_ref, r.provider, r.runner, r.outcome, r.reason, r.started_at, r.finished_at, r.phase, r.attempt_key IS NULL AS legacy,
+    tr.external_id AS task_id, tr.repo, t.title, t.state AS task_state,
+    n.state AS turn, n.state_at, n.transcript_at, n.stuck_at, n.said, n.said_note, n.said_at, n.diff_files, n.tool_kind, n.tool_at, n.question_note,
+    EXISTS (SELECT 1 FROM run p WHERE p.parent_run = r.id AND p.role = 'repair' AND p.outcome IS NULL) AS repairing,
+    (SELECT json_object('id', q.id, 'key', q.key, 'text', q.question) FROM agent_question q
+      WHERE q.run = r.id AND q.closed_at IS NULL AND q.attempt_key = r.attempt_key ORDER BY q.id LIMIT 1) AS question,
+    EXISTS (SELECT 1 FROM agent_seen s WHERE s.account = $account AND s.run = r.id) AS seen
+  FROM run r
+  JOIN task_ref tr ON tr.id = r.task_ref AND tr.backend = 'built-in' AND tr.repo IS NOT NULL
+  JOIN task t ON t.id = tr.external_id
+  LEFT JOIN agent_now n ON n.task_ref = r.task_ref AND n.run = r.id AND n.attempt_key = r.attempt_key
+  WHERE r.role = 'builder'`;
+function readFacts(row) {
+    let question = null;
+    try {
+        const parsed = row["question"] == null ? null : JSON.parse(String(row["question"]));
+        question = parsed === null ? null : { id: Number(parsed.id), key: String(parsed.key), text: String(parsed.text) };
+    }
+    catch {
+        question = null;
+    }
+    return {
+        runId: Number(row["id"]), taskRef: Number(row["task_ref"]), taskId: String(row["task_id"]), title: String(row["title"]), repo: str(row, "repo"),
+        provider: String(row["provider"] ?? "claude"), runner: String(row["runner"]), outcome: str(row, "outcome"), reason: str(row, "reason"),
+        startedAt: String(row["started_at"]), finishedAt: str(row, "finished_at"), legacy: Number(row["legacy"]) === 1, taskState: String(row["task_state"]),
+        turn: str(row, "turn"), stateAt: str(row, "state_at"), transcriptAt: str(row, "transcript_at"), stuckAt: str(row, "stuck_at"),
+        said: str(row, "said"), saidNote: str(row, "said_note"), saidAt: str(row, "said_at"), diffFiles: row["diff_files"] == null ? null : Number(row["diff_files"]),
+        toolKind: str(row, "tool_kind"), toolAt: str(row, "tool_at"), phase: str(row, "phase"), questionNote: str(row, "question_note"), repairing: Number(row["repairing"]) === 1,
+        question, seen: Number(row["seen"]) === 1,
+    };
+}
+/**
+ * The board's candidate builds, through the partial indexes (agent_board_open, agent_board_recent): open ones and
+ * those finished since $kept, one per task (its newest), never a scan of every run. A candidate a newer build of the
+ * same task has replaced is dropped by an indexed probe, so the row is still the task's newest build.
+ */
+export const BOARD_CANDIDATES = `WITH candidate AS (
+    SELECT task_ref, id FROM run WHERE role = 'builder' AND outcome IS NULL
+    UNION ALL
+    SELECT task_ref, id FROM run WHERE role = 'builder' AND outcome IS NOT NULL AND finished_at >= $kept
+  ), newest AS (SELECT task_ref, MAX(id) AS id FROM candidate GROUP BY task_ref)`;
+/** The board's candidate attempts: each task's newest build, open or recently finished, in the admitted projects. */
+export function agentFacts(store, now, access, account) {
+    return store.handle.prepare(agentFactsSql())
+        .all({ $account: account, $kept: new Date(now.getTime() - KEPT_MS).toISOString(), $all: access.repos === null ? 1 : 0, $repos: JSON.stringify(access.repos ?? []) })
+        .map(readFacts);
+}
+/** The board's query, exported for its query-plan test. */
+export function agentFactsSql() {
+    return `${BOARD_CANDIDATES}
+    ${FACTS.replace("FROM run r", "FROM newest c JOIN run r ON r.id = c.id")}
+      AND NOT EXISTS (SELECT 1 FROM run x WHERE x.task_ref = r.task_ref AND x.role = 'builder' AND x.id > r.id)
+      AND NOT EXISTS (SELECT 1 FROM task_ref c WHERE c.backend = tr.backend AND c.revision_of = tr.external_id AND c.repo IS tr.repo)
+      AND ($all = 1 OR tr.repo IN (SELECT value FROM json_each($repos)))
+    ORDER BY r.id DESC LIMIT ${BOARD_LIMIT}`;
+}
+/** One exact build attempt, whatever its age (the opened row), in the admitted projects: a repair opens as its parent. */
+export function agentFactsFor(store, run, access, account) {
+    const row = store.handle.prepare(`${FACTS} AND r.id = (SELECT CASE WHEN role = 'repair' AND parent_run IS NOT NULL THEN parent_run ELSE id END FROM run WHERE id = $run) AND ($all = 1 OR tr.repo IN (SELECT value FROM json_each($repos)))`)
+        .get({ $account: account, $run: run, $all: access.repos === null ? 1 : 0, $repos: JSON.stringify(access.repos ?? []) });
+    return row === undefined ? null : readFacts(row);
+}
+const FINISHED_WELL = new Set(["built", "no-change"]);
+const SETTLED_TASK = new Set(["done", "cancelled"]);
+/** Where an attempt sits on the board, and its one state word. Stuck is worked out from the facts now, so fresh
+ * transcript or activity clears it at once (the pulse's saved mark only tells open boards it crossed). */
+export function agentGroupOf(facts, activityAt, now) {
+    if (facts.outcome === null) {
+        if (facts.question !== null)
+            return { group: "needs-you", label: "Question" };
+        if (facts.repairing)
+            return { group: "working", label: "Working" };
+        if (facts.turn === "crashed")
+            return { group: "needs-you", label: "Stopped unexpectedly" };
+        if (facts.said === "blocked" && facts.turn !== "idle")
+            return { group: "needs-you", label: "Blocked" };
+        if (facts.turn === "busy" && stuckSince({ state: "busy", stateAt: facts.stateAt ?? facts.startedAt, transcriptAt: facts.transcriptAt ?? facts.startedAt, toolAt: facts.toolAt }, activityAt, now) !== null) {
+            return { group: "stuck", label: "Stuck" };
+        }
+        // Its turn has its result, but the build is still capturing and checking it: still at work, not idle.
+        return { group: "working", label: "Working" };
+    }
+    if (FINISHED_WELL.has(facts.outcome)) {
+        const label = facts.outcome === "built" ? "Done" : "No changes";
+        // Unread only for attempts the board saw start: a run from before it never counts as news.
+        return { group: facts.seen || facts.legacy ? "idle" : "done", label };
+    }
+    if (SETTLED_TASK.has(facts.taskState))
+        return { group: "idle", label: facts.outcome === "interrupted" ? "Stopped" : "Failed" };
+    return { group: "needs-you", label: facts.outcome === "parked" ? "Needs a decision" : facts.outcome === "interrupted" ? "Stopped" : facts.outcome === "refused" ? "Not started" : "Failed" };
+}
+const sealed = new Map();
+/** A finished attempt's sealed diff stats (cached by artifact: sealed bytes never change). */
+export function sealedDiffOf(store, root, run) {
+    if (root === undefined)
+        return null;
+    const artifact = store.artifactsFor(run).find(one => one.kind === "diff-stat");
+    if (artifact === undefined || artifact.captureStatus !== "ok")
+        return null;
+    if (sealed.has(artifact.id))
+        return sealed.get(artifact.id) ?? null;
+    let summary = null;
+    try {
+        const read = readVerifiedArtifact(root, artifact);
+        if (read.ok) {
+            const stat = JSON.parse(read.content.toString("utf8"));
+            const files = Array.isArray(stat.files) ? stat.files.filter(one => typeof one?.["path"] === "string").map(one => ({
+                path: String(one["path"]), additions: typeof one["additions"] === "number" ? one["additions"] : null, deletions: typeof one["deletions"] === "number" ? one["deletions"] : null
+            })) : [];
+            summary = { fileCount: Number(stat.fileCount ?? files.length) || 0, additions: Number(stat.additions ?? 0) || 0, deletions: Number(stat.deletions ?? 0) || 0, files };
+        }
+    }
+    catch {
+        summary = null;
+    }
+    if (sealed.size > 500)
+        sealed.clear();
+    sealed.set(artifact.id, summary);
+    return summary;
+}
+const files = (count) => `${count} ${count === 1 ? "file" : "files"}`;
+/** A row's diff size: the sealed stats once finished, the pulse's count while it runs. */
+export function diffWords(facts, diff) {
+    if (facts.outcome !== null) {
+        if (diff === null)
+            return null;
+        if (diff.fileCount === 0)
+            return "No changes";
+        return `+${diff.additions} −${diff.deletions} · ${files(diff.fileCount)}`;
+    }
+    if (facts.diffFiles === null)
+        return null;
+    return facts.diffFiles === 0 ? "No changes yet" : `${files(facts.diffFiles)} changed`;
+}
+const SETTLING_PHASES = new Set(["validating-handoff", "capturing-evidence", "committing", "verifying-proof", "correcting-proof"]);
+/** Reasons whose words only restate the Failed chip: the row shows the agent's own last word instead, or nothing. */
+const RESTATES_FAILED = new Set(["agent"]);
+const minutes = (ms) => Math.max(1, Math.floor(ms / 60_000));
+/** A finished attempt's one line: never the state again (the chip says it), only why. */
+function endedLine(facts) {
+    const own = facts.said === "blocked" || facts.said === "done" ? facts.saidNote : null;
+    if (FINISHED_WELL.has(facts.outcome ?? ""))
+        return facts.said === "done" ? facts.saidNote : null;
+    if (facts.outcome === "parked")
+        return "Stopped to ask a question";
+    if (RESTATES_FAILED.has(facts.reason?.trim() ?? ""))
+        return own;
+    return failedAttemptSentence(facts.reason);
+}
+/** One board row. */
+export function agentRowOf(store, facts, now, root) {
+    const activity = facts.outcome === null ? runActivityOf(store, { id: facts.runId, runner: facts.runner, startedAt: facts.startedAt }, now) : null;
+    const { group, label } = agentGroupOf(facts, activity?.at ?? null, now);
+    let line, quiet = false;
+    if (facts.outcome !== null)
+        line = endedLine(facts);
+    else if (facts.question !== null)
+        line = facts.question.text;
+    else if (facts.repairing)
+        line = "Fixing the handoff";
+    else if (group === "stuck")
+        line = `No new output for ${Math.max(4, minutes(now.getTime() - quietSince({ stateAt: facts.stateAt ?? facts.startedAt, transcriptAt: facts.transcriptAt ?? facts.startedAt, toolAt: facts.toolAt }, activity.at)))} min`;
+    else if (facts.turn === "idle" || (facts.turn !== "crashed" && SETTLING_PHASES.has(facts.phase ?? "")))
+        line = "Checking the result";
+    else if (facts.turn === "busy" && facts.toolAt !== null && now.getTime() - Date.parse(facts.toolAt) >= 60_000) {
+        line = `${facts.toolKind === "command" ? "Running a command" : "Waiting on a tool"} · ${minutes(now.getTime() - Date.parse(facts.toolAt))} min`;
+    }
+    else {
+        const said = facts.saidNote !== null && facts.saidAt !== null && facts.saidAt >= activity.at ? facts.saidNote : null;
+        const read = activityLine(activity, now.getTime());
+        line = said ?? read.text;
+        quiet = said === null && read.quiet;
+    }
+    return {
+        runId: facts.runId, taskId: facts.taskId, title: facts.title, project: facts.repo === null ? null : projectName(facts.repo), href: `/agents?run=${facts.runId}`,
+        group, label, line, quiet, startedAt: facts.startedAt, endedAt: facts.finishedAt,
+        diff: diffWords(facts, facts.outcome === null ? null : sealedDiffOf(store, root, facts.runId)), agent: providerName(facts.provider),
+    };
+}
+/** The whole board: groups in order, rows newest first within each; empty groups dropped. */
+export function agentsBoardOf(store, now, access, account, root) {
+    const recent = new Date(now.getTime() - RECENT_MS).toISOString();
+    const rows = agentFacts(store, now, access, account).map(facts => ({ facts, row: agentRowOf(store, facts, now, root) }))
+        .filter(({ facts, row }) => facts.outcome === null || row.group === "done" || row.group === "needs-you" || (facts.finishedAt ?? "") >= recent)
+        .map(({ row }) => row);
+    return AGENT_GROUPS.map(group => ({ ...group, rows: rows.filter(row => row.group === group.key) })).filter(group => group.rows.length > 0);
+}
+/** A board fingerprint for one exact build: what its open view shows moved, its repairs included. */
+export function agentRunFingerprint(store, run) {
+    const row = store.handle.prepare(`SELECT r.outcome, r.finished_at, r.phase, n.state, n.state_at, n.transcript_bytes, n.stuck_at, n.said_at, n.diff_files, n.tool_at, n.question_note,
+      (SELECT count(*) || ':' || coalesce(max(id), 0) || ':' || coalesce(sum(closed_at IS NULL), 0) FROM agent_question WHERE run = r.id) AS asks,
+      (SELECT count(*) || ':' || coalesce(max(id), 0) || ':' || coalesce(sum(outcome IS NULL), 0) FROM run p WHERE p.parent_run = r.id AND p.role = 'repair') AS repairs,
+      (SELECT at FROM run_activity WHERE run = r.id) AS activity,
+      (SELECT count(*) || ':' || coalesce(max(id), 0) FROM task_steer WHERE task_ref = r.task_ref) AS steer
+    FROM run r LEFT JOIN agent_now n ON n.run = r.id AND n.attempt_key = r.attempt_key WHERE r.id = ?`).get(run);
+    return row === undefined ? null : Object.values(row).map(value => String(value)).join("|");
+}

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";
@@ -83,6 +83,7 @@ export declare function assignmentForCoordinator(store: Store, token: string, op
                     at: string;
                     digest: string;
                     lead?: true;
+                    landed?: string;
                 } | null;
                 result: {
                     digest: string;

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): {
@@ -17,7 +23,7 @@ export declare function assignmentStatusBrief(assignment: AssignmentSnapshot): {
     } | null;
     runId: number | null;
     primaryAction: {
-        code: "confirm-stopped" | "inspect-decisions" | "inspect-run" | "inspect-stop" | "inspect-task" | "open-pr" | "reconcile-run" | "sign-in" | import("./dispatch.js").DispatchAction;
+        code: "answer-agent" | "confirm-stopped" | "inspect-decisions" | "inspect-run" | "inspect-stop" | "inspect-task" | "open-pr" | "reconcile-run" | "sign-in" | import("./dispatch.js").DispatchAction;
         label: string;
         target: import("./work-summary.js").WorkTarget;
     } | null;
@@ -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;