toolroll 0.9.10 → 0.9.12

package/dist/flow-triggers.js

@@ -446,7 +446,13 @@ function polled(config) {
 function startZone(config, definition) {
     return config.zone !== null && definition.stages.some(one => one.id === config.zone) ? config.zone : definition.start;
 }
-/** One outside thing into one card, at most once per trigger. Keys and control characters never reach a card. */
+/** The active flow that already made a card for this failing commit in a project, if any. */
+function checksCardOf(store, repo, key) {
+    const row = store.handle.prepare(`SELECT f.name FROM flow_trigger_event e JOIN flow_trigger t ON t.id = e.trigger JOIN flow f ON f.id = t.flow
+    WHERE f.repo = ? AND f.state = 'active' AND e.key = ? AND e.card IS NOT NULL LIMIT 1`).get(repo, key);
+    return row === undefined ? null : `“${String(row["name"])}”`;
+}
+/** One outside thing into one card, at most once per trigger (a failing run, once per project). Keys and control characters never reach a card. */
 function makeCard(store, trigger, config, item, by, now) {
     const flow = store.getFlow(trigger.flow);
     const definition = flow === null ? null : flowDefinitionOf(flow);
@@ -460,7 +466,17 @@ function makeCard(store, trigger, config, item, by, now) {
         store.recordFlowTriggerEvent(trigger.id, item.key, null, note, now);
         return { made: "skipped", note: `${item.source.label}: ${note}`, card: null };
     }
+    // Claimed inside the write lock: a worker and a console (or an old and a new worker) checking at once make one card.
     return store.transact(() => {
+        if (store.flowTriggerSaw(trigger.id, item.key))
+            return { made: "seen", note: null, card: null };
+        // One failing run is one fix: a second trigger watching the same checks in this project leaves it to the first.
+        const filed = item.key.startsWith("checks:") ? checksCardOf(store, flow.repo, item.key) : null;
+        if (filed !== null) {
+            const note = `already a card in ${filed}`;
+            store.recordFlowTriggerEvent(trigger.id, item.key, null, note, now);
+            return { made: "skipped", note: `${item.source.label}: ${note}`, card: null };
+        }
         const card = store.addFlowCard({ flow: flow.id, title: text.title, description: text.description, stage: startZone(config, definition), by, source: item.source }, now);
         store.recordFlowTriggerEvent(trigger.id, item.key, card, null, now);
         return { made: "added", note: null, card };

package/dist/guides.js

@@ -95,6 +95,15 @@ login, so your housekeeping never pings them.
   or for a security alert.
 - Hand a task to a person: \`task ask <id> --person <name> --why "<what
   they need to do>"\` — one message, and the task is theirs from then on.
+- Tell your person what you are doing, at milestones: \`lead say "<one
+  short line>" [--task <id>]\` when you start work, when you are handling a
+  failure, and when you are done. Plain words ("Fixing the release check's
+  failing test"); several within two minutes become one message.
+- Take on a task you are fixing: \`assignment claim <id>\`. It reads "Your
+  lead is on it" instead of waiting for them and leaves Needs you until you
+  complete it, hand it over with \`task ask\`, or go two hours without
+  acting on it (then it is back with them, and says so). Claim a failure
+  before you start on it, and \`lead say\` what you are doing.
 - Re-filing (a release check re-gated as \`release-<name>b\`): \`task add
   "<title>" --id <new> --replaces <old>\`, or \`task state <old> cancelled
   --replaced-by <new>\`. The old task reads "Replaced by <new>", never

package/dist/lead-status.d.ts

@@ -76,6 +76,14 @@ export type InstallationStatus = {
         headline: string;
         sentence: string;
     }[];
+    /** What the person's lead is doing now and when it last acted (lead-voice.ts), as one line. */
+    lead: {
+        owner: string;
+        doing: string;
+        at: string;
+        task: string | null;
+        line: string;
+    } | null;
 };
 /** One indexed observation for `task wait`. `watchedRun` is the attempt the
  * caller first saw. Each poll follows the task's newest attempt from there, so
@@ -93,6 +101,7 @@ export declare function repairStaleStatuses(store: Store, now: Date): {
     exitsRecorded: number;
     readyForReview: number;
 };
-export declare function installationStatus(store: Store, now: Date): InstallationStatus;
+/** `viewer`: the person asking (the lead asks as its person); null when nobody is known, which shows no lead. */
+export declare function installationStatus(store: Store, now: Date, viewer?: string | null): InstallationStatus;
 export declare function renderInstallationStatus(status: InstallationStatus): string[];
 export declare function renderTaskWait(snapshot: TaskWaitSnapshot, outcome?: string): string;

package/dist/lead-status.js

@@ -5,6 +5,8 @@ import { windowLabel } from "./provider-limits.js";
 import { openAuthPauses, signInCommand, signInReason } from "./provider-auth.js";
 import { BUILT_IN, checkSuitesOf } from "./store.js";
 import { workIndexPage, workReadyForReview } from "./work-index.js";
+import { currentActor } from "./actor.js";
+import { leadActivity, leadActivityLine } from "./lead-voice.js";
 const maybeNumber = (value) => value === null || value === undefined || !Number.isInteger(Number(value)) ? null : Number(value);
 const CHECK_COLUMNS = "rc.status AS check_status, rc.exit_code AS check_exit_code, rc.suites_json AS check_suites_json";
 function checkOf(row) {
@@ -177,7 +179,8 @@ export function repairStaleStatuses(store, now) {
     const exitsRecorded = store.recordFinishedRunExits(now);
     return { exitsRecorded, readyForReview: workReadyForReview(store, now, { principal: "operator", repos: null, includeUnplaced: true }, 0).count };
 }
-export function installationStatus(store, now) {
+/** `viewer`: the person asking (the lead asks as its person); null when nobody is known, which shows no lead. */
+export function installationStatus(store, now, viewer = currentActor()?.account ?? null) {
     const runningRows = store.handle.prepare(`SELECT run.id, run.role, run.phase, ref.external_id AS task
     FROM run INDEXED BY work_unfinished
     JOIN task_ref AS ref ON ref.id = run.task_ref
@@ -251,8 +254,13 @@ export function installationStatus(store, now) {
             observedAt: String(row["observed_at"]),
         })),
         signIn: pauses.map(one => ({ provider: one.provider, reason: signInReason(one), command: signInCommand(one), since: one.openedAt })),
-        tasks: workIndexPage(store, now, { principal: "operator", repos: null, includeUnplaced: true }, { limit: 8 }).items
+        tasks: workIndexPage(store, now, { principal: "operator", repos: null, includeUnplaced: true, viewer }, { limit: 8 }).items
             .map(one => ({ task: one.rootId, title: one.title, headline: one.status.label, sentence: one.status.detail })),
+        lead: (() => {
+            // Only the asker's own lead: another person's lead is never "Your lead".
+            const activity = leadActivity(store, viewer);
+            return activity === null ? null : { owner: activity.owner, doing: activity.doing, at: activity.at, task: activity.taskId, line: leadActivityLine(activity, now) };
+        })(),
     };
 }
 export function renderInstallationStatus(status) {
@@ -260,6 +268,8 @@ export function renderInstallationStatus(status) {
     // A paused provider comes first: it is the one thing a person must do.
     for (const one of status.signIn)
         lines.push(`${one.reason} — run \`${one.command}\`. Its tasks wait until then.`);
+    if (status.lead != null)
+        lines.push(status.lead.line);
     // Each task's one headline, the same words as the console and chat cards.
     if (status.tasks.length > 0) {
         lines.push("Tasks:");
@@ -295,7 +305,7 @@ export function renderInstallationStatus(status) {
             lines.push(`Plan windows: ${provider} — ${detail}`);
         }
     }
-    return lines.slice(0, 12 + status.signIn.length + (status.tasks.length === 0 ? 0 : status.tasks.length + 1));
+    return lines.slice(0, 12 + status.signIn.length + (status.lead == null ? 0 : 1) + (status.tasks.length === 0 ? 0 : status.tasks.length + 1));
 }
 export function renderTaskWait(snapshot, outcome = snapshot.outcome) {
     const check = snapshot.check.status === "unknown" ? "checks unknown" : snapshot.check.status === "not-run" ? "checks not run" : `checks ${snapshot.check.status}${snapshot.check.exitCode === null ? "" : ` (exit ${snapshot.check.exitCode})`}`;

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.d.ts

@@ -50,6 +50,8 @@ export type OperateOptions = {
     gitRunner?: CommandRunner;
     /** Injected by tests: the Telegram Bot API. Production dials the real one. */
     telegramTransport?: TelegramTransport;
+    /** Injected by tests: the environment checked for a fenced network before Telegram is reached (default: this process's, with the real transport). */
+    telegramEnv?: Record<string, string | undefined>;
     publishExec?: PublishExec;
     /** Injected by tests: the stop fence a watch would set. */
     shouldStop?: () => boolean;