toolroll 0.9.11 → 0.9.12

package/dist/lead-voice.d.ts

@@ -0,0 +1,81 @@
+/** The lead's voice: what the person's lead (an agent under their lead token) is doing, in their chat and on the
+ * console. `lead say` posts one short message from "Your lead"; several within two minutes are one message, edited
+ * in place as it grows. `assignment claim` marks a task the lead's: it reads "Your lead is on it" and leaves Needs
+ * you until the lead completes it, hands it to a person, or two hours pass with no lead act on it.
+ *
+ * Every fact is an append-only ledger row under "lead for <owner>"; no table of its own. The chat message is an
+ * ordinary notification addressed to the owner, so every chat delivers it with the usual receipts. */
+import { type Actor } from "./actor.js";
+import { type Notification, type Store } from "./store.js";
+/** Who the person's chat says the lead's messages are from. */
+export declare const LEAD_NAME = "Your lead";
+export declare const LEAD_SAY_KIND = "lead-say";
+/** Repaints the owner's task card when the lead takes a task on: it never makes a new message in quiet chat. */
+export declare const LEAD_ON_IT_KIND = "lead-on-it";
+/** Repaints the owner's task card when a claim lapses: the card reads its real state again, and says so. */
+export declare const LEAD_LAPSED_KIND = "lead-lapsed";
+export declare const LEAD_SAID = "lead said";
+export declare const LEAD_CLAIMED = "lead is on it";
+/** A claim lapses after this long without a lead act on the task. */
+export declare const LEAD_IDLE_MS: number;
+/** The lead's acts that hand the task back: done, handed to a person, or cancelled. */
+export declare const LEAD_ENDS: readonly ["task completed", "task handed to a person", "task cancelled"];
+export declare const LEAD_SAY_MAX = 300;
+/** The work index's reading of a claim, per row of its `classified` projection: 0 none, 1 on it, 2 lapsed. Only the
+ * viewer's own lead counts (`$leadOf`, "lead for <viewer>"; null for nobody): another person's lead is not yours. */
+export declare const LEAD_CLAIM_SQL: string;
+export type LeadClaim = {
+    state: "on-it" | "lapsed";
+    owner: string;
+    since: string;
+    lastActedAt: string;
+};
+export type LeadActivity = {
+    owner: string;
+    doing: string;
+    at: string;
+    taskId: string | null;
+};
+type Failure = {
+    ok: false;
+    reason: "usage" | "unknown-task" | "refused";
+    message: string;
+};
+/** One line of the lead's words: plain, short, no control characters. */
+export declare function leadWordsProblem(text: string): string | null;
+/** `lead say`: record the words as the lead's act, and post them in the owner's chat. Within two minutes of the
+ * first, a later say joins it: the new row carries every line, and the earlier one stops waiting to be sent (a
+ * chat that already showed it edits that message in place). */
+export declare function leadSay(store: Store, actor: Actor, text: string, taskId: string | null, now: Date): {
+    ok: true;
+    joined: boolean;
+    notification: number | null;
+} | Failure;
+/** The words a chat shows for a lead-say row: "Your lead", then each line, plain, with no task id. */
+export declare function leadSayText(row: Pick<Notification, "subject" | "body">): string;
+/** The earlier rows of a lead-say message (newest first): a chat that showed one edits it rather than sending again. */
+export declare function leadSayEarlier(store: Store, row: Pick<Notification, "id" | "kind" | "dedupeKey" | "recipient">): number[];
+/** `assignment claim` under the lead token: the task is the lead's until it completes it, hands it on, or goes
+ * quiet on it for two hours. Repeating a claim is safe and counts as a lead act. */
+export declare function leadClaim(store: Store, actor: Actor, taskId: string, now: Date): {
+    ok: true;
+    root: string;
+    claim: LeadClaim;
+} | Failure;
+/** Whether `viewer`'s own lead has this task now: on it, lapsed after two quiet hours (it says so), or null (never
+ * claimed by their lead, handed on by it since, or completed or cancelled by anyone). Another person's lead never counts. */
+export declare function leadClaimOf(store: Store, taskId: string, now: Date, viewer: string | null | undefined): LeadClaim | null;
+/** A claim that lapsed repaints its owner's card once per lapse: the card reads the task's real state again and
+ * says it is back with them. Run beside the evening digests on every chat pass; claims are found through their
+ * repaint rows (an indexed key range), so nothing scans the ledger. */
+export declare function enqueueLeadLapses(store: Store, now: Date): number;
+/** The lead's act on a task that a claim counts (a retry, a state change, a steer): one ledger row as the lead. */
+export declare function noteLeadWork(store: Store, actor: Actor, taskId: string, what: string, now: Date): void;
+/** What `owner`'s own lead is doing now and when it last acted, both from its one newest act: its words when that
+ * was a say, else the act in words. Nobody (null) has no lead line: another person's lead is never "Your lead". */
+export declare function leadActivity(store: Store, owner: string | null | undefined): LeadActivity | null;
+/** "just now", "3 min ago", "2 h ago", "yesterday", "4 days ago". */
+export declare function agoWords(at: string, now: Date): string;
+/** The one line `toolroll status` and the console say: "Your lead: fixing 0.9.12's release check · 3 min ago". */
+export declare function leadActivityLine(activity: LeadActivity, now: Date): string;
+export {};

