toolroll 0.9.63 → 0.9.65

package/dist/exec.js

@@ -6,9 +6,11 @@
  * command. And nothing here rejects: a failed command is a value. Discovery
  * walks repos it has never seen, and one broken repo must not end the scan.
  */
+import { ACP_LINE_CAP, createAcpConversation } from "./acp-client.js";
 import { linuxFenceAvailable, linuxFenced, macosFenceAvailable, macosFenced } from "./agent-fence.js";
-import { execFile, spawn } from "node:child_process";
-import { realpathSync } from "node:fs";
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
 import { observeProcessTree, stopProcessTree } from "./process-tree.js";
 import { jsonlDiscriminants } from "./jsonl-discriminants.js";
 import { createContainer, currentContainment } from "./containment.js";
@@ -45,6 +47,24 @@ const containers = new WeakMap();
 export class ContainmentRefusal extends Error {
     name = "ContainmentRefusal";
 }
+/**
+ * The command as it runs inside the agent fence (sandbox-exec or bubblewrap wrapping it), or as it is when it has no
+ * fence. A spawn whose confinement is required and that no backend here can wrap is refused (ContainmentRefusal):
+ * nothing runs, and nothing falls back to running it unwrapped.
+ */
+export function confined(file, args, bag) {
+    const fence = bag.fence ?? [];
+    if (fence.length > 0 && macosFenceAvailable())
+        return macosFenced(file, args, fence, bag.fenceGrants);
+    if (fence.length > 0 && linuxFenceAvailable())
+        return linuxFenced(file, args, fence, bag.fenceGrants);
+    if (bag.confinement === "required") {
+        throw new ContainmentRefusal(fence.length === 0
+            ? "This process must run inside the agent fence, and it was given none."
+            : "This machine can't confine a build (no macOS sandbox, no working bubblewrap), so nothing was started.");
+    }
+    return { file, args: [...args] };
+}
 /** A spawn callback refused custody AFTER the child existed: the caller
  * must reap exactly this child before answering. */
 class SpawnCustodyFailure extends Error {
@@ -72,10 +92,7 @@ function rejectedChild(error, child) {
  */
 function spawnContained(file, args, spawnOptions, label, bag, contain = true) {
     // The agent fence wraps the target itself (sandbox-exec then execs it, same pid).
-    if (bag.fence !== undefined && bag.fence.length > 0 && macosFenceAvailable())
-        ({ file, args } = macosFenced(file, args, bag.fence, bag.fenceGrants));
-    else if (bag.fence !== undefined && bag.fence.length > 0 && linuxFenceAvailable())
-        ({ file, args } = linuxFenced(file, args, bag.fence, bag.fenceGrants));
+    ({ file, args } = confined(file, args, bag));
     // The policy refusal comes first: nothing is reserved, recorded or
     // spawned for a spawn that cannot be contained as required.
     const effective = contain ? currentContainment() : null;
@@ -224,7 +241,7 @@ function containmentOf(container, empty, attachFailure) {
 }
 /** The streaming transports' spawn: contained when the spawn is a provider (process group), plain otherwise. */
 function spawnStream(file, args, options, stdio, childEnv) {
-    return spawnContained(file, args, { cwd: options.cwd, env: childEnv, stdio, detached: options.processGroup === true && process.platform !== "win32" }, options.owner ?? "stream", { beforeSpawn: options.beforeSpawn, onSpawn: options.onSpawn, onSpawnFailed: options.onSpawnFailed, onContainer: options.onContainer, onContainerEmpty: options.onContainerEmpty, onUnknown: options.onUnknown, fence: options.fence, fenceGrants: options.fenceGrants }, options.processGroup === true);
+    return spawnContained(file, args, { cwd: options.cwd, env: childEnv, stdio, detached: options.processGroup === true && process.platform !== "win32" }, options.owner ?? "stream", { beforeSpawn: options.beforeSpawn, onSpawn: options.onSpawn, onSpawnFailed: options.onSpawnFailed, onContainer: options.onContainer, onContainerEmpty: options.onContainerEmpty, onUnknown: options.onUnknown, fence: options.fence, fenceGrants: options.fenceGrants, confinement: options.confinement }, options.processGroup === true);
 }
 /** The refusal-before-spawn shape shared by every containable transport. */
 function refusedResult(error) {
@@ -522,6 +539,7 @@ export function run(file, args, options = {}) {
             ...(options.onStderr === undefined ? {} : { onStderr: options.onStderr }),
             ...(options.fence === undefined ? {} : { fence: options.fence }),
             ...(options.fenceGrants === undefined ? {} : { fenceGrants: options.fenceGrants }),
+            ...(options.confinement === undefined ? {} : { confinement: options.confinement }),
             ...(options.onDescendant === undefined ? {} : { onDescendant: options.onDescendant }),
             ...(options.onDescendantWriteFailure === undefined ? {} : { onDescendantWriteFailure: options.onDescendantWriteFailure }),
             ...(options.onDescendantExit === undefined ? {} : { onDescendantExit: options.onDescendantExit }),
@@ -531,8 +549,19 @@ export function run(file, args, options = {}) {
             ...(options.onContainerEmpty === undefined ? {} : { onContainerEmpty: options.onContainerEmpty }),
         }));
     }
+    // The plain road wraps exactly as the process-group road does: a fence given here is never dropped, and a spawn
+    // whose confinement is required and can't be wrapped refuses before anything runs.
+    let wrapped;
+    try {
+        wrapped = confined(file, args, options);
+    }
+    catch (error) {
+        if (!(error instanceof ContainmentRefusal))
+            throw error;
+        return Promise.resolve({ code: CONTAINMENT_REFUSED_CODE, stdout: "", stderr: error.message, timedOut: false, notFound: false, containment: { refused: error.message } });
+    }
     return retryTransientSpawn(() => new Promise(resolve => {
-        execFile(file, [...args], {
+        execFile(wrapped.file, wrapped.args, {
             cwd,
             timeout: timeoutMs,
             maxBuffer,
@@ -564,7 +593,7 @@ function runBufferedGroup(file, args, bag) {
         let container = null;
         let attached;
         try {
-            const spawned = spawnContained(file, args, { cwd: bag.cwd, env: bag.childEnv, stdio: [bag.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"], detached: process.platform !== "win32" }, bag.owner ?? "buffered", { beforeSpawn: bag.beforeSpawn, onSpawn: bag.onSpawn, onSpawnFailed: bag.onSpawnFailed, onContainer: bag.onContainer, onContainerEmpty: bag.onContainerEmpty, onUnknown: bag.onUnknown, fence: bag.fence, fenceGrants: bag.fenceGrants });
+            const spawned = spawnContained(file, args, { cwd: bag.cwd, env: bag.childEnv, stdio: [bag.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"], detached: process.platform !== "win32" }, bag.owner ?? "buffered", { beforeSpawn: bag.beforeSpawn, onSpawn: bag.onSpawn, onSpawnFailed: bag.onSpawnFailed, onContainer: bag.onContainer, onContainerEmpty: bag.onContainerEmpty, onUnknown: bag.onUnknown, fence: bag.fence, fenceGrants: bag.fenceGrants, confinement: bag.confinement });
             child = spawned.child;
             container = spawned.container;
             attached = spawned.attached;
@@ -1403,6 +1432,335 @@ export function runGeminiStreamJsonl(file, args, options = {}) {
         child.on("close", code => finish(code));
     });
 }
+/** One process listing: ids, group, state and command name only (never arguments — they can carry a brief). */
+function processRows() {
+    try {
+        return execFileSync("/bin/ps", ["-axo", "pid=,ppid=,pgid=,stat=,comm="], { encoding: "utf8", timeout: 2_000, maxBuffer: 8 * 1024 * 1024 })
+            .split("\n").flatMap(line => {
+            const parts = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(line);
+            return parts === null ? [] : [{ pid: Number(parts[1]), parent: Number(parts[2]), group: Number(parts[3]), state: parts[4], name: parts[5].trim() }];
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What the agent started and is still running: from `root` (the spawned process — the agent itself, or a fence
+ * wrapper around it), down to the agent's own process (the first whose command is the agent's launch, `names`), then
+ * every live, non-zombie process beneath it, with its group. The agent itself and any wrapper are never counted.
+ */
+function liveUnderAgent(root, names) {
+    const rows = processRows();
+    if (rows === null)
+        return null;
+    const children = new Map();
+    for (const row of rows)
+        children.set(row.parent, [...(children.get(row.parent) ?? []), row]);
+    const self = rows.find(row => row.pid === root);
+    const named = (row) => names.some(name => row.name === name || row.name.endsWith(`/${name}`));
+    // The agent: the root when it is the agent (macOS sandbox-exec execs in place), else the first named descendant.
+    let agent = self !== undefined && named(self) ? root : null;
+    const pending = [...(children.get(root) ?? [])];
+    while (agent === null && pending.length > 0) {
+        const row = pending.shift();
+        if (named(row))
+            agent = row.pid;
+        else
+            pending.push(...(children.get(row.pid) ?? []));
+    }
+    if (agent === null)
+        return [];
+    const found = [];
+    const below = [...(children.get(agent) ?? [])];
+    while (below.length > 0) {
+        const row = below.pop();
+        if (!row.state.startsWith("Z"))
+            found.push({ pid: row.pid, group: row.group });
+        below.push(...(children.get(row.pid) ?? []));
+    }
+    return found;
+}
+/** How long each shutdown step waits: session/close's answer, then exit after stdin closes, then exit after SIGTERM. */
+export const ACP_SHUTDOWN_MS = { close: 2_000, eof: 5_000, term: 5_000 };
+/** How long each handshake step (initialize, session/new, choosing the model) may take before the agent is stopped. */
+export const ACP_HANDSHAKE_MS = 30_000;
+/** After the agent itself has exited, how long its pipes may stay open (a descendant holding them) before they are closed. */
+const ACP_PIPES_AFTER_EXIT_MS = 5_000;
+/** SIGTERM the child's process group (POSIX) or the child alone; a container's own stop is the forced one, later. */
+function termGroup(child) {
+    const pid = child.pid;
+    try {
+        if (pid !== undefined && process.platform !== "win32")
+            process.kill(-pid, "SIGTERM");
+        else
+            child.kill("SIGTERM");
+    }
+    catch {
+        // Already gone.
+    }
+}
+/**
+ * One ACP build conversation over the agent's stdio (docs/plans/acp-adapter.md § Gateway, runner, custody). The
+ * conversation itself is acp-client.ts; this owns the process: the same contained spawn, ownership, descendant
+ * observation, container settlement and watchdog every other runner uses, with both clocks at once.
+ *
+ * After the prompt is answered it shuts the agent down in bounded steps — session/close (when offered), stdin EOF,
+ * SIGTERM to the group, then the forced kill — and returns only when the process has settled, so the gateway's
+ * witness records the real exit. A protocol failure kills at once. A stop, from the gateway's stop watch, kills at
+ * any step. The result's stdout is the conversation's retained record, never the agent's stream; its code is 0 only
+ * when the prompt was answered end_turn and the agent then exited cleanly or on our own signal.
+ */
+export function runAcpSession(file, args, options = {}) {
+    const acp = options.acp;
+    if (acp === undefined)
+        return Promise.resolve({ code: CONTAINMENT_REFUSED_CODE, stdout: "", stderr: "an ACP run needs its conversation terms", timedOut: false, notFound: false });
+    const childEnv = resolveChildEnv(options);
+    return new Promise(resolve => {
+        let child;
+        let container = null;
+        let attachFailure = null;
+        try {
+            const spawned = spawnStream(file, args, options, ["pipe", "pipe", "pipe"], childEnv);
+            child = spawned.child;
+            container = spawned.container;
+            void spawned.attached.then(outcome => { if (!outcome.ok)
+                attachFailure = outcome.detail; });
+        }
+        catch (error) {
+            void reapRejectedSpawn(rejectedChild(error, child), options.processGroup === true).then(() => resolve(refusedResult(error)));
+            return;
+        }
+        if (options.processGroup === true)
+            liveProviders.add(child);
+        registerOwned(options.owner, child);
+        if (options.processGroup === true && container === null)
+            observeProcessTree(child, options);
+        const conversation = createAcpConversation({ cwd: options.cwd ?? process.cwd(), prompt: acp.prompt, model: acp.model, expect: acp.expect });
+        // The agent's own process, as a listing names it: the launched file, or the script a pinned interpreter runs.
+        const agentNames = [...new Set([file, ...args.slice(0, 2)].filter(one => one.startsWith("/")).map(one => one.split("/").pop()).filter(one => one !== ""))];
+        let stderr = "";
+        let timedOut = false;
+        let notFound = false;
+        let settled = false;
+        let shuttingDown = false;
+        /** The signals the plane itself sent after the prompt was answered, by its own shutdown ladder: an exit by one of
+         * those is clean. A stop or a timeout kills through other roads and never sets these. */
+        let termAfterTerminal = false;
+        let killAfterTerminal = false;
+        /** How the process came to end, for the record: on its own (before or after stdin closed), or by our signal. */
+        let endedBy = "self";
+        let announced = null;
+        const timers = [];
+        const later = (ms, fn) => { const timer = setTimeout(fn, ms); timer.unref?.(); timers.push(timer); };
+        const write = (lines) => {
+            for (const one of lines) {
+                if (child.stdin === null || child.stdin.destroyed || child.stdin.writableEnded)
+                    return;
+                try {
+                    child.stdin.write(`${one}\n`);
+                }
+                catch { /* the agent closed its stdin: its exit decides */ }
+            }
+        };
+        const forceKill = () => {
+            endedBy = "kill";
+            if (options.processGroup === true)
+                killGroup(child);
+            else
+                child.kill("SIGKILL");
+        };
+        /** Each handshake step has its own deadline, beside the run's clocks. */
+        let handshakePhase = null;
+        const armHandshake = () => {
+            const phase = conversation.phase();
+            if (phase === handshakePhase || (phase !== "initialize" && phase !== "session" && phase !== "model"))
+                return;
+            handshakePhase = phase;
+            const limit = acp.handshakeMs ?? ACP_HANDSHAKE_MS;
+            later(limit, () => {
+                if (settled || conversation.phase() !== phase)
+                    return;
+                conversation.refuse(`the agent took more than ${limit / 1000} s to answer ${phase === "initialize" ? "initialize" : phase === "session" ? "session/new" : "the model choice"}`);
+                forceKill();
+            });
+        };
+        const exited = () => child.exitCode !== null || child.signalCode !== null;
+        const shutdown = () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            if (conversation.phase() === "failed") {
+                forceKill();
+                return;
+            }
+            const endInput = () => {
+                if (exited())
+                    return;
+                try {
+                    child.stdin?.end();
+                }
+                catch { /* gone */ }
+                endedBy = "eof";
+                later(ACP_SHUTDOWN_MS.eof, () => {
+                    if (exited())
+                        return;
+                    termAfterTerminal = conversation.phase() === "ended";
+                    endedBy = "term";
+                    termGroup(child);
+                    later(ACP_SHUTDOWN_MS.term, () => {
+                        if (exited())
+                            return;
+                        killAfterTerminal = conversation.phase() === "ended";
+                        forceKill();
+                    });
+                });
+            };
+            const close = conversation.close();
+            if (close.length === 0) {
+                endInput();
+                return;
+            }
+            write(close);
+            const started = Date.now();
+            const waitClose = () => {
+                if (conversation.closeAnswered() || Date.now() - started >= ACP_SHUTDOWN_MS.close || exited())
+                    endInput();
+                else
+                    later(50, waitClose);
+            };
+            waitClose();
+        };
+        const onLine = (framed) => {
+            if (settled)
+                return;
+            armHandshake();
+            const reaction = framed.overflowed
+                ? (conversation.refuse("the agent wrote a line too long to read"), { send: [], live: [] })
+                : conversation.receive(framed.prefix.toString("utf8"));
+            write(reaction.send);
+            const id = conversation.sessionId();
+            if (id !== null && announced === null) {
+                announced = id;
+                try {
+                    options.onSessionId?.(id);
+                }
+                catch { /* a registry that cannot be written must not kill the turn */ }
+            }
+            for (const update of reaction.live) {
+                try {
+                    options.onStreamEvent?.({ acp: update });
+                }
+                catch { /* observational only */ }
+            }
+            const phase = conversation.phase();
+            if (phase === "failed" || phase === "ended")
+                shutdown();
+            else
+                armHandshake();
+        };
+        const framing = boundedJsonlFramer(ACP_LINE_CAP, onLine);
+        const watchdog = streamWatchdog(options, () => {
+            timedOut = true;
+            forceKill();
+        });
+        child.stdout?.on("data", (chunk) => {
+            watchdog.touch();
+            framing.push(chunk);
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            watchdog.touch();
+            if (stderr.length < JSONL_STDERR_CAP)
+                stderr += chunk.slice(0, JSONL_STDERR_CAP - stderr.length);
+        });
+        child.stdin?.on("error", () => { });
+        write(conversation.start());
+        armHandshake();
+        try {
+            acp.onControl?.({
+                cancel: (deadlineMs) => {
+                    write(conversation.cancel());
+                    if (deadlineMs !== undefined)
+                        later(deadlineMs, () => {
+                            if (settled || conversation.terminal() !== null)
+                                return;
+                            conversation.refuse(`the agent didn't answer the cancel within ${Math.round(deadlineMs / 1000)} s`);
+                            forceKill();
+                        });
+                },
+                liveDescendants: () => process.platform === "win32" ? null : exited() || child.pid === undefined ? [] : liveUnderAgent(child.pid, agentNames),
+            });
+        }
+        catch { /* the caller's own failure */ }
+        // The moment the agent itself exits, what it left in its own group ends with it — not at "close", which a
+        // descendant holding the agent's pipes can postpone forever; and if those pipes are still open shortly after, they
+        // are closed, so settlement never waits on a stray. Escaped groups are the custody observer's, as for every runner.
+        let leftover = false;
+        child.on("exit", () => {
+            if (options.processGroup === true && container === null && child.pid !== undefined && process.platform !== "win32") {
+                try {
+                    process.kill(-child.pid, 0);
+                    leftover = true;
+                }
+                catch {
+                    leftover = false;
+                }
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                }
+                catch { /* none left */ }
+            }
+            later(ACP_PIPES_AFTER_EXIT_MS, () => {
+                if (settled)
+                    return;
+                for (const pipe of [child.stdout, child.stderr, child.stdin]) {
+                    try {
+                        pipe?.destroy();
+                    }
+                    catch { /* gone */ }
+                }
+            });
+        });
+        const finish = (code, signal) => {
+            if (settled)
+                return;
+            // The last record, even one with no newline after it, is read before anything is decided.
+            framing.finish();
+            settled = true;
+            for (const timer of timers)
+                clearTimeout(timer);
+            watchdog.stop();
+            liveProviders.delete(child);
+            // Whatever the agent started in its own group and left running ends with it (a group id can't be reused while any
+            // member lives, so this reaches only what it left). Escaped groups are the custody observer's, as for every runner.
+            const terminal = conversation.terminal();
+            const answered = terminal !== null && "stopReason" in terminal && terminal.stopReason === "end_turn" && conversation.failure() === null;
+            // A clean exit after the answer, or an exit by the plane's own post-answer signal (its shutdown ladder's SIGTERM,
+            // then SIGKILL), is success; anything else — a stop, a timeout, another signal — is its code.
+            const ownSignal = (termAfterTerminal && (signal === "SIGTERM" || code === 143)) || (killAfterTerminal && (signal === "SIGKILL" || code === 137));
+            const exitCode = answered && !timedOut && (code === 0 || ownSignal) ? 0 : (code ?? 1);
+            const settlement = container === null ? Promise.resolve(null) : settleContainer(container, options);
+            void settlement.then(empty => resolve({
+                code: notFound ? NOT_FOUND_CODE : timedOut ? TIMEOUT_CODE : attachFailure !== null || empty === false ? CONTAINMENT_REFUSED_CODE : exitCode,
+                // The runner's own account of the ending rides last: a type no agent can emit.
+                stdout: `${conversation.retained()}${JSON.stringify({ type: "acp.exit", how: endedBy, leftover: leftover || empty === false, timedOut })}\n`,
+                stderr: empty === false ? `${stderr}\nNative process containment could not prove all descendants exited.`.trim() : attachFailure !== null && stderr === "" ? attachFailure : stderr,
+                timedOut,
+                notFound,
+                ...containmentOf(container, empty, attachFailure),
+            }));
+        };
+        child.on("error", error => {
+            endedBy = "error";
+            notFound = error.code === "ENOENT";
+            if (stderr === "")
+                stderr = String(error);
+            finish(null, null);
+        });
+        child.on("close", (code, signal) => finish(code, signal));
+    });
+}
 const TRUNCATION_MARKER = "…[truncated]";
 /**
  * One serialized synthetic line, guaranteed ≤ JSONL_LINE_CAP in UTF-8

package/dist/export-ui.js

@@ -2,10 +2,10 @@
  * Settings → Data (v105): an instance operator downloads everything Standing
  * Orders knows as one .zip. One form: the password, typed again, and a button.
  */
-import { html, postForm } from "./html.js";
+import { html, postForm, reauth } from "./html.js";
 export const EXPORT_CSS = `.data-export{max-width:720px;min-width:0}.data-export label{display:grid;gap:4px;margin:14px 0 0;font-size:.875rem}` +
     `.data-export input[type=password]{width:100%;max-width:360px;box-sizing:border-box}.data-export button[type=submit]{margin-top:14px;min-height:44px;white-space:nowrap}`;
 export function dataExportHtml(notice) {
     const note = notice.problem ? html `<p class="problem" role="alert">${notice.problem}</p>` : "";
-    return html `<section class="data-export">${note}<p>Everything Toolroll knows, as one .zip: projects, tasks, runs and cost, the action ledger, evidence packs, chats, flows, subagents and settings. Passwords, keys and tokens are never included.</p>${postForm("/settings/data", html `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label><button type="submit">Download export</button>`)}<p class="meta">The same export from the command line: <code>toolroll export --out &lt;path&gt; [--zip]</code></p></section>`;
+    return html `<section class="data-export">${note}<p>Everything Toolroll knows, as one .zip: projects, tasks, runs and cost, the action ledger, evidence packs, chats, flows, subagents and settings. Passwords, keys and tokens are never included.</p>${postForm("/settings/data", html `${reauth(html `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label>`)}<button type="submit">Download export</button>`)}<p class="meta">The same export from the command line: <code>toolroll export --out &lt;path&gt; [--zip]</code></p></section>`;
 }

package/dist/flow-engine.js

@@ -6,10 +6,10 @@
  * waits for people. See flows.ts for what each zone does.
  */
 import { assignmentOf } from "./assignment.js";
-import { filerFor } from "./approval-policy.js";
 import { diagnoseTaskDispatch } from "./dispatch.js";
 import { passOn, TEXT_LIMITS } from "./text-limits.js";
 import { deciderOf, durationWords, fillFlowText, flowGoal, flowValueLabel, flowWorkTemplate, validateFlowDefinition, withinHours } from "./flows.js";
+import { readSnapshot, referenceWords, snapshotOf } from "./task-source.js";
 import { reportFillIns, reportSummaryFor } from "./report-summary.js";
 import { fileTaskProposal } from "./proposal.js";
 import { FLOW_ACCEPTANCE, unattendedCoverageFor } from "./flow-unattended.js";
@@ -273,13 +273,20 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
                 title: (report ? `${stage.title}: ${card.title}` : card.title).slice(0, 200),
                 repo,
                 goal,
-                filedVia: `flow:${flow.id}`, filedBy: filerFor(card.createdBy), // who made the card asked for the work (an owner can be reassigned by anyone)
+                filedVia: `flow:${flow.id}`,
+                // Who made the card asked for the work (an owner can be reassigned by anyone). v126: an automation's card (a
+                // delivery, a poll, a schedule, a form) files as automation, by the kind kept on the card, never by its name.
+                filedBy: { name: card.createdBy, kind: card.createdKind },
                 deliverable: report ? "report" : "branch",
                 planning: report ? "skip" : stage.planning ?? "auto",
                 acceptance: grant === null ? ACCEPTANCE[kind] : grant.terms.acceptance[kind],
                 ...(grant?.terms.perAttemptBudgetMicrousd == null ? {} : { budgetMicrousd: grant.terms.perAttemptBudgetMicrousd }),
                 admittedRepos: [repo],
             }, now);
+            // v126: a card an outside event's delivery made gives its task a snapshot of where it came from, in this transaction.
+            const snapshot = made.ok ? snapshotOf(fresh.source) : null;
+            if (made.ok && snapshot !== null)
+                store.recordTaskSource(made.id, { flow: flow.id, card: fresh.id, entry: fresh.entry }, JSON.stringify(snapshot), now);
             const ranOnItsOwn = made.ok && grant !== null && sealFlowFilingUnderGrant(store, made.id, grant, fresh, now);
             if (made.ok)
                 store.updateFlowCard(card.id, { task: made.id, ...(report || fresh.primaryTask !== null ? {} : { primaryTask: made.id }), waiting: ranOnItsOwn ? "Filed as a task, approved: this flow runs on its own" : "Filed as a task" }, now);
@@ -359,12 +366,24 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
  * 64 KiB), so in practice an attachment is never shortened. */
 const FLOW_ATTACHED_LIMIT = 128_000;
 export function flowGoalCuts(store, taskId, goal) {
+    let cuts = [];
     try {
-        return goalCuts(store, taskId, goal);
+        cuts = goalCuts(store, taskId, goal);
     }
     catch {
-        return [];
+        cuts = [];
     } // context, never a reason a build can't start
+    // v126: where the work came from, from the task's own kept source (or the task it revises) — never from the card's
+    // current task link or zone, which move on. Given whole whenever the goal itself couldn't carry it.
+    try {
+        const kept = store.taskSourceOf(taskId);
+        const snapshot = kept === null ? null : readSnapshot(kept.sourceJson);
+        const words = snapshot === null ? "" : referenceWords(snapshot);
+        if (words !== "" && !goal.includes(words) && !cuts.some(one => one.text === words))
+            cuts.push({ label: flowValueLabel("card.source"), text: words });
+    }
+    catch { /* context, never a reason a build can't start */ }
+    return cuts;
 }
 function goalCuts(store, taskId, goal) {
     const root = store.taskFamilyOf(taskId, null, true)?.root.id ?? taskId;
@@ -418,7 +437,7 @@ export function addCardToFlow(store, flow, input, actor, now) {
     if ("problem" in text)
         return { ok: false, message: text.problem };
     const stage = definition.stages.find(one => one.id === input.stage) ?? definition.stages.find(one => one.id === definition.start);
-    const card = store.addFlowCard({ flow: flow.id, title: text.title, description: text.description, stage: stage.id, by: actor }, now);
+    const card = store.addFlowCard({ flow: flow.id, title: text.title, description: text.description, stage: stage.id, by: actor, byKind: "person" }, now);
     // Whoever adds a card follows it; owning it is a separate, deliberate step.
     store.setFlowCardWatcher(card, actor, true, now);
     return { ok: true, said: `Card added to ${zoneWords(stage.title)}`, card };

package/dist/flow-gallery-ui.js

@@ -7,7 +7,7 @@
 import { brandMarkHtml } from "./brand-mark.js";
 import { BLANK, GALLERY, GALLERY_GROUPS, galleryDiagram, galleryToolsOf, OUTDATED_COMMANDS, SEND_RESULT, sendsAlready } from "./flow-gallery.js";
 import { choiceTargets } from "./flows.js";
-import { html, joinHtml, postForm } from "./html.js";
+import { html, joinHtml, postForm, reauth } from "./html.js";
 export const GALLERY_CSS = `.gallery{max-width:1120px;min-width:0}.gallery h2{margin:28px 0 10px;font-size:.9375rem}.gallery h2:first-of-type{margin-top:8px}` +
     `.gallery-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(250px,1fr));gap:12px}` +
     `.gallery-card{display:flex;flex-direction:column;gap:8px;padding:16px;border:1px solid var(--so-line);border-radius:10px;background:var(--so-paper);min-width:0}` +
@@ -89,7 +89,7 @@ export function galleryUseHtml(input) {
         if (tool.state === "connected" || tool.state === "taken" || input.csrf === "")
             return html `<div class="gallery-connect" data-tool="${tool.id}" data-state="${String(tool.state)}">${head}</div>`;
         const how = tool.id === "figma-desktop" ? "Open the Figma desktop app and turn on its Dev Mode MCP server in Preferences." : `You sign in on ${tool.label}, then come back here.`;
-        return html `<div class="gallery-connect" data-tool="${tool.id}" data-state="open">${head}${postForm("/settings/tools/connect", html `<p class="meta">${how}</p><label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label><button name="service" value="${tool.id}">Connect ${tool.label}</button>`, { hidden: { repo: input.repo, shown: input.repo, template: template.id } })}</div>`;
+        return html `<div class="gallery-connect" data-tool="${tool.id}" data-state="open">${head}${postForm("/settings/tools/connect", html `<p class="meta">${how}</p>${reauth(html `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label>`)}<button name="service" value="${tool.id}">Connect ${tool.label}</button>`, { hidden: { repo: input.repo, shown: input.repo, template: template.id } })}</div>`;
     };
     const toolsBlock = tools.length === 0 ? "" : html `<section class="gallery-tools-use" aria-label="Tools">${tools.map(connect)}</section>`;
     // Made without a tool, the preview names the zone that needs it.

package/dist/flow-gallery.js

@@ -266,10 +266,26 @@ export const GALLERY = [
         does: ["Checks for outdated {{ask.outdated}} packages {{ask.schedule-words}}, with no AI.", "When some are out of date, updates them as a task, under your usual approvals.", "What you approve opens a pull request."],
         never: NEVER_MERGES,
     },
+    {
+        // v126: the direct road from a signed outside request to a build that waits for your approval.
+        id: "webhook-to-build", name: "Webhook to build", group: "health",
+        promise: "A signed request from any tool becomes a build, under your usual approvals.",
+        needs: ["A tool that can send signed webhooks", "GitHub"], asks: [],
+        steps: [
+            { id: "build", title: "Build it", kind: "task", instructions: work("{{card.title}}\n\n{{card.description}}") },
+            owner("review", "Review the build"),
+            { ...pr, next: "Done" },
+            { id: "done", title: "Done", kind: "done" },
+        ],
+        triggers: [{ kind: "webhook", sender: "standard", title: "Request" }],
+        does: ["Adds a webhook signed the Standard Webhooks way. Once the flow is made, open its Triggers and choose Set up under Signing: it shows the address and the secret together, once; give both to the sender.",
+            "Each signed request becomes a card and is built as a task. The task waits for your approval, like any other.", "You review the build; what you approve opens a pull request."],
+        never: NEVER_MERGES,
+    },
     {
         id: "error-to-fix", name: "Error to fix", group: "health", tools: ["sentry"],
-        promise: "New errors from Sentry or any error tracker are sorted, researched and fixed.",
-        needs: ["A webhook from Sentry or another tracker", SORTS], asks: [],
+        promise: "New Sentry errors are sorted, researched and fixed.",
+        needs: ["A Sentry Internal Integration", SORTS], asks: [],
         steps: [
             { id: "worth-fixing", title: "Worth fixing?", kind: "sort", question: "Is this error in our own code, and new or frequent enough to fix now?",
                 answers: [
@@ -284,8 +300,9 @@ export const GALLERY = [
             { id: "done", title: "Done", kind: "done" },
             { id: "ignored", title: "Ignored", kind: "done" },
         ],
-        triggers: [{ kind: "webhook", title: "Error", titleField: "data.issue.title", bodyField: "data.issue.culprit" }],
-        does: ["Adds a webhook. Once the flow is made, open its Triggers and choose New address, then paste that into Sentry or another error tracker.", "Jev keeps errors in your code that are new or frequent, and drops noise; ones it isn't sure about wait for you.",
+        // v126: signed by Sentry and read by Toolroll's Sentry reader: one card per issue, linked to it.
+        triggers: [{ kind: "webhook", sender: "sentry", title: "Error" }],
+        does: ["Adds a Sentry webhook. Once the flow is made, open its Triggers and choose New address; in Sentry create an Internal Integration (Settings → Developer Settings), paste that address as its Webhook URL, turn on Alert Rule Action and Issue events, then paste its Client Secret under Signing on the flow's Triggers.", "One card per Sentry issue, however often it alerts, linked to the issue.", "Jev keeps errors in your code that are new or frequent, and drops noise; ones it isn't sure about wait for you.",
             "Each kept error is researched, then fixed as a task, under your usual approvals.", "What you approve opens a pull request."],
         never: NEVER_MERGES,
     },
@@ -300,7 +317,7 @@ export const GALLERY = [
             pr,
         ],
         triggers: [{ kind: "webhook", title: "Incident", titleField: "data.attributes.name" }],
-        does: ["Adds a webhook. Once the flow is made, open its Triggers and choose New address, then paste that into Better Stack.", "Reads the incident, its monitor's history and your recent commits and deploys, and sends you the likely cause.", "You choose Fix or Ignore; a fix is built as a task, under your usual approvals, and opens a pull request."],
+        does: ["Adds a webhook. Once the flow is made, open its Triggers and choose New address, then paste that into Better Stack. Better Stack doesn't sign its webhooks, so anyone with the address could add cards: keep it private.", "Reads the incident, its monitor's history and your recent commits and deploys, and sends you the likely cause.", "You choose Fix or Ignore; a fix is built as a task, under your usual approvals, and opens a pull request."],
         never: NEVER_MERGES,
     },
     {
@@ -335,8 +352,9 @@ export const GALLERY = [
             pr,
             send("Send the fix"),
         ],
-        triggers: [{ kind: "webhook", title: "Failed deployment", titleField: "payload.deployment.name" }],
-        does: ["Adds a webhook. Once the flow is made, open its Triggers and choose New address, then paste that into Vercel for failed deployments.", "Reads the build log and finds the cause.", "Builds a fix as a task, under your usual approvals, opens a pull request and sends it to you."],
+        // v126: signed by Vercel and read by Toolroll's Vercel reader: failed deployments only, one card each.
+        triggers: [{ kind: "webhook", sender: "vercel", title: "Failed deployment" }],
+        does: ["Adds a Vercel webhook. Once the flow is made, open its Triggers and choose New address; in Vercel (Settings → Webhooks) paste that address and choose Deployment Error, then paste the secret Vercel shows under Signing on the flow's Triggers. Put your Vercel project ID in Signing too, so only its deployments add cards.", "Reads the build log and finds the cause.", "Builds a fix as a task, under your usual approvals, opens a pull request and sends it to you."],
         never: NEVER_MERGES,
     },
     // ---------------------------------------------------------- Hear from users
@@ -637,7 +655,8 @@ export function useGalleryTemplate(store, template, repo, given, input) {
             const id = store.createFlow({ repo, name, definitionJson: JSON.stringify(built.definition), by: input.by }, input.now);
             const made = store.getFlow(id);
             for (const trigger of built.triggers) {
-                const added = addFlowTriggerTo(store, made, { ...trigger, zone: trigger["zone"] ?? flowDefinitionOf(made).start }, input.by, input.now, input.dir);
+                // No one is shown the gallery's addresses: a webhook is made with none until its panel makes one (v126).
+                const added = addFlowTriggerTo(store, made, { ...trigger, zone: trigger["zone"] ?? flowDefinitionOf(made).start }, input.by, input.now, input.dir, { shown: false });
                 if (!added.ok)
                     throw new Error(added.message);
                 if (added.reveal !== null)