@timqi/pier 0.0.29 → 0.1.1

package/dist/tasks/tool.js

@@ -1,21 +1,14 @@
 import { isAbsolute, resolve } from "node:path";
 import { Type } from "typebox";
-import { TaskDefinitions, record, requiredString } from "./definitions.js";
-import { TaskMessenger } from "./messages.js";
-import { TaskStore } from "./store.js";
+import { logger } from "../log.js";
+import { record, requiredString } from "./definitions.js";
+import { isTerminal } from "./types.js";
+const log = logger("tasks");
 // JSON-Schema enum emits ~1/3 the tokens of typebox's anyOf-of-consts.
 const strEnum = (...values) => Type.Unsafe({ type: "string", enum: [...values] });
-/**
- * Drop the fields with nothing in them instead of sending `null`.
- *
- * A run summary has eighteen fields and most are empty for most of a run's
- * life; a model reads "absent" and "null" the same way. On a `get` that lists
- * several runs this is a third of the payload.
- *
- * The input names every field — a summary that forgot one would otherwise pass
- * as "that field was empty" — and the result is the type with the empty ones
- * gone, which is why those are declared optional above.
- */
+/** Absent instead of `null`: a model reads both the same way, and on a group
+ *  summary the nulls are a third of the payload. The input names every field
+ *  so a summary that forgot one cannot pass as "empty". */
 const defined = (value) => Object.fromEntries(Object.entries(value).filter(([, v]) => v !== null && v !== undefined));
 const summarize = (run, pendingDecisionId) => defined({
     runId: run.id,
@@ -28,6 +21,7 @@ const summarize = (run, pendingDecisionId) => defined({
     targetSessionId: run.targetSessionId,
     callbackSessionId: run.callbackSessionId,
     callbackState: run.callbackState,
+    callbackMode: run.callbackMode ?? null,
     pendingDecisionId,
     depth: run.depth,
     queuedAt: run.queuedAt,
@@ -36,9 +30,35 @@ const summarize = (run, pendingDecisionId) => defined({
     result: run.result,
     error: run.error,
     skipReason: run.skipReason,
+    next: null,
 });
-/** A list echoes many results at once, so each is capped; a single-run `get`
- * stays whole — it is the escape hatch every truncation note points at. */
+/** The receipt says the callback is the whole answer, or a model that just
+ *  launched work reaches for a status call. */
+const receipt = (summary, callbackSessionId, mode, callerSessionId) => ({
+    ...summary,
+    next: callbackSessionId === null
+        ? "callback none: the result is not delivered to anyone"
+        : callbackSessionId !== callerSessionId
+            ? `the result is delivered to session ${callbackSessionId}; this session will not receive a callback`
+            : mode === "steer"
+                ? "the result interrupts your running turn as a steer message; nothing to query"
+                : "the result arrives as a callback message once your turn ends; nothing to query",
+});
+const SUBAGENT_REDIRECT = "subagents cannot redirect callbacks (callback_session_id)";
+/** Who a new run's result goes to — the caller, nobody, or a named session that
+ *  must exist. Shared by `run` and `resume`: a resumed run is a new run. */
+const callbackTarget = async (input, definitions, callerSessionId) => {
+    if (input.callback_session_id === undefined)
+        return input.callback === "none" ? null : callerSessionId;
+    if (input.callback === "none")
+        throw new Error("callback none and callback_session_id conflict: pick one delivery target");
+    const target = requiredString(input.callback_session_id, "callback_session_id");
+    if (!(await definitions.sessionExists(target)))
+        throw new Error(`unknown session: ${target}`);
+    return target;
+};
+/** A group echoes many results at once, so each is capped; a single-run
+ * `recover` stays whole — it is the escape hatch every truncation note points at. */
 const trimResult = (summary) => {
     if (summary.result?.type !== "agent" || summary.result.text.length <= 2000)
         return summary;
@@ -46,24 +66,36 @@ const trimResult = (summary) => {
         ...summary,
         result: {
             ...summary.result,
-            text: `${summary.result.text.slice(0, 2000)}\n[truncated — get run_id ${summary.runId} for the full text]`,
+            text: `${summary.result.text.slice(0, 2000)}\n[truncated — recover run_id ${summary.runId} with a reason for the full text]`,
         },
     };
 };
+/** Delivered, given up on and reported, or never owed (`callback:"none"`).
+ *  Anything else is still on its way, and reading it here would be reading it twice. */
+const settled = (callback) => callback.callbackState === null || callback.callbackState === "delivered" || callback.callbackState === "abandoned";
+/** The same words for queued, running, pending and retrying: a refusal that
+ *  named the state would be the status query this operation replaced. */
+const notRecoverable = (what, callback) => {
+    throw new Error(callback.callbackSessionId === null
+        ? `${what} is not recoverable yet: it was launched with callback none, so nothing will be delivered; recover reads finished results only and cannot wait for work`
+        : `${what} is not recoverable yet: wait for automatic delivery to session ${callback.callbackSessionId}; recover cannot wait for work`);
+};
 const summarizeGroup = (group, members, messages) => defined({
     groupId: group.id,
     join: group.join,
     state: group.finishedAt ? "finished" : "running",
     callbackState: group.callbackState,
+    callbackMode: group.callbackMode ?? null,
     winnerRunId: group.winnerRunId,
     members: members.map((run) => trimResult(summarize(run, messages.openDecisionId(run.id)))),
+    next: null,
 });
 const LaunchSchema = Type.Object({
     model: Type.Optional(Type.Object({ provider: Type.String(), id: Type.String() })),
     thinking: Type.Optional(Type.String()),
 });
-// Model-facing draft shape. Guidance only: runtime truth stays in parseDraft,
-// so schema drift can never loosen boundary validation.
+// Guidance only: runtime truth stays in parseDraft, so schema drift cannot
+// loosen boundary validation.
 const DraftSchema = Type.Object({
     name: Type.Optional(Type.String({ description: "Defaults to the prompt's first line." })),
     description: Type.Optional(Type.String()),
@@ -103,34 +135,32 @@ export function taskToolSpec(execute) {
     return {
         name: "task",
         label: "Pier Task",
-        description: "Manage durable Pier tasks and subagents. Agent tasks run in a fresh session or a reused one. create files a definition the operator sees in the Console — only for schedules or roles you will run again; a one-off is run with a prompt. Run executes a stored task by task_id, a one-shot subagent from a prompt (shorthand: prompt + optional cwd/launch/name — cwd defaults to your own directory, relative paths resolve against it, name comes from the prompt) or from a full inline task draft, or a core-joined fan-out via tasks[] with join all|first. Get accepts run_id, group_id, or task_id for that task's recent runs. Every operation returns immediately: results, group joins, and decision replies arrive as callback messages. Use steer/follow_up/resume for child control and contact/reply for supervisor decisions. models lists the deployment's model menu (operator pins with intent notes, else the live catalog).",
+        description: "Manage durable Pier tasks and subagents. Agent tasks run in a fresh session or a reused one. create files a definition the operator sees in the Console — only for schedules or roles you will run again; a one-off is run with a prompt. Run executes a stored task by task_id, a one-shot subagent from a prompt (shorthand: prompt + optional cwd/launch/name/timeoutSeconds — cwd defaults to your own directory, relative paths resolve against it, name comes from the prompt) or from a full inline task draft, or a core-joined fan-out via tasks[] with join all|first. Every operation returns immediately: results, group joins, and decision replies arrive as callback messages once your turn ends — there is no status query; pass callback 'steer' to have a result interrupt your running turn instead, or 'none' for no callback at all. recover (run_id or group_id, plus a reason) re-reads a finished result after its callback has settled — for truncated text or lost context, never to check progress. Use steer/follow_up/resume for child control and contact/reply for supervisor decisions. models lists the deployment's model menu (operator pins with intent notes, else the live catalog).",
         parameters: Type.Object({
-            operation: strEnum("list", "create", "update", "run", "get", "cancel", "steer", "follow_up", "resume", "contact", "reply", "models"),
+            operation: strEnum("list", "create", "update", "run", "recover", "cancel", "steer", "follow_up", "resume", "contact", "reply", "models"),
             task_id: Type.Optional(Type.String()),
             run_id: Type.Optional(Type.String()),
             group_id: Type.Optional(Type.String()),
             message_id: Type.Optional(Type.String()),
             message: Type.Optional(Type.String()),
-            reason: Type.Optional(strEnum("progress", "decision")),
+            reason: Type.Optional(Type.String({ description: "contact: progress | decision. recover: why the delivered callback is not enough (required)." })),
             session_mode: Type.Optional(strEnum("fresh")),
-            // The one-shot shorthand: a prompt is the whole delegation, and the
-            // fresh session in the caller's own directory is what it means.
             prompt: Type.Optional(Type.String()),
             cwd: Type.Optional(Type.String()),
             launch: Type.Optional(LaunchSchema),
             name: Type.Optional(Type.String()),
+            timeoutSeconds: Type.Optional(Type.Number({ description: "1–86400; defaults to 3600." })),
             task: Type.Optional(DraftSchema),
-            // The same draft again, spelled out, cost more tokens in every session
-            // than the whole rest of this contract. One copy is the guidance; this
-            // one points at it, and `parseDraft` is what actually validates either.
+            // Spelled out, the draft schema costs more tokens per session than the
+            // rest of this contract; `parseDraft` validates either shape.
             tasks: Type.Optional(Type.Unsafe({
                 type: "array",
-                description: "2+ entries, each a prompt string, {prompt, cwd?, launch?, name?}, a task draft shaped exactly like `task`, or {task_id}.",
+                description: "2+ entries, each a prompt string, {prompt, cwd?, launch?, name?, timeoutSeconds?}, a task draft shaped exactly like `task`, or {task_id}.",
                 items: { type: "object" },
             })),
             join: Type.Optional(strEnum("all", "first")),
             input: Type.Optional(Type.Unknown()),
-            callback: Type.Optional(strEnum("origin", "none")),
+            callback: Type.Optional(strEnum("origin", "none", "steer")),
             callback_session_id: Type.Optional(Type.String()),
         }),
         execute,
@@ -156,12 +186,19 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
         return definitions.update(requiredString(input.task_id, "task_id"), await expandDraft(definitions, input.task, callerSessionId));
     }
     if (input.operation === "run") {
+        const callbackMode = input.callback === "steer" ? "steer" : "followUp";
+        // A run's own callback is its parent's link back; a child that could point
+        // it elsewhere would strand the supervisor waiting for a result.
+        if (active && input.callback_session_id !== undefined)
+            throw new Error(SUBAGENT_REDIRECT);
         if (Array.isArray(input.tasks)) {
             // Core-joined fan-out: members run detached, one aggregated callback.
             if (input.task !== undefined || input.task_id !== undefined)
                 throw new Error("use either task/task_id or tasks[]");
             if (input.session_mode !== undefined)
                 throw new Error("session_mode applies to a single run only");
+            if (input.callback_session_id !== undefined)
+                throw new Error("callback_session_id applies to a single run only");
             if (input.tasks.length < 2)
                 throw new Error("tasks[] needs at least 2 entries; use task for a single run");
             const resolved = [];
@@ -173,8 +210,9 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
                     ? await resolveDraft(definitions, entry, active, callerSessionId)
                     : resolveStored(definitions, entry.task_id, active));
             }
-            const { group, runs } = host.runGroup(resolved, input.join === "first" ? "first" : "all", callerSessionId, active?.id ?? null, input.callback === "none" ? null : callerSessionId);
-            return summarizeGroup(group, runs, messages);
+            const groupCallbackSessionId = input.callback === "none" ? null : callerSessionId;
+            const { group, runs } = host.runGroup(resolved, input.join === "first" ? "first" : "all", callerSessionId, active?.id ?? null, groupCallbackSessionId, callbackMode);
+            return receipt(summarizeGroup(group, runs, messages), groupCallbackSessionId, callbackMode, callerSessionId);
         }
         const draft = input.task_id === undefined ? inlineDraft(input) : undefined;
         const task = draft
@@ -186,33 +224,56 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
             throw new Error(`unsupported session_mode: ${String(input.session_mode)}`);
         }
         const sessionMode = input.session_mode;
-        let callbackSessionId = input.callback === "none" ? null : callerSessionId;
-        if (!active && callbackSessionId && typeof input.callback_session_id === "string") {
-            callbackSessionId = requiredString(input.callback_session_id, "callback_session_id");
-            if (!(await definitions.sessionExists(callbackSessionId)))
-                throw new Error(`unknown session: ${callbackSessionId}`);
-        }
+        const callbackSessionId = await callbackTarget(input, definitions, callerSessionId);
         const run = host.run(task.id, input.input, "agent", active?.id ?? null, {
             invokedBySessionId: callerSessionId,
             sourceSessionId: callerSessionId,
             callbackSessionId,
+            callbackMode,
             background: true,
             sessionMode,
         });
-        return summarize(run, null);
+        return receipt(summarize(run, null), callbackSessionId, callbackMode, callerSessionId);
     }
-    if (input.operation === "get") {
+    if (input.operation === "recover") {
+        // History only, never status: readable once the callback has said its last
+        // word. The required reason is the friction, and the operator sees it.
+        const reason = requiredString(input.reason, "reason");
+        // The open question is the notification; the reply's continuation reports.
+        const decisionOpen = (run) => {
+            throw new Error(`run ${run.id} finished awaiting your decision ${messages.openDecisionId(run.id) ?? ""}; reply to it — the continuation's callback brings the result`);
+        };
+        // A race winner need not wait for losing members to finish cancelling.
+        const groupReady = (group) => {
+            if (!group.finishedAt || !settled(group))
+                notRecoverable(`group ${group.id}`, group);
+        };
         if (typeof input.group_id === "string") {
             const { group, members } = host.getGroup(input.group_id);
+            groupReady(group);
+            if (!members.every((run) => isTerminal(run.state))) {
+                throw new Error(`recover cannot inspect active members; the race has settled — recover its winning result with run_id ${group.winnerRunId ?? "from the callback"} and a reason`);
+            }
+            const asking = members.find((run) => messages.openDecisionId(run.id));
+            if (asking)
+                decisionOpen(asking);
+            log.info(`recover group ${group.id} by ${callerSessionId}: ${reason}`);
             return summarizeGroup(group, members, messages);
         }
-        // Run history by task: without it, checking what a task did (or whether a
-        // cascade landed) means leaving the tool for the database.
-        if (input.run_id === undefined && typeof input.task_id === "string") {
-            return host.listRuns(input.task_id, 10).map((run) => trimResult(summarize(run, messages.openDecisionId(run.id))));
-        }
         const run = host.getRun(requiredString(input.run_id, "run_id"));
-        return summarize(run, messages.openDecisionId(run.id));
+        if (run.groupId) {
+            const { group } = host.getGroup(run.groupId);
+            groupReady(group);
+            if (!isTerminal(run.state))
+                throw new Error("the group has reported its outcome; recover reads finished results only and cannot wait for this member");
+        }
+        else if (!isTerminal(run.state) || !settled(run)) {
+            notRecoverable(`run ${run.id}`, run);
+        }
+        if (messages.openDecisionId(run.id))
+            decisionOpen(run);
+        log.info(`recover run ${run.id} by ${callerSessionId}: ${reason}`);
+        return summarize(run, null);
     }
     if (input.operation === "cancel") {
         if (typeof input.group_id === "string") {
@@ -235,17 +296,28 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
     if (input.operation === "resume") {
         const prior = host.getRun(requiredString(input.run_id, "run_id"));
         assertOwns(store, callerSessionId, active, prior);
+        // The resumed run is a new run, so it carries its own callback options,
+        // under the same rule as `run`: a subagent may not redirect them.
+        if (active && input.callback_session_id !== undefined)
+            throw new Error(SUBAGENT_REDIRECT);
+        const callbackMode = input.callback === "steer" ? "steer" : "followUp";
+        const callbackSessionId = await callbackTarget(input, definitions, callerSessionId);
         const run = host.resume(prior.id, requiredString(input.message, "message"), {
             invokedBySessionId: callerSessionId,
-            callbackSessionId: input.callback === "none" ? null : callerSessionId,
+            callbackSessionId,
+            callbackMode,
             background: true,
         });
-        return summarize(run, null);
+        return receipt(summarize(run, null), callbackSessionId, callbackMode, callerSessionId);
     }
     if (input.operation === "contact") {
         if (!active)
             throw new Error("contact is only available inside an active Agent run");
-        const reason = input.reason === "decision" ? "decision" : "progress";
+        // The schema no longer narrows `reason` (recover shares the field), so the
+        // two names contact accepts are checked here.
+        const reason = input.reason === undefined ? "progress" : input.reason;
+        if (reason !== "progress" && reason !== "decision")
+            throw new Error(`contact reason must be progress or decision, got ${String(reason)}`);
         return messages.contact(active, callerSessionId, reason, requiredString(input.message, "message"));
     }
     if (input.operation === "reply") {
@@ -255,28 +327,22 @@ export async function handleTaskTool(host, definitions, store, messages, raw, ca
 }
 /** A single run's draft: the top-level shorthand (`prompt` …) or `task`, never both. */
 function inlineDraft(input) {
-    const { prompt, cwd, launch, name } = input;
+    const { prompt, cwd, launch, name, timeoutSeconds } = input;
     if (prompt === undefined)
         return record(input.task) ?? undefined;
     if (input.task !== undefined)
         throw new Error("use either prompt or task");
-    return { prompt, cwd, launch, name };
+    return { prompt, cwd, launch, name, timeoutSeconds };
 }
-/** The prompt's first line, unmarked and cut short: a label for the Console,
- *  not an identifier — the run's id is what anything addresses. */
+/** A label for the Console, not an identifier. */
 function nameFromPrompt(prompt) {
     const line = prompt.split("\n")
         .map((l) => l.replace(/^[\s#>*-]+/, "").replace(/[*_`]/g, "").replace(/\s+/g, " ").trim())
         .find(Boolean) ?? "subagent";
     return line.length > 60 ? `${line.slice(0, 59).trimEnd()}…` : line;
 }
-/**
- * The shape a draft is validated in, from the shapes a caller may write it in.
- * A `prompt` shorthand becomes a fresh Agent action; a fresh session's cwd
- * resolves against the caller's own directory (and is that directory when
- * omitted); a missing name is the prompt's first line. Everything the caller
- * did spell out passes through untouched — parseDraft still judges it.
- */
+/** A `prompt` shorthand becomes a fresh Agent action in the caller's own
+ *  directory; everything the caller did spell out passes through to parseDraft. */
 async function expandDraft(definitions, raw, callerSessionId) {
     let draft = record(raw);
     if (!draft)
@@ -299,8 +365,8 @@ async function expandDraft(definitions, raw, callerSessionId) {
         draft = { ...draft, name: nameFromPrompt(action.prompt) };
     return draft;
 }
-/** Inline one-shot subagent: persisted like any task (kind "subagent",
- * filtered from default lists) so runs stay auditable and resumable. */
+/** Persisted like any task (kind "subagent", filtered from default lists) so
+ *  runs stay auditable and resumable. */
 async function resolveDraft(definitions, raw, active, callerSessionId) {
     const draft = record(await expandDraft(definitions, raw, callerSessionId));
     if (!draft)
@@ -308,6 +374,11 @@ async function resolveDraft(definitions, raw, active, callerSessionId) {
     if (draft.trigger !== undefined && record(draft.trigger)?.type !== "manual") {
         throw new Error("inline subagent tasks must use a manual trigger");
     }
+    // Delivery of a one-off run is the top-level fields' business; a nested
+    // callback only means anything on a stored definition's schedule.
+    if (draft.callback !== undefined || draft.callback_session_id !== undefined) {
+        throw new Error("an inline task draft cannot set callback; use the top-level callback / callback_session_id");
+    }
     if (active) {
         const action = record(draft.action);
         if (action?.type !== "agent")

package/dist/tools-task.js

@@ -1,36 +1,21 @@
-// One reason: a tools switch has to become exactly one run of the one task
-// Pier owns — which takes knowing what that task runs, keeping it the task
-// Pier wrote, and turning a burst of switches into one run of it.
-//
-// It lives beside tools.ts rather than inside it because tools.ts may not
-// import tasks/, and outside main.ts because main.ts is wiring: this is the
-// only rule in the instance layer that is neither construction nor a callback.
-// The task's run history *is* the tools status surface — the install, the daily
-// update and every failure are runs with output, so there is no second place to
-// look (§5b).
+// A tools switch becomes exactly one run of the one task Pier owns. Beside
+// tools.ts because tools.ts may not import tasks/; the task's run history is
+// the tools status surface (§5).
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { logger } from "./log.js";
 import { PIER_HOME } from "./paths.js";
 import { isTerminal } from "./tasks/types.js";
 import { coalescedSync } from "./tools.js";
-/** Marks the daily update task as Pier's own — this file finds the one it owns
- *  rather than one a person wrote, and names itself with it when it writes the
- *  definition back (the owner guard in tasks/definitions.ts). */
+/** The owner guard in tasks/definitions.ts: only this creator may write it back. */
 const TOOLS_TASK_CREATOR = "tools";
-// The area these lines have always logged under: the move must not rename
-// anything an operator greps the journal for.
+// "pier", not "tools": what an operator greps the journal for.
 const log = logger("pier");
-/** POSIX single quotes: `$`, a backtick and a backslash mean things inside
- *  double quotes, and this string is run by bash months from now. */
+/** POSIX single quotes: this string is run by bash months from now. */
 const shellQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
-/**
- * How this Pier runs `pier tools sync`. Installed, that is the built CLI beside
- * main.js. From a source checkout there is no `cli.js` and node cannot strip
- * types through imports that still say `.js`, so it is the same command under
- * tsx — which is what a source checkout has. Neither available is a refusal
- * with a reason, never a task whose script cannot run.
- */
+/** From a source checkout there is no `cli.js` and node cannot strip types
+ *  through `.js` imports, so it is the same command under tsx. Neither
+ *  available is a refusal with a reason, never a task whose script cannot run. */
 const toolsSyncScript = () => {
     const built = fileURLToPath(new URL("./cli.js", import.meta.url));
     if (existsSync(built))
@@ -49,22 +34,10 @@ const toolsSyncScript = () => {
     }
 };
 export function toolsTask(tasks) {
-    /** Which task is Pier's, and the id every managed run goes through. */
     let toolsTaskId = null;
-    /**
-     * The one task Pier owns, brought in line with what it should be.
-     *
-     * Created once and never retired: a task that comes and goes is a state class
-     * of its own (two boots racing to create it, a retirement racing a switch),
-     * and the run it would have been retired for already says "no tools switched
-     * on".
-     *
-     * It repairs rather than trusts because of what came before the owner guard
-     * (tasks/definitions.ts): a definition edited by an older Pier, or by a
-     * release where the routes could still write it, is brought back to the one
-     * Pier owns here. Nothing can edit it any more — so this is a boot-time
-     * repair of state that already exists, not a defence.
-     */
+    /** Created once and never retired: a task that comes and goes is a state
+     *  class of its own, and a run with nothing on already says so. Repairs a
+     *  definition an older Pier could still edit. */
     const ensureToolsTask = async () => {
         const command = toolsSyncScript();
         if ("problem" in command)
@@ -83,40 +56,31 @@ export function toolsTask(tasks) {
             callback: { type: "none" },
             timeoutSeconds: 1800,
         };
-        // Archived is not "owned but edited": nothing can un-archive a task, so the
-        // replacement is a new one and the old one keeps its history.
+        // Nothing can un-archive a task, so an archived one is replaced, history kept.
         const owned = tasks.list().filter((task) => task.creator === TOOLS_TASK_CREATOR && !task.archived);
-        // One per creator. Two would fight over ubix's state lock every night, each
-        // reporting the other's run as an overlap.
+        // Two would fight over ubix's state lock every night.
         for (const extra of owned.slice(1)) {
             log.warn(`archiving a second tools update task (${extra.id})`);
             tasks.archive(extra.id, TOOLS_TASK_CREATOR);
         }
         const task = owned[0];
-        // Every field Pier owns, not just the command: a paused task, a renamed one
-        // or one pointed at a callback still claims to be keeping the tools current
-        // while the daily run never happens.
+        // Every field, not just the command: a paused or renamed task still claims
+        // to keep the tools current while the daily run never happens.
         if (task && Object.entries(draft).some(([key, value]) => JSON.stringify(task[key]) !== JSON.stringify(value))) {
             log.warn("the tools update task was edited — restoring the definition Pier owns");
-            // Named as the owner: this is the one path allowed to write it back
-            // (tasks/definitions.ts).
             await tasks.update(task.id, draft, TOOLS_TASK_CREATOR);
         }
         const id = task ? task.id : (await tasks.create(draft, TOOLS_TASK_CREATOR)).id;
         toolsTaskId = id;
         return { id };
     };
-    /** The half of `coalescedSync` (tools.ts, which has the rule and why) that
-     *  knows what a task is: start a run, and hand back what to wait for — our own
-     *  run, or the one already in flight that made ours a `skipped` row. */
+    /** The half of `coalescedSync` (tools.ts) that knows what a task is. */
     const requestSync = coalescedSync(() => {
         if (!toolsTaskId)
             throw new Error("no tools update task to run");
         const settled = (id) => tasks.waitForRun(id).then(() => undefined);
-        // Bounded, because the only way round this loop is a run that finished
-        // between being in flight and being asked about: real, rare, and not
-        // something to spin on. Three refusals in a row with nothing running is a
-        // bug, and it is reported as one rather than retried forever.
+        // A run can finish between being in flight and being asked about; three
+        // refusals with nothing running is a bug, reported rather than retried.
         for (let attempt = 0; attempt < 3; attempt++) {
             const mine = tasks.run(toolsTaskId, null, "manual");
             if (!isTerminal(mine.state))
@@ -127,8 +91,6 @@ export function toolsTask(tasks) {
         }
         throw new Error("the tools sync was refused as an overlap three times with nothing running");
     }, (err) => log.error("the tools sync could not be run", err));
-    /** A switch was flipped: make sure the task is the one Pier means, then ask
-     *  for a sync. Answers with what that switch should say about it. */
     const toolsChanged = async () => {
         try {
             const task = await ensureToolsTask();
@@ -144,10 +106,8 @@ export function toolsTask(tasks) {
         }
     };
     return {
-        /** Reconcile now. At boot, before any route exists: two first flips could
-         *  otherwise both find no task and create one each. */
+        /** At boot, before any route exists: two first flips could otherwise both create one. */
         reconcile: ensureToolsTask,
-        /** The task whose runs are the status surface, null until there is one. */
         id: () => toolsTaskId,
         changed: toolsChanged,
     };