package/dist/lead-voice.js

@@ -0,0 +1,275 @@
+/** The lead's voice: what the person's lead (an agent under their lead token) is doing, in their chat and on the
+ * console. `lead say` posts one short message from "Your lead"; several within two minutes are one message, edited
+ * in place as it grows. `assignment claim` marks a task the lead's: it reads "Your lead is on it" and leaves Needs
+ * you until the lead completes it, hands it to a person, or two hours pass with no lead act on it.
+ *
+ * Every fact is an append-only ledger row under "lead for <owner>"; no table of its own. The chat message is an
+ * ordinary notification addressed to the owner, so every chat delivers it with the usual receipts. */
+import { actorLabel, withActor } from "./actor.js";
+import { chatControlHref } from "./chat-controls.js";
+import { BATCH_MS, chatText, chatTitle } from "./chat-voice.js";
+import { BUILT_IN } from "./store.js";
+import { LEAD_LAPSED } from "./task-status.js";
+import { phoneText as plain } from "./telegram-status.js";
+/** Who the person's chat says the lead's messages are from. */
+export const LEAD_NAME = "Your lead";
+export const LEAD_SAY_KIND = "lead-say";
+/** Repaints the owner's task card when the lead takes a task on: it never makes a new message in quiet chat. */
+export const LEAD_ON_IT_KIND = "lead-on-it";
+/** Repaints the owner's task card when a claim lapses: the card reads its real state again, and says so. */
+export const LEAD_LAPSED_KIND = "lead-lapsed";
+export const LEAD_SAID = "lead said";
+export const LEAD_CLAIMED = "lead is on it";
+/** A claim lapses after this long without a lead act on the task. */
+export const LEAD_IDLE_MS = 2 * 3_600_000;
+/** The lead's acts that hand the task back: done, handed to a person, or cancelled. */
+export const LEAD_ENDS = ["task completed", "task handed to a person", "task cancelled"];
+/** Acts by anyone that end a claim: a completed or cancelled task is nobody's to be on. */
+const DONE_ACTS_SQL = "'completed','cancelled'";
+export const LEAD_SAY_MAX = 300;
+/** Lines one batched message keeps; the oldest go first. */
+const BATCH_LINES = 8;
+const ENDS_SQL = LEAD_ENDS.map(one => `'${one}'`).join(",");
+/** The work index's reading of a claim, per row of its `classified` projection: 0 none, 1 on it, 2 lapsed. Only the
+ * viewer's own lead counts (`$leadOf`, "lead for <viewer>"; null for nobody): another person's lead is not yours. */
+export const LEAD_CLAIM_SQL = `COALESCE((SELECT CASE
+      WHEN EXISTS(SELECT 1 FROM action_ledger e WHERE e.task_id IN (SELECT m.id FROM ordered m WHERE m.root_ref = c.root_ref)
+        AND e.id > claim.id AND e.actor = claim.actor AND e.action IN (${ENDS_SQL})) THEN 0
+      WHEN EXISTS(SELECT 1 FROM task_act t WHERE t.task_ref IN (SELECT m.ref_id FROM ordered m WHERE m.root_ref = c.root_ref)
+        AND t.act IN (${DONE_ACTS_SQL}) AND t.at >= claim.at) THEN 0
+      WHEN (SELECT MAX(a.at) FROM action_ledger a WHERE a.task_id IN (SELECT m.id FROM ordered m WHERE m.root_ref = c.root_ref)
+        AND a.id >= claim.id AND a.actor = claim.actor) > $leadIdleSince THEN 1 ELSE 2 END
+    FROM action_ledger claim WHERE claim.id = (SELECT MAX(id) FROM action_ledger WHERE task_id = c.root_id AND action = '${LEAD_CLAIMED}' AND actor = $leadOf)), 0)`;
+/** A task family's root and every version, following revisions both ways. */
+function familyOf(store, taskId) {
+    const root = store.handle.prepare(`WITH RECURSIVE up(id, depth) AS (SELECT ?, 0 UNION ALL
+      SELECT r.revision_of, up.depth + 1 FROM up JOIN task_ref r ON r.backend = ? AND r.external_id = up.id WHERE r.revision_of IS NOT NULL AND up.depth < 64)
+    SELECT id FROM up ORDER BY depth DESC LIMIT 1`).get(taskId, BUILT_IN);
+    const top = root === undefined ? taskId : String(root["id"]);
+    const ids = store.handle.prepare(`WITH RECURSIVE down(id, depth) AS (SELECT ?, 0 UNION ALL
+      SELECT r.external_id, down.depth + 1 FROM down JOIN task_ref r ON r.backend = ? AND r.revision_of = down.id WHERE down.depth < 64)
+    SELECT DISTINCT id FROM down`).all(top, BUILT_IN).map(row => String(row["id"]));
+    return { root: top, ids };
+}
+/** One line of the lead's words: plain, short, no control characters. */
+export function leadWordsProblem(text) {
+    const words = text.trim();
+    if (words === "")
+        return "Say something: `toolroll lead say \"<what you're doing>\"`.";
+    if (words.length > LEAD_SAY_MAX)
+        return `Keep it short: at most ${LEAD_SAY_MAX} characters.`;
+    if (/[\u0000-\u001f\u007f]/.test(words))
+        return "One line of plain text.";
+    return null;
+}
+/** The task the lead names, if its owner can see it. */
+function admittedTask(store, owner, taskId) {
+    const ref = store.lookupRef(taskId);
+    if (ref === null || store.getTask(taskId) === null)
+        return { ok: false, reason: "unknown-task", message: `No task \`${taskId}\`.` };
+    if (ref.repo !== null && !store.accountCanAccess(owner, ref.repo))
+        return { ok: false, reason: "unknown-task", message: `No task \`${taskId}\`.` };
+    return { refId: ref.id, repo: ref.repo };
+}
+/** `lead say`: record the words as the lead's act, and post them in the owner's chat. Within two minutes of the
+ * first, a later say joins it: the new row carries every line, and the earlier one stops waiting to be sent (a
+ * chat that already showed it edits that message in place). */
+export function leadSay(store, actor, text, taskId, now) {
+    if (!actor.lead)
+        return { ok: false, reason: "refused", message: "Only the lead speaks as the lead: pass its lead token." };
+    const problem = leadWordsProblem(text);
+    if (problem !== null)
+        return { ok: false, reason: "usage", message: problem };
+    const task = taskId === null ? null : admittedTask(store, actor.account, taskId);
+    if (task !== null && "ok" in task)
+        return task;
+    // The task's own id never reaches a chat: it reads as the task's short title (chat-voice.ts).
+    const said = taskId === null ? text.trim() : chatText(text.trim(), [{ id: taskId, title: chatTitle(store, taskId) }]);
+    return store.transact(() => {
+        const stamp = now.toISOString();
+        const ledger = store.recordAction({ at: stamp, actor: actorLabel(actor), repo: task?.repo ?? null, taskId, runId: null,
+            action: LEAD_SAID, outcome: "recorded", source: "work", detail: text.trim() });
+        const open = store.handle.prepare(`SELECT id, dedupe_key, body FROM notification WHERE kind = ? AND recipient = ? ORDER BY id DESC LIMIT 1`)
+            .get(LEAD_SAY_KIND, actor.account);
+        const opened = open === undefined ? null : /^lead-say:(.+):\d+$/.exec(String(open["dedupe_key"]))?.[1] ?? null;
+        const joined = open !== undefined && opened !== null && Date.parse(opened) > now.getTime() - BATCH_MS && Date.parse(opened) <= now.getTime();
+        const lines = [...(joined ? String(open["body"]).split("\n") : []), said].slice(-BATCH_LINES);
+        if (joined)
+            store.handle.prepare("UPDATE notification SET resolved_at = ? WHERE id = ? AND resolved_at IS NULL").run(stamp, Number(open["id"]));
+        const key = `lead-say:${joined ? opened : stamp}:${ledger}`;
+        store.enqueueNotification({ dedupeKey: key, kind: LEAD_SAY_KIND, subject: LEAD_NAME, body: lines.join("\n"),
+            recipient: actor.account, source: { installation: true }, ...(taskId === null ? {} : { link: chatControlHref("task", taskId) }) }, now);
+        const row = store.handle.prepare("SELECT id FROM notification WHERE dedupe_key = ?").get(key);
+        return { ok: true, joined, notification: row === undefined ? null : Number(row["id"]) };
+    });
+}
+/** The words a chat shows for a lead-say row: "Your lead", then each line, plain, with no task id. */
+export function leadSayText(row) {
+    return chatText([plain(row.subject, 60), "", ...row.body.split("\n").map(line => plain(line, LEAD_SAY_MAX)).filter(line => line !== "")].join("\n"));
+}
+/** The earlier rows of a lead-say message (newest first): a chat that showed one edits it rather than sending again. */
+export function leadSayEarlier(store, row) {
+    if (row.kind !== LEAD_SAY_KIND || row.recipient === null)
+        return [];
+    const opened = /^(lead-say:.+:)\d+$/.exec(row.dedupeKey)?.[1];
+    if (opened === undefined)
+        return [];
+    return store.handle.prepare(`SELECT id FROM notification WHERE kind = ? AND recipient = ? AND id < ? AND substr(dedupe_key, 1, ?) = ? ORDER BY id DESC`)
+        .all(LEAD_SAY_KIND, row.recipient, row.id, opened.length, opened).map(one => Number(one["id"]));
+}
+/** `assignment claim` under the lead token: the task is the lead's until it completes it, hands it on, or goes
+ * quiet on it for two hours. Repeating a claim is safe and counts as a lead act. */
+export function leadClaim(store, actor, taskId, now) {
+    if (!actor.lead)
+        return { ok: false, reason: "refused", message: "Only the lead takes a task on as the lead: pass its lead token." };
+    const task = admittedTask(store, actor.account, taskId);
+    if ("ok" in task)
+        return task;
+    const { root } = familyOf(store, taskId);
+    store.transact(() => {
+        const ledger = store.recordAction({ at: now.toISOString(), actor: actorLabel(actor), repo: task.repo, taskId: root, runId: null,
+            action: LEAD_CLAIMED, outcome: "recorded", source: "work" });
+        // The owner's card for this task repaints to "Your lead is on it": quiet chat edits its card, and every-update
+        // chat edits the attempt's own card (the Failed alert), or follows it up when that message is gone.
+        store.enqueueNotification({ dedupeKey: `lead-on-it:${ledger}`, kind: LEAD_ON_IT_KIND, subject: "Your lead is on it", body: "",
+            link: chatControlHref("task", taskId), source: cardSource(store, root) ?? { taskRef: task.refId } }, now);
+    });
+    return { ok: true, root, claim: leadClaimOf(store, taskId, now, actor.account) };
+}
+/** Where a task's chat card lives: the family's newest attempt (the card every-update chat edits), else its newest
+ * version. Null for a task with no reference. */
+function cardSource(store, root) {
+    const refs = familyOf(store, root).ids.map(id => store.lookupRef(id)).filter(ref => ref !== null).sort((a, b) => b.id - a.id);
+    const newest = refs[0];
+    if (newest === undefined)
+        return null;
+    const runs = refs.flatMap(ref => store.runsFor(ref.id)).filter(one => one.role === "builder" && one.contestant === null);
+    const run = runs.reduce((top, one) => top === null || one.id > top ? one.id : top, null);
+    return run === null ? { taskRef: newest.id } : { run };
+}
+/** Whether anyone completed or cancelled the task family (since `since`, when given), or its newest version is
+ * cancelled however that happened: a finished task is nobody's to be on. */
+function familyEnded(store, ids, since) {
+    const refs = ids.map(id => store.lookupRef(id)).filter(ref => ref !== null).sort((a, b) => b.id - a.id);
+    if (refs[0] === undefined)
+        return false;
+    if (store.getTask(refs[0].externalId)?.state === "cancelled")
+        return true;
+    return store.handle.prepare(`SELECT 1 AS hit FROM task_act WHERE task_ref IN (${refs.map(() => "?").join(",")}) AND act IN (${DONE_ACTS_SQL})
+    AND at >= ? LIMIT 1`).get(...refs.map(ref => ref.id), since ?? "") !== undefined;
+}
+/** Whether `viewer`'s own lead has this task now: on it, lapsed after two quiet hours (it says so), or null (never
+ * claimed by their lead, handed on by it since, or completed or cancelled by anyone). Another person's lead never counts. */
+export function leadClaimOf(store, taskId, now, viewer) {
+    if (viewer == null || viewer === "")
+        return null;
+    try {
+        const { root, ids } = familyOf(store, taskId);
+        const claim = store.handle.prepare("SELECT id, at, actor FROM action_ledger WHERE task_id = ? AND action = ? AND actor = ? ORDER BY id DESC LIMIT 1")
+            .get(root, LEAD_CLAIMED, `lead for ${viewer}`);
+        if (claim === undefined)
+            return null;
+        const family = `task_id IN (${ids.map(() => "?").join(",")}) AND id >= ? AND actor = ?`;
+        const args = [...ids, Number(claim["id"]), String(claim["actor"])];
+        // Completed, handed on or cancelled by the lead since its claim: the claim is over.
+        if (store.handle.prepare(`SELECT 1 AS hit FROM action_ledger WHERE ${family} AND action IN (${ENDS_SQL}) LIMIT 1`).get(...args) !== undefined)
+            return null;
+        if (familyEnded(store, ids, String(claim["at"])))
+            return null;
+        const latest = store.handle.prepare(`SELECT MAX(at) AS at FROM action_ledger WHERE ${family}`).get(...args);
+        const lastActedAt = String(latest?.["at"] ?? claim["at"]);
+        return { state: Date.parse(lastActedAt) > now.getTime() - LEAD_IDLE_MS ? "on-it" : "lapsed",
+            owner: String(claim["actor"]).replace(/^lead for /, ""), since: String(claim["at"]), lastActedAt };
+    }
+    catch {
+        // An older store being read by a newer build: no claim is the safe reading.
+        return null;
+    }
+}
+/** A claim that lapsed repaints its owner's card once per lapse: the card reads the task's real state again and
+ * says it is back with them. Run beside the evening digests on every chat pass; claims are found through their
+ * repaint rows (an indexed key range), so nothing scans the ledger. */
+export function enqueueLeadLapses(store, now) {
+    let count = 0;
+    try {
+        const since = new Date(now.getTime() - 14 * 86_400_000).toISOString();
+        const claims = store.handle.prepare(`SELECT DISTINCT n.task_id, a.account FROM notification n JOIN notification_actor a ON a.notification = n.id AND a.lead = 1
+      WHERE n.dedupe_key >= 'lead-on-it:' AND n.dedupe_key < 'lead-on-it;' AND n.created_at >= ? AND n.task_id IS NOT NULL`).all(since);
+        for (const row of claims) {
+            const owner = String(row["account"]);
+            const taskId = String(row["task_id"]);
+            const claim = leadClaimOf(store, taskId, now, owner);
+            if (claim?.state !== "lapsed")
+                continue;
+            const { root, ids } = familyOf(store, taskId);
+            // A completed or cancelled task never repaints as back with them.
+            if (store.getTask(root) === null || familyEnded(store, ids, null))
+                continue;
+            const source = cardSource(store, root);
+            if (source === null)
+                continue;
+            // The owner's lead let it go: only its owner's card hears of it (store.pingAllowed).
+            if (withActor({ account: owner, lead: true }, () => store.enqueueNotification({ dedupeKey: `lead-lapsed:${root}:${owner}:${claim.lastActedAt}`,
+                kind: LEAD_LAPSED_KIND, subject: LEAD_LAPSED, body: "", link: chatControlHref("task", root), source }, now)))
+                count++;
+        }
+    }
+    catch {
+        // An older store being read by a newer build: nothing to repaint.
+    }
+    return count;
+}
+/** The lead's act on a task that a claim counts (a retry, a state change, a steer): one ledger row as the lead. */
+export function noteLeadWork(store, actor, taskId, what, now) {
+    if (!actor.lead)
+        return;
+    const ref = store.lookupRef(taskId);
+    if (ref === null)
+        return;
+    store.recordAction({ at: now.toISOString(), actor: actorLabel(actor), repo: ref.repo, taskId, runId: null, action: `lead ${what}`, outcome: "recorded", source: "work" });
+}
+const ACT_WORDS = {
+    "task filed": "filed", "task approved": "approved", "task cancelled": "cancelled", "task completed": "completed",
+    "task handed to a person": "handed on", [LEAD_CLAIMED]: "working on",
+};
+/** What `owner`'s own lead is doing now and when it last acted, both from its one newest act: its words when that
+ * was a say, else the act in words. Nobody (null) has no lead line: another person's lead is never "Your lead". */
+export function leadActivity(store, owner) {
+    if (owner == null || owner === "")
+        return null;
+    try {
+        const last = store.handle.prepare("SELECT id, at, actor, task_id, action, detail FROM action_ledger WHERE actor = ? ORDER BY id DESC LIMIT 1").get(`lead for ${owner}`);
+        if (last === undefined)
+            return null;
+        const task = last["task_id"] == null ? null : String(last["task_id"]);
+        const title = task === null ? "" : (() => { try {
+            return ` ${chatTitle(store, task)}`;
+        }
+        catch {
+            return "";
+        } })();
+        const doing = last["action"] === LEAD_SAID && last["detail"] != null ? chatText(String(last["detail"]), task === null ? [] : [{ id: task, title: title.trim() }])
+            : `${ACT_WORDS[String(last["action"])] ?? String(last["action"]).replace(/^lead /, "")}${title}`;
+        return { owner, doing: doing.replace(/[.\s]+$/u, ""), at: String(last["at"]), taskId: task };
+    }
+    catch {
+        return null;
+    }
+}
+/** "just now", "3 min ago", "2 h ago", "yesterday", "4 days ago". */
+export function agoWords(at, now) {
+    const minutes = Math.max(0, Math.floor((now.getTime() - Date.parse(at)) / 60_000));
+    if (!Number.isFinite(minutes) || minutes < 1)
+        return "just now";
+    if (minutes < 60)
+        return `${minutes} min ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours} h ago`;
+    const days = Math.floor(hours / 24);
+    return days === 1 ? "yesterday" : `${days} days ago`;
+}
+/** The one line `toolroll status` and the console say: "Your lead: fixing 0.9.12's release check · 3 min ago". */
+export function leadActivityLine(activity, now) {
+    return `${LEAD_NAME}: ${activity.doing} · ${agoWords(activity.at, now)}`;
+}

