toolroll 0.9.10 → 0.9.12

package/dist/browser-workspace.d.ts

@@ -7,6 +7,8 @@ export { browserCrewFromIndex, browserWorkActionHref } from './browser-crew.js';
 import type { Store } from './store.js';
 import type { WorkSummaryAccess } from './work-summary.js';
 import type { StatusTone } from './workspace-ui.js';
+import type { Ask } from './needs-you.js';
+import type { WorkIndexGroup } from './work-index.js';
 import type { AssignmentCard } from './assignment-ui.js';
 import type { TaskStatus } from './task-status.js';
 import type { FirstRunStep, FirstTaskSuggestion, JourneyStep } from './first-run.js';
@@ -103,6 +105,14 @@ export type BrowserTasksView = {
         count: number;
         active: boolean;
     })[];
+    /** Tasks waiting on a person in this view's scope ("3 need you" beside the title). */
+    needsYou: number;
+    /** All and Needs you list their rows in these groups, in this order (empty ones left out); null: one plain list. */
+    groups: {
+        key: BrowserTaskGroup;
+        label: string;
+        count: number;
+    }[] | null;
     rows: {
         id: string;
         title: string;
@@ -114,6 +124,9 @@ export type BrowserTasksView = {
             tone: StatusTone;
             token: string;
         };
+        /** What a Needs you row asks (its chip); null for every other row. */
+        ask: Ask | null;
+        group: BrowserTaskGroup;
         action: BrowserLink | null;
         detail: string | null;
         problem: string | null;
@@ -133,6 +146,7 @@ export type BrowserTasksView = {
     limits: BrowserLimits | null;
 };
 /** One limit: a plan's usage window ("Claude · 5-hour, 48%") or a monthly budget ("shop · Budget, $4.20 of $10"). */
+export type BrowserTaskGroup = WorkIndexGroup;
 export type BrowserLimitTile = {
     key: string;
     name: string;
@@ -436,6 +450,7 @@ export type BrowserResultPanel = {
      * Accept that records the decision (null when it is not offered here). */
     youCheck: {
         lines: string[];
+        items: BrowserCheckItem[];
         accept: {
             action: string;
             run: number;
@@ -465,6 +480,39 @@ export type BrowserResultPanel = {
     /** The feedback section holds only the closed form (no notes, revisions or history). */
     requestQuiet: boolean;
 };
+/** One "You check this one" item and the evidence to judge it by: the
+ * changed lines it cites (or, citing none, the change's own first lines),
+ * its screenshots, and the agent's note. Wrapped text, never sideways. */
+export type BrowserCheckItem = {
+    id: string;
+    statement: string;
+    words: string;
+    note: string | null;
+    excerpts: {
+        path: string;
+        cited: boolean;
+        lines: {
+            kind: "addition" | "deletion" | "context";
+            line: number | null;
+            text: string;
+        }[];
+        more: number;
+    }[];
+    shots: {
+        src: string;
+        href: string;
+        caption: string;
+    }[];
+};
+/** The result's one decision: what Accept is called, why it isn't plain
+ * Accept, and what pressing it does. */
+export type BrowserResultDecision = {
+    label: "Accept" | "Accept without checks";
+    ready: boolean;
+    why: string | null;
+    effect: string;
+    sentence: string;
+};
 /** A Needs you action: a link, (Confirm it stopped) a form behind the password, (Build again) one
  * button, or (on the result itself) Accept, which records the person's acceptance; `note` asks why
  * when the evidence disagrees. */
@@ -531,6 +579,8 @@ export type BrowserResultView = {
             receipt: string;
             run: number;
         } | null;
+        /** Words for the result's Accept: Mark complete when offered, else the Needs you acceptance. */
+        decision: BrowserResultDecision | null;
         checks: {
             detail: string;
             problem: boolean;
@@ -889,6 +939,11 @@ export type BrowserWorkspace = {
     refreshSeconds?: number;
     /** Providers whose sign-in stopped working: their work waits (one per provider). */
     signIn?: BrowserSignIn[];
+    /** A demo database: the notice that says so, scrolling with the page (`short`: its one line on a phone). */
+    demo?: {
+        text: string;
+        short: string;
+    };
     /** A newer Toolroll exists: a quiet notice for an operator, until they dismiss this version. */
     update?: BrowserUpdateNotice;
     /** Chat's first run, until the first Ready result: the three steps and first tasks to try. */
@@ -945,6 +1000,12 @@ export type BrowserHome = {
     }[];
     catchUp: BrowserCatchUpItem[];
     allHref: string;
+    /** What this person's lead is doing now and when it last acted (lead-voice.ts); its task when it named one. */
+    lead?: {
+        doing: string;
+        at: string;
+        href: string | null;
+    } | null;
 };
 /** `sandbox`: the demo command, offered beside the sign-in command while no agent is signed in. `intro`: how it works,
  * once, above the composer with the suggestions. `lead`: the one line saying what runs the lead, and where to change it.

package/dist/chat-channel.d.ts

@@ -12,18 +12,18 @@ export type ResolvedMate = {
     };
 } | {
     ok: false;
-    reason: "unpaired" | "unconfigured" | "direct-api" | "no-projects" | "session-mismatch" | "thread-mismatch";
+    reason: "unpaired" | "unconfigured" | "direct-api" | "no-projects" | "busy" | "no-session";
     said: string | null;
 };
 /**
  * The session and thread a paired phone speaks in: the approver's live
  * session when it is compatible (same generation, same membership
- * credential, same ceiling), else one minted under the very terms the
- * console and CLI state for membership chat (no dollar ceiling, this
- * ceiling digest) — and only when NO session is live, because minting
- * ends the previous one and an unrelated console conversation is not
- * this phone's to end. The same rule for the thread: reused when its
- * ceiling matches, never closed from here.
+ * credential, same ceiling), else a fresh one minted under the very terms
+ * the console and CLI state for membership chat (no dollar ceiling, this
+ * ceiling digest). An incompatible session or thread left open on the
+ * computer is replaced rather than refused, so a message from the phone
+ * always gets an answer — except while a turn is still running there,
+ * which is "busy": the message waits its turn instead of ending it.
  */
 export declare function resolveChannelMate(store: Store, binding: {
     approver: string;
@@ -34,6 +34,8 @@ export declare function resolveChannelMate(store: Store, binding: {
  * chat as well, so the task shows everything asked of it wherever it was
  * asked. Best effort: the phone conversation never depends on it. */
 export declare function mirrorToTaskChat(store: Store, who: VerifiedApprover, taskId: string, surface: string, message: string, reply: string, now: Date): void;
+/** The one short message a person gets when their question could not be answered. */
+export declare function couldNotAnswerText(reason: string): string;
 export declare function tooLongText(length: number): string;
 /** A reply to a message about several tasks is never guessed: it names them and says how to choose. */
 export declare function whichTaskText(titles: readonly string[]): string;

package/dist/chat-channel.js

@@ -25,12 +25,12 @@ export function channelRepos(store, approver, registry) {
 /**
  * The session and thread a paired phone speaks in: the approver's live
  * session when it is compatible (same generation, same membership
- * credential, same ceiling), else one minted under the very terms the
- * console and CLI state for membership chat (no dollar ceiling, this
- * ceiling digest) — and only when NO session is live, because minting
- * ends the previous one and an unrelated console conversation is not
- * this phone's to end. The same rule for the thread: reused when its
- * ceiling matches, never closed from here.
+ * credential, same ceiling), else a fresh one minted under the very terms
+ * the console and CLI state for membership chat (no dollar ceiling, this
+ * ceiling digest). An incompatible session or thread left open on the
+ * computer is replaced rather than refused, so a message from the phone
+ * always gets an answer — except while a turn is still running there,
+ * which is "busy": the message waits its turn instead of ending it.
  */
 export function resolveChannelMate(store, binding, repos, now) {
     const config = store.getChatConfig();
@@ -60,18 +60,17 @@ export function resolveChannelMate(store, binding, repos, now) {
         return { ok: false, reason: "unpaired", said: null };
     const who = verified.who;
     const credentialKey = subscriptionCredentialKey(config.provider);
-    const mismatch = "Your open chat session on the computer covers different projects or another provider. Finish or end it there, then message here again. Nothing was changed.";
     let session = store.activeMateSession(who.name);
-    if (session !== null &&
+    const liveThread = store.liveMateThreadFor(who.name);
+    const sessionMismatch = session !== null &&
         (session.approverGeneration !== who.generation ||
             session.credentialKey !== credentialKey ||
-            session.ceilingDigest !== who.ceilingDigest)) {
-        return { ok: false, reason: "session-mismatch", said: mismatch };
-    }
-    const liveThread = store.liveMateThreadFor(who.name);
-    if (liveThread !== null && liveThread.ceilingDigest !== who.ceilingDigest)
-        return { ok: false, reason: "thread-mismatch", said: mismatch };
-    if (session === null) {
+            session.ceilingDigest !== who.ceilingDigest);
+    const threadMismatch = liveThread !== null && liveThread.ceilingDigest !== who.ceilingDigest;
+    // Replacing either would end a turn still running on the computer.
+    if ((sessionMismatch || threadMismatch) && store.liveMateTurnFor(who.name) !== null)
+        return { ok: false, reason: "busy", said: null };
+    if (session === null || sessionMismatch) {
         const termsDigest = createHash("sha256")
             .update(`0\n${who.ceilingDigest}`)
             .digest("hex");
@@ -85,9 +84,12 @@ export function resolveChannelMate(store, binding, repos, now) {
         }, now);
         session = store.getMateSession(id);
         if (session === null)
-            return { ok: false, reason: "session-mismatch", said: mismatch };
+            return { ok: false, reason: "no-session", said: couldNotAnswerText("a new chat session couldn't be started") };
     }
-    const thread = liveThread ?? store.openMateThread(who.name, who.ceilingDigest, now).thread;
+    // openMateThread closes a thread kept under another ceiling.
+    const thread = threadMismatch || liveThread === null
+        ? store.openMateThread(who.name, who.ceilingDigest, now).thread
+        : liveThread;
     return {
         ok: true,
         who,
@@ -113,6 +115,10 @@ export function mirrorToTaskChat(store, who, taskId, surface, message, reply, no
         // The task chat is a copy; the phone's own conversation already has it.
     }
 }
+/** The one short message a person gets when their question could not be answered. */
+export function couldNotAnswerText(reason) {
+    return `I couldn't answer that just now: ${reason}. Ask again, or open the console.`;
+}
 export function tooLongText(length) {
     return `That message is ${length.toLocaleString("en-US")} characters; chat takes up to ${MATE_MESSAGE_MAX_CHARS.toLocaleString("en-US")}. Nothing was sent to the assistant. Send it in shorter parts, or say which part matters most.`;
 }

package/dist/chat-delivery.js

@@ -11,6 +11,7 @@ import { triggerConfigOf } from "./flow-triggers.js";
 import { telegramProgressCard } from "./telegram-progress.js";
 import { enqueueEveningDigests, finishedView, isTaskFact, joinsBatch, needsPerson, quietCardView } from "./chat-quiet.js";
 import { BATCH_MS, chatText, chatTitle } from "./chat-voice.js";
+import { LEAD_SAY_KIND, enqueueLeadLapses, leadSayEarlier, leadSayText } from "./lead-voice.js";
 import { phoneText, PHONE_HELP, phoneCommand, phoneStatus, phoneTaskView, phoneTaskChoices, phoneTaskListText, resolvePhoneTask, phoneFocusText, PHONE_NO_MATCH, PHONE_BACK_TO_LEAD } from "./telegram-status.js";
 import { applyRoomInbound, conversationRow, roomCardApprover, roomCommand, roomGrantAllowed, roomMessagesAfter, roomMessageText, teamDomain } from "./chat-rooms.js";
 import { isTelegramProgressNotification, proposalTaskOf } from "./store.js";
@@ -202,6 +203,10 @@ export async function processChatEvent(options) {
                 return true;
             }
             const resolved = resolveChannelMate(store, { approver: binding.approver, approverGeneration: binding.generation }, repos, now);
+            if (!resolved.ok && resolved.reason === "busy") {
+                state.defer(event.id, "Assistant is answering another message", new Date(now.getTime() + 5000));
+                return true;
+            }
             if (!resolved.ok) {
                 state.plan(event.id, [
                     {
@@ -647,6 +652,7 @@ export async function planChatNotifications(options) {
         enqueueEveningDigests(store, nowOf(options), options.evidenceRoot);
     }
     catch { /* Retried on the next pass. */ }
+    enqueueLeadLapses(store, nowOf(options));
     const cursor = Number(state
         .prepare("SELECT notification FROM chat_runtime WHERE installation=?")
         .get(identity.installation)?.notification ?? 0);
@@ -672,6 +678,21 @@ export async function planChatNotifications(options) {
                     // Only when I'm needed (the default): the task's one card is edited in place, and a new message
                     // follows only when this person is needed. Every step keeps the branches below unchanged.
                     const quiet = !personal && isTaskFact(notification) && store.notificationPreference(binding.approver).mode === "quiet";
+                    if (notification.kind === LEAD_SAY_KIND) {
+                        // The lead's words (lead-voice.ts): one message, repainted in place when a later say joins it.
+                        const content = { text: leadSayText(notification),
+                            ...(notification.link ? { link: { label: "Open", path: notification.link } } : {}) };
+                        const earlier = leadSayEarlier(store, notification).map(one => state.prepare("SELECT id FROM chat_part WHERE event=?")
+                            .get(chatHash(`${options.state.channel}:notice:${binding.id}:${one}`))).find(one => one !== undefined);
+                        if (earlier !== undefined) {
+                            state.prepare("UPDATE chat_part SET payload=?,state='pending',created=?,next_at=NULL WHERE id=? AND state!='dropped'").run(JSON.stringify(content), now.toISOString(), Number(earlier.id));
+                            return;
+                        }
+                        state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
+                            ts: "", thread: "", payload: "{}", created: now.toISOString() });
+                        state.plan(id, [content], now);
+                        return;
+                    }
                     if (quiet) {
                         planQuietCard(options, binding, notification, now);
                         if (!needsPerson(notification))

package/dist/chat-quiet.js

@@ -149,6 +149,7 @@ function lineOf(store, item, now, root, viewer) {
         pullRequest,
         // The lead speaks as "I" for what it did: the work it filed or approved, or the completion it recorded.
         lead: card.status.headline === "Complete" ? card.completedByLead : store.leadWorkOf(item.taskRef) !== null,
+        ...(card.facts.lead === "on-it" ? { leadOnIt: true } : {}),
     };
     // A result ready for a person offers its real next step, then a look first.
     if (asksToFinish(fact))

package/dist/chat-voice.d.ts

@@ -34,6 +34,8 @@ export type FinishedFact = {
         words: string;
         phrase: string;
     } | null;
+    /** The person's lead took it on (lead-voice.ts): "Your lead is on it", never "It waits for you". */
+    leadOnIt?: boolean;
 };
 /** The two buttons under a result ready for a person: the real next step, then a look first. */
 export declare const READY_ACTIONS: {
@@ -53,7 +55,7 @@ export declare function batchLine(facts: readonly FinishedFact[]): string;
  * StandingOrders is renamed, so a name a person chose later is kept. Best effort: a refused or failed call
  * leaves the old name and never blocks pairing or delivery. Returns whether a rename was sent and accepted.
  */
-export declare function nameTelegramBot(transport: TelegramTransport, when: "pairing" | "upgrade"): Promise<boolean>;
+export declare function nameTelegramBot(transport: TelegramTransport, when: "pairing" | "upgrade", signal?: AbortSignal): Promise<boolean>;
 /** The last word on any pushed chat text: a task's own id (bare or in brackets), a "— revision" suffix and a
  * "Replaced by <id>" never reach a chat, whatever words the fact was recorded with. A bare id reads as the
  * task's short title when one is given, else "this task". */

package/dist/chat-voice.js

@@ -53,6 +53,9 @@ export function finishedLine(fact) {
         return fact.update.words;
     const name = fact.summary, lower = inSentence(fact.summary);
     const ready = fact.lead === true ? `I finished ${lower}` : `${name} is ready`;
+    // What waited on the person and the lead has taken on (Needs you reads Waiting then).
+    if (fact.leadOnIt === true && (fact.headline === "Needs you" || fact.headline === "Waiting" || fact.headline === "Stopped"))
+        return `${name}: your lead is on it.`;
     switch (fact.headline) {
         case "Ready for review":
             if (fact.report)
@@ -63,6 +66,8 @@ export function finishedLine(fact) {
                 return `${ready}. Checks are off for this project, so look it over first.`;
             return `${ready}, but no tests ran. Look it over first.`;
         case "Failed":
+            if (fact.leadOnIt === true)
+                return fact.checks === "failed" ? `${name} is built, but its tests failed. Your lead is on it.` : `${name} stopped before it finished. Your lead is on it.`;
             if (fact.checks === "failed")
                 return fact.lead === true
                     ? `I built ${lower}, but its tests failed. It waits for you: retry or ask for changes.`
@@ -103,8 +108,9 @@ export function batchLine(facts) {
     const shown = names.slice(0, 3).join(", ");
     const first = `${facts.length} ${finishedOnly ? "tasks finished" : "updates"}: ${shown}${names.length > 3 ? ", …" : "."}`;
     // What happens next: anything that broke or needs a decision waits for the person.
-    const failed = facts.filter(one => one.headline === "Failed");
-    const needs = facts.filter(one => one.headline === "Needs you").length;
+    // What the lead is on waits for nobody.
+    const failed = facts.filter(one => one.headline === "Failed" && one.leadOnIt !== true);
+    const needs = facts.filter(one => one.headline === "Needs you" && one.leadOnIt !== true).length;
     const broke = failed.length !== 1 ? `${failed.length} failed`
         : failed[0].checks === "failed" ? `tests failed on ${inSentence(failed[0].summary)}` : `${inSentence(failed[0].summary)} stopped before it finished`;
     const waits = [
@@ -123,16 +129,18 @@ const OLD_NAME = /standing\s*-?\s*orders/i;
  * StandingOrders is renamed, so a name a person chose later is kept. Best effort: a refused or failed call
  * leaves the old name and never blocks pairing or delivery. Returns whether a rename was sent and accepted.
  */
-export async function nameTelegramBot(transport, when) {
+export async function nameTelegramBot(transport, when, signal) {
     try {
-        const current = await transport("getMyName", {});
+        const current = await transport("getMyName", {}, signal);
         const name = current.ok ? current.result?.name : undefined;
         const shown = typeof name === "string" ? name : null;
         if (shown === BOT_NAME)
             return false;
         if (when === "upgrade" && (shown === null || !OLD_NAME.test(shown)))
             return false;
-        const set = await transport("setMyName", { name: BOT_NAME });
+        if (signal?.aborted)
+            return false;
+        const set = await transport("setMyName", { name: BOT_NAME }, signal);
         return set.ok;
     }
     catch {

package/dist/cli.d.ts

@@ -39,7 +39,7 @@ export type ParseResult = {
     error: string;
 };
 type Write = (line: string) => void;
-export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> connect one (no path: the repo you are in)\n  toolroll repos remove <path>\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll update           update to the latest release: verified, drained, undoable\n                                   (preview first; --yes, --now, --at HH:MM, --rollback)\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll lead token       mint your lead agent's credential: its own work pings nobody\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll flows list | show <id> | create | edit | trigger | script | card | archive\n                               set up and inspect flows (writes preview until --yes)\n  toolroll chat --as <you> --token <t>\n                               talk to the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
+export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> connect one (no path: the repo you are in)\n  toolroll repos remove <path>\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll update           update to the latest release: verified, drained, undoable\n                                   (preview first; --yes, --now, --at HH:MM, --rollback)\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll lead token       mint your lead agent's credential: its own work pings nobody\n  toolroll lead say \"<text>\"  (the lead) one short message in its person's chat\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll flows list | show <id> | create | edit | trigger | script | card | archive\n                               set up and inspect flows (writes preview until --yes)\n  toolroll chat --as <you> --token <t>\n                               talk to the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
 export declare function parseArgs(argv: readonly string[]): ParseResult;
 /** The commands that operate the queue rather than report on the world. */
 /** Every verb the CLI routes OUTSIDE runOperate. Exported (with

package/dist/cli.js

@@ -66,6 +66,7 @@ Usage
   toolroll connect          save a private connection to your central service
   toolroll lead             named leads on the connected service
   toolroll lead token       mint your lead agent's credential: its own work pings nobody
+  toolroll lead say "<text>"  (the lead) one short message in its person's chat
   toolroll conversation     shared and private conversations on that service
   toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)
 

package/dist/coding-update.d.ts

@@ -10,6 +10,19 @@ export declare function activeCodingUpdateWork(orders: Database): {
 /** An idle provider may remain loaded during drain. The normal server stop
  * must close it and establish native/tool exit before either app swap. */
 export declare function assertCodingUpdateStopped(orders: Database): void;
+/** What a stale owner record named when an updater released it, for its ledger. */
+export type ReleasedCodingOwner = {
+    pid: number;
+    nativePid: number | null;
+};
+/** A runtime killed before its close (deploys over 0.9.11, Oct 2) leaves the
+ * owner record naming a dead process, and every later swap refuses. Only an
+ * updater that has itself proved each process of the stopped service gone may
+ * release it here, and only while nothing the catalog records still lives:
+ * the agent, its tools, a session or an unconfirmed message. Returns what it
+ * released, or null when the record was already released by an ordinary stop;
+ * anything unproven keeps the ordinary refusal. */
+export declare function releaseStaleCodingOwner(orders: Database, stoppedPids: readonly number[], alive?: (pid: number, group: boolean) => boolean): ReleasedCodingOwner | null;
 /** Back up through SQLite so committed WAL records are included. This is a
  * retained recovery artifact; updates never restore the live catalog. */
 export declare function backupCodingCatalog(sourceFile: string, target: string, updateId: string): Promise<void>;

package/dist/coding-update.js

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto';
 import { chmodSync, closeSync, fsyncSync, lstatSync, openSync } from 'node:fs';
+import { hostname } from 'node:os';
 import { sqliteRuntime } from './sqlite-runtime.js';
+import { processMayBeAlive } from './process-liveness.js';
 const gatePrefix = 'so_coding_update_';
 const pausedMessage = 'Toolroll is updating. Current work can finish; new coding work will resume after the update.';
 export function codingCatalogPath(orders) {
@@ -100,6 +102,72 @@ export function assertCodingUpdateStopped(orders) {
             throw Error('The coding server has not verified agent and tool shutdown. No app was replaced.');
     });
 }
+/** A runtime killed before its close (deploys over 0.9.11, Oct 2) leaves the
+ * owner record naming a dead process, and every later swap refuses. Only an
+ * updater that has itself proved each process of the stopped service gone may
+ * release it here, and only while nothing the catalog records still lives:
+ * the agent, its tools, a session or an unconfirmed message. Returns what it
+ * released, or null when the record was already released by an ordinary stop;
+ * anything unproven keeps the ordinary refusal. */
+export function releaseStaleCodingOwner(orders, stoppedPids, alive = processMayBeAlive) {
+    return withCatalog(orders, null, false, db => {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const owner = db.prepare('SELECT token,pid,native_pid,clean FROM coding_owner WHERE singleton=1').get();
+            const pid = Number(owner['pid']), nativePid = owner['native_pid'] === null ? null : Number(owner['native_pid']);
+            if (owner['token'] === '' && pid === 0 && nativePid === null && owner['clean'] === 1) {
+                db.exec('ROLLBACK');
+                return null;
+            }
+            const refuse = (why) => { throw Error(`The coding server has not verified agent and tool shutdown (${why}). No app was replaced.`); };
+            // A record its own server released while recovery was still required stays as it is: that needs a person's check.
+            if (owner['token'] === '' || !Number.isSafeInteger(pid) || pid <= 0)
+                refuse('its saved record needs a recovery check');
+            if (!stoppedPids.includes(pid))
+                refuse(`process ${pid} is not one this update stopped`);
+            if (alive(pid, false))
+                refuse(`process ${pid} is still running`);
+            // The agent runs in its own process group: a service killed by launchd can leave it behind.
+            if (nativePid !== null && alive(nativePid, true))
+                refuse(`the agent process ${nativePid} is still running`);
+            const custody = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='coding_custody'").get()
+                ? db.prepare('SELECT payload FROM coding_custody WHERE singleton=1').get() : undefined;
+            if (custody) {
+                let c;
+                try {
+                    c = JSON.parse(String(custody['payload']));
+                }
+                catch {
+                    c = {};
+                }
+                const processes = Array.isArray(c.descendants) ? c.descendants : null;
+                if (c.host !== hostname() || c.container || c.observationUnknown !== false || processes === null)
+                    refuse("the agent's tool processes could not be accounted for");
+                const recorded = [...(c.pid === null ? [] : [{ pid: c.pid, group: c.group }]), ...processes];
+                for (const one of recorded) {
+                    if (!Number.isSafeInteger(one.pid) || Number(one.pid) <= 0)
+                        refuse("the agent's tool processes could not be accounted for");
+                    if (alive(Number(one.pid), one.group === true))
+                        refuse(`the agent's process ${String(one.pid)} is still running`);
+                }
+            }
+            const sessions = Number(db.prepare("SELECT count(*) n FROM coding_session WHERE json_extract(document,'$.status') IN ('starting','working','needs-input','stopping','uncertain') OR json_extract(document,'$.turnId') IS NOT NULL").get()?.['n']);
+            const deliveries = Number(db.prepare("SELECT count(*) n FROM coding_submission WHERE status IN ('preparing','pending','uncertain')").get()?.['n']);
+            if (sessions > 0 || deliveries > 0)
+                refuse(`${sessions} coding session(s) and ${deliveries} unconfirmed message(s) were still active`);
+            db.prepare("UPDATE coding_owner SET token='',pid=0,native_pid=NULL,clean=1 WHERE singleton=1 AND token=?").run(owner['token']);
+            db.exec('COMMIT');
+            return { pid, nativePid };
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* already ended */ }
+            throw error;
+        }
+    });
+}
 function snapshot(db) {
     const data = {};
     // Include every catalog table, including current/future custody records.

package/dist/desktop-update.d.ts

@@ -1,5 +1,6 @@
 import type { DatabaseSync } from "node:sqlite";
 import { type DesktopBundle } from "./desktop-bundle.js";
+import { type ReleasedCodingOwner } from "./coding-update.js";
 type Phase = "prepared" | "draining" | "backing-up" | "stopping" | "installing" | "verifying" | "rolling-back" | "releasing" | "complete" | "restored" | "cancelled" | "needs-attention";
 export type UpdateJournal = {
     version: 1;
@@ -31,6 +32,10 @@ export type UpdateJournal = {
     waiting?: LingeringRun & {
         since: string;
     };
+    /** The service's supervisor and controller, recorded before it is stopped: the processes proved gone afterwards. */
+    stoppedPids?: number[];
+    /** A stale coding owner record this update released after proving those processes gone. */
+    codingOwnerReleased?: ReleasedCodingOwner;
 };
 type ServiceState = {
     state: string;
@@ -49,6 +54,8 @@ export type UpdateHooks = {
     /** Fault injection for state-machine tests, never selectable by a CLI flag. */
     checkpoint?: (phase: Phase) => void;
     otherControllers?: (bundle: DesktopBundle, stateDir: string) => Promise<boolean>;
+    /** Whether a recorded service process still runs (tests). */
+    processAlive?: (pid: number) => boolean;
 };
 export declare const updateTerminal: (phase: string) => boolean;
 /** Durable receipts are private and independent of the app being replaced. */

package/dist/desktop-update.js

@@ -10,7 +10,8 @@ import { run } from "./exec.js";
 import { readSchemaVersion, SCHEMA_VERSION, Store } from "./store.js";
 import { activeUpdateWork, freezeUpdateGate, installUpdateGate, removeUpdateGate, updateAdmissionPaused } from "./desktop-update-gate.js";
 import { currentDesktopAccess } from "./desktop-access.js";
-import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists } from "./coding-update.js";
+import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists, releaseStaleCodingOwner } from "./coding-update.js";
+import { processMayBeAlive } from "./process-liveness.js";
 /** Loaded on first use (as backup.ts and store.ts do), so modules that only import this one (the console,
  * and tests that load it in a browser-like environment) never need `node:sqlite` itself. */
 function sqlite() {
@@ -76,6 +77,8 @@ export function readUpdateJournal(stateDir, retainedReceipt) {
         throw Error("The recorded replacement state is invalid. Nothing was changed.");
     if (j.codingCatalogExpected !== undefined && typeof j.codingCatalogExpected !== "boolean")
         throw Error("The recorded coding catalog presence is invalid. Nothing was changed.");
+    if (j.stoppedPids !== undefined && (!Array.isArray(j.stoppedPids) || !j.stoppedPids.every(pid => Number.isSafeInteger(pid) && pid > 1)))
+        throw Error("The recorded service processes are invalid. Nothing was changed.");
     if ((j.codingBackupPath === undefined) !== (j.codingBackupHash === undefined) || (j.codingBackupPath && (dirname(j.codingBackupPath) !== j.workDir || !/^coding\.backup(?:\.[a-f0-9-]{36})?\.sqlite$/.test(basename(j.codingBackupPath)))) || (j.codingBackupHash && !/^[a-f0-9]{64}$/.test(j.codingBackupHash)))
         throw Error("The retained coding backup paths or identity are invalid. Nothing was changed.");
     for (const directory of [dirname(j.workDir), j.workDir]) {
@@ -537,6 +540,34 @@ function assertDesktopCodingStopped(j, db) {
     assertCodingCatalogPresent(j);
     assertCodingUpdateStopped(db);
 }
+/** The service's own processes, from its supervisor's status file: read before the stop, never after. */
+function servicePids(stateDir) {
+    try {
+        const status = JSON.parse(readFileSync(join(stateDir, "controller-supervisor.json"), "utf8"));
+        return [status.supervisorPid, status.controllerPid].filter((pid) => Number.isSafeInteger(pid) && Number(pid) > 1);
+    }
+    catch {
+        return [];
+    }
+}
+/** An older app killed before its close leaves the coding owner record behind. Once the stopped service's processes
+ * are proved gone, it is released here (and recorded in the ledger); anything unproven keeps the ordinary refusal. */
+function releaseDesktopCodingOwner(j, db, alive) {
+    assertCodingCatalogPresent(j);
+    const released = releaseStaleCodingOwner(db, j.stoppedPids ?? [], (pid, group) => alive(pid) || processMayBeAlive(pid, group));
+    if (released === null)
+        return;
+    j.codingOwnerReleased = released;
+    save(j, j.phase, j.detail);
+    const ledger = connect(j.databaseFile);
+    try {
+        ledger.prepare("INSERT INTO action_ledger(at,actor,repo,task_id,run_id,action,outcome,source,detail) VALUES (?,'desktop update',NULL,NULL,NULL,'coding owner released','released','policy',?)")
+            .run(new Date().toISOString(), `${j.old.version} stopped without releasing the coding workspace; process ${released.pid}${released.nativePid === null ? "" : ` and agent ${released.nativePid}`} proved gone`);
+    }
+    finally {
+        ledger.close();
+    }
+}
 function assertCodingBackup(j) {
     assertCodingCatalogPresent(j);
     if (j.codingBackupPath || j.codingBackupHash) {
@@ -815,15 +846,25 @@ export async function runDesktopUpdate(stateDir, hooks = {}) {
             throw Error("The installed app changed after preview. Nothing was replaced.");
         const current = actual === j.old.hash ? j.old : atInstalled(j.next, j);
         j.serviceInterrupted = true;
+        // Recorded once, before the first stop: a resumed update keeps the processes it first saw.
+        if (j.stoppedPids === undefined)
+            j.stoppedPids = servicePids(j.stateDir);
         checkpoint("stopping", "Current work is finished. Stopping the background service for the update.");
         await control("stop", current, j);
         const stopped = await status(current, j);
         if (["running", "loaded"].includes(stopped.state))
             throw Error("The background service did not stop. No app swap was attempted.");
+        const alive = hooks.processAlive ?? (pid => processMayBeAlive(pid, false));
+        for (let waited = 0; j.stoppedPids.some(alive); waited += 250) {
+            if (waited >= 60_000)
+                throw Error(`The background service is still running (process ${j.stoppedPids.filter(alive).join(", ")}) after it was stopped. No app swap was attempted.`);
+            await sleep(250);
+        }
         const afterStop = connect(j.databaseFile, true);
         try {
             if (Object.values(activeUpdateWork(afterStop)).some(n => n !== 0) || afterStop.prepare("SELECT 1 FROM watch_lease WHERE expires_at>? LIMIT 1").get(new Date().toISOString()))
                 throw Error("A worker or active operation still uses this database. Stop the other controller before continuing the update.");
+            releaseDesktopCodingOwner(j, afterStop, alive);
             assertDesktopCodingStopped(j, afterStop);
         }
         finally {