toolroll 0.9.60 → 0.9.62

package/dist/surface.js

@@ -67,9 +67,11 @@ const GUIDE_ROWS = [
     // D5: the central team service (connect, the central lead verbs, conversation …) and native coding sessions are
     // deprecated: they still run this release, with a warning, but are no longer declared here.
     operator("chat", "talk to your lead: one conversation across every project; --say sends one message; --follow enables crew updates and --no-follow pauses them; proposals keep their approval requirements"),
-    { invocation: "repos add", synopsis: "add a project: a Git repository, in the console at once; the lead adds with its token", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
+    // Unkeyed: --remote with a different URL replaces the project's trusted remote (recorded in the action ledger).
+    { invocation: "repos add", synopsis: "add a project: a Git repository, in the console at once; the lead adds with its token; --remote records or replaces its trusted remote", audience: "agent", agentMayInvoke: true, mutation: "unkeyed",
         positionals: [{ name: "path", required: false, meaning: "the repository (default: the one you are in)" }],
-        flags: [jsonFlag, { name: "token", takesValue: true, meaning: "the lead token (or TOOLROLL_LEAD_TOKEN)" }],
+        flags: [jsonFlag, { name: "token", takesValue: true, meaning: "the lead token (or TOOLROLL_LEAD_TOKEN)" },
+            { name: "remote", takesValue: true, meaning: "an HTTPS or SSH URL without credentials whose main may complete landed work; replaces a different recorded one (owner or an instance operator's lead only)" }],
         notableReasons: ["not-git", "unavailable", "refused", "locked"] },
     { invocation: "repos remove", synopsis: "remove a project from the console and the builder; its tasks and results stay saved", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
         positionals: [{ name: "path", required: true, meaning: "the repository" }],
@@ -242,7 +244,9 @@ const GUIDE_ROWS = [
         positionals: [{ name: "id", required: true, meaning: "the task" }],
         flags: [jsonFlag, dbFlag, keyFlag, { name: "undo", takesValue: false, meaning: "back to filing order" }],
         notableReasons: ["unknown-task", "claimed"] },
-    operator("task steer", "one credentialed note for the task's agent — a running build reads it when it next checks for notes, otherwise the next attempt does; steering speaks with the operator's voice"),
+    operator("task steer", "one credentialed note for the task's agent — a running Claude build gets it in seconds, another running build reads it when it next checks for notes, otherwise the next attempt does; --now pauses the running Claude build first; steering speaks with the operator's voice"),
+    operator("task pause", "stop a running Claude build's current turn and keep the build (--run <id> names the attempt): its next note continues it; never a stop"),
+    operator("task continue", "resume a paused Claude build where it stopped, without a note (--run <id> names the attempt)"),
     { invocation: "task assign", synopsis: "reserve a task for one worker, or return it to the shared queue", audience: "agent", agentMayInvoke: true, mutation: "keyed",
         positionals: [{ name: "id", required: true, meaning: "the task" }],
         flags: [jsonFlag, dbFlag, keyFlag,
@@ -449,7 +453,7 @@ const REMOTE_STEP_UP = [
 const REMOTE_YES = [
     "status", "integrations", "ready", "gaps", "grants", "sync", "audit",
     "task add", "task ask", "task checks", "task add-tests", "task list", "task show", "check-progress", "task wait", "task complete", "task revise",
-    "task state", "task block", "task unblock", "task next", "task steer", "task assign", "task scope", "task plan", "task hold", "task unhold", "task require",
+    "task state", "task block", "task unblock", "task next", "task steer", "task pause", "task continue", "task assign", "task scope", "task plan", "task hold", "task unhold", "task require",
     "task requeue", "task review", "task repair", "task route", "task reopen", "task stop", "task resume",
     "runner list", "coordinator list", "cap list", "cap add", "outbox list", "incident list", "incident resolve",
     "config show", "verify show", "intake show", "intake run", "intake preview", "intake pr-comments", "template list", "template show",

package/dist/sweep-quarantine.d.ts

@@ -0,0 +1,28 @@
+export declare const QUARANTINE_NOTE = ".toolroll-sweep.json";
+type Journal<T> = {
+    version: 1;
+    name: string;
+    data: T;
+    deleting: boolean;
+    pid: number;
+    host: string;
+    bootId: string | null;
+};
+export type Quarantine<T> = {
+    path: string;
+    original: string;
+    journal: Journal<T>;
+};
+export declare function quarantineEntries<T>(root: string): Quarantine<T>[];
+/** A small marker closes discovery before the atomic rename. It is never published half-written. */
+export declare function quarantine<T>(original: string, data: T): Quarantine<T> | null;
+/** Returns null if another sweep owns it (or won recovery). */
+export declare function claimQuarantine<T>(entry: Quarantine<T>): Quarantine<T> | null;
+export declare function releaseQuarantine<T>(entry: Quarantine<T>): void;
+/** A partially deleted tree must never become discoverable again. */
+export declare function restoreQuarantine<T>(entry: Quarantine<T>): boolean;
+/** Keep the journal until all potentially large removals succeeded. Recovery never guesses at a half-deleted tree. */
+export declare function deleteQuarantine<T>(entry: Quarantine<T>, remove: (path: string) => void | Promise<void>): Promise<void>;
+/** Staged pruning is also called synchronously by update/deploy. */
+export declare function deleteQuarantineSync<T>(entry: Quarantine<T>, remove: (path: string) => void): void;
+export {};

package/dist/sweep-quarantine.js

@@ -0,0 +1,153 @@
+/** Atomic rename before deletion. Trash is never a reusable dependency copy or staged runtime.
+ * Its journal survives partial deletion so the next sweep can recheck the original identity and retry.
+ * No database write lock spans filesystem work. A live owner keeps its trash; recovery claims a dead
+ * owner's folder by renaming it to a fresh, never-reused name, so two recoverers cannot both win. */
+import { randomBytes } from "node:crypto";
+import { existsSync, linkSync, lstatSync, readFileSync, readdirSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { currentBootId, provenDeadByBootChange } from "./boot-identity.js";
+export const QUARANTINE_NOTE = ".toolroll-sweep.json";
+const PREFIX = ".toolroll-trash-";
+const freshPath = (root) => join(root, `${PREFIX}${randomBytes(16).toString("hex")}`);
+const owner = () => ({ pid: process.pid, host: hostname(), bootId: currentBootId() });
+function alive(one) {
+    if (one.pid === 0)
+        return false;
+    if (one.host !== hostname())
+        return true;
+    if (one.bootId !== null && provenDeadByBootChange(one))
+        return false;
+    try {
+        process.kill(one.pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+function read(path) {
+    try {
+        const j = JSON.parse(readFileSync(join(path, QUARANTINE_NOTE), "utf8"));
+        return j.version === 1 && typeof j.name === "string" && j.name !== "." && j.name !== ".." &&
+            j.name !== "" && !/[\\/\0]/.test(j.name) && Number.isSafeInteger(j.pid) && j.pid >= 0 && typeof j.host === "string" &&
+            (j.bootId === null || typeof j.bootId === "string") && typeof j.deleting === "boolean" ? j : null;
+    }
+    catch {
+        return null;
+    }
+}
+function write(path, journal, exclusive = false) {
+    const note = join(path, QUARANTINE_NOTE), temp = `${note}.${randomBytes(8).toString("hex")}`;
+    writeFileSync(temp, JSON.stringify(journal), { mode: 0o600, flag: "wx" });
+    try {
+        if (exclusive)
+            linkSync(temp, note);
+        else
+            renameSync(temp, note);
+    }
+    finally {
+        try {
+            unlinkSync(temp);
+        }
+        catch { /* renamed */ }
+    }
+}
+export function quarantineEntries(root) {
+    let names;
+    try {
+        names = readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+    return names.filter(name => /^\.toolroll-trash-[0-9a-f]{32}$/.test(name)).flatMap(name => {
+        const path = join(root, name);
+        try {
+            if (!lstatSync(path).isDirectory())
+                return [];
+        }
+        catch {
+            return [];
+        }
+        const journal = read(path);
+        // A crash after unlinking the journal can leave only an empty folder. No resource data remains in it.
+        if (journal === null) {
+            try {
+                if (readdirSync(path).length === 0)
+                    rmdirSync(path);
+            }
+            catch { /* next pass */ }
+        }
+        return journal === null ? [] : [{ path, original: join(root, journal.name), journal }];
+    });
+}
+/** A small marker closes discovery before the atomic rename. It is never published half-written. */
+export function quarantine(original, data) {
+    if (!lstatSync(original).isDirectory())
+        return null;
+    let journal = read(original);
+    if (journal !== null && alive(journal))
+        return null;
+    if (journal === null) {
+        journal = { version: 1, name: basename(original), data, deleting: false, ...owner() };
+        write(original, journal, true);
+    }
+    else {
+        journal = { ...journal, ...owner() };
+        write(original, journal);
+    }
+    const path = freshPath(dirname(original));
+    renameSync(original, path);
+    return { path, original, journal };
+}
+/** Returns null if another sweep owns it (or won recovery). */
+export function claimQuarantine(entry) {
+    const seen = read(entry.path);
+    if (seen === null || alive(seen))
+        return null;
+    const journal = { ...seen, ...owner() };
+    const path = freshPath(dirname(entry.path));
+    try {
+        // Mark live before moving. Contenders already reading the old name race the rename; just one wins.
+        write(entry.path, journal);
+        renameSync(entry.path, path);
+        write(path, journal);
+        return { ...entry, path, journal };
+    }
+    catch {
+        return null;
+    }
+}
+export function releaseQuarantine(entry) {
+    if (existsSync(entry.path))
+        write(entry.path, { ...entry.journal, pid: 0 });
+}
+/** A partially deleted tree must never become discoverable again. */
+export function restoreQuarantine(entry) {
+    if (entry.journal.deleting || existsSync(entry.original))
+        return false;
+    renameSync(entry.path, entry.original);
+    unlinkSync(join(entry.original, QUARANTINE_NOTE));
+    return true;
+}
+/** Keep the journal until all potentially large removals succeeded. Recovery never guesses at a half-deleted tree. */
+export async function deleteQuarantine(entry, remove) {
+    entry.journal = { ...entry.journal, deleting: true };
+    write(entry.path, entry.journal);
+    for (const name of readdirSync(entry.path))
+        if (name !== QUARANTINE_NOTE)
+            await remove(join(entry.path, name));
+    unlinkSync(join(entry.path, QUARANTINE_NOTE));
+    rmdirSync(entry.path);
+}
+/** Staged pruning is also called synchronously by update/deploy. */
+export function deleteQuarantineSync(entry, remove) {
+    entry.journal = { ...entry.journal, deleting: true };
+    write(entry.path, entry.journal);
+    for (const name of readdirSync(entry.path))
+        if (name !== QUARANTINE_NOTE)
+            remove(join(entry.path, name));
+    unlinkSync(join(entry.path, QUARANTINE_NOTE));
+    rmdirSync(entry.path);
+}

package/dist/task-base.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Where a task's work starts, against current main (fresh base): one view for
+ * the task page and `task show`. The base is saved run lineage — a builder
+ * branch's pinned origin, or the newest plan's base — and the behind count is
+ * read from Git now. Reads only.
+ */
+import type { Store } from "./store.js";
+export type TaskBaseView = {
+    /** The base commit, in full. */
+    base: string;
+    branch: string;
+    /** The project's main: its checked-out branch, as a dispatch pass resolves it. Null when Git could not say. */
+    main: string | null;
+    /** Commits on main the base does not have; null when Git could not say. */
+    behind: number | null;
+    /** One short line: `Base 9d087efe · Behind main by 2 commits`. */
+    words: string;
+};
+/** A synchronous, read-only Git call in `cwd`: its trimmed output, or null on any failure. */
+export type GitRead = (cwd: string, args: readonly string[]) => string | null;
+export declare const readGit: GitRead;
+/** The base line on its own, for surfaces that label it already: `9d087efe · Behind main by 2 commits`. */
+export declare function baseStandingWords(view: Pick<TaskBaseView, "base" | "main" | "behind">): string;
+/**
+ * The lease's fresh-base request for one attempt on `branch`, or nothing when the task's start is pinned elsewhere: a
+ * revision keeps the head of the attempt it revises, and a prepared candidate or coding review keeps the base its
+ * candidate was proved against.
+ */
+export declare function freshBaseFor(store: Store, taskId: string, branch: string, main: string): {
+    freshBase: {
+        main: string;
+        recordedBase: string | null;
+    };
+} | Record<string, never>;
+export declare function taskBaseOf(store: Store, taskId: string, git?: GitRead): TaskBaseView | null;

package/dist/task-base.js

@@ -0,0 +1,51 @@
+/**
+ * Where a task's work starts, against current main (fresh base): one view for
+ * the task page and `task show`. The base is saved run lineage — a builder
+ * branch's pinned origin, or the newest plan's base — and the behind count is
+ * read from Git now. Reads only.
+ */
+import { execFileSync } from "node:child_process";
+export const readGit = (cwd, args) => {
+    try {
+        return execFileSync("git", ["--no-optional-locks", ...args], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000, maxBuffer: 65_536 }).trim();
+    }
+    catch {
+        return null;
+    }
+};
+const commits = (count) => `${count} commit${count === 1 ? "" : "s"}`;
+/** The base line on its own, for surfaces that label it already: `9d087efe · Behind main by 2 commits`. */
+export function baseStandingWords(view) {
+    const short = view.base.slice(0, 8);
+    if (view.main === null || view.behind === null)
+        return short;
+    return view.behind === 0 ? `${short} · Up to date with ${view.main}` : `${short} · Behind ${view.main} by ${commits(view.behind)}`;
+}
+/**
+ * The lease's fresh-base request for one attempt on `branch`, or nothing when the task's start is pinned elsewhere: a
+ * revision keeps the head of the attempt it revises, and a prepared candidate or coding review keeps the base its
+ * candidate was proved against.
+ */
+export function freshBaseFor(store, taskId, branch, main) {
+    const ref = store.lookupRef(taskId);
+    if (ref === null || ref.revisionOf !== null || store.getScope(taskId)?.candidate != null || store.filedViaOf(taskId)?.startsWith("coding:") === true)
+        return {};
+    return { freshBase: { main, recordedBase: store.recordedBranchBase(ref.id, branch) } };
+}
+export function taskBaseOf(store, taskId, git = readGit) {
+    const ref = store.lookupRef(taskId);
+    if (ref === null || ref.repo === null)
+        return null;
+    const latest = store.runsFor(ref.id).find(one => one.role !== "reviewer" && one.branch !== null && one.baseRevision !== null);
+    if (latest === undefined || latest.branch === null || latest.baseRevision === null)
+        return null;
+    const branch = latest.branch;
+    // A move to current main newer than the latest attempt is where the next one starts.
+    const move = store.latestBranchBaseMove(ref.id, branch);
+    const base = move !== null && move.afterRun >= latest.id ? move.to : store.recordedBranchBase(ref.id, branch) ?? latest.baseRevision;
+    const main = git(ref.repo, ["symbolic-ref", "--short", "-q", "HEAD"]) || null;
+    const counted = main === null ? null : git(ref.repo, ["rev-list", "--count", `${base}..refs/heads/${main}`]);
+    const behind = counted === null || !/^\d+$/.test(counted) ? null : Number(counted);
+    const view = { base, branch, main: behind === null ? null : main, behind };
+    return { ...view, words: `Base ${baseStandingWords(view)}` };
+}

package/dist/task-status.d.ts

@@ -134,6 +134,8 @@ export type TaskStatusFacts = {
         damaged: number;
     } | null;
     completedBy?: string | null;
+    /** Marked complete by Toolroll because its work landed: why, in a few words ("its pull request merged"). */
+    landed?: string | null;
     action?: StatusAction | null;
     /** Where a row's one action leads: the result (and its Checks tab), the task's pull request, Run checks. */
     links?: {

package/dist/task-status.js

@@ -127,6 +127,9 @@ function sentenceOf(headline, facts) {
                 return "Review the change, then mark it complete.";
             return "Built without a passing project check. Review the change, then mark it complete.";
         case "Complete": {
+            // Landed work says why once; its merged pull request is that reason, not a second sentence.
+            if (facts.landed)
+                return `Marked complete automatically: ${facts.landed}.`;
             const by = facts.completedBy ? `Marked complete by ${facts.completedBy}.` : "Marked complete.";
             const pr = facts.pullRequest;
             return pr?.state === "merged" ? `${by} ${pr.number === null ? "Its pull request" : `Pull request #${pr.number}`} merged.` : by;
@@ -488,7 +491,8 @@ export function assignmentStatusFacts(assignment, options = {}) {
         ...(withResult && receipt?.proofAcceptance != null ? { accepted: true } : {}),
         ...(withResult && (assignment.readiness?.blockers.length ?? 0) > 0 ? { blockers: assignment.readiness.blockers } : {}),
         evidence: withResult ? options.evidence ?? evidenceOf(receipt, [...(receipt?.caveats ?? []), ...assignment.attention]) : null,
-        completedBy: assignment.completion === null ? null : assignment.completion.lead === true ? "the lead" : assignment.completion.actor.replace(/^(?:operator|coordinator|lead):/, ""),
+        completedBy: assignment.completion === null || assignment.completion.landed !== undefined ? null : assignment.completion.lead === true ? "the lead" : assignment.completion.actor.replace(/^(?:operator|coordinator|lead):/, ""),
+        ...(assignment.completion?.landed === undefined ? {} : { landed: assignment.completion.landed }),
         action: options.action ?? null,
         ...(options.links === undefined ? {} : { links: options.links }),
         why: options.why ?? [],

package/dist/test-temp.d.ts

@@ -25,13 +25,16 @@ export type RemoveOptions = {
     ownerAlive?: (owner: TempOwner) => boolean;
     /** At most this many go in one pass (a sweep after weeks can find 100,000); `more` says some were left. */
     max?: number;
+    /** Something live work uses (storage-sweep.ts): asked right before each folder goes; true keeps it. */
+    spare?: (path: string) => boolean;
 };
 /**
  * Remove the test temp folders nothing has touched for a day; each is looked at again right before it goes (still a
- * folder of its own, not a link, still directly in its temp folder, still a day untouched, its owner gone).
+ * folder of its own, not a link, still directly in its temp folder, still a day untouched, its owner gone, nothing
+ * live using it). Removal never holds the event loop: a worker's heartbeats keep beating while thousands go.
  */
-export declare function removeStaleTestTemp(roots: readonly string[], now: Date, options?: RemoveOptions): {
+export declare function removeStaleTestTemp(roots: readonly string[], now: Date, options?: RemoveOptions): Promise<{
     removed: string[];
     failed: string[];
     more: boolean;
-};
+}>;

package/dist/test-temp.js

@@ -8,8 +8,9 @@
  * Every prefix the tests and scripts give tmpdir() is covered here (test-temp.test.ts reads the sources to keep it
  * so), and Playwright's own browser profiles.
  */
-import { spawnSync } from "node:child_process";
-import { lstatSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { lstatSync, readFileSync, readdirSync } from "node:fs";
+import { rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 const DAY_MS = 86_400_000;
@@ -96,9 +97,10 @@ export function testTempFolders(roots, now) {
 }
 /**
  * Remove the test temp folders nothing has touched for a day; each is looked at again right before it goes (still a
- * folder of its own, not a link, still directly in its temp folder, still a day untouched, its owner gone).
+ * folder of its own, not a link, still directly in its temp folder, still a day untouched, its owner gone, nothing
+ * live using it). Removal never holds the event loop: a worker's heartbeats keep beating while thousands go.
  */
-export function removeStaleTestTemp(roots, now, options = {}) {
+export async function removeStaleTestTemp(roots, now, options = {}) {
     const removed = [];
     const failed = [];
     const stale = testTempFolders(roots, now).stale;
@@ -107,6 +109,7 @@ export function removeStaleTestTemp(roots, now, options = {}) {
     for (const one of stale) {
         if (removed.length + failed.length >= max)
             return { removed, failed, more: true };
+        await nextTurn();
         try {
             const stat = lstatSync(one.path);
             if (stat.isSymbolicLink() || !inside.has(resolve(dirname(one.path))))
@@ -116,7 +119,9 @@ export function removeStaleTestTemp(roots, now, options = {}) {
             const owner = stat.isDirectory() ? tempOwner(one.path) : null;
             if (owner !== null && (options.ownerAlive ?? (() => false))(owner))
                 continue;
-            removeTree(one.path);
+            if (options.spare?.(one.path) === true)
+                continue;
+            await removeTree(one.path);
             removed.push(one.path);
         }
         catch {
@@ -125,14 +130,15 @@ export function removeStaleTestTemp(roots, now, options = {}) {
     }
     return { removed, failed, more: false };
 }
+const nextTurn = () => new Promise(resolve => setImmediate(resolve));
 /** rm -r; a tree a test made read-only (a shared dependency copy, a locked fixture) is made writable first. */
-function removeTree(path) {
+async function removeTree(path) {
     try {
-        rmSync(path, { recursive: true, force: true, maxRetries: 3 });
+        await rm(path, { recursive: true, force: true, maxRetries: 3 });
         return;
     }
     catch { /* read-only inside */ }
     if (process.platform !== "win32")
-        spawnSync("chmod", ["-R", "u+w", path], { timeout: 120_000 });
-    rmSync(path, { recursive: true, force: true, maxRetries: 3 });
+        await new Promise(resolve => execFile("chmod", ["-R", "u+w", path], { timeout: 120_000 }, () => resolve()));
+    await rm(path, { recursive: true, force: true, maxRetries: 3 });
 }

package/dist/toolroll-update.js

@@ -35,7 +35,7 @@ import { processMayBeAlive } from "./process-liveness.js";
 import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists, releaseStaleCodingOwner, removeCodingUpdateGate } from "./coding-update.js";
 import { installLaunchdService, launchdPlist, stopLaunchdService, writeFileDurably } from "./daemon.js";
 import { NAME } from "./names.js";
-import { orphanKey, updateSafeSchema, V117_RENAMED_COLUMNS, V117_RENAMED_TABLES, V118_MERGED_TABLES, V119_ADDED_COLUMNS, V120_ADDED_COLUMNS } from "./store.js";
+import { orphanKey, updateSafeSchema, V117_RENAMED_COLUMNS, V117_RENAMED_TABLES, V118_MERGED_TABLES, V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS } from "./store.js";
 import { isNewer, REGISTRY } from "./releases.js";
 import { markNeverIndex } from "./never-index.js";
 import { readRuntimeUpdateJournal, RUNTIME_PHASES, RUNTIME_UPDATE_STEPS, stagedStartedAt, updaterStartingOf } from "./contracts/update-journal.js";
@@ -398,7 +398,9 @@ const HISTORY_RULES = {
     // the declared value (generation 0, no closure reason).
     // v120: a steering note's mailing and acknowledgement, and a run's steering folder, are new columns; every row
     // saved before them reads none.
-    ...addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS),
+    // v121: live steering's columns and a run's attempt key read none, and no sends, the same way.
+    // v122: a project's recorded remote reads none the same way.
+    ...addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS),
 };
 /** The tables a migration may remove whole (v115's removed features). */
 export const RETIRED_TABLES = Object.freeze(Object.keys(HISTORY_RULES).filter(name => HISTORY_RULES[name].retired));

package/dist/work-index.d.ts

@@ -32,6 +32,7 @@ export type WorkIndexItem = {
         actor: string;
         at: string;
         digest: string;
+        landed?: string;
     } | null;
     evidence: 'recorded';
     /** The viewer's own lead took it on (lead-voice.ts): "<name> is on it.", by the name they gave it, read now. */

package/dist/work-index.js

@@ -16,6 +16,7 @@ import { shownVerdictOf } from './proof.js';
 import { isCheckLevel, requiredCheckCommandFor } from './check-levels.js';
 import { MARKER } from './worktree.js';
 import { withFollowUps } from './result-follow-ups.js';
+import { LANDED_ACTOR, landedReasonOf } from './result-completion.js';
 import { ASKS, NEED_ASK, NEEDS, askChipOf, failedAttemptSentence, processNeedOf, resultHoldUpSentence } from './needs-you.js';
 import { LEAD_CLAIM_SQL, LEAD_IDLE_MS } from './lead-voice.js';
 export const WORK_INDEX_PAGE_LIMIT = 40;
@@ -26,6 +27,9 @@ const FAMILY_PROBLEM = 'Task history is unavailable or incomplete. This task is
 const VIEWS = ['all', 'needs-you', 'running', 'completed'];
 const n = (row, key) => Number(row[key] ?? 0);
 const s = (row, key) => row[key] == null ? null : String(row[key]);
+/** The running agent's oldest open question (agent-board.ts), from its open newest attempt only. */
+const AGENT_ASK = `(SELECT q.id FROM agent_question q JOIN run qr ON qr.id=q.run WHERE q.task_ref=a.ref_id AND q.closed_at IS NULL
+      AND qr.outcome IS NULL AND qr.attempt_key=q.attempt_key ORDER BY q.id LIMIT 1)`;
 /** Keep the lineage predicates identical to Store.taskFamilyProjection: an
  * admitted child needs its parent's exact revision brief, in the same repo.
  * All subsequent reads are scalar/indexed metadata, never artifact bytes.
@@ -88,7 +92,7 @@ const PROJECTION = `WITH RECURSIVE admitted AS MATERIALIZED (
     (SELECT id FROM run WHERE task_ref=a.ref_id AND outcome IS NULL ORDER BY id DESC LIMIT 1) unfinished,
     CASE WHEN a.state='done' THEN (SELECT id FROM run WHERE task_ref=a.ref_id AND finished_at IS NOT NULL AND role IN ('builder','scout') ORDER BY id DESC LIMIT 1) END result_id,
     (SELECT h.id FROM hold h WHERE h.task_ref=a.ref_id AND (h.until IS NULL OR h.until>$now) ORDER BY h.held_at,h.id LIMIT 1) hold_id,
-    q.decision_id,(cu.task_ref IS NOT NULL OR a.ref_id IN (SELECT value FROM json_each($workspaceCustody)))
+    q.decision_id,${AGENT_ASK} agent_ask,(cu.task_ref IS NOT NULL OR a.ref_id IN (SELECT value FROM json_each($workspaceCustody)))
       AND a.ref_id NOT IN (SELECT value FROM json_each($settledCustody)) custody_unresolved
   FROM admitted a LEFT JOIN lineage l ON l.ref_id=a.ref_id
   LEFT JOIN questions q ON q.task_ref=a.ref_id LEFT JOIN custody cu ON cu.task_ref=a.ref_id
@@ -186,7 +190,7 @@ const PROJECTION = `WITH RECURSIVE admitted AS MATERIALIZED (
     AND a.action='assignment handoff checked' AND a.source='work' AND a.repo IS f.repo
     AND length(a.outcome)=64 AND a.outcome NOT GLOB '*[^a-f0-9]*'
     AND a.at>=f.family_updated AND a.at>=f.finished_at AND a.at>=f.approved_at AND a.at>=f.proposed_at
-    AND (a.actor GLOB 'operator:?*' OR a.actor GLOB 'coordinator:?*' OR a.actor GLOB 'lead:?*')
+    AND (a.actor GLOB 'operator:?*' OR a.actor GLOB 'coordinator:?*' OR a.actor GLOB 'lead:?*' OR a.actor='${LANDED_ACTOR}')
     AND (cm.changed_id IS NULL OR a.id>=cm.changed_id) AND (cm.artifact_at IS NULL OR a.at>=cm.artifact_at)
     AND NOT EXISTS(SELECT 1 FROM proof_verdict p WHERE p.run=f.result_id AND p.decided_at>a.at)
     AND NOT EXISTS(SELECT 1 FROM proof_acceptance p WHERE p.run=f.result_id AND p.accepted_at>a.at)
@@ -203,7 +207,7 @@ const PROJECTION = `WITH RECURSIVE admitted AS MATERIALIZED (
     WHEN state='done' THEN 'result-needs-attention'
     WHEN custody_unresolved AND live_lease IS NULL THEN 'process-needs-attention'
     WHEN state='failed' THEN 'failed'
-    WHEN live_lease IS NOT NULL THEN CASE WHEN question_id IS NOT NULL THEN 'waiting-decision' ELSE 'running' END
+    WHEN live_lease IS NOT NULL THEN CASE WHEN question_id IS NOT NULL OR agent_ask IS NOT NULL THEN 'waiting-decision' ELSE 'running' END
     WHEN state='running' OR unfinished IS NOT NULL THEN 'vanished-run'
     WHEN EXISTS(SELECT 1 FROM sqlite_master WHERE type='trigger' AND name GLOB 'so_desktop_update_*') THEN 'updating'
     WHEN hold_kind='backoff' THEN 'retry-scheduled'
@@ -239,7 +243,7 @@ const PROJECTION = `WITH RECURSIVE admitted AS MATERIALIZED (
       WHEN ${CUSTODY_WAITS} OR code IN ('updating','retry-scheduled','waiting-dependency','worker-at-capacity','planning-ready','scouting-ready','queued') THEN 2 ELSE 0 END rank,
     ${ASK_RANK} ask_rank,
     CASE WHEN code='complete' THEN completed.at ELSE family_updated END sort_at,
-    completed.actor checked_actor,completed.at checked_at,completed.outcome checked_digest
+    completed.actor checked_actor,completed.at checked_at,completed.outcome checked_digest,completed.detail checked_detail
   FROM claimed c LEFT JOIN action_ledger completed ON completed.id=c.checked_id WHERE ($state IS NULL OR c.state=$state) AND ($leadId IS NULL OR EXISTS(SELECT 1 FROM team_task_owner own WHERE own.task_ref=c.root_ref AND own.lead=$leadId))
 )`;
 const registered = new WeakMap();
@@ -280,7 +284,11 @@ function registerValidators(store) {
     const available = new Set(db.prepare(`SELECT name FROM sqlite_master WHERE type='index'
     AND name IN ('work_open_decision','work_spawned_run','work_unsettled_custody','work_result')`)
         .all().map(row => String(row['name'])));
-    const projection = available.size === 4 ? PROJECTION : PROJECTION.replace(/ INDEXED BY (work_open_decision|work_spawned_run|work_unsettled_custody|work_result)\b/g, (hint, name) => available.has(name) ? hint : '');
+    const indexed = available.size === 4 ? PROJECTION : PROJECTION.replace(/ INDEXED BY (work_open_decision|work_spawned_run|work_unsettled_custody|work_result)\b/g, (hint, name) => available.has(name) ? hint : '');
+    // A same-schema reader whose file has not taken the Agents board's tables yet reads no agent questions.
+    const asks = db.prepare("SELECT 1 AS hit FROM sqlite_master WHERE type='table' AND name='agent_question'").get() !== undefined;
+    const projection = asks ? indexed : indexed.replace(AGENT_ASK, 'NULL')
+        .replace(`'agent_ask_run',(SELECT run FROM agent_question WHERE id=page.agent_ask),'agent_ask_text',(SELECT substr(question,1,300) FROM agent_question WHERE id=page.agent_ask),`, '');
     registered.set(db, projection);
     return projection;
 }
@@ -398,10 +406,11 @@ function readWorkIndexPage(store, now, access, options, taskId = null) {
       AND f.action='checks finished' AND f.outcome LIKE q.id||':%' LIMIT 1),'open')) FROM (SELECT id,outcome FROM action_ledger WHERE repo IS page.repo AND run_id=page_result_id AND action='checks requested' ORDER BY id) q),
     'proof_verdict',(SELECT COALESCE(machine_verdict,verdict) FROM proof_verdict WHERE run=page_result_id),
     'proof_failed_check',(SELECT verdict='refuted' AND reasons_json LIKE '%approved verification command exited%' FROM proof_verdict WHERE run=page_result_id),'code',code,'needs',needs,'person_need',person_need,'lead_claim',lead_claim,'family_running',family_running,'rank',rank,'ask_rank',ask_rank,'list_order',${ORDER},'sort_at',sort_at,
-    'checked_actor',checked_actor,'checked_at',checked_at,'checked_digest',checked_digest,'question_id',question_id,
+    'checked_actor',checked_actor,'checked_at',checked_at,'checked_digest',checked_digest,'checked_detail',checked_detail,'question_id',question_id,
     'dependency_id',dependency_id,'dependency_state',dependency_state,'custody_unresolved',custody_unresolved,'hold_kind',hold_kind,'hold_reason',substr(hold_reason,1,300),'hold_id',hold_id,'live_lease',live_lease IS NOT NULL,'approved',COALESCE(approved,0),
     'plan_changed',scope_digest IS NOT NULL AND digest IS NOT scope_digest,'head_ok',length(head_revision)=40 AND head_revision NOT GLOB '*[^a-f0-9]*','stop_run',stop_run,'unfinished',unfinished,'signed_out',signed_out,
-    'question_run',(SELECT run FROM decision WHERE id=page.question_id),'replaced_by',(SELECT successor FROM task_replacement WHERE task_ref=page.ref_id),
+    'question_run',(SELECT run FROM decision WHERE id=page.question_id),'agent_ask',page.agent_ask,
+    'agent_ask_run',(SELECT run FROM agent_question WHERE id=page.agent_ask),'agent_ask_text',(SELECT substr(question,1,300) FROM agent_question WHERE id=page.agent_ask),'replaced_by',(SELECT successor FROM task_replacement WHERE task_ref=page.ref_id),
     'completed_by_lead',(SELECT lead FROM task_act WHERE task_ref=page.root_ref AND act='completed' ORDER BY id DESC LIMIT 1),
     'question_task',(SELECT r.external_id FROM decision d JOIN run ON run.id=d.run JOIN task_ref r ON r.id=run.task_ref WHERE d.id=page.question_id)) FROM page`)
         .all({ ...parameters(now, access, options, custody), $taskId: taskId, $cursorRoot: cursor?.root ?? 0, $cursorRank: cursor?.rank ?? 0, $cursorAt: cursor?.at ?? '', $limit: limit + 1, $recent: new Date(now.getTime() - 86_400_000).toISOString() });
@@ -508,7 +517,7 @@ function itemOf(row, principal, probe, leadName, readiness) {
         complete: ['Complete', 'Completion is recorded for this result. Open it to inspect the saved evidence.', 'open-result', 'Open result'],
         cancelled: ['Cancelled', 'This assignment was cancelled.', 'inspect-task', 'View assignment'],
         running: ['Running now', '', null, ''],
-        'waiting-decision': ['Needs your decision', 'An unanswered question is waiting.', n(row, 'question_id') ? 'answer-decision' : 'inspect-decisions', 'Answer question'],
+        'waiting-decision': ['Needs your decision', 'An unanswered question is waiting.', n(row, 'question_id') ? 'answer-decision' : n(row, 'agent_ask') ? 'answer-agent' : 'inspect-decisions', 'Answer question'],
         'decision-queue': ['Needs your decision', 'The decision queue is full.', 'inspect-decisions', 'Review open questions'],
         // Its own reason replaces this below (resultHoldUpSentence).
         'result-needs-attention': ['Needs your decision', '', 'inspect-run', 'Inspect run'],
@@ -588,11 +597,11 @@ function itemOf(row, principal, probe, leadName, readiness) {
     const read = actionCode !== null && ['inspect-task', 'inspect-run', 'inspect-stop', 'inspect-decisions', 'open-result'].includes(actionCode);
     const primaryAction = actionCode === null ? null : { code: actionCode, label: actionLabel,
         target: { taskId: successor ?? (code === 'earlier-active' ? s(row, 'earlier_id') ?? id : actionCode === 'answer-decision' ? s(row, 'question_task') ?? id : id),
-            runId: actionCode === 'answer-decision' ? n(row, 'question_run') || null : actionCode === 'inspect-run' && code === 'running' ? n(row, 'live_run') || null : actionCode === 'open-result' || actionCode === 'inspect-run' ? n(row, 'result_id') || null
+            runId: actionCode === 'answer-decision' ? n(row, 'question_run') || null : actionCode === 'answer-agent' ? n(row, 'agent_ask_run') || null : actionCode === 'inspect-run' && code === 'running' ? n(row, 'live_run') || null : actionCode === 'open-result' || actionCode === 'inspect-run' ? n(row, 'result_id') || null
                 : actionCode === 'reconcile-run' ? n(row, 'unfinished') || null : ['resume-run', 'inspect-stop'].includes(actionCode) ? n(row, 'stop_run') || null
                     : actionCode === 'confirm-stopped' ? process?.build ?? (n(row, 'result_id') || null) : null,
             decisionId: actionCode === 'answer-decision' ? n(row, 'question_id') || null : null },
-        access: read ? 'read' : principal === 'operator' ? 'operator-control' : ['answer-decision', 'write-scope', 'unhold'].includes(actionCode) ? 'proposal-only' : 'operator-handoff',
+        access: read ? 'read' : principal === 'operator' ? 'operator-control' : ['answer-decision', 'answer-agent', 'write-scope', 'unhold'].includes(actionCode) ? 'proposal-only' : 'operator-handoff',
         retry: actionCode === 'reconcile-run' ? 'reconcile-before-retry' : read ? 'read-again' : 'refresh-before-acting' };
     // The one shared status: the headline and sentence every surface uses.
     const coded = stageOfCode(code, { needsPerson: personNeed, planning: s(row, 'live_role') === 'planner', operatorHold: s(row, 'hold_kind') === 'operator' });
@@ -605,12 +614,15 @@ function itemOf(row, principal, probe, leadName, readiness) {
     const own = checkStatus === 'failed' || n(row, 'proof_failed_check') === 1 ? 'failed' : checkStatus === 'passed' || verdict === 'verified' ? 'passed' : null;
     const listedChecks = !finished ? null : listChecksOf(own, s(row, 'check_level'), row['check_follows']);
     const ready = reading.stage === 'finished' && readiness !== undefined ? readiness(row, listedChecks) : null;
+    // Toolroll marked it complete because its work landed: the reason, said once.
+    const landed = code === 'complete' ? landedReasonOf(s(row, 'checked_actor'), s(row, 'checked_detail')) : null;
     const shared = taskStatusOf({ stage: reading.stage, ...(reading.need === undefined ? {} : { need: reading.need }), ...(reading.wait === undefined ? {} : { wait: reading.wait }),
         ...(process === null ? {} : { needContext: { build: process.build } }),
         reason: finished ? null : plainReasonOf(reading.stage, code, detail || null), report: s(row, 'result_role') === 'scout',
         checks: ready?.checks ?? listedChecks,
         ...(ready === null ? {} : { requirements: ready.requirements ?? null, ...(ready.accepted ? { accepted: true } : {}), ...(ready.blockers === undefined ? {} : { blockers: ready.blockers }) }),
-        completedBy: code !== 'complete' ? null : n(row, 'completed_by_lead') === 1 ? 'the lead' : String(row['checked_actor']).replace(/^(?:operator|coordinator|lead):/, ''),
+        completedBy: code !== 'complete' || landed !== null ? null : n(row, 'completed_by_lead') === 1 ? 'the lead' : String(row['checked_actor']).replace(/^(?:operator|coordinator|lead):/, ''),
+        ...(landed === null ? {} : { landed }),
         ...(lead === null ? {} : { lead, ...(leadName === undefined ? {} : { leadName }) }) });
     label = shared.headline;
     detail = shared.sentence;
@@ -619,6 +631,14 @@ function itemOf(row, principal, probe, leadName, readiness) {
         actionLabel = shared.need.action.label;
         primaryAction.label = actionLabel;
     }
+    // A running agent's own question (agent-board.ts): its words, and Reply on the Agents board.
+    if (actionCode === 'answer-agent' && primaryAction !== null) {
+        actionLabel = 'Reply';
+        primaryAction.label = actionLabel;
+        const asked = s(row, 'agent_ask_text');
+        if (asked !== null)
+            detail = `The agent asks: ${asked}`;
+    }
     const views = ['all'];
     if (need)
         views.push('needs-you');
@@ -635,6 +655,6 @@ function itemOf(row, principal, probe, leadName, readiness) {
             action: primaryAction === null ? null : { label: actionLabel, kind: actionCode === 'open-result' ? 'open-result' : 'open-task' }, views, rank: n(row, 'rank') },
         ask: need ? ASKS[n(row, 'ask_rank')] ?? 'unblock' : null,
         chip: need ? askChipOf({ headline: shared.headline, need: shared.need?.key ?? null, planChanged, mismatch: verdict === 'refuted' && n(row, 'proof_failed_check') !== 1, ask: ASKS[n(row, 'ask_rank')] ?? 'unblock' }) : null,
-        primaryAction, completion: code === 'complete' ? { actor: String(row['checked_actor']), at: String(row['checked_at']), digest: String(row['checked_digest']) } : null,
+        primaryAction, completion: code === 'complete' ? { actor: String(row['checked_actor']), at: String(row['checked_at']), digest: String(row['checked_digest']), ...(landed === null ? {} : { landed }) } : null,
         evidence: 'recorded', ...(lead === 'on-it' ? { lead: leadOnIt(leadName) } : {}) };
 }

package/dist/work-summary.d.ts

@@ -9,8 +9,8 @@ export type WorkTarget = {
 };
 export type WorkAction = {
     /** `confirm-stopped`: an approver confirms a finished build stopped (behind the password);
-     * `sign-in`: the agent's sign-in, in Settings. */
-    code: DispatchAction | "inspect-task" | "inspect-run" | "inspect-stop" | "inspect-decisions" | "reconcile-run" | "open-pr" | "confirm-stopped" | "sign-in";
+     * `sign-in`: the agent's sign-in, in Settings; `answer-agent`: Reply to a running agent's question on the Agents board. */
+    code: DispatchAction | "inspect-task" | "inspect-run" | "inspect-stop" | "inspect-decisions" | "reconcile-run" | "open-pr" | "confirm-stopped" | "sign-in" | "answer-agent";
     label: string;
     target: WorkTarget;
     access: "read" | "operator-control" | "proposal-only" | "operator-handoff";

package/dist/workspace-revision.js

@@ -4,7 +4,9 @@ export const WORKSPACE_REVISION_KEY = 'workspace-content:v1';
 const KEY = WORKSPACE_REVISION_KEY;
 const MAX_AGE_MS = 60_000;
 const OMIT = new Set(['schema_version', 'service_cursor', 'wake', 'notification_delivery', 'sqlite_sequence',
-    'team_read', 'team_request', 'push_delivery', 'chat_message_ref']);
+    'team_read', 'team_request', 'push_delivery', 'chat_message_ref',
+    // Who is watching an agent right now: renewed by every open page's keep-alive, never news.
+    'agent_view']);
 const QUIET = {
     runner: ['heartbeat_at'], claim: ['heartbeat_at', 'expires_at'], watch_lease: ['heartbeat_at', 'expires_at'],
     watch_episode: ['ticks'], provider_readiness: ['observed_at'],