package/dist/needs-you.d.ts

@@ -29,6 +29,13 @@ type Need = {
     withReason?: (reason: string) => string;
 };
 export declare const NEEDS: Readonly<Record<NeedKey, Need>>;
+/** What a waiting task asks of a person, in three kinds the Tasks list groups
+ * by: a choice to make, a result to accept or send back, or something in the
+ * way to clear. Decide comes first. */
+export type Ask = "decide" | "review" | "unblock";
+export declare const ASKS: readonly Ask[];
+export declare const ASK_LABEL: Readonly<Record<Ask, string>>;
+export declare const NEED_ASK: Readonly<Record<NeedKey, Ask>>;
 export declare const WAITS: Readonly<Record<WaitKey, (context: NeedContext) => string>>;
 /** Words that name the machine's internals; no Needs you or Waiting sentence carries them. */
 export declare const BANNED_WORDS: readonly ["witness", "unproven", "quiescence", "quiescent", "digest", "scope digest"];

package/dist/needs-you.js

@@ -34,6 +34,15 @@ export const NEEDS = {
     "earlier-version": { sentence: () => "An earlier version of this task still needs you. Finish it first.", action: { code: "inspect-task", label: "Open earlier version" } },
     other: { sentence: () => "Open the task to see what it needs from you.", action: { code: "inspect-task", label: "Open the task" }, useReason: always },
 };
+export const ASKS = ["decide", "review", "unblock"];
+export const ASK_LABEL = { decide: "Decide", review: "Review", unblock: "Unblock" };
+export const NEED_ASK = {
+    approval: "decide", card: "decide", answer: "decide", questions: "decide", "choose-project": "decide", "define-task": "decide",
+    "fix-request": "decide", "choose-agent": "decide",
+    "review-result": "review", rebuild: "review",
+    "sign-in": "unblock", "confirm-stopped": "unblock", "check-stopped": "unblock", hold: "unblock", "fix-dependency": "unblock",
+    "add-requirement": "unblock", "connect-builder": "unblock", "start-builder": "unblock", vanished: "unblock", "earlier-version": "unblock", other: "unblock",
+};
 export const WAITS = {
     "build-stopping": context => `Waiting for ${build(context)} to stop. Nothing is needed from you.`,
     "other-computer": context => `Waiting for the computer that ran ${build(context)} to confirm it stopped.`,

package/dist/operate.js

@@ -89,6 +89,7 @@ import { pushPass } from "./push.js";
 import { chmodSync, closeSync, constants as fsConstants, existsSync, fstatSync, fsyncSync, openSync, readFileSync, readSync, realpathSync, renameSync, unlinkSync, writeSync, writeFileSync, mkdirSync } from "node:fs";
 import { BRANCH_PREFIX, envTwins, envValue, existingOrFirst, namedPath, taskBranches } from "./names.js";
 import { claimActor, currentActor, parseLeadToken, withActor } from "./actor.js";
+import { leadClaim, leadSay, noteLeadWork } from "./lead-voice.js";
 import { createServer as createNetServer } from "node:net";
 import { spawn as spawnChild } from "node:child_process";
 import { envelopeJson } from "./envelope.js";
@@ -638,6 +639,8 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "replaced-by", "replaces",
     // Check levels: a project's level, the quick command, a task's choice.
     "quick", "level", "checks",
+    // lead say: the task the lead's words are about.
+    "task",
 ]);
 export const OPERATE_BOOLEAN_FLAGS = new Set([
     "json", "yes", "all", "local", "history", "latest-watch", "dry-run", "file", "allow-paid-fallback",
@@ -968,6 +971,9 @@ async function dispatch(command, positional, flags, context) {
                 return projectConcurrencyCommand(positional, flags, context);
             return runProjectCommand(positional, flags, context);
         case "assignment":
+            // The person's own lead (its lead token) claims as the lead; coordinator credentials keep their own path.
+            if (positional[0] === "claim" && currentActor()?.lead === true && !flags.has("token-env") && !flags.has("token-file"))
+                return leadClaimCommand(positional, flags, context);
             return runAssignmentCommand(positional, flags, context);
         case "knowledge":
             return runKnowledgeCommand(positional, flags, { ...context, now: context.clock() });
@@ -7334,6 +7340,8 @@ function startTelegramFollower(args) {
         return null;
     });
 }
+/** How long a stopping service waits for the aborted Telegram follower. */
+const TELEGRAM_STOP_WAIT_MS = 5_000;
 let staleStatusesRepaired = false;
 async function runWatchLoop(args) {
     const { context, flags, runner, token, repo, progress } = args;
@@ -8488,6 +8496,10 @@ async function upCommand(flags, context) {
         resolveStopped();
         for (const controller of followControllers)
             controller.abort();
+        // The coding owner record is released first, whatever else is still
+        // finishing: launchd kills a service that outlasts its exit window, and a
+        // killed process cannot release it. Its outcome is read again at close.
+        console_.server.closeCoding().catch(() => { });
         const building = store.liveClaimCount(runnerName, clock());
         if (building > 0) {
             progress(`Stopping: ${building} build(s) running. Waiting up to ${Math.round(stopGraceMs / 1000)}s for them to finish; any still running then is saved and resumes when the builder starts again.`);
@@ -8591,7 +8603,11 @@ async function upCommand(flags, context) {
         const pause = (ms) => new Promise(resolvePause => {
             const timer = setTimeout(done, ms);
             function done() { clearTimeout(timer); telegramController.signal.removeEventListener("abort", done); resolvePause(); }
-            telegramController.signal.addEventListener("abort", done, { once: true });
+            // An aborted signal never fires again: without this a stop waited the whole pause.
+            if (telegramController.signal.aborted)
+                done();
+            else
+                telegramController.signal.addEventListener("abort", done, { once: true });
         });
         while (!stopping && !telegramController.signal.aborted) {
             const follower = startTelegramFollower({
@@ -8740,7 +8756,14 @@ async function upCommand(flags, context) {
     await stopped;
     await registrySupervisor;
     await Promise.all([...loopResults.values()]);
-    await telegramSupervisor;
+    // The follower was aborted with the stop. A send or a chat turn it is still
+    // finishing keeps its own durable record; the service does not wait past
+    // this for it.
+    await new Promise(done => {
+        const timer = setTimeout(done, TELEGRAM_STOP_WAIT_MS);
+        const finish = () => { clearTimeout(timer); done(); };
+        void telegramSupervisor.then(finish, finish);
+    });
     clearInterval(runnerHeartbeat);
     if (runTimer !== undefined)
         clearTimeout(runTimer);
@@ -9630,7 +9653,9 @@ async function statusCommand(positional, flags, context) {
     }
     if (positional.length > 0)
         return fail(context.write, context.json, command, "usage", "Use `toolroll status [--json]`.", EXIT.usage);
-    const status = installationStatus(context.store, context.clock());
+    // Whose lead the status line follows: the lead's own person, else the remembered login; nobody shows no lead.
+    const viewer = currentActor()?.account ?? readLoginFile(join(dirname(context.databaseFile), UP_LOGIN_FILE))?.name ?? null;
+    const status = installationStatus(context.store, context.clock(), viewer);
     // One line, only when a newer Toolroll exists; offline or switched off says nothing.
     const current = PACKAGE_VERSION;
     const method = installMethod(context.installBin);
@@ -9770,6 +9795,19 @@ function taskCommand(positional, flags, context) {
         context.write(OPERATE_HELP);
         return EXIT.ok;
     }
+    // The lead's work on a task it took on counts as acting on it (lead-voice.ts): its claim stays fresh.
+    const actor = currentActor();
+    if (actor?.lead === true && rest[0] !== undefined && LEAD_WORK_VERBS.has(action)) {
+        const noted = (code) => { if (code === EXIT.ok)
+            noteLeadWork(context.store, actor, rest[0], action, context.clock()); return code; };
+        const done = taskAction(action, rest, flags, context);
+        return typeof done === "number" ? noted(done) : done.then(noted);
+    }
+    return taskAction(action, rest, flags, context);
+}
+/** Task verbs that are the lead working on a task, not reading it. */
+const LEAD_WORK_VERBS = new Set(["state", "steer", "reopen", "requeue", "regate", "repair", "resume", "stop", "scope", "approve", "plan", "checks", "revise", "hold", "unhold", "route", "require"]);
+function taskAction(action, rest, flags, context) {
     switch (action) {
         case "complete":
         case "revise":
@@ -10598,9 +10636,11 @@ function askTask(positional, flags, context) {
 async function leadCommand(positional, flags, context) {
     const { store, write, json } = context;
     const [action, ...extra] = positional;
+    if (action === "say")
+        return leadSayCommand(extra, flags, context);
     const command = "lead token";
     if (action !== "token" || extra.length > 0)
-        return fail(write, json, `lead ${action ?? ""}`.trim(), "usage", "`toolroll lead token [--revoke] --as <you> --token <password>`", EXIT.usage);
+        return fail(write, json, `lead ${action ?? ""}`.trim(), "usage", "`toolroll lead token [--revoke] --as <you> --token <password>` · `toolroll lead say \"<text>\" [--task <id>]` with the lead token", EXIT.usage);
     for (const name of flags.keys())
         if (!["as", "token", "revoke", "db", "json"].includes(name))
             return fail(write, json, command, "usage", `--${name} is not a lead token option.`, EXIT.usage);
@@ -10624,6 +10664,42 @@ async function leadCommand(positional, flags, context) {
         "it reaches you when the lead asks you (task ask), when it fails with nothing left to try, or for a security alert.",
     ]);
 }
+/** `lead say "<text>" [--task <id>]` with the lead token: one short message in its person's chat from "Your lead".
+ * Several within two minutes are one message. */
+function leadSayCommand(positional, flags, context) {
+    const { store, write, json } = context;
+    const command = "lead say";
+    for (const name of flags.keys())
+        if (!["task", "db", "json"].includes(name))
+            return fail(write, json, command, "usage", `--${name} is not a lead say option.`, EXIT.usage);
+    const task = flags.get("task");
+    if (positional.length === 0 || task === true)
+        return fail(write, json, command, "usage", "`toolroll lead say \"<what you're doing>\" [--task <id>]` with the lead token", EXIT.usage);
+    const actor = currentActor();
+    if (actor?.lead !== true)
+        return fail(write, json, command, "unauthenticated", "Only the lead speaks as the lead: pass its lead token (--token or TOOLROLL_LEAD_TOKEN).", EXIT.refused);
+    const said = leadSay(store, actor, positional.join(" "), task ?? null, context.clock());
+    if (!said.ok)
+        return fail(write, json, command, said.reason, said.message, said.reason === "usage" ? EXIT.usage : EXIT.refused);
+    return succeed(write, json, command, { owner: actor.account, task: task ?? null, joined: said.joined, notification: said.notification }, () => [said.joined ? `Added to your last message to ${actor.account}.` : `Told ${actor.account}.`]);
+}
+/** `assignment claim <task>` with the lead token: the task reads "Your lead is on it" and leaves Needs you until the
+ * lead completes it, hands it on (task ask), or two hours pass with no lead act on it. */
+function leadClaimCommand(positional, flags, context) {
+    const { store, write, json } = context;
+    const command = "assignment claim";
+    for (const name of flags.keys())
+        if (!["db", "json"].includes(name))
+            return fail(write, json, command, "usage", `--${name} is not an assignment claim option.`, EXIT.usage);
+    const id = positional[1];
+    if (id === undefined || positional.length !== 2)
+        return fail(write, json, command, "usage", "assignment claim takes exactly one task id.", EXIT.usage);
+    const actor = currentActor();
+    const claimed = leadClaim(store, actor, id, context.clock());
+    if (!claimed.ok)
+        return fail(write, json, command, claimed.reason, claimed.message, claimed.reason === "usage" ? EXIT.usage : EXIT.refused);
+    return succeed(write, json, command, { task: id, root: claimed.root, lead: claimed.claim }, () => [`${id} is yours: it reads "Your lead is on it" until you complete it, hand it on with task ask, or go two hours without acting on it.`]);
+}
 function blockTask(positional, flags, context) {
     const { store, write, json } = context;
     const id = positional[0];

package/dist/serve.d.ts

@@ -189,10 +189,14 @@ export type ServeOptions = {
 /** Where `up`'s one-time sign-in link points, and how long it works. */
 export declare const SIGN_IN_LINK_PATH = "/login/once/";
 export declare const SIGN_IN_LINK_MS: number;
-/** The console's server, and the one-time sign-in link `up` opens: a path on this server, or null for no such approver. */
+/** The console's server, and the one-time sign-in link `up` opens: a path on this server, or null for no such approver.
+ * closeCoding starts the coding shutdown on its own, ahead of the rest of a stop; close() awaits the same promise. */
 export type DecisionServer = Server & {
     mintSignInLink(account: string): string | null;
+    closeCoding(): Promise<void>;
 };
+/** How long a stop waits for teammates and the lead's follow pass before closing anyway. */
+export declare const SHUTDOWN_WAIT_MS = 5000;
 export declare function createDecisionServer(options: ServeOptions): DecisionServer;
 /**
  * A vscode://file href, or null (arc 6, finding 2): the link exists only