From 01e2d58ae3cb22499b93d1a057ef3c1e35e527fd Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Sun, 18 Oct 2026 20:36:11 +0200
Subject: [PATCH 01/30] feat(question): a decision post can carry the number
 the chat reply gave it, so the log and its links never point at another
 decision

---
 src/genesis-tools-mcp/lib/server.ts           |  3 +-
 .../lib/tools/question-post.ts                |  6 +++
 src/question/commands/ask.ts                  |  1 +
 src/question/lib/decisions/items.ts           | 12 ++++++
 src/question/lib/decisions/schema.ts          |  9 ++++
 src/question/lib/decisions/store.test.ts      | 42 +++++++++++++++++++
 src/question/lib/decisions/store.ts           |  9 +++-
 7 files changed, 80 insertions(+), 2 deletions(-)

diff --git a/src/genesis-tools-mcp/lib/server.ts b/src/genesis-tools-mcp/lib/server.ts
index cd62eb9cbe..1a00d68766 100644
--- a/src/genesis-tools-mcp/lib/server.ts
+++ b/src/genesis-tools-mcp/lib/server.ts
@@ -107,7 +107,8 @@ export function serverInstructions({ askViaQuestionTool, inboxState }: Instructi
         "one list.\n" +
         'DECISIONS AND TODOS: a `question_post` item with `type: "decision"` or `type: "todo"` is not a form. ' +
         "It is numbered in this session's decision log (❓ DECISION N, TODO N; numbers never reused) and the " +
-        "result is the markdown section to paste into your reply. " +
+        "result is the markdown section to paste into your reply. When your reply already numbered it, pass that " +
+        "`number`, so the log and the chat agree. " +
         decisionNudge({ state: inboxState, askViaQuestionTool }) +
         "Record " +
         "progress (acknowledged, implemented, commit refs, verdict, comments, a copy of a chat answer) with " +
diff --git a/src/genesis-tools-mcp/lib/tools/question-post.ts b/src/genesis-tools-mcp/lib/tools/question-post.ts
index 6d106d488d..f42d923533 100644
--- a/src/genesis-tools-mcp/lib/tools/question-post.ts
+++ b/src/genesis-tools-mcp/lib/tools/question-post.ts
@@ -346,6 +346,12 @@ const ITEM_SCHEMA = {
                 "screenshots for this item (any type): copied into the question store and appended to " +
                 "promptMarkdown as images, so the card shows previews",
         },
+        number: {
+            type: "integer",
+            description:
+                "decision/todo: the number this item already has in your reply (❓ DECISION 24), so the log and the " +
+                "chat agree and a later link to it opens the right one. Omit it to take the next free number.",
+        },
         supersedes: {
             type: "string",
             description:
diff --git a/src/question/commands/ask.ts b/src/question/commands/ask.ts
index e79e42170e..59491d0177 100644
--- a/src/question/commands/ask.ts
+++ b/src/question/commands/ask.ts
@@ -97,6 +97,7 @@ const ASK_JSON_HELP = `
   for              decision/todo: who acts on it, "human" (default for a decision), "agent" or a model name
   reevaluateWhen   decision/todo: a condition that reopens it, e.g. "after the PR merges"
   refs             decision: [{ path, line?, endLine?, sha? }]; the first ref's lines become the excerpt
+  number           decision/todo: the number your chat reply already shows, so the log matches it
   supersedes       decision/todo: id of an open or drafted item this one replaces (it keeps its id and
                    number; the old text stays as a version: ${toolCommand("question show", "<id>", "--versions")})
   attachments      any item: screenshots, [{ "type": "image", "path": "/abs/shot.png", "label"?: "After" }];
diff --git a/src/question/lib/decisions/items.ts b/src/question/lib/decisions/items.ts
index 4cb159c111..0c259f7005 100644
--- a/src/question/lib/decisions/items.ts
+++ b/src/question/lib/decisions/items.ts
@@ -29,6 +29,8 @@ export interface QuestionItemInput extends CreateAskItemInput {
     blocking?: boolean;
     /** Decision/todo: the id of an open or drafted item this post replaces; the old text is kept as a version. */
     supersedes?: string;
+    /** Decision/todo: the number the item already has in the chat reply, so the log uses the same one. */
+    number?: number;
     /**
      * Screenshots for any item type. `prepareQuestionItems` copies them into the question store, appends them to
      * `promptMarkdown` as markdown images and removes this field, so neither store ever sees it.
@@ -59,6 +61,7 @@ const ITEM_KEYS = new Set([
     "refs",
     "blocking",
     "supersedes",
+    "number",
     "attachments",
 ]);
 
@@ -130,6 +133,14 @@ export function validateQuestionItems(value: unknown, help: string): QuestionIte
         ) {
             problems.push(`${at}: supersedes must be a decision or todo id like d_3_<session>`);
         }
+
+        if (record.number !== undefined && record.type !== "decision" && record.type !== "todo") {
+            problems.push(`${at}: number applies to decision and todo items`);
+        }
+
+        if (record.number !== undefined && (!Number.isInteger(record.number) || Number(record.number) < 1)) {
+            problems.push(`${at}: number must be a positive whole number, the one your reply shows`);
+        }
     });
 
     if (problems.length > 0) {
@@ -200,6 +211,7 @@ export function decisionPayload(items: QuestionItemInput[], hint: DecisionSessio
             ...(item.for ? { for: item.for } : {}),
             ...(item.reevaluateWhen ? { reevaluateWhen: item.reevaluateWhen } : {}),
             ...(item.supersedes ? { supersedes: item.supersedes } : {}),
+            ...(item.number === undefined ? {} : { number: item.number }),
             ...decisionTransclusion(item.transclusion),
         })),
     };
diff --git a/src/question/lib/decisions/schema.ts b/src/question/lib/decisions/schema.ts
index 8ed50ea87e..4d22b41362 100644
--- a/src/question/lib/decisions/schema.ts
+++ b/src/question/lib/decisions/schema.ts
@@ -47,6 +47,15 @@ export const postedDecisionSchema = z.object({
         .enum(DECISION_KINDS)
         .optional()
         .describe("decision (default): a numbered ❓ DECISION N. todo: a numbered TODO N, options optional."),
+    number: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe(
+            "The number this item already has in your reply (❓ DECISION 24), so the log and the chat agree. Omit it " +
+                "to take the next free number. Refused when this session already used it for this kind."
+        ),
     prompt: z.string().min(1).describe("The question, self-contained."),
     options: z.array(z.string()).default([]).describe("The answer options in order: a), b), c)."),
     excerpt: z.string().optional().describe("Context text. Defaults to up to 40 lines of the first ref."),
diff --git a/src/question/lib/decisions/store.test.ts b/src/question/lib/decisions/store.test.ts
index db71652821..9fc47df536 100644
--- a/src/question/lib/decisions/store.test.ts
+++ b/src/question/lib/decisions/store.test.ts
@@ -21,6 +21,7 @@ import { answerGitWithoutSpawning } from "@genesiscz/utils/test/no-git";
 import { z } from "zod";
 import { DeliveryUnknownError, deliverToSession, resolveDeliveryTarget } from "./deliver";
 import { livePaneTargets, noPaneTargets } from "./deliver.fixtures";
+import { decisionPayload, validateQuestionItems } from "./items";
 import {
     decisionLine,
     decisionsMarkdown,
@@ -111,6 +112,47 @@ describe("decision store", () => {
         expect(first[0]?.sessionId).toBe("abc");
     });
 
+    test("a post keeps the number its chat reply gave, and refuses one the session already used", async () => {
+        const dir = mkdtempSync(join(tmpdir(), "decisions-"));
+        const file = join(dir, "decisions.jsonl");
+        const events = join(dir, "events.jsonl");
+        const chat = await postDecisions(file, events, {
+            sessionId: "abc",
+            decisions: [{ number: 24, prompt: "close the alternative?", options: ["a", "b"] }],
+        });
+        const next = await postDecisions(file, events, {
+            sessionId: "abc",
+            decisions: [{ prompt: "next", options: ["a"] }],
+        });
+
+        expect(chat[0]?.number).toBe(24);
+        expect(chat[0]?.id).toBe("d_24_abc");
+        expect(next[0]?.number).toBe(25);
+        await expect(
+            postDecisions(file, events, {
+                sessionId: "abc",
+                decisions: [{ number: 24, prompt: "again", options: ["a"] }],
+            })
+        ).rejects.toThrow("DECISION 24 is already in session abc");
+        expect(readDecisions(file)).toHaveLength(2);
+    });
+
+    test("a question_post item carries its chat number to the store, and only a decision or todo may", () => {
+        const items = validateQuestionItems(
+            [{ type: "decision", number: 24, promptMarkdown: "close it?", choices: ["a", "b"] }],
+            "help"
+        );
+        const payload = postDecisionsInputSchema.parse(decisionPayload(items, { sessionId: "abc" }));
+
+        expect(payload.decisions[0]?.number).toBe(24);
+        expect(() => validateQuestionItems([{ number: 3, promptMarkdown: "a form" }], "help")).toThrow(
+            "number applies to decision and todo items"
+        );
+        expect(() =>
+            validateQuestionItems([{ type: "decision", number: 0, promptMarkdown: "x", choices: ["a"] }], "help")
+        ).toThrow("number must be a positive whole number");
+    });
+
     test("a post allocates its number only after another writer releases the lock", async () => {
         const dir = mkdtempSync(join(tmpdir(), "decisions-"));
         const file = join(dir, "decisions.jsonl");
diff --git a/src/question/lib/decisions/store.ts b/src/question/lib/decisions/store.ts
index eccae5391f..c7d8830637 100644
--- a/src/question/lib/decisions/store.ts
+++ b/src/question/lib/decisions/store.ts
@@ -344,7 +344,14 @@ export async function postDecisions(
             }
 
             const used = numbers[kind];
-            const number = used.size === 0 ? 1 : Math.max(...used) + 1;
+            if (decision.number !== undefined && used.has(decision.number)) {
+                throw new Error(
+                    `${kind === "todo" ? "TODO" : "DECISION"} ${decision.number} is already in session ${sessionId}; ` +
+                        "post a later number, or revise the earlier one with supersedes"
+                );
+            }
+
+            const number = decision.number ?? (used.size === 0 ? 1 : Math.max(...used) + 1);
             const row: DecisionRecord = {
                 id: `${ID_PREFIX[kind]}_${number}_${sessionId}`,
                 sessionId,

From c7f1a92bbcb9c18fe01b9fc1d3aa8655928db675 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Sun, 18 Oct 2026 20:55:13 +0200
Subject: [PATCH 02/30] feat(skills, babysit): tmp-reclaim --own-session
 reclaims the running session's own SwiftPM build output, and briefs give
 every reply item a severity

---
 .claude/skills/babysit/scripts/tmp-reclaim.ts | 320 +++++++++++++++++-
 1 file changed, 317 insertions(+), 3 deletions(-)

diff --git a/.claude/skills/babysit/scripts/tmp-reclaim.ts b/.claude/skills/babysit/scripts/tmp-reclaim.ts
index 1ecf70f4bd..17762822d7 100644
--- a/.claude/skills/babysit/scripts/tmp-reclaim.ts
+++ b/.claude/skills/babysit/scripts/tmp-reclaim.ts
@@ -23,7 +23,18 @@
  * - its tree could not be scanned within the time budget.
  *
  *   bun tmp-reclaim.ts [--run <dir>] [--min-age-hours 6] [--live-hours 12] [--protect <id|path> ...]
+ *   bun tmp-reclaim.ts --own-session <session uuid> [--min-age-minutes 10] [--run <dir>]
  *   bun tmp-reclaim.ts --apply --plan <plan.json> [--run <dir>]
+ *
+ * `--own-session` is for the session that runs it, which the live-session guard otherwise always shields
+ * (2026-10-18: a lead's own `/tmp/cc/GenesisTools/<session>/` held 14 GB of SwiftPM scratch builds while the disk was
+ * full). It lists BUILD OUTPUT only, inside `/tmp/cc/<project>/<that session>/`: a SwiftPM triple folder
+ * (`arm64-apple-macosx`, `x86_64-apple-macosx`), a SwiftPM scratch folder (`.build` or a `--scratch-path`) that holds
+ * nothing but SwiftPM's own entries, and a Swift or clang module cache (only `.pcm`, `.swiftmodule`, `.timestamp`,
+ * `.modulevalidation` and `.lock` files). Notes, logs, reply files, patches, briefs, worktrees' sources and the
+ * `removals/` folder are never listed. Every other guard stays: no open file, socket, FIFO or `.git` inside, same
+ * owner and device, not changed in the last --min-age-minutes (default 10, because the session is live), and on
+ * apply the same inode and the same build-output class again.
  */
 import {
     existsSync,
@@ -55,8 +66,42 @@ interface Plan {
     createdAt: number;
     minAgeHours: number;
     candidates: Candidate[];
+    /** Set by an `--own-session` dry run: the apply re-checks each entry as that session's build output. */
+    ownSession?: { id: string; dirs: string[]; minAgeMinutes: number };
 }
 
+export type BuildOutputKind = "swiftpm-triple" | "swiftpm-scratch" | "module-cache";
+
+const SWIFTPM_TRIPLES = new Set(["arm64-apple-macosx", "x86_64-apple-macosx"]);
+/** What SwiftPM itself writes into a scratch path; a folder holding anything else is not pure build output. */
+const SWIFTPM_SCRATCH_ENTRIES = new Set([
+    ...SWIFTPM_TRIPLES,
+    ".lock",
+    "artifacts",
+    "build.db",
+    "checkouts",
+    "debug",
+    "debug.yaml",
+    "index-build",
+    "manifest.db",
+    "manifest.db-shm",
+    "manifest.db-wal",
+    "plugin-tools.yaml",
+    "plugins",
+    "prebuilts",
+    "registry",
+    "release",
+    "release.yaml",
+    "repositories",
+    "workspace-state.json",
+]);
+const MODULE_CACHE_FILES = [".pcm", ".swiftmodule", ".timestamp", ".modulevalidation", ".lock"];
+const MODULE_CACHE_MARKERS = [".pcm", ".swiftmodule", "modules.timestamp"];
+/** Never walked in an own-session scan: dependency trees, repositories and moved-aside files a user may restore. */
+const OWN_SESSION_SKIP = new Set(["node_modules", ".git", "removals"]);
+const OWN_SESSION_MAX_DEPTH = 12;
+const SESSION_UUID = /^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+
 const PLAN_MAX_AGE_MS = 30 * 60_000;
 const SCAN_BUDGET_MS = 20_000;
 const SYSTEM_PREFIXES = [
@@ -295,6 +340,215 @@ function judge(path: string, protection: Protection, open: string[]): Candidate
     return { path, ino: st.ino, bytes: tree.bytes, newest: tree.newest };
 }
 
+function childNames(path: string): string[] | null {
+    try {
+        return readdirSync(path);
+    } catch {
+        return null;
+    }
+}
+
+/** True when every file of the tree is a module-cache file and at least one is a compiled module. */
+function isModuleCache(path: string): boolean {
+    const deadline = Date.now() + SCAN_BUDGET_MS;
+    const stack = [path];
+    let modules = 0;
+
+    while (stack.length) {
+        if (Date.now() > deadline) {
+            return false;
+        }
+
+        const p = stack.pop() as string;
+        const st = lstatSync(p, { throwIfNoEntry: false });
+
+        if (!st || st.isSymbolicLink()) {
+            return false;
+        }
+
+        if (st.isDirectory()) {
+            const names = childNames(p);
+
+            if (!names) {
+                return false;
+            }
+
+            stack.push(...names.map((name) => join(p, name)));
+            continue;
+        }
+
+        if (!st.isFile() || !MODULE_CACHE_FILES.some((ext) => p.endsWith(ext))) {
+            return false;
+        }
+
+        if (p.endsWith(".pcm") || p.endsWith(".swiftmodule")) {
+            modules++;
+        }
+    }
+
+    return modules > 0;
+}
+
+/** Which kind of regenerable build output a folder is, or null when it is anything else. */
+export function buildOutputKind(path: string): BuildOutputKind | null {
+    const st = lstatSync(path, { throwIfNoEntry: false });
+
+    if (!st?.isDirectory() || st.isSymbolicLink()) {
+        return null;
+    }
+
+    const name = basename(path);
+
+    if (SWIFTPM_TRIPLES.has(name)) {
+        return "swiftpm-triple";
+    }
+
+    const names = childNames(path) ?? [];
+
+    if (
+        names.length > 0 &&
+        names.every((child) => SWIFTPM_SCRATCH_ENTRIES.has(child)) &&
+        (name === ".build" || names.includes("workspace-state.json") || names.some((n) => SWIFTPM_TRIPLES.has(n)))
+    ) {
+        return "swiftpm-scratch";
+    }
+
+    if (names.some((child) => MODULE_CACHE_MARKERS.some((m) => child.endsWith(m))) && isModuleCache(path)) {
+        return "module-cache";
+    }
+
+    return null;
+}
+
+/** The scratch folders of one session: every `<ccRoot>/<project>/<session uuid>` that is a real folder. */
+export function ownSessionDirs(id: string, ccRoot: string): string[] {
+    if (!SESSION_UUID.test(id)) {
+        throw new Error(`--own-session needs the full session uuid, got ${SafeJSON.stringify(id)}`);
+    }
+
+    return (childNames(ccRoot) ?? [])
+        .map((project) => join(ccRoot, project, id))
+        .filter((dir) => {
+            const st = lstatSync(dir, { throwIfNoEntry: false });
+            return Boolean(st?.isDirectory() && !st.isSymbolicLink());
+        });
+}
+
+/**
+ * The build output inside one session folder. A SwiftPM scratch folder whose tree the guards refuse (its
+ * `checkouts/` are git clones) is not listed whole; its triple folders below it are.
+ */
+export function ownBuildOutput(sessionDir: string): string[] {
+    const out: string[] = [];
+    const rootDev = lstatSync(sessionDir).dev;
+    const stack: Array<{ dir: string; depth: number }> = [{ dir: sessionDir, depth: 0 }];
+
+    while (stack.length) {
+        const { dir, depth } = stack.pop() as { dir: string; depth: number };
+
+        for (const name of childNames(dir) ?? []) {
+            const path = join(dir, name);
+            const st = lstatSync(path, { throwIfNoEntry: false });
+
+            if (!st?.isDirectory() || st.isSymbolicLink() || OWN_SESSION_SKIP.has(name)) {
+                continue;
+            }
+
+            const kind = buildOutputKind(path);
+
+            if (kind === "swiftpm-scratch" && "refuse" in scan(path, rootDev)) {
+                stack.push({ dir: path, depth: depth + 1 });
+                continue;
+            }
+
+            if (kind) {
+                out.push(path);
+                continue;
+            }
+
+            if (depth < OWN_SESSION_MAX_DEPTH) {
+                stack.push({ dir: path, depth: depth + 1 });
+            }
+        }
+    }
+
+    return out.sort();
+}
+
+/** The guards for one entry of an own-session plan; the live-session guard is the one it leaves out. */
+export function judgeOwn(
+    path: string,
+    options: { sessionDirs: string[]; open: string[]; minAgeMinutes: number }
+): Candidate | string {
+    const st = lstatSync(path, { throwIfNoEntry: false });
+
+    if (!st) {
+        return "gone";
+    }
+
+    if (st.isSymbolicLink()) {
+        return "symlink";
+    }
+
+    if (st.uid !== uid) {
+        return "other-user";
+    }
+
+    const real = realpathSync(path);
+    const sessionDir = options.sessionDirs
+        .filter((dir) => existsSync(dir))
+        .map((dir) => realpathSync(dir))
+        .find((dir) => real.startsWith(`${dir}/`));
+
+    if (!sessionDir) {
+        return "outside-session";
+    }
+
+    if (
+        relative(sessionDir, real)
+            .split("/")
+            .some((part) => OWN_SESSION_SKIP.has(part))
+    ) {
+        return "skipped-folder";
+    }
+
+    const kind = buildOutputKind(path);
+
+    if (!kind) {
+        return "not-build-output";
+    }
+
+    if (options.open.some((o) => o === path || o.startsWith(`${path}/`) || o === real || o.startsWith(`${real}/`))) {
+        return "open-file";
+    }
+
+    const tree = scan(path, lstatSync(sessionDir).dev);
+
+    if ("refuse" in tree) {
+        return tree.refuse;
+    }
+
+    if (Date.now() - tree.newest < options.minAgeMinutes * 60_000) {
+        return "recent";
+    }
+
+    return { path, ino: st.ino, bytes: tree.bytes, newest: tree.newest };
+}
+
+/** The session folder an own-session entry sits in (canonical paths only): its quarantine goes there, on one volume. */
+function ownRoot(path: string, sessionDirs: string[]): string | null {
+    if (typeof path !== "string" || resolve(path) !== path || realpathSync(path) !== path) {
+        return null;
+    }
+
+    return (
+        sessionDirs
+            .filter((dir) => existsSync(dir))
+            .map((dir) => realpathSync(dir))
+            .find((dir) => path.startsWith(`${dir}/`)) ?? null
+    );
+}
+
 /** Only canonical paths (realpath equal, so no symlink anywhere in them) with the planner's shapes may be reclaimed. */
 function candidateRoot(path: string): string | null {
     if (typeof path !== "string" || resolve(path) !== path) {
@@ -348,7 +602,62 @@ function entries(): string[] {
 
 const gb = (bytes: number) => `${(bytes / 1e9).toFixed(2)} GB`;
 
+function ownSessionDryRun(id: string): void {
+    const minAgeMinutes = Number(flag("--min-age-minutes") ?? 10);
+
+    if (!Number.isFinite(minAgeMinutes) || minAgeMinutes < 1) {
+        console.error("✖ --min-age-minutes must be at least 1");
+        process.exit(2);
+    }
+
+    const dirs = ownSessionDirs(id, join(roots[0] ?? "/tmp", "cc"));
+
+    if (dirs.length === 0) {
+        console.error(`✖ no /tmp/cc/<project>/${id} folder`);
+        process.exit(2);
+    }
+
+    const open = openPaths();
+    const candidates: Candidate[] = [];
+    const skipped: Record<string, number> = {};
+
+    for (const path of dirs.flatMap((dir) => ownBuildOutput(dir))) {
+        const verdict = judgeOwn(path, { sessionDirs: dirs, open, minAgeMinutes });
+
+        if (typeof verdict === "string") {
+            skipped[verdict] = (skipped[verdict] ?? 0) + 1;
+        } else {
+            candidates.push(verdict);
+        }
+    }
+
+    candidates.sort((a, b) => b.bytes - a.bytes);
+
+    for (const c of candidates.slice(0, 40)) {
+        const age = ((Date.now() - c.newest) / 60_000).toFixed(0);
+        console.log(`${(c.bytes / 1e6).toFixed(0).padStart(7)} MB  ${age.padStart(6)} min  ${c.path}`);
+    }
+
+    const total = candidates.reduce((sum, c) => sum + c.bytes, 0);
+    const planDir = runDir ? join(runDir, "logs") : join(roots[0] ?? "/tmp", "cc");
+    mkdirSync(planDir, { recursive: true });
+    const planPath = join(planDir, `tmp-reclaim-plan-${Date.now()}.json`);
+    const plan: Plan = { createdAt: Date.now(), minAgeHours: 0, candidates, ownSession: { id, dirs, minAgeMinutes } };
+    writeFileSync(planPath, SafeJSON.stringify(plan, null, 2));
+    console.log(
+        `${candidates.length} build-output candidates of session ${id}, ${gb(total)}; skipped ${SafeJSON.stringify(skipped)}`
+    );
+    console.log(`plan: ${planPath}\napply it within 30 minutes: bun tmp-reclaim.ts --apply --plan ${planPath}`);
+    process.exit(0);
+}
+
 function main(): void {
+    const ownSession = flag("--own-session");
+
+    if (!has("--apply") && ownSession) {
+        ownSessionDryRun(ownSession);
+    }
+
     if (!has("--apply")) {
         const protection = protectedEntries();
         const open = openPaths();
@@ -409,7 +718,10 @@ function main(): void {
     // The dry run decided with its own threshold; the re-check uses the same one.
     minAgeHours = validAge(plan.minAgeHours, "plan.minAgeHours");
 
-    const protection = protectedEntries();
+    const own = plan.ownSession;
+    // An own-session plan is re-checked by judgeOwn, which needs no live-session list (that scan reads every
+    // agent's transcript folders).
+    const protection = own ? null : protectedEntries();
     const open = openPaths();
     let freed = 0;
     let removed = 0;
@@ -421,7 +733,7 @@ function main(): void {
         for (const planned of plan.candidates) {
             let root: string | null = null;
             try {
-                root = candidateRoot(planned.path);
+                root = own ? ownRoot(planned.path, own.dirs) : candidateRoot(planned.path);
             } catch {
                 // A vanished or unreadable path is no longer a candidate either.
             }
@@ -431,7 +743,9 @@ function main(): void {
                 continue;
             }
 
-            const now = judge(planned.path, protection, open);
+            const now = own
+                ? judgeOwn(planned.path, { sessionDirs: own.dirs, open, minAgeMinutes: own.minAgeMinutes })
+                : judge(planned.path, protection ?? protectedEntries(), open);
 
             if (typeof now === "string" || now.ino !== planned.ino) {
                 const why = typeof now === "string" ? now : "replaced";

From aa7bc0f4bee21c6dbc47611ed39dd2181af2b763 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Sun, 18 Oct 2026 20:46:58 +0200
Subject: [PATCH 03/30] docs(skills, babysit): Martin's 2026-10-18 rules: round
 3 fixes only cheap or same-class Medium and Low, confirmation only for
 self-spawned workers, Swift suite before ready, tmp-reclaim without asking

---
 .claude/skills/babysit/SKILL.md               | 155 ++++++++++++------
 .../babysit/references/brief-self-fetch.md    |   5 +
 .../babysit/references/brief-template.md      |   9 +-
 .claude/skills/babysit/scripts/policy.ts      |  12 +-
 .../skills/babysit/scripts/scripts.test.ts    | 135 ++++++++++++++-
 5 files changed, 256 insertions(+), 60 deletions(-)

diff --git a/.claude/skills/babysit/SKILL.md b/.claude/skills/babysit/SKILL.md
index 59441a3552..7fdcbb36fb 100644
--- a/.claude/skills/babysit/SKILL.md
+++ b/.claude/skills/babysit/SKILL.md
@@ -29,6 +29,21 @@ Invoke, with the Skill tool, before any other step:
 These skills own their mechanics; this file only says how they fit together. When they disagree with this file,
 they win for their own mechanics, and you say so in the report.
 
+## 0a. Start of every run: the checklist
+
+Do all of these before the first dispatch, in this order:
+
+1. The skills of step 0 are loaded.
+2. 🛑 **Disk alarm:** `bun .claude/skills/babysit/scripts/df-watch.ts --below-gb 5` with Bash `run_in_background`. It
+   exits, and so wakes you, only when free space drops below 5 GB. When it fires, run step 7c's `tmp-reclaim.ts` at
+   once and start the alarm again; never wait for the user (2026-10-18: the disk sat full three times while the lead
+   waited for the user, although this script and Martin's standing permission existed).
+3. The run card (step 1) and the mode (step 2).
+4. The plan confirmation for the workers you spawn yourself (step 2).
+5. The owner check of every PR (step 3.1).
+6. Decisions: every ❓ DECISION of the run goes into the decision log under its chat number and into the chat, and
+   gets a `decision` event in the run ledger (review-loop, "Decisions during a loop"). A later mention is a link.
+
 ## 1. The run card: what to configure
 
 Write it to `/tmp/cc/<project>/<session>/babysit/run.json` at the start; the scripts read it.
@@ -71,9 +86,12 @@ above 10 GB after all worker worktrees, else `unified`.
   cherry-picks onto the PR branch in a scratch worktree, and a file that unified changed later than the PR branch
   conflicts (#511's import list did). Use it only when disk is short.
 
-🛑 **Confirmation period (from 2026-10-14 until Martin says he no longer needs it):** before you dispatch, show the
-plan with AskUserQuestion and wait: the PRs, the worker per PR, the mode with the free-disk numbers, `post`, and
-the stop point. After the confirmation period, state the plan in one line and proceed.
+🛑 **Plan confirmation for the workers you spawn yourself** (Martin, 2026-10-18; it narrows the confirmation period
+that started 2026-10-14). Before you dispatch a worker that YOU decided to spawn, show the plan with
+AskUserQuestion and wait: the PRs, the worker per PR, the mode with the free-disk numbers, `post`, and the stop
+point. A session the user assigns to you (he names it, or another session hands it over on his word) needs no
+confirmation: state the plan in one line and proceed. (2026-10-18: the lead dispatched self-spawned workers with no
+confirmation.)
 
 ## 3. Prepare each PR
 
@@ -90,30 +108,29 @@ the stop point. After the confirmation period, state the plan in one line and pr
    the hidden channels, `expand` every thread (the L1 table can scramble files). Keep each thread's `threadId`.
 4. Read the source at every cited line before you brief: a stale or wrong finding is briefed as such, so the worker
    does not "fix" it.
-5. **Round policy** (Martin, 2026-10-17 12:16; it replaces "fix every finding in every round", because eve opened
-   new Medium and Low findings on every push of #536 for 28 rounds). The executable rule is `scripts/policy.ts`;
-   `fill-brief.ts` derives it from the round, GitHub's changed-file count and `--dedicated-review`. Both brief
-   templates and judging use that generated policy. Count the PR's fix rounds; a follow-up PR starts at round 1.
-   - A PR with more than 100 changed files: rounds 1 to 3 fix every valid finding, Medium and Low included. From
-     round 4, fix only Critical and High.
-   - A PR with 100 changed files or fewer: rounds 1 and 2 fix every valid finding. From round 3, fix only Critical
-     and High.
-   - In the rounds that fix only Critical and High, a Medium or Low finding gets a reply (valid or not, and why).
-     It is not fixed in that PR, and its thread stays OPEN: resolve only a thread that was acted on (fixed, or
-     rejected with a cited file:line). Record a policy deferral with the reply transport's supported
-     `"verdict": "belongs-elsewhere"` and explain the policy in the reply; do not add unsupported schema fields. `integrate.ts` keeps it in the summary but partitions it into a separate
-     `post-replies.ts --no-resolve` batch, never the batch that resolves threads (Martin, 2026-10-17 12:45).
-   - **A valid security finding is always fixed**, at any severity and in any round (Martin, 2026-10-17 12:45:
-     "security valid always"). Read the reviewer's category (`🔒 Security`), not only its severity.
+5. **Round policy**: review-loop's "Round policy" section is the source; this is its short form (Martin,
+   2026-10-18). The executable rule is `scripts/policy.ts`; `fill-brief.ts` derives it from the round, GitHub's
+   changed-file count and `--dedicated-review`, and both brief templates and judging use that generated policy.
+   Count the fix rounds of the PR; a follow-up PR starts again at round 1.
+   - Rounds 1 and 2 fix every valid finding, Medium and Low included, whatever the PR's size. No deferral, and every
+     file a valid fix needs is in scope. A `no-change` or rejection needs a cited file:line that proves the finding
+     wrong.
+   - Round 3 and later fix every valid Critical and High. A Medium or Low is fixed only when it is cheap (about 20
+     changed lines) or the same class as an earlier round's fix; every other one gets a reply (valid or not, and why
+     it waits) and its thread stays OPEN: resolve only a thread that was acted on. Record such a deferral with the
+     reply transport's `"verdict": "belongs-elsewhere"` and explain the policy in the reply; `integrate.ts` keeps it
+     in the summary but posts it in a separate `post-replies.ts --no-resolve` batch, never the batch that resolves
+     threads (Martin, 2026-10-17 12:45). (2026-10-18: a lead fixed a Low in round 3 with neither reason.)
+   - **A valid security finding is always fixed**, at any severity and in any round. Read the reviewer's category
+     (`🔒 Security`), not only its severity.
    - **A dedicated code review the user asks for** (an independent worker review such as `review-brief.ts` on Astra
-     or Sol) is fixed in full: every valid finding, Medium and Low included, whatever round the PR is in. Fix it
-     yourself or steer the PR's fixing worker, then judge it as any round (Martin, 2026-10-17 13:05).
-   - Inside the fix-everything rounds, a deferral is not accepted ("nothing is a follow up or out of scope", Martin,
-     2026-10-17), and every file a valid fix needs is in scope. A `no-change` or rejection needs a cited file:line
-     that proves the finding wrong.
+     or Sol) is fixed in full, whatever round the PR is in. Fix it yourself or steer the PR's fixing worker, then
+     judge it as any round (Martin, 2026-10-17 13:05).
    - **Merge bar:** when the last round's Critical and High findings are fixed and judged, merge without waiting
-     for eve to review that last fix. The PR still needs at least one CodeRabbit review, green CI and a reply on
-     every thread.
+     for eve to review that last fix (eve's degraded pass counts as a review). A PR over about 50 changed files
+     still needs at least one CodeRabbit review, asked through review-loop's `scripts/cr-queue.ts`; a smaller PR may
+     land on eve's review. Green CI, and a reply on every Critical, Major, High, Security, refused and deferred
+     thread (review-loop step 5a).
 6. Scope: `git fetch origin <pr branch>`, then `bun .claude/skills/babysit/scripts/pr-scope.ts <N> --compare HEAD`.
    It lists the PR's files, the test file of each one (a sibling `.test.ts`, or a neighbour test that imports it),
    and whether unified differs from the PR branch per file. That list is the starting context, not a scope limit.
@@ -212,7 +229,7 @@ Three Monitors, all with `timeout_ms: 1800000`, each re-armed as the very next t
    approving it.
 
 Two-way proof: once per new worker, send a ping on the bus (`--to grok_pr<N>` or `--to codex_<name>`) and see the
-reply arrive (Sol answered in 20 s, Grok in 59 s). During the confirmation period do it for every worker.
+reply arrive (Sol answered in 20 s, Grok in 59 s). Do it for every worker you spawn yourself.
 
 Waiting on a Codex turn: `bun .claude/skills/babysit/scripts/wait-turn.ts --run <dir> --worker <name> --thread <id>
 --pr <N> --round <R>` with Bash `run_in_background`; the harness wakes the lead when the turn ends, and the worker's
@@ -249,11 +266,18 @@ PR: VERIFIED, VERIFIED WITH CAVEATS, or REFUTED, with evidence.
 
 Judge against the same derived round policy from `scripts/policy.ts` that `fill-brief.ts` put in the brief.
 Every required finding is fixed in its PR before the push; a valid security finding and every valid finding in a
-dedicated user review are always required, including Medium and Low. Other Medium/Low findings deferred by the
-ordinary later-round policy get explained replies and remain OPEN. Verify that integrate partitions those replies
-into its no-resolve batch. If a required fix needs a file outside the original diff, change it in this PR and explain
-it in the reply; scope never excuses a required fix. A Swift change the worker could not run is not judged until the
-lead ran its tests: `swift-typecheck.ts` proves it compiles, and #501 round 2 typechecked clean yet broke a test.
+dedicated user review are always required. In rounds 1 and 2 that is every valid finding, and a deferral is not
+accepted. Medium/Low findings deferred by the later-round policy get explained replies and remain OPEN; verify that
+integrate partitions those replies into its no-resolve batch. If a required fix needs a file outside the original
+diff, change it in this PR and explain it in the reply; scope never excuses a required fix. A Swift change the worker
+could not run is not judged until the lead ran its tests through `swift-slot.ts`: `swift-typecheck.ts` proves it
+compiles, and #501 round 2 typechecked clean yet broke a test.
+
+🛑 **Swift and "ready".** CI runs no Swift. A PR that changes Swift is prepared for merge only after a local run of the
+FULL Swift suite of every package it changes, at the PR's final head, with the result written into the PR (the
+commands, the head SHA, the test count, the exit code; a round summary's "Also in this push" line or a PR comment).
+Add `src/macos/GenesisTools` (`--disable-build-manifest-caching`) when GenesisKit changed. A filtered judge run is
+not the suite (Martin, 2026-10-18; that night Swift PRs were called ready before their suites reran).
 
 ## 7. Correct, integrate, push
 
@@ -305,11 +329,17 @@ Off unless the user approves it in their own words for this run ("drive the PRs
 only for PRs the run owns: never another session's PR, never the integration branch. Ask once, early, and keep
 running review rounds while the question is open: a missing answer never blocks a round, it only means no merge.
 
-A PR lands when all hold: at least 3 review rounds done; every finding required by the derived policy is fixed
-and judged (including every valid security finding and all dedicated-review findings); at least one CodeRabbit
-review; a reply on every thread; CI green on the landing tree; its base is master or a parent the run merges first
-(a PR stacked on another session's branch waits for that branch). Merge without waiting for eve to review the last
-judged fix. Policy-deferred Medium/Low threads may remain OPEN. Then the review-loop landing recipe, which
+A PR lands when all hold: review-loop step 5a ("Before you call a PR ready") passes; at least 3 review rounds done;
+every finding required by the derived policy is fixed and judged (every valid security finding and all
+dedicated-review findings included), so no critical or high finding is open; eve reviewed the head before the last
+fix (the merge bar, step 3.5); a PR over about 50 files has a CodeRabbit review; a reply on every thread; CI green
+on the landing tree; its base is master or a parent the run merges first (a PR stacked on another session's branch
+waits for that branch). Merge without waiting for eve to review the last judged fix. Policy-deferred Medium/Low
+threads may remain OPEN. In an unattended land-it job a red CI, an open
+Critical or High, a conflict or a failing test is the next task, never a reason to park the PR with a note (Martin,
+2026-10-05: "you just resolve the issues and iterate until ur able to drive it to master"); keep the guardrails
+(`tools github merge` only, no bypassed check, no paid CodeRabbit usage). Then the review-loop landing recipe (its
+file-set check for a recommitted stacked branch included), which
 `bun .claude/skills/babysit/scripts/land.ts --run <dir> --pr <N> --merge` runs as one command (without `--merge` it
 only prepares and prints the squash; every git call is an argument array, because a hand-typed
 `--force-with-lease=$B:c1a…` in zsh read `:c` as a modifier and pushed without the lease):
@@ -330,7 +360,8 @@ only prepares and prints the squash; every git call is an argument array, becaus
 3. `git fetch origin <branch>` in the main checkout (`tools github merge` compares against the local remote ref and
    refuses a "moved" branch otherwise), then `tools github merge --rebase <N>`. Stacks merge bottom-up; the tool
    retargets dependents.
-4. Log a `note` event with the merge SHA, and list every PR that did not land with its reason in the report.
+4. Check `gh pr view <N> --json state`: a restacked merge can leave the PR OPEN (#501, 2026-10-15). Log a `note`
+   event with the merge SHA, and list every PR that did not land with its reason in the report.
 
 A PR that conflicts with master, or whose parent was just squash-merged, is restacked first:
 `bun .claude/skills/babysit/scripts/restack.ts --wt <worktree> --onto origin/master [--upstream <fork point>]`. It runs
@@ -344,11 +375,14 @@ code: rerun CI and judge it before the merge; eve need not re-review the last ju
 CodeRabbit review and a reply on every thread. When the restack carries a fix round too, push it with
 `integrate.ts … --restacked-from <old head>`: the lease is that old head, and the gates check only the PR's own commits.
 
-## 7c. Disk: watch it, reclaim /tmp safely
+## 7c. Disk: watch it, reclaim /tmp yourself
 
-A night of worktrees, Swift builds and test runs fills a disk. Start `bun .claude/skills/babysit/scripts/df-watch.ts
---below-gb 5` with Bash `run_in_background` at the start of a run: it exits (and wakes you) only when free space drops
-below the threshold. Then, and only with the user's standing permission for /tmp cleanup:
+A night of worktrees, Swift builds and test runs fills a disk. `df-watch.ts --below-gb 5` runs from the start of
+every run (step 0a.2). When it fires, or whenever free disk is low, reclaim at once with the steps below. Do not wait
+for the user and do not ask: Martin gave the standing permission on 2026-10-18 (an agent may reclaim its own
+session scratch and its own build output, and `tmp-reclaim.ts` is the sanctioned way to delete in /tmp, not `rm`).
+On 2026-10-18 the disk sat full three times while the lead waited for him, and the lead's own session folder held
+14 GB, most of it SwiftPM scratch builds.
 
 1. `bun .claude/skills/babysit/scripts/tmp-reclaim.ts --run <dir>` (dry run): lists the candidates in /tmp, $TMPDIR and
    each `/tmp/cc/<project>/<session>` folder, writes a plan file, deletes nothing. It skips live sessions (any agent
@@ -359,8 +393,25 @@ below the threshold. Then, and only with the user's standing permission for /tmp
    inode, still old, still closed), moved into a scratch folder in the same root and deleted there. The result is a
    `note` in the run ledger.
 
-Never delete a worktree this way (it refuses `.git` anyway): worktrees go through step 8's release. Machine caches
-outside /tmp (uv, SwiftPM, a repo's `.build`) are a separate, user-approved decision, not this script's.
+Limits you must know:
+
+- The plain dry run never picks a LIVE session's folder, and that includes your own. For your own session run a
+  second dry run with `--own-session <your session uuid>` (then `--apply --plan <file>` as above): it lists BUILD
+  OUTPUT only inside `/tmp/cc/<project>/<that session>/`, even though the session is live. That is SwiftPM triple
+  folders (`arm64-apple-macosx`, `x86_64-apple-macosx`), SwiftPM scratch folders that hold only SwiftPM's own
+  entries, and Swift or clang module caches (only `.pcm`, `.swiftmodule` and their stamp files). It never lists
+  notes, logs, reply files, patches, briefs, `node_modules` or `removals/`, and it keeps the other guards (no open
+  file, socket, FIFO or `.git` inside; not changed in the last `--min-age-minutes`, default 10; the same inode and
+  the same build-output class again at apply). Measured 2026-10-18 on this run's lead session: 38 candidates,
+  10.55 GB. Worker and scratch worktrees still go through step 8's release, and review clones through review-loop's
+  `scripts/cleanup.ts`.
+- Never delete a worktree this way (it refuses `.git` anyway): worktrees go through step 8's release.
+- Machine caches outside /tmp (uv, SwiftPM, a repo's `.build`) are a separate, user-approved decision, not this
+  script's.
+- 🛑 Never copy a SwiftPM `.build/` folder for a bench or an A/B: build and measure in the checkout's real `.build`,
+  and for a before and after use two worktrees that already exist (Martin, 2026-10-07; four copies cost 3.5 GB on a
+  full disk, 2026-10-06, when the session folder had grown to 3.8 GB).
+- Check `du -sh /tmp/cc/<project>/<session>` before the final report.
 
 ## 8. Clean up after every round, automatically
 
@@ -397,16 +448,22 @@ everything that arrived after a merge; it exits 1 while any of those needs work.
 follow-up commit on a branch from master, with a reply on the thread naming it. Never write "every thread answered" or
 "clean at merge" without a fresh exit 0, or a list of what is still open.
 
-A CodeRabbit thread that WE resolved without a reply is not a gap: post-replies resolves a fixed CodeRabbit thread
-silently on purpose, because a thread reply spends CodeRabbit's hourly chat budget, and the round summary comment
-carries the answer. The audit counts those apart ("resolved by us with the answer in the round summary"). Answer by
-hand only a thread the reviewer resolved itself with no answer anywhere (2026-10-14: five #515 threads were answered
-by hand for nothing).
+Thread replies follow review-loop's "Thread replies by severity" (Martin, 2026-10-18): every Critical, Major, High
+and Security thread gets our reply on the thread, from any reviewer, CodeRabbit included (every reply item carries
+the required `severity`, and post-replies posts the CodeRabbit ones of those severities); so does every refusal and
+deferral. A fixed Medium or Low CodeRabbit
+thread that WE resolved without a reply is not a gap and needs no backfill: post-replies resolves it silently on
+purpose, because a thread reply spends CodeRabbit's hourly chat budget, and the round summary comment carries the
+answer. The audit counts those apart ("resolved by us with the answer in the round summary"). Answer by hand only a
+thread the reviewer resolved itself with no answer anywhere (2026-10-14: five #515 threads were answered by hand for
+nothing). (2026-10-18: Critical and High CodeRabbit threads were resolved with no reply.)
+
+Before the word "ready" goes into any report, run review-loop step 5a ("Before you call a PR ready") for each PR.
 
 ## 10. Bugs in the harness: fix them, after the user confirms
 
 A defect in handoff-to, agents-talk, `tools codex`, `tools grok`, `tools claude worker` or `tools agents` that broke a
 step, cost real time, or reported something false: describe it in one line with the proposed fix and ask the user
-(AskUserQuestion) before you change anything. On yes: fix on unified with a test, then cherry-pick onto the open PR
+(AskUserQuestion, and post it to the decision log under its chat number, step 0a.6) before you change anything. On yes: fix on unified with a test, then cherry-pick onto the open PR
 that owns that code (on 2026-10-14 that was #509 for Codex). Do not nitpick: wording, cosmetics and one-off quirks go
 into the report's "what to change" list, not into a fix.
diff --git a/.claude/skills/babysit/references/brief-self-fetch.md b/.claude/skills/babysit/references/brief-self-fetch.md
index b4b42f4633..db65f26c83 100644
--- a/.claude/skills/babysit/references/brief-self-fetch.md
+++ b/.claude/skills/babysit/references/brief-self-fetch.md
@@ -37,6 +37,10 @@ reruns your checks, and pushes. Quality is judged, not speed.
    (name the commit), or `no-change` (only when a cited file:line proves the finding wrong). For valid findings deferred
    by the derived policy, use `belongs-elsewhere` (the reply schema's deferral verdict), explain the policy, and keep
    the thread OPEN. Do not add fields the installed reply schema does not support.
+   Give every item its `severity`, the reviewer's label lower-cased: `critical`, `major`, `high`, `security`,
+   `medium`, `minor` or `low` (a security finding is `security` at any level; CodeRabbit's Trivial or Nitpick is
+   `low`). The file is refused without it, and critical, major, high and security threads get a reply on the
+   thread.
 2. Fix the valid findings selected by the derived round policy at the root. Respect each module's documented contracts and its callers. Add or extend a test
    that fails without the fix, in an existing test file next to the code. Do not create a new test file unless the
    code has none.
@@ -68,6 +72,7 @@ finding, including rejected ones:
       "where": "<file>:<line>",
       "title": "<one-line title of the defect>",
       "context": "<what was flagged and why it matters>",
+      "severity": "<critical | major | high | security | medium | minor | low>",
       "verdict": "fixed",
       "commits": ["<your commit, 9-char short SHA>"],
       "codeBefore": { "lang": "ts", "code": "<1 to 8 lines>" },
diff --git a/.claude/skills/babysit/references/brief-template.md b/.claude/skills/babysit/references/brief-template.md
index ddcf7e3296..daffff3fda 100644
--- a/.claude/skills/babysit/references/brief-template.md
+++ b/.claude/skills/babysit/references/brief-template.md
@@ -54,9 +54,11 @@ Codex variant:
 
 1. For each finding, read the current source at the cited lines BEFORE you judge it. A finding is a claim with a
    timestamp, not a fact. One verdict per finding: `fixed`, `rejected` (cite the file:line that disproves it),
-   `already-done`, or `no-change` (only when a cited file:line proves the finding wrong). A valid finding deferred
-   by the derived policy uses `belongs-elsewhere` (the reply schema's deferral verdict), an explained reply, and an
-   OPEN thread. Do not add fields the installed reply schema does not support.
+   `already-done`, or `no-change` (only when a cited file:line proves the finding wrong). Give every item its
+   `severity`, the reviewer's label lower-cased (`critical`, `major`, `high`, `security`, `medium`, `minor`, `low`;
+   security at any level is `security`, CodeRabbit's Trivial or Nitpick is `low`); the file is refused without it.
+   A valid finding deferred by the derived policy uses `belongs-elsewhere` (the reply schema's deferral verdict), an
+   explained reply, and an OPEN thread. Do not add fields the installed reply schema does not support.
 2. Fix the valid findings selected by the derived round policy at the root, and respect the module's documented contracts (what a function promises to throw
    or return) and its callers. Add or extend a test that fails without the fix, in the test files listed above. Do
    NOT create a new test file.
@@ -85,6 +87,7 @@ Codex variant:
          "where": "<file>:<line>",
          "title": "<one-line title of the defect>",
          "context": "<what was flagged and why it matters>",
+         "severity": "<critical | major | high | security | medium | minor | low>",
          "verdict": "fixed",
          "commits": ["<your commit, 9-char short SHA>"],
          "codeBefore": { "lang": "ts", "code": "<1 to 8 lines before>" },
diff --git a/.claude/skills/babysit/scripts/policy.ts b/.claude/skills/babysit/scripts/policy.ts
index d81b2543f7..d5160e2e28 100644
--- a/.claude/skills/babysit/scripts/policy.ts
+++ b/.claude/skills/babysit/scripts/policy.ts
@@ -1,14 +1,20 @@
-/** One policy for generated worker briefs, judging and reply disposition. Dedicated user reviews are fixed in full. */
+/**
+ * One policy for generated worker briefs, judging and reply disposition (review-loop "Round policy", Martin,
+ * 2026-10-18): rounds 1 and 2 fix every valid finding whatever the PR's size; later rounds fix Critical, High and
+ * security, plus a Medium or Low that is cheap or of an earlier fix's class. Dedicated user reviews are fixed in full.
+ */
 export function roundPolicy(options: { round: number; changedFiles: number; dedicatedReview?: boolean }) {
     const { round, changedFiles, dedicatedReview = false } = options;
     if (!Number.isSafeInteger(round) || round < 1 || !Number.isSafeInteger(changedFiles) || changedFiles < 0) {
         throw new Error("round and changed-file count must be finite integers (round >= 1, files >= 0)");
     }
-    const throughRound = changedFiles > 100 ? 3 : 2;
+    const throughRound = 2;
     const fixAll = dedicatedReview || round <= throughRound;
     const text = [
         `Round ${round} (${changedFiles} changed files${dedicatedReview ? ", dedicated user review" : ""}): ` +
-            (fixAll ? "fix EVERY valid finding, critical, high, medium and low." : "fix Critical and High findings."),
+            (fixAll
+                ? "fix EVERY valid finding, critical, high, medium and low."
+                : "fix Critical and High findings, and a valid Medium or Low only when the fix is cheap (about 20 changed lines) or the same class as an earlier round's fix."),
         "A valid security finding is always fixed, at any severity and in any round; use the reviewer's Security category.",
         fixAll
             ? "Fix every valid finding in this PR, including every file it needs; no deferral is accepted."
diff --git a/.claude/skills/babysit/scripts/scripts.test.ts b/.claude/skills/babysit/scripts/scripts.test.ts
index 1e91f603ed..7ac377fea8 100644
--- a/.claude/skills/babysit/scripts/scripts.test.ts
+++ b/.claude/skills/babysit/scripts/scripts.test.ts
@@ -30,7 +30,7 @@ import { reviewBrief } from "./review-brief";
 import { loadRun, runPaths } from "./run";
 import { trySwiftSlot } from "./swift-slot";
 import { parseSwiftTargets, typecheckPackage } from "./swift-typecheck";
-import { openPaths } from "./tmp-reclaim";
+import { buildOutputKind, judgeOwn, openPaths, ownBuildOutput, ownSessionDirs } from "./tmp-reclaim";
 import {
     conflictedFiles,
     higherVersionSide,
@@ -1450,7 +1450,7 @@ describe("round 5 carried findings", () => {
     });
 });
 
-test("generated worker briefs follow the size, round and dedicated-review policy", () => {
+test("generated worker briefs follow the round and dedicated-review policy", () => {
     const dir = fs.mkdtempSync(join(tmpdir(), "babysit-policy-"));
     const preload = join(dir, "github-fixture.ts");
     fs.writeFileSync(join(dir, "run.json"), SafeJSON.stringify({ repo: "fixture/repo", main: dir }));
@@ -1475,7 +1475,7 @@ test("generated worker briefs follow the size, round and dedicated-review policy
         [63, 1, false, true],
         [63, 2, false, true],
         [63, 3, false, false],
-        [120, 3, false, true],
+        [120, 3, false, false],
         [120, 4, false, false],
         [120, 32, true, true],
     ] as const) {
@@ -1513,6 +1513,7 @@ test("generated worker briefs follow the size, round and dedicated-review policy
         expect(brief).toContain("A valid security finding is always fixed");
         expect(brief).toContain("Change every file the fix needs in this PR");
         if (!all) {
+            expect(brief).toContain("about 20 changed lines");
             expect(brief).toContain("deferred");
             expect(brief).toContain("OPEN");
             expect(brief).not.toContain("never defer");
@@ -4151,7 +4152,7 @@ describe("round 22 external Swift products", () => {
         });
         try {
             for (const [manifest, expected] of [
-                ["src/macos/GenesisTools/Package.swift", ["GenesisTools", "GenesisToolsTests"]],
+                ["src/macos/GenesisTools/Package.swift", ["GenesisToolsHost", "GenesisTools", "GenesisToolsTests"]],
                 ["src/macos/GenesisWidgetPreview/Package.swift", ["GenesisWidgetPreview"]],
             ] as const) {
                 const text = fs.readFileSync(join(import.meta.dir, "../../../..", manifest), "utf8");
@@ -4973,7 +4974,9 @@ describe("round 32 policy and landing routing", () => {
             true
         );
         expect(roundPolicy({ round: 3, changedFiles: 100 }).fixAll).toBe(false);
-        expect(roundPolicy({ round: 3, changedFiles: 101 }).fixAll).toBe(true);
+        // One rule for every size since 2026-10-18: a PR over 100 files no longer gets a third fix-everything round.
+        expect(roundPolicy({ round: 3, changedFiles: 101 }).fixAll).toBe(false);
+        expect(roundPolicy({ round: 2, changedFiles: 101 }).fixAll).toBe(true);
         for (const template of ["brief-self-fetch.md", "brief-template.md"]) {
             const text = fs.readFileSync(join(import.meta.dir, "../references", template), "utf8");
             expect(text).toContain("{{ROUND_POLICY}}");
@@ -5150,3 +5153,125 @@ describe("round 32 policy and landing routing", () => {
         }
     );
 });
+
+describe("tmp-reclaim --own-session lists only the live session's build output", () => {
+    const session = "1b4001ba-d479-40f2-9e25-b13cb2ef5a13";
+
+    function plantSession(): { cc: string; dir: string; nonBuild: string[] } {
+        const cc = fs.realpathSync(fs.mkdtempSync(join(tmpdir(), "babysit-own-")));
+        const dir = join(cc, "Project", session);
+        const file = (path: string, text = "x") => {
+            fs.mkdirSync(dirname(join(dir, path)), { recursive: true });
+            fs.writeFileSync(join(dir, path), text);
+        };
+        // Build output: a scratch path of SwiftPM entries only, a `.build` whose checkouts are git clones (so only its
+        // triple folder may go), and a module cache.
+        file("pluggable/b-hub/arm64-apple-macosx/debug/App.o");
+        file("pluggable/b-hub/workspace-state.json", "{}");
+        file("pluggable/b-hub/build.db");
+        file("pkg/.build/arm64-apple-macosx/debug/Kit.o");
+        file("pkg/.build/workspace-state.json", "{}");
+        file("pkg/.build/checkouts/dep/.git/HEAD", "ref: refs/heads/main\n");
+        file("pluggable/mc/ABC/Foundation-1.pcm");
+        file("pluggable/mc/Swift-2.swiftmodule");
+        file("pluggable/mc/modules.timestamp");
+        // Everything below must never be listed, nor any folder above it.
+        const nonBuild = [
+            "briefs/520-r1.md",
+            "logs/run.log",
+            "524-r2-replies.json",
+            "fix.patch",
+            "pluggable/b-notes/notes.md",
+            "mc-mixed/readme.txt",
+            "removals/old/arm64-apple-macosx/debug/Old.o",
+            "worktrees/w/node_modules/dep/.build/arm64-apple-macosx/x.o",
+        ];
+        for (const path of nonBuild) {
+            file(path);
+        }
+        file("pluggable/b-notes/arm64-apple-macosx/debug/Notes.o");
+        file("pluggable/b-notes/workspace-state.json", "{}");
+        file("mc-mixed/Foundation-1.pcm");
+        fs.symlinkSync(join(dir, "pluggable/b-hub/arm64-apple-macosx"), join(dir, "linked-triple"));
+        return { cc, dir, nonBuild: nonBuild.map((path) => join(dir, path)) };
+    }
+
+    test("the dry-run list holds build output and never a planted non-build file", () => {
+        const { dir, nonBuild } = plantSession();
+        const listed = ownBuildOutput(dir);
+        expect(listed).toEqual(
+            [
+                "pkg/.build/arm64-apple-macosx",
+                "pluggable/b-hub",
+                "pluggable/b-notes/arm64-apple-macosx",
+                "pluggable/mc",
+            ].map((path) => join(dir, path))
+        );
+        for (const path of nonBuild) {
+            expect(listed.filter((candidate) => path === candidate || path.startsWith(`${candidate}/`))).toEqual([]);
+        }
+        expect(buildOutputKind(join(dir, "pluggable/b-notes"))).toBeNull();
+        expect(buildOutputKind(join(dir, "mc-mixed"))).toBeNull();
+        expect(buildOutputKind(join(dir, "linked-triple"))).toBeNull();
+        expect(buildOutputKind(join(dir, "pluggable/mc"))).toBe("module-cache");
+    });
+
+    test("judgeOwn keeps the guards: recent, open, FIFO, outside the session, not build output", () => {
+        const { cc, dir } = plantSession();
+        // A change time can sit a millisecond ahead of Date.now(); with a zero age limit that still reads as recent.
+        Bun.sleepSync(20);
+        const options = { sessionDirs: [dir], open: [] as string[], minAgeMinutes: 0 };
+        const hub = join(dir, "pluggable/b-hub");
+        const verdict = judgeOwn(hub, options);
+        expect(typeof verdict === "string" ? verdict : verdict.path).toBe(hub);
+        expect(judgeOwn(hub, { ...options, minAgeMinutes: 10 })).toBe("recent");
+        expect(judgeOwn(hub, { ...options, open: [join(hub, "build.db")] })).toBe("open-file");
+        expect(judgeOwn(join(dir, "pluggable/b-notes"), options)).toBe("not-build-output");
+        expect(judgeOwn(join(dir, "removals/old/arm64-apple-macosx"), options)).toBe("skipped-folder");
+        expect(judgeOwn(join(dir, "linked-triple"), options)).toBe("symlink");
+        const outside = join(cc, "Other", "arm64-apple-macosx");
+        fs.mkdirSync(outside, { recursive: true });
+        expect(judgeOwn(outside, options)).toBe("outside-session");
+        expect(
+            Bun.spawnSync(["mkfifo", join(hub, "arm64-apple-macosx/debug/pipe")], { env: process.env }).exitCode
+        ).toBe(0);
+        expect(judgeOwn(hub, options)).toBe("socket");
+    });
+
+    test("the session is found by its full uuid only", () => {
+        const { cc, dir } = plantSession();
+        expect(ownSessionDirs(session, cc)).toEqual([dir]);
+        expect(() => ownSessionDirs("1b4001ba", cc)).toThrow("full session uuid");
+    });
+
+    test("apply removes the planned build output and refuses an entry that is no longer build output", () => {
+        const { dir } = plantSession();
+        const hub = join(dir, "pluggable/b-hub");
+        const notesTriple = join(dir, "pluggable/b-notes/arm64-apple-macosx");
+        const candidate = (path: string) => ({ path, ino: fs.lstatSync(path).ino, bytes: 1, newest: 0 });
+        const planned = [candidate(hub), candidate(notesTriple)];
+        // After the dry run someone put a note into the triple folder's place: the apply must refuse it.
+        fs.rmSync(notesTriple, { recursive: true });
+        fs.mkdirSync(notesTriple);
+        fs.writeFileSync(join(notesTriple, "kept.md"), "a note");
+        const plan = join(dir, "..", "plan.json");
+        fs.writeFileSync(
+            plan,
+            SafeJSON.stringify({
+                createdAt: Date.now(),
+                minAgeHours: 0,
+                candidates: planned,
+                ownSession: { id: session, dirs: [dir], minAgeMinutes: 0 },
+            })
+        );
+        const result = Bun.spawnSync(
+            [process.execPath, join(import.meta.dir, "tmp-reclaim.ts"), "--apply", "--plan", plan],
+            { stdout: "pipe", stderr: "pipe", env: process.env }
+        );
+        expect(result.stderr.toString()).toBe("");
+        expect(result.stdout.toString()).toContain("removed 1 of 2 planned entries");
+        expect(fs.existsSync(hub)).toBe(false);
+        expect(fs.readFileSync(join(notesTriple, "kept.md"), "utf8")).toBe("a note");
+        expect(fs.existsSync(join(dir, "pluggable/b-notes/notes.md"))).toBe(true);
+    });
+});

From ce3c083a83a83bc4a3ffe812f59a4711cf008141 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Wed, 21 Oct 2026 22:06:09 +0200
Subject: [PATCH 04/30] fix(question): a decision the agent got answered in
 chat moves to acknowledged or implemented without a send, unless a queued
 delivery holds it

---
 src/question/lib/decisions/store.test.ts | 23 +++++++++++++++++++++++
 src/question/lib/decisions/store.ts      | 10 ++++++++--
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/src/question/lib/decisions/store.test.ts b/src/question/lib/decisions/store.test.ts
index 9fc47df536..dff1dd4bf9 100644
--- a/src/question/lib/decisions/store.test.ts
+++ b/src/question/lib/decisions/store.test.ts
@@ -1675,6 +1675,29 @@ test("an answer reserved by a queued delivery cannot be changed under its queue
     }
     expect(readDecisions(file)[0].option).toBe("a");
     await updateDecision(file, events, row.id, { comment: "a note is still fine" });
+    await expect(updateDecision(file, events, row.id, { state: "implemented" })).rejects.toThrow(
+        "reserved by a queued delivery"
+    );
+});
+
+test("an answer the agent got in chat moves to acknowledged and implemented without a send", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "decision-chat-answer-"));
+    const file = join(dir, "decisions.jsonl");
+    const events = join(dir, "events.jsonl");
+    const [first, second] = await postDecisions(file, events, {
+        sessionId: "test-session",
+        decisions: [
+            { prompt: "First?", options: ["yes"] },
+            { prompt: "Second?", options: ["no"] },
+        ],
+    });
+    for (const row of [first, second]) {
+        await updateDecision(file, events, row.id, { state: "answered", answer: "yes" });
+    }
+
+    expect((await updateDecision(file, events, first.id, { state: "acknowledged" })).state).toBe("acknowledged");
+    expect((await updateDecision(file, events, first.id, { state: "implemented" })).state).toBe("implemented");
+    expect((await updateDecision(file, events, second.id, { state: "implemented" })).state).toBe("implemented");
 });
 
 test("decision revisions preserve the source turn of each posted version", async () => {
diff --git a/src/question/lib/decisions/store.ts b/src/question/lib/decisions/store.ts
index c7d8830637..8e7948c7fa 100644
--- a/src/question/lib/decisions/store.ts
+++ b/src/question/lib/decisions/store.ts
@@ -180,8 +180,10 @@ const NEXT: Record<DecisionKind, Record<DecisionState, DecisionState[]>> = {
         // Saving a draft again replaces it: the user edits a draft more than once before sending.
         // Clearing the last pick puts it back to open; Dismiss drops it without an answer.
         drafted: ["answered", "drafted", "open", "dismissed"],
-        answered: ["sent"],
-        sent: ["acknowledged"],
+        // An agent that got the answer in chat records its progress without a send (patched() refuses it while a
+        // queued delivery holds the row).
+        answered: ["sent", "acknowledged", "implemented"],
+        sent: ["acknowledged", "implemented"],
         acknowledged: ["implemented"],
         implemented: [],
         dismissed: [],
@@ -512,6 +514,10 @@ function patched(row: DecisionRecord, patch: DecisionPatch, ts: string): Decisio
         throw new Error(`cannot move ${row.id} from ${row.state} to ${patch.state}`);
     }
 
+    if (row.state === "answered" && patch.state && patch.state !== "sent" && row.delivery?.queueId) {
+        throw new Error(`${row.id} is reserved by a queued delivery; wait for its consumer acknowledgement`);
+    }
+
     // A queued answer is matched by revision on ACK, and these fields do not bump it; the ACK must not confirm new text.
     const content = [patch.answer, patch.option, patch.draft, patch.draftOption].some((value) => value !== undefined);
     if (row.delivery?.queueId && content) {

From dab09f19fa3af6bee52eaa51fcf866ac175e3042 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Wed, 21 Oct 2026 23:55:36 +0200
Subject: [PATCH 05/30] fix(question): an item that carries the post's wait, or
 a source, names where the key belongs

---
 src/question/commands/ask.test.ts   | 7 +++++++
 src/question/lib/decisions/items.ts | 4 ++++
 2 files changed, 11 insertions(+)

diff --git a/src/question/commands/ask.test.ts b/src/question/commands/ask.test.ts
index 1b8c390749..98578724ba 100644
--- a/src/question/commands/ask.test.ts
+++ b/src/question/commands/ask.test.ts
@@ -69,6 +69,13 @@ describe("parseItems", () => {
         expect(() => parseItems({ json })).toThrow(/Run tools question ask --help/);
     });
 
+    test("a post-level wait or a source inside an item names where it belongs", () => {
+        const json = '[{"type":"decision","promptMarkdown":"Keep?","wait":true,"source":"a.ts"}]';
+
+        expect(() => parseItems({ json })).toThrow(/unknown key "wait" \(did you mean the post's own "wait"/);
+        expect(() => parseItems({ json })).toThrow(/unknown key "source" \(did you mean refs\?\)/);
+    });
+
     test("an item without promptMarkdown is refused, also inside a question_post payload", () => {
         expect(() => parseItems({ json: '{"items":[{"type":"todo","title":"Rerun"}]}' })).toThrow(
             /item 1: promptMarkdown must be a non-empty string/
diff --git a/src/question/lib/decisions/items.ts b/src/question/lib/decisions/items.ts
index 0c259f7005..87833764f1 100644
--- a/src/question/lib/decisions/items.ts
+++ b/src/question/lib/decisions/items.ts
@@ -73,6 +73,10 @@ const KEY_HINTS: Record<string, string> = {
     options: "choices",
     images: "attachments",
     screenshots: "attachments",
+    // `source` and `wait` inside an item both failed a post on 2026-10-21; `wait` belongs to the post itself.
+    source: "refs",
+    sources: "refs",
+    wait: 'the post\'s own "wait", next to "items"',
 };
 
 const ITEM_TYPES = new Set(["question", "decision", "todo"]);

From 57fb24b270100acc1a62fb14555eb855adcac569 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 16:54:56 +0200
Subject: [PATCH 06/30] feat(tools): every failed tool run lands in a day's
 failures log with its command, message, stderr and the agent, session and
 model that ran it, from runTool and the entries with parsers of their own

---
 src/ask/index.ts                        |   4 +-
 src/cursor/index.ts                     |   5 +
 src/jenkins-mcp/index.ts                |   3 +
 src/macos-resources/index.tsx           |   4 +
 src/utils/cli/commander.test.ts         |  25 +-
 src/utils/cli/commander.ts              |   9 +-
 src/utils/cli/failures/caller.ts        | 147 ++++++++++
 src/utils/cli/failures/failures.test.ts | 150 +++++++++++
 src/utils/cli/failures/record.ts        | 140 ++++++++++
 src/utils/cli/failures/watch.ts         | 345 ++++++++++++++++++++++++
 src/utils/cli/run-record.ts             |   4 +
 11 files changed, 830 insertions(+), 6 deletions(-)
 create mode 100644 src/utils/cli/failures/caller.ts
 create mode 100644 src/utils/cli/failures/failures.test.ts
 create mode 100644 src/utils/cli/failures/record.ts
 create mode 100644 src/utils/cli/failures/watch.ts

diff --git a/src/ask/index.ts b/src/ask/index.ts
index 3b29751e6a..d188806dfd 100644
--- a/src/ask/index.ts
+++ b/src/ask/index.ts
@@ -18,6 +18,7 @@ import { expandAtMentions } from "@ask/utils/at-mentions";
 import { webSearchTool } from "@ask/utils/websearch";
 import * as p from "@clack/prompts";
 import { transcriptionManager } from "@genesiscz/utils/ai/transcription/TranscriptionManager";
+import { watchToolRun } from "@genesiscz/utils/cli/failures/watch";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { logger, out } from "@genesiscz/utils/logger";
 import { input } from "@genesiscz/utils/prompts/clack";
@@ -845,7 +846,8 @@ class ASKTool {
     }
 }
 
-// Run the tool
+// Run the tool. Its argument parser is its own (ask/utils/cli), so it records its failures itself, as runTool does.
+watchToolRun({ tool: "ask" });
 const askTool = new ASKTool();
 askTool.main().catch((err) => {
     logger.error(`Unexpected error: ${err}`);
diff --git a/src/cursor/index.ts b/src/cursor/index.ts
index ef2e68254e..352f3f04d4 100644
--- a/src/cursor/index.ts
+++ b/src/cursor/index.ts
@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 
+import { noteUsageError, watchToolRun } from "@genesiscz/utils/cli/failures/watch";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { out } from "@genesiscz/utils/logger";
 import { handleReadmeFlag } from "@genesiscz/utils/readme";
@@ -8,12 +9,15 @@ import { parseCursorArgs } from "./lib/args";
 import { streamCursorAgent } from "./lib/stream-agent";
 
 handleReadmeFlag(import.meta.url);
+// The parser below is stricter than commander on purpose (lib/args.ts), so this entry records its failures itself.
+watchToolRun({ tool: "cursor" });
 
 // ─── CLI argument parsing ──────────────────────────────────────────────────
 
 const parsed = parseCursorArgs(process.argv.slice(2), process.cwd());
 
 if (!parsed.ok) {
+    noteUsageError(parsed.message);
     out.error(pc.red(parsed.message));
     out.error(pc.dim(`Run ${toolCommand("cursor")} --help for the options.`));
     process.exit(1);
@@ -42,6 +46,7 @@ Each option also takes its value as --option=value. A question that starts with
 }
 
 if (!question) {
+    noteUsageError("No question provided.");
     out.error(pc.red("No question provided."));
     out.error(pc.dim(`Usage: ${toolCommand("cursor")} "which service creates the reservation?"`));
     process.exit(1);
diff --git a/src/jenkins-mcp/index.ts b/src/jenkins-mcp/index.ts
index 5620efd6e2..2b527de874 100644
--- a/src/jenkins-mcp/index.ts
+++ b/src/jenkins-mcp/index.ts
@@ -1,5 +1,8 @@
 #!/usr/bin/env bun
+import { watchToolRun } from "@genesiscz/utils/cli/failures/watch";
+
 // Kept so `tools jenkins-mcp` and MCP configs that launch it keep working. The code lives in src/jenkins.
+watchToolRun({ tool: "jenkins-mcp" });
 const { runEntry } = await import("../jenkins/lib/mcp/entry");
 
 await runEntry(process.argv.slice(2));
diff --git a/src/macos-resources/index.tsx b/src/macos-resources/index.tsx
index 548d19d08c..ce166ae813 100644
--- a/src/macos-resources/index.tsx
+++ b/src/macos-resources/index.tsx
@@ -2,6 +2,7 @@
 
 import "@genesiscz/utils/ink/react-production";
 import { parseArgs } from "node:util";
+import { noteUsageError, watchToolRun } from "@genesiscz/utils/cli/failures/watch";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { requireInteractiveTty } from "@genesiscz/utils/ink/lib/tty-guard";
 import { logger, out } from "@genesiscz/utils/logger";
@@ -602,12 +603,15 @@ const App: React.FC<{ options: AppOptions }> = ({ options }) => {
 export default App;
 
 if (import.meta.main) {
+    // An Ink app with a node:util parser: it records its failures itself, as runTool does for commander tools.
+    watchToolRun({ tool: "macos-resources" });
     let options: AppOptions | "help";
 
     try {
         options = parseCliOptions(process.argv.slice(2));
     } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        noteUsageError(message);
         logger.error(message);
         process.exit(1);
     }
diff --git a/src/utils/cli/commander.test.ts b/src/utils/cli/commander.test.ts
index b9030f8c09..2958aa6427 100644
--- a/src/utils/cli/commander.test.ts
+++ b/src/utils/cli/commander.test.ts
@@ -1,8 +1,11 @@
 import { afterEach, describe, expect, it, spyOn } from "bun:test";
-import { readFileSync } from "node:fs";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { readFailures, type ToolFailure } from "@genesiscz/utils/cli/failures/record";
 import { env } from "@genesiscz/utils/env";
 import { setConsoleLevel } from "@genesiscz/utils/logger";
+import { genesisToolsDirIn } from "@genesiscz/utils/storage/root";
 import { Command } from "commander";
 import {
     addGlobalVerboseOption,
@@ -163,9 +166,13 @@ describe("addGlobalVerboseOption trace gate", () => {
 // runTool: a real run (a child process, because runTool refuses process.argv under the test runner) and a caller
 // that passes its own argv.
 describe("runTool error boundary", () => {
-    async function runFixture(...args: string[]): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+    // Each run gets its own home, so the failure record it writes can be read back.
+    async function runFixture(
+        ...args: string[]
+    ): Promise<{ exitCode: number; stdout: string; stderr: string; failures: ToolFailure[] }> {
+        const home = mkdtempSync(join(tmpdir(), "gt-run-tool-"));
         const proc = Bun.spawn(["bun", "run", BOUNDARY_FIXTURE, ...args], {
-            env: process.env,
+            env: { ...process.env, GENESIS_TOOLS_HOME: home },
             stdout: "pipe",
             stderr: "pipe",
         });
@@ -175,7 +182,10 @@ describe("runTool error boundary", () => {
             proc.exited,
         ]);
 
-        return { exitCode, stdout, stderr };
+        const failures = [
+            ...readFailures({ fromDay: "0000-00-00", toDay: "9999-99-99", dir: genesisToolsDirIn(home, "logs") }),
+        ];
+        return { exitCode, stdout, stderr, failures };
     }
 
     it("reports an action error from a real run as one ERROR line and exits 1", async () => {
@@ -185,6 +195,10 @@ describe("runTool error boundary", () => {
         expect(run.stderr.match(/^ERROR: boom$/gm)?.length).toBe(1);
         expect(run.stderr).not.toContain("run-tool-boundary.ts");
         expect(run.stdout).toBe("");
+        expect(run.failures.map((failure) => [failure.kind, failure.tool, failure.command, failure.message])).toEqual([
+            ["error", "boundary", "boundary boom", "boom"],
+        ]);
+        expect(run.failures[0].stack).toContain("Error: boom");
     });
 
     it("leaves a Commander error to Commander's own exit path", async () => {
@@ -193,6 +207,9 @@ describe("runTool error boundary", () => {
         expect(run.exitCode).toBe(1);
         expect(run.stderr).toContain("unknown command 'nope'");
         expect(run.stderr).not.toContain("ERROR:");
+        expect(run.failures.map((failure) => [failure.kind, failure.argv, failure.message, failure.exitCode])).toEqual([
+            ["usage", ["nope"], "error: unknown command 'nope'", 1],
+        ]);
     });
 
     it("hands an action error back to a caller that passes its own argv", async () => {
diff --git a/src/utils/cli/commander.ts b/src/utils/cli/commander.ts
index da943888d0..838cfe8583 100644
--- a/src/utils/cli/commander.ts
+++ b/src/utils/cli/commander.ts
@@ -6,8 +6,9 @@ import { consoleFloorFor } from "@genesiscz/utils/logging/tool-policy";
 import { type Command, CommanderError } from "commander";
 import { setCurrentCommand } from "./current-command";
 import { enhanceHelp, markRequiredOptionsDeep, setSuggestCommandProgram, showHelpAfterErrorDeep } from "./executor";
+import { commandPathFromArgv, noteToolError, watchToolRun } from "./failures/watch";
 import { observeInterrupts } from "./interrupt";
-import { recordRunOnExit, setRunLabel } from "./run-record";
+import { currentRunLabel, recordRunOnExit, setRunLabel } from "./run-record";
 
 export type Verbosity = 0 | 1 | 2 | 3;
 
@@ -207,6 +208,7 @@ function launchedByTestRunner(): boolean {
 export function reportUnhandledToolError(error: unknown): void {
     const message = error instanceof Error ? error.message : String(error);
     logger.debug({ err: error }, "unhandled tool error");
+    noteToolError(error);
     process.stderr.write(`ERROR: ${message}\n`);
     process.exitCode = 1;
 }
@@ -263,6 +265,11 @@ export async function runTool(
 
     if (argv === process.argv) {
         recordRunOnExit(tool);
+        watchToolRun({
+            tool,
+            argv: argv.slice(2),
+            commandPath: () => currentRunLabel() ?? commandPathFromArgv(program, argv.slice(2)),
+        });
     }
 
     if (!opts.ignoreParams?.includes("verbose")) {
diff --git a/src/utils/cli/failures/caller.ts b/src/utils/cli/failures/caller.ts
new file mode 100644
index 0000000000..5efd4f64e9
--- /dev/null
+++ b/src/utils/cli/failures/caller.ts
@@ -0,0 +1,147 @@
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { AgentRuntimeContext } from "@genesiscz/utils/agent/context";
+import { readLastLines } from "@genesiscz/utils/fs/read-lines";
+import { SafeJSON } from "@genesiscz/utils/json";
+import { logger } from "@genesiscz/utils/logger";
+import type { FailureCaller } from "./record";
+
+const TAIL_BYTES = 512 * 1024;
+const CODEX_DAYS_BACK = 7;
+
+/** Claude names a project folder after the session's cwd with every non-alphanumeric character as `-`. */
+export function claudeProjectFolder(cwd: string): string {
+    return cwd.replace(/[^A-Za-z0-9]/g, "-");
+}
+
+function claudeTranscript(sessionId: string, cwds: string[], configDir: string): string | null {
+    const projects = join(configDir, "projects");
+    const file = `${sessionId}.jsonl`;
+
+    for (const cwd of cwds) {
+        const direct = join(projects, claudeProjectFolder(cwd), file);
+        if (existsSync(direct)) {
+            return direct;
+        }
+    }
+
+    if (!existsSync(projects)) {
+        return null;
+    }
+
+    for (const folder of readdirSync(projects)) {
+        const candidate = join(projects, folder, file);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+
+    return null;
+}
+
+function codexRollout(threadId: string, codexHome: string, now: Date): string | null {
+    for (let back = 0; back < CODEX_DAYS_BACK; back++) {
+        const day = new Date(now.getTime() - back * 86_400_000);
+        const dir = join(
+            codexHome,
+            "sessions",
+            String(day.getFullYear()),
+            String(day.getMonth() + 1).padStart(2, "0"),
+            String(day.getDate()).padStart(2, "0")
+        );
+        if (!existsSync(dir)) {
+            continue;
+        }
+
+        const name = readdirSync(dir).find((entry) => entry.endsWith(`-${threadId}.jsonl`));
+        if (name) {
+            return join(dir, name);
+        }
+    }
+
+    return null;
+}
+
+/** The newest model the transcript tail names: Claude's assistant `message.model`, Codex's `turn_context` model. */
+export function modelInTranscriptLines(lines: string[]): string | null {
+    for (let index = lines.length - 1; index >= 0; index--) {
+        const line = lines[index];
+        if (!line.includes('"model"')) {
+            continue;
+        }
+
+        let entry: unknown;
+        try {
+            entry = SafeJSON.parse(line, { strict: true });
+        } catch (error) {
+            logger.debug({ error }, "failures: a transcript line did not parse");
+            continue;
+        }
+
+        if (typeof entry !== "object" || entry === null) {
+            continue;
+        }
+
+        const record = entry as { type?: unknown; message?: { model?: unknown }; payload?: { model?: unknown } };
+        const model =
+            record.type === "assistant"
+                ? record.message?.model
+                : record.type === "turn_context"
+                  ? record.payload?.model
+                  : undefined;
+        if (typeof model === "string" && model && !model.startsWith("<")) {
+            return model;
+        }
+    }
+
+    return null;
+}
+
+export interface CallerInputs {
+    context: AgentRuntimeContext;
+    processEnv: NodeJS.ProcessEnv;
+    now?: Date;
+    home?: string;
+}
+
+/** The transcript of the calling session, when this machine has it. */
+export function transcriptOf({ context, processEnv, now = new Date(), home = homedir() }: CallerInputs): string | null {
+    if (!context.sessionId) {
+        return null;
+    }
+
+    if (context.agent === "claude-code") {
+        const configDir = processEnv.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude");
+        return claudeTranscript(context.sessionId, [context.cwd, context.repoRoot], configDir);
+    }
+
+    if (context.agent === "codex") {
+        return codexRollout(context.sessionId, processEnv.CODEX_HOME?.trim() || join(home, ".codex"), now);
+    }
+
+    return null;
+}
+
+export function failureCaller(inputs: CallerInputs): FailureCaller {
+    const { context, processEnv } = inputs;
+    const transcript = transcriptOf(inputs);
+    let model: string | null = null;
+    if (transcript) {
+        model = modelInTranscriptLines(readLastLines(transcript, { maxBytes: TAIL_BYTES }).lines);
+    }
+
+    return {
+        agent: context.agent,
+        sessionId: context.sessionId,
+        sessionTitle: context.sessionTitle,
+        model,
+        effort: processEnv.CLAUDE_EFFORT?.trim() || null,
+        aiAgent: context.aiAgent ?? (processEnv.AI_AGENT?.trim() || null),
+        project: context.project,
+        repoRoot: context.repoRoot,
+        branch: context.branch,
+        commitSha: context.commitSha,
+        worktreePath: context.worktreePath,
+    };
+}
diff --git a/src/utils/cli/failures/failures.test.ts b/src/utils/cli/failures/failures.test.ts
new file mode 100644
index 0000000000..c53617385a
--- /dev/null
+++ b/src/utils/cli/failures/failures.test.ts
@@ -0,0 +1,150 @@
+import { describe, expect, it } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { claudeProjectFolder, modelInTranscriptLines } from "./caller";
+import { appendFailure, readFailures, type ToolFailure } from "./record";
+import { classifyExit, commandPathFromArgv, jsonErrorMessage, messageOfTail, redactArgv } from "./watch";
+
+describe("redactArgv", () => {
+    it("masks the value of a secret-named flag in both spellings and keeps the rest", () => {
+        expect(redactArgv(["login", "--api-key", "abc123", "--token=xyz", "--name", "work"])).toEqual([
+            "login",
+            "--api-key",
+            "[redacted]",
+            "--token=[redacted]",
+            "--name",
+            "work",
+        ]);
+    });
+
+    it("masks a secret-shaped argument without a flag", () => {
+        expect(redactArgv(["set", "sk-ant-abcdefghijklmnopqrstuvwxyz0123"])).toEqual(["set", "[redacted]"]);
+    });
+});
+
+describe("classifyExit", () => {
+    const none = { noted: null, stderrTail: "" };
+
+    it("is no failure on exit 0 and an interrupt on 130 or 143", () => {
+        expect(classifyExit({ exitCode: 0, ...none })).toBeNull();
+        expect(classifyExit({ exitCode: 130, ...none })).toBe("interrupt");
+        expect(classifyExit({ exitCode: 143, ...none })).toBe("interrupt");
+    });
+
+    it("names commander's refusal and a bare help as usage, anything else as exit", () => {
+        expect(classifyExit({ exitCode: 1, noted: null, stderrTail: "error: unknown option '--x'\n" })).toBe("usage");
+        expect(classifyExit({ exitCode: 1, noted: null, stderrTail: "Usage: tools ts [options]\n" })).toBe("usage");
+        expect(classifyExit({ exitCode: 2, noted: null, stderrTail: "could not find it\n" })).toBe("exit");
+    });
+
+    it("a fatal crash wins even when the exit event reports 0 (Bun after an unhandled rejection)", () => {
+        expect(
+            classifyExit({ exitCode: 0, noted: { kind: "crash", error: new Error("x"), fatal: true }, stderrTail: "" })
+        ).toBe("crash");
+        expect(
+            classifyExit({ exitCode: 1, noted: { kind: "error", error: new Error("x"), fatal: true }, stderrTail: "" })
+        ).toBe("error");
+    });
+});
+
+describe("messageOfTail", () => {
+    it("picks commander's error line over the help printed after it", () => {
+        expect(
+            messageOfTail("error: missing required argument 'entry'\n\nUsage: tools ts imports analyze <entry>\n")
+        ).toBe("error: missing required argument 'entry'");
+    });
+
+    it("falls back to the last non-empty line", () => {
+        expect(messageOfTail("working…\nno such worktree: feat/x\n\n")).toBe("no such worktree: feat/x");
+        expect(messageOfTail("")).toBeNull();
+    });
+});
+
+describe("jsonErrorMessage", () => {
+    it("reads the last JSON error line in each common shape and ignores results", () => {
+        expect(
+            jsonErrorMessage(
+                '{"type":"progress"}\n{"type":"error","command":"update","message":"index is not built"}\n'
+            )
+        ).toBe("index is not built");
+        expect(jsonErrorMessage('{"error":{"message":"rate limited"}}')).toBe("rate limited");
+        expect(jsonErrorMessage('{"error":"busy"}')).toBe("busy");
+        expect(jsonErrorMessage('{"rows":[]}\nplain text')).toBeNull();
+    });
+});
+
+describe("commandPathFromArgv", () => {
+    interface Node {
+        name(): string;
+        aliases(): string[];
+        commands: Node[];
+    }
+    const node = (name: string, commands: Node[] = [], aliases: string[] = []): Node => ({
+        name: () => name,
+        aliases: () => aliases,
+        commands,
+    });
+    const program = node("ai", [node("usage", [node("sessions")], ["u"])]);
+
+    it("follows the leading words through subcommands and aliases, and stops at an option", () => {
+        expect(commandPathFromArgv(program, ["u", "sessions", "--bad"])).toBe("ai usage sessions");
+        expect(commandPathFromArgv(program, ["usage", "--hours", "sessions"])).toBe("ai usage");
+        expect(commandPathFromArgv(program, ["nope"])).toBe("ai");
+    });
+});
+
+describe("modelInTranscriptLines", () => {
+    it("reads the newest model of a Claude or a Codex transcript and skips synthetic turns", () => {
+        const claude = [
+            '{"type":"assistant","message":{"model":"claude-sonnet-5-5"}}',
+            '{"type":"user","message":{"content":"x"}}',
+            '{"type":"assistant","message":{"model":"<synthetic>"}}',
+        ];
+        expect(modelInTranscriptLines(claude)).toBe("claude-sonnet-5-5");
+        expect(modelInTranscriptLines(['{"type":"turn_context","payload":{"model":"gpt-6.1-sol"}}'])).toBe(
+            "gpt-6.1-sol"
+        );
+        expect(modelInTranscriptLines(['{"type":"user"}'])).toBeNull();
+    });
+
+    it("names the project folder the way Claude does", () => {
+        expect(claudeProjectFolder("/Users/me/Projects/My App.v2")).toBe("-Users-me-Projects-My-App-v2");
+    });
+});
+
+describe("failure records", () => {
+    it("reads back what was appended, by day, and skips a cut line", async () => {
+        const dir = mkdtempSync(join(tmpdir(), "gt-failures-"));
+        const failure: ToolFailure = {
+            v: 1,
+            id: "a-1",
+            at: new Date(2026, 9, 22, 12).toISOString(),
+            kind: "usage",
+            tool: "ts",
+            command: "ts skeleton",
+            argv: ["skeleton", "--bogus"],
+            exitCode: 1,
+            message: "error: unknown option '--bogus'",
+            errorName: null,
+            stack: null,
+            stderrTail: null,
+            fatal: true,
+            durationMs: 120,
+            pid: 1,
+            ppid: 0,
+            cwd: "/repo",
+            traceId: null,
+            toolsRoot: "/repo",
+            caller: null,
+        };
+        appendFailure(failure, dir);
+        await Bun.write(
+            join(dir, "2026-10-22-failures.jsonl"),
+            `${await Bun.file(join(dir, "2026-10-22-failures.jsonl")).text()}{"v":1,"to`
+        );
+
+        expect([...readFailures({ fromDay: "2026-10-22", toDay: "2026-10-22", dir })]).toEqual([failure]);
+        expect([...readFailures({ fromDay: "2026-10-23", toDay: "2026-10-24", dir })]).toEqual([]);
+    });
+});
diff --git a/src/utils/cli/failures/record.ts b/src/utils/cli/failures/record.ts
new file mode 100644
index 0000000000..2f5d121de1
--- /dev/null
+++ b/src/utils/cli/failures/record.ts
@@ -0,0 +1,140 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { AgentRuntimeContext } from "@genesiscz/utils/agent/context";
+import { formatLocalDate } from "@genesiscz/utils/date";
+import { readLinesSync } from "@genesiscz/utils/fs/read-lines";
+import { SafeJSON } from "@genesiscz/utils/json";
+import { logger } from "@genesiscz/utils/logger";
+import { genesisToolsDir } from "@genesiscz/utils/storage/root";
+
+/**
+ * - `usage`: commander refused the command line (unknown option, missing argument).
+ * - `error`: the tool's action threw and runTool printed `ERROR: …`.
+ * - `crash`: an uncaught exception or an unhandled rejection; `fatal` says whether it ended the process.
+ * - `exit`: a non-zero exit with none of the above (the tool printed its own message and exited 1).
+ * - `interrupt`: Ctrl-C or SIGTERM (130 / 143); often a harness timeout rather than a bug.
+ */
+export const FAILURE_KINDS = ["usage", "error", "crash", "exit", "interrupt"] as const;
+export type FailureKind = (typeof FAILURE_KINDS)[number];
+
+/** Who ran the tool. Model and effort come from the agent's own transcript and env, never guessed. */
+export interface FailureCaller {
+    agent: AgentRuntimeContext["agent"];
+    sessionId: string | null;
+    sessionTitle: string | null;
+    model: string | null;
+    effort: string | null;
+    /** `AI_AGENT` as the harness sets it, e.g. `claude-code_2-1-296_agent`. */
+    aiAgent: string | null;
+    project: string;
+    repoRoot: string;
+    branch: string | null;
+    commitSha: string | null;
+    worktreePath: string | null;
+}
+
+export interface ToolFailure {
+    v: 1;
+    id: string;
+    at: string;
+    kind: FailureKind;
+    tool: string;
+    /** The command path, `ai usage sessions`: names only, never argument values. */
+    command: string | null;
+    /** The arguments after the tool name, secrets masked. */
+    argv: string[];
+    exitCode: number | null;
+    message: string | null;
+    errorName: string | null;
+    stack: string | null;
+    /** The last stderr the process wrote, ANSI stripped and secrets masked. */
+    stderrTail: string | null;
+    fatal: boolean;
+    durationMs: number;
+    pid: number;
+    ppid: number;
+    cwd: string;
+    /** Set when GenesisTools.app started the command. */
+    traceId: string | null;
+    /** The GenesisTools checkout that ran the tool: the main one or a worktree. */
+    toolsRoot: string;
+    caller: FailureCaller | null;
+}
+
+const FILE = /^(\d{4}-\d{2}-\d{2})-failures\.jsonl$/;
+
+export function failuresDir(): string {
+    return genesisToolsDir("logs");
+}
+
+export function failureLogPath(day: string, dir = failuresDir()): string {
+    return join(dir, `${day}-failures.jsonl`);
+}
+
+/** One line per failure, appended with a single write so concurrent tools never interleave a record. */
+export function appendFailure(failure: ToolFailure, dir = failuresDir()): void {
+    const path = failureLogPath(formatLocalDate(new Date(failure.at)), dir);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${SafeJSON.stringify(failure)}\n`);
+}
+
+/** The days that have a failure log, oldest first. */
+export function failureDays(dir = failuresDir()): string[] {
+    if (!existsSync(dir)) {
+        return [];
+    }
+
+    return readdirSync(dir)
+        .flatMap((name) => FILE.exec(name)?.[1] ?? [])
+        .sort();
+}
+
+export function isToolFailure(value: unknown): value is ToolFailure {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+
+    const record = value as Record<string, unknown>;
+    return (
+        record.v === 1 &&
+        typeof record.tool === "string" &&
+        typeof record.at === "string" &&
+        FAILURE_KINDS.includes(record.kind as FailureKind)
+    );
+}
+
+/** Every failure recorded on `fromDay` through `toDay` (inclusive, `YYYY-MM-DD`), oldest first. */
+export function* readFailures({
+    fromDay,
+    toDay,
+    dir = failuresDir(),
+}: {
+    fromDay: string;
+    toDay: string;
+    dir?: string;
+}): Generator<ToolFailure> {
+    for (const day of failureDays(dir)) {
+        if (day < fromDay || day > toDay) {
+            continue;
+        }
+
+        for (const line of readLinesSync(failureLogPath(day, dir))) {
+            if (!line.trim()) {
+                continue;
+            }
+
+            let parsed: unknown;
+            try {
+                parsed = SafeJSON.parse(line, { strict: true });
+            } catch (error) {
+                // A line cut by a full disk or a killed writer; the rest of the day still reads.
+                logger.debug({ error, day }, "failures: skipped an unreadable line");
+                continue;
+            }
+
+            if (isToolFailure(parsed)) {
+                yield parsed;
+            }
+        }
+    }
+}
diff --git a/src/utils/cli/failures/watch.ts b/src/utils/cli/failures/watch.ts
new file mode 100644
index 0000000000..893694ac92
--- /dev/null
+++ b/src/utils/cli/failures/watch.ts
@@ -0,0 +1,345 @@
+import { resolve } from "node:path";
+import { format } from "node:util";
+import { env } from "@genesiscz/utils/env";
+import { SafeJSON } from "@genesiscz/utils/json";
+import { logger } from "@genesiscz/utils/logger";
+import { stripAnsi } from "@genesiscz/utils/string";
+import { currentTraceId } from "@genesiscz/utils/trace";
+import { redactSecretsInText } from "@genesiscz/utils/transclude/redact";
+import { failureCaller } from "./caller";
+import { appendFailure, type FailureCaller, type FailureKind, type ToolFailure } from "./record";
+
+const TAIL_CHARS = 4000;
+const TOOLS_ROOT = resolve(import.meta.dir, "../../../..");
+const SECRET_FLAG = /^--?[\w-]*(?:token|secret|password|passwd|api[-_]?key|auth|cookie|credential)[\w-]*$/i;
+/** Commander's own refusals; each starts a stderr write with `error: `. */
+const USAGE_LINE =
+    /^error: (?:unknown option|unknown command|missing required argument|option .+ argument missing|required option|too many arguments|option .+ argument .+ is invalid|command-argument value .+ is invalid|option .+ cannot be used with)/m;
+
+interface Noted {
+    kind: "usage" | "error" | "crash";
+    error: unknown;
+    fatal: boolean;
+}
+
+interface Run {
+    tool: string;
+    argv: string[];
+    commandPath: () => string | null;
+    stderr: string;
+    /** Only read for a JSON error object; never stored, since stdout is the tool's result. */
+    stdout: string;
+    noted: Noted | null;
+    ended: boolean;
+}
+
+let run: Run | null = null;
+
+/** Masks the value of a secret-named flag (`--token x`, `--api-key=x`) and any secret-shaped argument. */
+export function redactArgv(args: readonly string[]): string[] {
+    return args.map((arg, index) => {
+        const assigned = /^(--?[\w-]+)=/.exec(arg);
+        if (assigned && SECRET_FLAG.test(assigned[1])) {
+            return `${assigned[1]}=[redacted]`;
+        }
+
+        if (index > 0 && SECRET_FLAG.test(args[index - 1]) && !arg.startsWith("-")) {
+            return "[redacted]";
+        }
+
+        return redactSecretsInText(arg);
+    });
+}
+
+interface CommandNode {
+    name(): string;
+    aliases(): string[];
+    readonly commands: readonly CommandNode[];
+}
+
+/** `ai usage sessions` for `tools ai usage sessions --bad`: the deepest subcommand the leading words name. */
+export function commandPathFromArgv(program: CommandNode, args: readonly string[]): string {
+    const names = [program.name()];
+    let current = program;
+
+    for (const word of args) {
+        if (word.startsWith("-")) {
+            break;
+        }
+
+        const next = current.commands.find((command) => command.name() === word || command.aliases().includes(word));
+        if (!next) {
+            break;
+        }
+
+        names.push(next.name());
+        current = next;
+    }
+
+    return names.join(" ");
+}
+
+/** What a run that ends with `exitCode` was. Null when it is not a failure. */
+export function classifyExit({
+    exitCode,
+    noted,
+    stderrTail,
+}: {
+    exitCode: number;
+    noted: Noted | null;
+    stderrTail: string;
+}): FailureKind | null {
+    if (noted?.kind === "crash" && noted.fatal) {
+        return "crash";
+    }
+
+    if (exitCode === 0) {
+        return null;
+    }
+
+    if (exitCode === 130 || exitCode === 143) {
+        return "interrupt";
+    }
+
+    if (noted?.kind === "error" || noted?.kind === "usage") {
+        return noted.kind;
+    }
+
+    if (USAGE_LINE.test(stderrTail) || /^Usage: /.test(stderrTail.trimStart())) {
+        return "usage";
+    }
+
+    return "exit";
+}
+
+/** The line a reader needs: commander's `error:` line, else the last non-empty stderr line. */
+export function messageOfTail(tail: string): string | null {
+    const usage = USAGE_LINE.exec(tail);
+    if (usage) {
+        const end = tail.indexOf("\n", usage.index);
+        return tail.slice(usage.index, end === -1 ? undefined : end);
+    }
+
+    if (/^Usage: /.test(tail.trimStart())) {
+        return "no subcommand given; the help was printed";
+    }
+
+    const lines = tail.split("\n").filter((line) => line.trim());
+    return lines.at(-1)?.trim() ?? null;
+}
+
+/**
+ * The message of the last JSON error line a `--json` run printed: `{"type":"error","message":…}`,
+ * `{"error":"…"}` or `{"error":{"message":"…"}}` (du index, ai usage and others report failures on stdout).
+ */
+export function jsonErrorMessage(stdoutTail: string): string | null {
+    const lines = stdoutTail.split("\n").filter((line) => line.trimStart().startsWith("{"));
+
+    for (const line of lines.reverse()) {
+        let value: unknown;
+        try {
+            value = SafeJSON.parse(line, { strict: true });
+        } catch (error) {
+            logger.debug({ error }, "failures: a stdout line looked like JSON and was not");
+            continue;
+        }
+
+        if (typeof value !== "object" || value === null) {
+            continue;
+        }
+
+        const record = value as { type?: unknown; message?: unknown; error?: unknown };
+        if (record.type === "error" && typeof record.message === "string") {
+            return record.message;
+        }
+
+        if (typeof record.error === "string") {
+            return record.error;
+        }
+
+        if (typeof record.error === "object" && record.error !== null) {
+            const nested = (record.error as { message?: unknown }).message;
+            if (typeof nested === "string") {
+                return nested;
+            }
+        }
+    }
+
+    return null;
+}
+
+function text(chunk: unknown): string {
+    return typeof chunk === "string" ? chunk : chunk instanceof Uint8Array ? new TextDecoder().decode(chunk) : "";
+}
+
+function remember(chunk: unknown): void {
+    if (run) {
+        run.stderr = (run.stderr + text(chunk)).slice(-TAIL_CHARS);
+    }
+}
+
+function tapStderr(): void {
+    const write = process.stderr.write;
+    process.stderr.write = function (this: NodeJS.WriteStream, ...args: Parameters<typeof write>) {
+        remember(args[0]);
+        return Reflect.apply(write, this, args);
+    } as typeof write;
+
+    const writeOut = process.stdout.write;
+    process.stdout.write = function (this: NodeJS.WriteStream, ...args: Parameters<typeof writeOut>) {
+        if (run) {
+            run.stdout = (run.stdout + text(args[0])).slice(-TAIL_CHARS);
+        }
+
+        return Reflect.apply(writeOut, this, args);
+    } as typeof writeOut;
+
+    // Bun's console.error and console.warn write to fd 2 without process.stderr.write.
+    const consoleError = console.error;
+    const consoleWarn = console.warn;
+    console.error = (...data: unknown[]) => {
+        remember(`${format(...data)}\n`);
+        consoleError(...data);
+    };
+    console.warn = (...data: unknown[]) => {
+        remember(`${format(...data)}\n`);
+        consoleWarn(...data);
+    };
+}
+
+function caller(): FailureCaller | null {
+    try {
+        // Loaded here, on a failure only: the runtime context pulls the history index reader, which every tool
+        // would otherwise import at start. The exit event is synchronous, so the load is too.
+        const {
+            getAgentRuntimeContext,
+        }: typeof import("@genesiscz/utils/agent/runtime") = require("@genesiscz/utils/agent/runtime");
+        const processEnv = env.getProcessEnv();
+        return failureCaller({ context: getAgentRuntimeContext({}, processEnv), processEnv });
+    } catch (error) {
+        logger.debug({ error }, "failures: no caller context");
+        return null;
+    }
+}
+
+function write(kind: FailureKind, exitCode: number | null, fatal: boolean): void {
+    if (!run) {
+        return;
+    }
+
+    try {
+        const error = run.noted?.error;
+        const err = error instanceof Error ? error : null;
+        const tail = redactSecretsInText(stripAnsi(run.stderr)).trim();
+        const message = err
+            ? err.message
+            : error !== undefined && error !== null
+              ? String(error)
+              : (jsonErrorMessage(run.stdout) ?? messageOfTail(tail));
+        const failure: ToolFailure = {
+            v: 1,
+            id: `${Date.now().toString(36)}-${process.pid}`,
+            at: new Date().toISOString(),
+            kind,
+            tool: run.tool,
+            command: run.commandPath()?.replace(/^tools /, "") ?? null,
+            argv: redactArgv(run.argv),
+            exitCode,
+            message: message ? redactSecretsInText(stripAnsi(message)).slice(0, 2000) : null,
+            errorName: err?.name ?? null,
+            stack: err?.stack ? redactSecretsInText(err.stack).slice(0, 8000) : null,
+            stderrTail: tail || null,
+            fatal,
+            durationMs: Math.round(performance.now()),
+            pid: process.pid,
+            ppid: process.ppid,
+            cwd: process.cwd(),
+            traceId: currentTraceId() ?? null,
+            toolsRoot: TOOLS_ROOT,
+            caller: caller(),
+        };
+        appendFailure(failure);
+    } catch (writeError) {
+        logger.debug({ error: writeError }, "failures: the record was not written");
+    }
+}
+
+function finish(code: number): void {
+    if (!run || run.ended) {
+        return;
+    }
+
+    run.ended = true;
+    const exitCode = code || (typeof process.exitCode === "number" ? process.exitCode : 0);
+    const kind = classifyExit({ exitCode, noted: run.noted, stderrTail: stripAnsi(run.stderr) });
+    if (kind) {
+        write(kind, exitCode, true);
+    }
+}
+
+/** A crash some other listener handles: the process goes on, so it is written now, not at exit. */
+function noteCrash(error: unknown, fatal: boolean): void {
+    if (!run) {
+        return;
+    }
+
+    run.noted = { kind: "crash", error, fatal };
+    if (!fatal) {
+        write("crash", null, false);
+        run.noted = null;
+    }
+}
+
+function onRejection(reason: unknown): void {
+    const handledElsewhere = process.listenerCount("unhandledRejection") > 1;
+    noteCrash(reason, !handledElsewhere);
+    if (handledElsewhere) {
+        return;
+    }
+
+    // Bun ends the process on an unhandled rejection unless a listener exists; this listener keeps that ending.
+    logger.debug({ err: reason }, "unhandled rejection");
+    process.stderr.write(`ERROR: unhandled rejection: ${reason instanceof Error ? reason.message : String(reason)}\n`);
+    process.exit(1);
+}
+
+/** A parser of its own refused the command line (an entry point without commander). */
+export function noteUsageError(message: string): void {
+    if (run) {
+        run.noted = { kind: "usage", error: message, fatal: true };
+    }
+}
+
+/** The action threw and runTool printed it. */
+export function noteToolError(error: unknown): void {
+    if (run) {
+        run.noted = { kind: "error", error, fatal: true };
+    }
+}
+
+/**
+ * Records every failed run of this process into `~/.genesis-tools/logs/<date>-failures.jsonl`: a usage error, a
+ * thrown action, a crash, a plain non-zero exit, an interrupt. `runTool` calls it; an entry point without commander
+ * calls it itself. Once per process; only a real CLI run, never a test that passes its own argv.
+ */
+export function watchToolRun({
+    tool,
+    argv = process.argv.slice(2),
+    commandPath = () => null,
+}: {
+    tool: string;
+    argv?: string[];
+    commandPath?: () => string | null;
+}): void {
+    if (run) {
+        return;
+    }
+
+    run = { tool, argv, commandPath, stderr: "", stdout: "", noted: null, ended: false };
+    tapStderr();
+    process.on("uncaughtExceptionMonitor", (error) => {
+        noteCrash(error, process.listenerCount("uncaughtException") === 0);
+    });
+    process.on("unhandledRejection", onRejection);
+    process.once("exit", finish);
+}
diff --git a/src/utils/cli/run-record.ts b/src/utils/cli/run-record.ts
index b0b1cf15d7..feebd4d513 100644
--- a/src/utils/cli/run-record.ts
+++ b/src/utils/cli/run-record.ts
@@ -8,6 +8,10 @@ export function setRunLabel(label: string): void {
     runLabel = label;
 }
 
+export function currentRunLabel(): string | null {
+    return runLabel;
+}
+
 /**
  * One `[profile:cli]` line per command run, written at exit: wall time since the process started (Bun
  * startup and imports included, which is what a caller waits for), CPU time, peak memory, and

From f7da1c03c0ff78db607b47f83a61c54b0b59d6fb Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 16:55:15 +0200
Subject: [PATCH 07/30] feat(tools): tools genesis-tools logs lists, groups and
 shows failed runs, refused command lines, crashes, day-log records and slow
 timers

---
 src/genesis-tools/README.md            |  37 +++
 src/genesis-tools/commands/logs.ts     | 393 +++++++++++++++++++++++++
 src/genesis-tools/index.ts             |  14 +
 src/genesis-tools/lib/crash-reports.ts |  37 +++
 src/genesis-tools/lib/day-log.ts       | 154 ++++++++++
 src/genesis-tools/lib/failures.ts      | 205 +++++++++++++
 src/genesis-tools/lib/logs.test.ts     | 152 ++++++++++
 src/genesis-tools/lib/profile-log.ts   |  73 +++++
 src/genesis-tools/lib/window.ts        |  58 ++++
 9 files changed, 1123 insertions(+)
 create mode 100644 src/genesis-tools/README.md
 create mode 100644 src/genesis-tools/commands/logs.ts
 create mode 100644 src/genesis-tools/index.ts
 create mode 100644 src/genesis-tools/lib/crash-reports.ts
 create mode 100644 src/genesis-tools/lib/day-log.ts
 create mode 100644 src/genesis-tools/lib/failures.ts
 create mode 100644 src/genesis-tools/lib/logs.test.ts
 create mode 100644 src/genesis-tools/lib/profile-log.ts
 create mode 100644 src/genesis-tools/lib/window.ts

diff --git a/src/genesis-tools/README.md b/src/genesis-tools/README.md
new file mode 100644
index 0000000000..9ca1a7bbec
--- /dev/null
+++ b/src/genesis-tools/README.md
@@ -0,0 +1,37 @@
+# tools genesis-tools
+
+Developer tools for GenesisTools itself: what failed, crashed or ran slow, and who ran it.
+
+## Failure log
+
+Every tool run through `runTool` (and the few entry points without commander, through `watchToolRun`) writes one
+JSON line per failed run to `~/.genesis-tools/logs/<date>-failures.jsonl`
+(`src/utils/cli/failures/`). Kinds:
+
+| kind | when |
+|---|---|
+| `usage` | commander refused the command line: unknown option or command, missing argument, no subcommand |
+| `error` | the action threw and `runTool` printed `ERROR: …` |
+| `crash` | an uncaught exception or an unhandled rejection; `fatal: false` when another handler kept the process alive |
+| `exit` | a non-zero exit with none of the above (the tool printed its own message) |
+| `interrupt` | Ctrl-C or SIGTERM (130, 143), often a harness timeout; hidden unless `--interrupts` |
+
+Each record carries the tool, the command path, the arguments with secrets masked, the exit code, the message, the
+stack, the last 4 KB of stderr, the cwd, the pid, the run time, the app trace id when GenesisTools.app started it, the
+checkout that ran it, and the caller: agent (Claude Code, Codex, Grok, Copilot, or a shell), session id and title,
+model and effort (from the session's own transcript), project, branch and commit.
+
+## Commands
+
+```bash
+tools genesis-tools logs failures [--since 24h] [--tool git] [--kind usage,error] [--model haiku] [--agent codex]
+tools genesis-tools logs show <id>          # one failure in full, with the day-log lines of its pid
+tools genesis-tools logs stats --by tool,command,model
+tools genesis-tools logs usage              # refused command lines: where the help or an alias is missing
+tools genesis-tools logs crashes            # crash records and macOS crash reports of GenesisTools processes
+tools genesis-tools logs day --level warn --tool ai --since 2h   # the pino day log, through rg
+tools genesis-tools logs profile --min-ms 5000 --scope cli       # slow timers (tools config profiling)
+tools genesis-tools logs paths
+```
+
+Every listing takes `--json`. `--since` reads `30m`, `24h`, `7d`, `HH:MM` or `YYYY-MM-DD`.
diff --git a/src/genesis-tools/commands/logs.ts b/src/genesis-tools/commands/logs.ts
new file mode 100644
index 0000000000..efb32fe9da
--- /dev/null
+++ b/src/genesis-tools/commands/logs.ts
@@ -0,0 +1,393 @@
+import { parseVariadic } from "@genesiscz/utils/cli";
+import { FAILURE_KINDS, type FailureKind, failuresDir, type ToolFailure } from "@genesiscz/utils/cli/failures/record";
+import { formatLocalDate } from "@genesiscz/utils/date";
+import { out } from "@genesiscz/utils/logger";
+import { dayLogsDir } from "@genesiscz/utils/logger/day-logs";
+import { formatTable, truncateDisplay } from "@genesiscz/utils/table";
+import type { Command } from "commander";
+import pc from "picocolors";
+import { crashReports, crashReportsDir } from "../lib/crash-reports";
+import { LEVELS, type LevelName, levelName, queryDayLog } from "../lib/day-log";
+import { type FailureFilter, GROUP_KEYS, groupFailures, isGroupKey, loadFailures, usageGaps } from "../lib/failures";
+import { queryProfileLog } from "../lib/profile-log";
+import { daysIn, resolveWindow, type TimeWindow } from "../lib/window";
+
+interface WindowOptions {
+    since?: string;
+    until?: string;
+    json?: boolean;
+}
+
+interface FilterOptions extends WindowOptions {
+    tool?: string[];
+    kind?: string[];
+    command?: string;
+    agent?: string;
+    model?: string;
+    session?: string;
+    exit?: string[];
+    grep?: string;
+    interrupts?: boolean;
+}
+
+const KIND_COLOR: Record<FailureKind, (text: string) => string> = {
+    usage: pc.yellow,
+    error: pc.red,
+    crash: pc.magenta,
+    exit: pc.red,
+    interrupt: pc.dim,
+};
+
+function withWindow(command: Command, since = "24h"): Command {
+    return command
+        .option("--since <when>", "Start of the window: 30m, 24h, 7d, HH:MM, YYYY-MM-DD", since)
+        .option("--until <when>", "End of the window (default: now)")
+        .option("--json", "Print JSON");
+}
+
+function withFilters(command: Command): Command {
+    return withWindow(command)
+        .option("--tool <names...>", "Only these tools (comma or space separated)")
+        .option("--kind <kinds...>", `Only these kinds: ${FAILURE_KINDS.join(", ")}`)
+        .option("--command <text>", "Command path contains this (usage sessions)")
+        .option("--agent <agent>", "claude-code, codex, grok, copilot or unknown (a shell)")
+        .option("--model <text>", "Model contains this (sonnet, opus, haiku, gpt-6)")
+        .option("--session <id>", "Session id or its leading part")
+        .option("--exit <codes...>", "Only these exit codes")
+        .option("--grep <text>", "Message, arguments or stderr contain this")
+        .option("--interrupts", "Include Ctrl-C and SIGTERM endings");
+}
+
+function windowOf(options: WindowOptions): TimeWindow {
+    return resolveWindow({ since: options.since, until: options.until });
+}
+
+function filterOf(options: FilterOptions): FailureFilter {
+    const kinds = parseVariadic(options.kind);
+    const unknown = kinds.filter((kind) => !FAILURE_KINDS.some((known) => known === kind));
+    if (unknown.length > 0) {
+        throw new Error(`--kind ${unknown.join(", ")} is not a kind; use ${FAILURE_KINDS.join(", ")}`);
+    }
+
+    return {
+        kinds: FAILURE_KINDS.filter((kind) => kinds.includes(kind)),
+        tools: parseVariadic(options.tool),
+        command: options.command,
+        agent: options.agent,
+        model: options.model,
+        session: options.session,
+        exitCodes: parseVariadic(options.exit).map(Number),
+        grep: options.grep,
+        interrupts: options.interrupts === true,
+    };
+}
+
+function clock(iso: string, window: TimeWindow): string {
+    const at = new Date(iso);
+    const time = at.toTimeString().slice(0, 8);
+    return daysIn(window).length > 1 ? `${formatLocalDate(at).slice(5)} ${time}` : time;
+}
+
+/** Day-log times are UTC; a reader works in local time. */
+function localTime(iso: string, millis = false): string {
+    const at = new Date(iso);
+    const time = at.toTimeString().slice(0, 8);
+    return millis ? `${time}.${String(at.getMilliseconds()).padStart(3, "0")}` : time;
+}
+
+function who(failure: ToolFailure): string {
+    const caller = failure.caller;
+    if (!caller || caller.agent === "unknown") {
+        return "shell";
+    }
+
+    return caller.model ?? caller.agent;
+}
+
+function printFailures(failures: ToolFailure[], window: TimeWindow): void {
+    if (failures.length === 0) {
+        out.println(pc.dim("No failures in this window."));
+        return;
+    }
+
+    const rows = failures.map((failure) => [
+        pc.dim(clock(failure.at, window)),
+        KIND_COLOR[failure.kind](failure.kind),
+        failure.command ?? failure.tool,
+        String(failure.exitCode ?? "-"),
+        pc.cyan(who(failure)),
+        truncateDisplay(failure.message, 90),
+        pc.dim(failure.id),
+    ]);
+    out.println(formatTable(rows, ["TIME", "KIND", "COMMAND", "EXIT", "WHO", "MESSAGE", "ID"]));
+    out.println(pc.dim(`\n${failures.length} failures. Details: tools genesis-tools logs show <id>`));
+}
+
+function registerFailures(logs: Command): void {
+    withFilters(logs.command("failures").alias("list").description("Failed tool runs, newest last"))
+        .option("--limit <n>", "Show the newest N", "40")
+        .action((options: FilterOptions & { limit: string }) => {
+            const window = windowOf(options);
+            const failures = loadFailures({ window, filter: filterOf(options) }).slice(-Number(options.limit));
+            if (options.json) {
+                out.result(failures);
+                return;
+            }
+
+            printFailures(failures, window);
+        });
+
+    withFilters(logs.command("stats").description("Failure counts grouped by tool, kind, model and more"))
+        .option("--by <keys...>", `Group by: ${GROUP_KEYS.join(", ")}`, ["tool", "kind"])
+        .option("--top <n>", "Show the top N groups", "30")
+        .action((options: FilterOptions & { by: string[]; top: string }) => {
+            const by = parseVariadic(options.by);
+            const unknown = by.filter((key) => !isGroupKey(key));
+            if (unknown.length > 0) {
+                throw new Error(`--by ${unknown.join(", ")} is not a key; use ${GROUP_KEYS.join(", ")}`);
+            }
+
+            const ordered = by.filter(isGroupKey);
+            const failures = loadFailures({ window: windowOf(options), filter: filterOf(options) });
+            const groups = groupFailures(failures, ordered).slice(0, Number(options.top));
+            if (options.json) {
+                out.result({ total: failures.length, by: ordered, groups });
+                return;
+            }
+
+            const rows = groups.map((group) => [
+                String(group.count),
+                ...group.key.map((value) => truncateDisplay(value, 70)),
+                String(group.sessions),
+                truncateDisplay(group.models.join(", "), 40),
+                pc.dim(group.lastId),
+            ]);
+            out.println(
+                formatTable(rows, ["COUNT", ...ordered.map((key) => key.toUpperCase()), "SESSIONS", "MODELS", "LAST"])
+            );
+            out.println(pc.dim(`\n${failures.length} failures in ${groups.length} groups.`));
+        });
+
+    withFilters(logs.command("usage").description("Command lines the tools refused: where help or an alias is missing"))
+        .option("--top <n>", "Show the top N", "25")
+        .action((options: FilterOptions & { top: string }) => {
+            const gaps = usageGaps(loadFailures({ window: windowOf(options), filter: filterOf(options) })).slice(
+                0,
+                Number(options.top)
+            );
+            if (options.json) {
+                out.result(gaps);
+                return;
+            }
+
+            if (gaps.length === 0) {
+                out.println(pc.dim("No refused command lines in this window."));
+                return;
+            }
+
+            for (const gap of gaps) {
+                out.println(`${pc.bold(String(gap.count).padStart(4))}  ${pc.cyan(gap.command)}  ${gap.message}`);
+                out.println(pc.dim(`      models: ${gap.models.join(", ") || "-"}`));
+                for (const example of gap.examples) {
+                    out.println(pc.dim(`      $ ${example}`));
+                }
+            }
+        });
+}
+
+function registerShow(logs: Command): void {
+    logs.command("show")
+        .description("One failure in full, with the day-log lines its process wrote")
+        .argument("<id>", "The failure id (from the list), or its leading part")
+        .option("--since <when>", "How far back to look for the id", "7d")
+        .option("--json", "Print JSON")
+        .action(async (id: string, options: WindowOptions) => {
+            const failure = loadFailures({ window: windowOf(options), filter: { interrupts: true } })
+                .reverse()
+                .find((candidate) => candidate.id.startsWith(id));
+            if (!failure) {
+                throw new Error(`no failure with id ${id} in the last ${options.since ?? "7d"} (try --since 30d)`);
+            }
+
+            const end = new Date(failure.at);
+            const start = new Date(end.getTime() - failure.durationMs - 1000);
+            const lines = await queryDayLog({
+                window: { from: start, to: new Date(end.getTime() + 1000) },
+                pid: failure.pid,
+                limit: 200,
+            });
+            if (options.json) {
+                out.result({ failure, dayLog: lines.map((line) => line.record) });
+                return;
+            }
+
+            const caller = failure.caller;
+            const rows: Array<[string, string | null | undefined]> = [
+                ["kind", `${failure.kind}${failure.fatal ? "" : " (the process went on)"}`],
+                ["at", new Date(failure.at).toLocaleString()],
+                ["command", `tools ${failure.tool} ${failure.argv.join(" ")}`],
+                ["exit", String(failure.exitCode ?? "-")],
+                ["message", failure.message],
+                ["cwd", failure.cwd],
+                ["took", `${failure.durationMs} ms`],
+                ["pid", `${failure.pid} (parent ${failure.ppid})`],
+                ["checkout", failure.toolsRoot],
+                ["agent", caller ? `${caller.agent}${caller.aiAgent ? ` (${caller.aiAgent})` : ""}` : null],
+                ["model", caller?.model ? `${caller.model}${caller.effort ? `, effort ${caller.effort}` : ""}` : null],
+                [
+                    "session",
+                    caller?.sessionId
+                        ? `${caller.sessionId}${caller.sessionTitle ? `  ${caller.sessionTitle}` : ""}`
+                        : null,
+                ],
+                ["project", caller ? `${caller.project} @ ${caller.branch ?? "?"} ${caller.commitSha ?? ""}` : null],
+                ["app trace", failure.traceId],
+            ];
+            for (const [name, value] of rows) {
+                if (value) {
+                    out.println(`${pc.dim(name.padEnd(10))} ${value}`);
+                }
+            }
+
+            if (failure.stack) {
+                out.println(`\n${pc.bold("stack")}\n${pc.dim(failure.stack)}`);
+            }
+
+            if (failure.stderrTail) {
+                out.println(`\n${pc.bold("stderr (tail)")}\n${failure.stderrTail}`);
+            }
+
+            out.println(`\n${pc.bold(`day log, pid ${failure.pid}`)} ${pc.dim(`(${lines.length} lines)`)}`);
+            for (const line of lines) {
+                out.println(`${pc.dim(localTime(line.time, true))} ${levelName(line.level).padEnd(5)} ${line.msg}`);
+            }
+        });
+}
+
+function registerCrashes(logs: Command): void {
+    withWindow(
+        logs.command("crashes").description("Crashed tool runs and macOS crash reports of GenesisTools processes"),
+        "7d"
+    ).action((options: WindowOptions) => {
+        const window = windowOf(options);
+        const failures = loadFailures({ window, filter: { kinds: ["crash"] } });
+        const reports = crashReports(window);
+        if (options.json) {
+            out.result({ failures, reports });
+            return;
+        }
+
+        printFailures(failures, window);
+        out.println(`\n${pc.bold("macOS crash reports")} ${pc.dim(crashReportsDir())}`);
+        if (reports.length === 0) {
+            out.println(pc.dim("None in this window."));
+        }
+
+        for (const report of reports) {
+            out.println(`${pc.dim(clock(report.at, window))}  ${report.process}  ${pc.dim(report.path)}`);
+        }
+    });
+}
+
+function registerDay(logs: Command): void {
+    withWindow(logs.command("day").description("The day log (every tool's pino records), filtered"), "1h")
+        .option("--level <level>", `Lowest level: ${Object.keys(LEVELS).join(", ")}`, "warn")
+        .option("--tool <name>", "Only records of this tool")
+        .option("--pid <pid>", "Only records of this process")
+        .option("--grep <text>", "The record contains this")
+        .option("--limit <n>", "Show the newest N", "100")
+        .action(
+            async (
+                options: WindowOptions & { level: string; tool?: string; pid?: string; grep?: string; limit: string }
+            ) => {
+                const minLevel = LEVELS[options.level as LevelName];
+                if (minLevel === undefined) {
+                    throw new Error(`--level ${options.level} is not a level; use ${Object.keys(LEVELS).join(", ")}`);
+                }
+
+                const entries = await queryDayLog({
+                    window: windowOf(options),
+                    minLevel,
+                    tool: options.tool,
+                    pid: options.pid ? Number(options.pid) : undefined,
+                    grep: options.grep,
+                    limit: Number(options.limit),
+                });
+                if (options.json) {
+                    out.result(entries.map((entry) => entry.record));
+                    return;
+                }
+
+                for (const entry of entries) {
+                    const level = levelName(entry.level);
+                    const color =
+                        entry.level >= LEVELS.error ? pc.red : entry.level >= LEVELS.warn ? pc.yellow : pc.dim;
+                    out.println(
+                        `${pc.dim(localTime(entry.time))} ${color(level.padEnd(5))} ${pc.cyan((entry.tool ?? "-").padEnd(14))} ${pc.dim(String(entry.pid ?? "").padStart(6))} ${entry.msg}`
+                    );
+                }
+
+                out.println(pc.dim(`\n${entries.length} records.`));
+            }
+        );
+}
+
+function registerProfile(logs: Command): void {
+    withWindow(
+        logs.command("profile").description("Slow timers from the profiling log (tools config profiling)"),
+        "24h"
+    )
+        .option("--min-ms <ms>", "Only timers at least this long", "1000")
+        .option("--scope <scopes...>", "Only these scopes (cli, spawn, agent-sessions, …)")
+        .option("--grep <text>", "The label contains this")
+        .option("--pid <pid>", "Only this process")
+        .option("--top <n>", "Show the slowest N", "40")
+        .action(
+            (
+                options: WindowOptions & { minMs: string; scope?: string[]; grep?: string; pid?: string; top: string }
+            ) => {
+                const entries = queryProfileLog({
+                    days: daysIn(windowOf(options)),
+                    minMs: Number(options.minMs),
+                    scopes: parseVariadic(options.scope),
+                    grep: options.grep,
+                    pid: options.pid ? Number(options.pid) : undefined,
+                })
+                    .sort((a, b) => b.ms - a.ms)
+                    .slice(0, Number(options.top));
+                if (options.json) {
+                    out.result(entries);
+                    return;
+                }
+
+                const rows = entries.map((entry) => [
+                    `${(entry.ms / 1000).toFixed(2)} s`,
+                    entry.scope,
+                    truncateDisplay(entry.label, 100),
+                    String(entry.pid),
+                    pc.dim(entry.day),
+                ]);
+                out.println(formatTable(rows, ["TIME", "SCOPE", "LABEL", "PID", "DAY"]));
+            }
+        );
+}
+
+export function registerLogsCommand(program: Command): void {
+    const logs = program
+        .command("logs")
+        .description("Failures, crashes, the day log and profiling of every GenesisTools tool");
+    registerFailures(logs);
+    registerShow(logs);
+    registerCrashes(logs);
+    registerDay(logs);
+    registerProfile(logs);
+    logs.command("paths")
+        .description("Where each log lives")
+        .action(() => {
+            const day = formatLocalDate(new Date());
+            out.println(`failures   ${failuresDir()}/${day}-failures.jsonl`);
+            out.println(`day log    ${dayLogsDir()}/${day}.log`);
+            out.println(`profiling  ${dayLogsDir()}/${day}-profiling.log`);
+            out.println(`crashes    ${crashReportsDir()}`);
+        });
+}
diff --git a/src/genesis-tools/index.ts b/src/genesis-tools/index.ts
new file mode 100644
index 0000000000..2ab17a6b6c
--- /dev/null
+++ b/src/genesis-tools/index.ts
@@ -0,0 +1,14 @@
+#!/usr/bin/env bun
+import { runTool } from "@genesiscz/utils/cli";
+import { Command } from "commander";
+import { registerLogsCommand } from "./commands/logs";
+
+const program = new Command()
+    .name("genesis-tools")
+    .description("Developer tools for GenesisTools itself: what failed, crashed or ran slow, and who ran it");
+
+registerLogsCommand(program);
+
+if (import.meta.main) {
+    await runTool(program, { tool: "genesis-tools" });
+}
diff --git a/src/genesis-tools/lib/crash-reports.ts b/src/genesis-tools/lib/crash-reports.ts
new file mode 100644
index 0000000000..2ed9203c40
--- /dev/null
+++ b/src/genesis-tools/lib/crash-reports.ts
@@ -0,0 +1,37 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { TimeWindow } from "./window";
+
+/** The processes GenesisTools runs as: the app's faces, the Genesis apps, and bun under every `tools` command. */
+const OURS = /^(GenesisTools|Genesis|Genesis Markdown|GenesisTools Preview|bun)[-_ ].*\.ips$/;
+
+export interface CrashReport {
+    path: string;
+    process: string;
+    at: string;
+}
+
+export function crashReportsDir(home = homedir()): string {
+    return join(home, "Library", "Logs", "DiagnosticReports");
+}
+
+/** macOS crash and hang reports of GenesisTools processes written inside the window, newest first. */
+export function crashReports(window: TimeWindow, dir = crashReportsDir()): CrashReport[] {
+    if (!existsSync(dir)) {
+        return [];
+    }
+
+    return readdirSync(dir)
+        .filter((name) => OURS.test(name))
+        .flatMap((name): CrashReport[] => {
+            const path = join(dir, name);
+            const mtime = statSync(path).mtime;
+            if (mtime < window.from || mtime > window.to) {
+                return [];
+            }
+
+            return [{ path, process: name.replace(/[-_ ]\d{4}-\d{2}-\d{2}.*$/, ""), at: mtime.toISOString() }];
+        })
+        .sort((a, b) => b.at.localeCompare(a.at));
+}
diff --git a/src/genesis-tools/lib/day-log.ts b/src/genesis-tools/lib/day-log.ts
new file mode 100644
index 0000000000..488ee461c1
--- /dev/null
+++ b/src/genesis-tools/lib/day-log.ts
@@ -0,0 +1,154 @@
+import { ripgrepFiles } from "@genesiscz/utils/compress/search";
+import { readLinesSync } from "@genesiscz/utils/fs/read-lines";
+import { SafeJSON } from "@genesiscz/utils/json";
+import { logger } from "@genesiscz/utils/logger";
+import { listDayLogs } from "@genesiscz/utils/logger/day-logs";
+import { ripgrepBinary } from "@genesiscz/utils/ripgrep";
+import { daysIn, inWindow, type TimeWindow } from "./window";
+
+export const LEVELS = { trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60 } as const;
+export type LevelName = keyof typeof LEVELS;
+
+export function levelName(level: number): string {
+    const found = Object.entries(LEVELS).find(([, value]) => value === level);
+    return found ? found[0] : String(level);
+}
+
+export interface DayLogQuery {
+    window: TimeWindow;
+    minLevel?: number;
+    tool?: string;
+    pid?: number;
+    /** Case-insensitive substring of the whole record. */
+    grep?: string;
+    /** The newest N matching records. */
+    limit?: number;
+}
+
+export interface DayLogEntry {
+    time: string;
+    level: number;
+    pid: number | null;
+    tool: string | null;
+    msg: string;
+    record: Record<string, unknown>;
+}
+
+export function parseDayLogLine(line: string): DayLogEntry | null {
+    if (!line.startsWith("{")) {
+        return null;
+    }
+
+    let parsed: unknown;
+    try {
+        parsed = SafeJSON.parse(line, { strict: true });
+    } catch (error) {
+        logger.debug({ error }, "day log: a line did not parse");
+        return null;
+    }
+
+    if (typeof parsed !== "object" || parsed === null) {
+        return null;
+    }
+
+    const record = parsed as Record<string, unknown>;
+    if (typeof record.time !== "string" || typeof record.level !== "number") {
+        return null;
+    }
+
+    return {
+        time: record.time,
+        level: record.level,
+        pid: typeof record.pid === "number" ? record.pid : null,
+        tool: typeof record.tool === "string" ? record.tool : null,
+        msg: typeof record.msg === "string" ? record.msg : "",
+        record,
+    };
+}
+
+export function matchesDayLog(entry: DayLogEntry, query: DayLogQuery, line: string): boolean {
+    if (!inWindow(entry.time, query.window)) {
+        return false;
+    }
+
+    if (query.minLevel !== undefined && entry.level < query.minLevel) {
+        return false;
+    }
+
+    if (query.tool && entry.tool !== query.tool) {
+        return false;
+    }
+
+    if (query.pid !== undefined && entry.pid !== query.pid) {
+        return false;
+    }
+
+    return !query.grep || line.toLowerCase().includes(query.grep.toLowerCase());
+}
+
+/**
+ * The cheapest fixed string every wanted line must hold, so rg reads the day log (often 200 MB or more) instead
+ * of a JSON parse per line. Null when no filter narrows it.
+ */
+export function prefilterFor(query: DayLogQuery): { pattern: string; fixed: boolean } | null {
+    if (query.pid !== undefined) {
+        return { pattern: `"pid":${query.pid},`, fixed: true };
+    }
+
+    if (query.tool) {
+        return { pattern: `"tool":${SafeJSON.stringify(query.tool)}`, fixed: true };
+    }
+
+    if (query.minLevel !== undefined && query.minLevel >= LEVELS.warn) {
+        const levels = Object.values(LEVELS).filter((level) => level >= (query.minLevel ?? 0));
+        return { pattern: `"level":(${levels.join("|")})[,}]`, fixed: false };
+    }
+
+    if (query.grep) {
+        return { pattern: query.grep, fixed: true };
+    }
+
+    return null;
+}
+
+async function candidateLines(files: string[], query: DayLogQuery): Promise<string[]> {
+    const prefilter = prefilterFor(query);
+    const rg = ripgrepBinary();
+
+    if (!prefilter || !rg) {
+        if (prefilter) {
+            logger.debug("day log: rg is not on PATH, reading every line");
+        }
+
+        return files.flatMap((file) => [...readLinesSync(file)]);
+    }
+
+    const args = ["--no-config", "--no-filename", "--no-line-number", ...(prefilter.fixed ? ["-F", "-i"] : [])];
+    const run = await ripgrepFiles({ rg, args: [...args, "-e", prefilter.pattern], files, timeoutMs: 120_000 });
+    if (run.signal || run.code > 1) {
+        throw new Error(`rg over the day logs failed (${run.signal ?? `exit ${run.code}`}): ${run.stderr.trim()}`);
+    }
+
+    return run.stdout.split("\n");
+}
+
+/** The newest `limit` matching records, oldest first. */
+export async function queryDayLog(query: DayLogQuery): Promise<DayLogEntry[]> {
+    const days = new Set(daysIn(query.window));
+    const files = listDayLogs()
+        .filter((file) => days.has(file.day))
+        .sort((a, b) => a.day.localeCompare(b.day))
+        .map((file) => file.path);
+    logger.debug({ files, prefilter: prefilterFor(query) }, "day log: query");
+
+    const found: DayLogEntry[] = [];
+    for (const line of await candidateLines(files, query)) {
+        const entry = parseDayLogLine(line);
+        if (entry && matchesDayLog(entry, query, line)) {
+            found.push(entry);
+        }
+    }
+
+    found.sort((a, b) => a.time.localeCompare(b.time));
+    return query.limit ? found.slice(-query.limit) : found;
+}
diff --git a/src/genesis-tools/lib/failures.ts b/src/genesis-tools/lib/failures.ts
new file mode 100644
index 0000000000..8f14e7b708
--- /dev/null
+++ b/src/genesis-tools/lib/failures.ts
@@ -0,0 +1,205 @@
+import { type FailureKind, readFailures, type ToolFailure } from "@genesiscz/utils/cli/failures/record";
+import { formatLocalDate } from "@genesiscz/utils/date";
+import { daysIn, inWindow, type TimeWindow } from "./window";
+
+export interface FailureFilter {
+    kinds?: FailureKind[];
+    tools?: string[];
+    /** Substring of the command path (`usage sessions`). */
+    command?: string;
+    /** `claude-code`, `codex`, `grok`, `unknown` (a shell). */
+    agent?: string;
+    /** Substring of the model, case-insensitive (`sonnet`, `opus-5`, `gpt-6`). */
+    model?: string;
+    /** A session id or its leading part. */
+    session?: string;
+    exitCodes?: number[];
+    /** Substring of the message, the arguments or the stderr tail, case-insensitive. */
+    grep?: string;
+    /** Interrupts (Ctrl-C, SIGTERM) are left out unless asked for. */
+    interrupts?: boolean;
+}
+
+export function matchesFailure(failure: ToolFailure, filter: FailureFilter): boolean {
+    if (filter.kinds?.length) {
+        if (!filter.kinds.includes(failure.kind)) {
+            return false;
+        }
+    } else if (!filter.interrupts && failure.kind === "interrupt") {
+        return false;
+    }
+
+    if (filter.tools?.length && !filter.tools.includes(failure.tool)) {
+        return false;
+    }
+
+    if (filter.command && !(failure.command ?? "").includes(filter.command)) {
+        return false;
+    }
+
+    if (filter.agent && (failure.caller?.agent ?? "unknown") !== filter.agent) {
+        return false;
+    }
+
+    if (filter.model && !(failure.caller?.model ?? "").toLowerCase().includes(filter.model.toLowerCase())) {
+        return false;
+    }
+
+    if (filter.session && !(failure.caller?.sessionId ?? "").startsWith(filter.session)) {
+        return false;
+    }
+
+    if (filter.exitCodes?.length && !filter.exitCodes.includes(failure.exitCode ?? -1)) {
+        return false;
+    }
+
+    if (filter.grep) {
+        const needle = filter.grep.toLowerCase();
+        const haystack = [failure.message ?? "", failure.argv.join(" "), failure.stderrTail ?? ""].join("\n");
+        if (!haystack.toLowerCase().includes(needle)) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/** The failures in the window that pass the filter, oldest first. */
+export function loadFailures({
+    window,
+    filter = {},
+    dir,
+}: {
+    window: TimeWindow;
+    filter?: FailureFilter;
+    dir?: string;
+}): ToolFailure[] {
+    const days = daysIn(window);
+    const found: ToolFailure[] = [];
+
+    for (const failure of readFailures({ fromDay: days[0], toDay: days.at(-1) ?? days[0], dir })) {
+        if (inWindow(failure.at, window) && matchesFailure(failure, filter)) {
+            found.push(failure);
+        }
+    }
+
+    return found;
+}
+
+export const GROUP_KEYS = ["tool", "kind", "command", "model", "agent", "message", "exit", "day", "session"] as const;
+export type GroupKey = (typeof GROUP_KEYS)[number];
+
+export function isGroupKey(value: string): value is GroupKey {
+    return GROUP_KEYS.some((key) => key === value);
+}
+
+function keyOf(failure: ToolFailure, by: GroupKey): string {
+    switch (by) {
+        case "tool":
+            return failure.tool;
+        case "kind":
+            return failure.kind;
+        case "command":
+            return failure.command ?? failure.tool;
+        case "model":
+            return failure.caller?.model ?? "(none)";
+        case "agent":
+            return failure.caller?.agent ?? "unknown";
+        case "message":
+            return failure.message ?? "(no message)";
+        case "exit":
+            return String(failure.exitCode ?? "-");
+        case "day":
+            return formatLocalDate(new Date(failure.at));
+        case "session":
+            return failure.caller?.sessionId ?? "(none)";
+    }
+}
+
+export interface FailureGroup {
+    key: string[];
+    count: number;
+    lastAt: string;
+    lastId: string;
+    models: string[];
+    sessions: number;
+}
+
+/** Counts by the given keys, most frequent first. */
+export function groupFailures(failures: ToolFailure[], by: GroupKey[]): FailureGroup[] {
+    const groups = new Map<string, FailureGroup & { sessionIds: Set<string> }>();
+
+    for (const failure of failures) {
+        const key = by.map((name) => keyOf(failure, name));
+        const id = key.join("\u0000");
+        const group = groups.get(id) ?? {
+            key,
+            count: 0,
+            lastAt: failure.at,
+            lastId: failure.id,
+            models: [],
+            sessions: 0,
+            sessionIds: new Set<string>(),
+        };
+        group.count++;
+        if (failure.at >= group.lastAt) {
+            group.lastAt = failure.at;
+            group.lastId = failure.id;
+        }
+
+        const model = failure.caller?.model;
+        if (model && !group.models.includes(model)) {
+            group.models.push(model);
+        }
+
+        if (failure.caller?.sessionId) {
+            group.sessionIds.add(failure.caller.sessionId);
+        }
+
+        groups.set(id, group);
+    }
+
+    return [...groups.values()]
+        .map(({ sessionIds, ...group }) => ({ ...group, sessions: sessionIds.size }))
+        .sort((a, b) => b.count - a.count || b.lastAt.localeCompare(a.lastAt));
+}
+
+export interface UsageGap {
+    tool: string;
+    command: string;
+    message: string;
+    count: number;
+    models: string[];
+    /** Up to three distinct command lines that hit it, newest first. */
+    examples: string[];
+}
+
+/**
+ * The command lines tools refused, grouped by what they refused: each row is a place where the help, an alias or a
+ * clearer error would have saved a retry. Agents' misuses count the same as a person's.
+ */
+export function usageGaps(failures: ToolFailure[]): UsageGap[] {
+    const usage = failures.filter((failure) => failure.kind === "usage");
+    const gaps = new Map<string, UsageGap>();
+
+    for (const failure of [...usage].reverse()) {
+        const command = failure.command ?? failure.tool;
+        const message = failure.message ?? "(no message)";
+        const id = `${command}\u0000${message}`;
+        const gap = gaps.get(id) ?? { tool: failure.tool, command, message, count: 0, models: [], examples: [] };
+        gap.count++;
+        const model = failure.caller?.model;
+        if (model && !gap.models.includes(model)) {
+            gap.models.push(model);
+        }
+
+        const example = `tools ${failure.tool} ${failure.argv.join(" ")}`.trim();
+        if (gap.examples.length < 3 && !gap.examples.includes(example)) {
+            gap.examples.push(example);
+        }
+
+        gaps.set(id, gap);
+    }
+
+    return [...gaps.values()].sort((a, b) => b.count - a.count);
+}
diff --git a/src/genesis-tools/lib/logs.test.ts b/src/genesis-tools/lib/logs.test.ts
new file mode 100644
index 0000000000..37383883ce
--- /dev/null
+++ b/src/genesis-tools/lib/logs.test.ts
@@ -0,0 +1,152 @@
+import { describe, expect, it } from "bun:test";
+import type { FailureCaller, ToolFailure } from "@genesiscz/utils/cli/failures/record";
+import { matchesDayLog, parseDayLogLine, prefilterFor } from "./day-log";
+import { groupFailures, matchesFailure, usageGaps } from "./failures";
+import { parseProfileLine } from "./profile-log";
+import { daysIn, resolveWindow } from "./window";
+
+const NOW = new Date(2026, 9, 22, 16, 0);
+
+function caller(model: string | null, sessionId: string | null): FailureCaller {
+    return {
+        agent: sessionId ? "claude-code" : "unknown",
+        sessionId,
+        sessionTitle: null,
+        model,
+        effort: null,
+        aiAgent: null,
+        project: "app",
+        repoRoot: "/repo",
+        branch: "main",
+        commitSha: null,
+        worktreePath: null,
+    };
+}
+
+function failure(overrides: Partial<ToolFailure>): ToolFailure {
+    return {
+        v: 1,
+        id: "x",
+        at: NOW.toISOString(),
+        kind: "usage",
+        tool: "git",
+        command: "git base",
+        argv: ["base", "--repo", "."],
+        exitCode: 1,
+        message: "error: unknown option '--repo'",
+        errorName: null,
+        stack: null,
+        stderrTail: null,
+        fatal: true,
+        durationMs: 100,
+        pid: 1,
+        ppid: 0,
+        cwd: "/repo",
+        traceId: null,
+        toolsRoot: "/repo",
+        caller: caller("claude-sonnet-5-5", "s-111"),
+        ...overrides,
+    };
+}
+
+describe("window", () => {
+    it("reads relative and clock times and lists every day it touches", () => {
+        const window = resolveWindow({ since: "2d", now: NOW });
+        expect(window.from).toEqual(new Date(2026, 9, 20, 16, 0));
+        expect(daysIn(window)).toEqual(["2026-10-20", "2026-10-21", "2026-10-22"]);
+        expect(resolveWindow({ since: "09:30", now: NOW }).from).toEqual(new Date(2026, 9, 22, 9, 30));
+        expect(() => resolveWindow({ since: "soon", now: NOW })).toThrow("--since soon is not a time");
+    });
+});
+
+describe("failure filters and groups", () => {
+    const rows = [
+        failure({ id: "a" }),
+        failure({ id: "b", caller: caller("claude-haiku-5-5", "s-222") }),
+        failure({ id: "c", kind: "interrupt", exitCode: 130, message: null }),
+        failure({
+            id: "d",
+            kind: "error",
+            tool: "ts",
+            command: "ts skeleton",
+            argv: ["skeleton", "src"],
+            message: "boom",
+            caller: caller(null, null),
+        }),
+    ];
+
+    it("leaves interrupts out unless asked and matches model by substring", () => {
+        expect(rows.filter((row) => matchesFailure(row, {})).map((row) => row.id)).toEqual(["a", "b", "d"]);
+        expect(rows.filter((row) => matchesFailure(row, { interrupts: true })).length).toBe(4);
+        expect(rows.filter((row) => matchesFailure(row, { model: "HAIKU" })).map((row) => row.id)).toEqual(["b"]);
+        expect(rows.filter((row) => matchesFailure(row, { agent: "unknown" })).map((row) => row.id)).toEqual(["d"]);
+        expect(rows.filter((row) => matchesFailure(row, { grep: "--repo" })).map((row) => row.id)).toEqual(["a", "b"]);
+    });
+
+    it("counts groups and the sessions and models in each", () => {
+        const groups = groupFailures(rows.slice(0, 2).concat(rows[3]), ["tool", "kind"]);
+        expect(groups.map((group) => [group.key, group.count, group.sessions, group.models])).toEqual([
+            [["git", "usage"], 2, 2, ["claude-sonnet-5-5", "claude-haiku-5-5"]],
+            [["ts", "error"], 1, 0, []],
+        ]);
+    });
+
+    it("groups refused command lines by what was refused, with examples", () => {
+        expect(usageGaps(rows)).toEqual([
+            {
+                tool: "git",
+                command: "git base",
+                message: "error: unknown option '--repo'",
+                count: 2,
+                models: ["claude-haiku-5-5", "claude-sonnet-5-5"],
+                examples: ["tools git base --repo ."],
+            },
+        ]);
+    });
+});
+
+describe("day log", () => {
+    const line = '{"level":50,"time":"2026-10-22T13:00:00.000Z","pid":42,"tool":"ai","msg":"[cmux] command failed"}';
+    const window = { from: new Date("2026-10-22T12:00:00Z"), to: new Date("2026-10-22T14:00:00Z") };
+
+    it("parses a pino line and filters by level, tool, pid and text", () => {
+        const entry = parseDayLogLine(line);
+        expect(entry && [entry.level, entry.pid, entry.tool, entry.msg]).toEqual([
+            50,
+            42,
+            "ai",
+            "[cmux] command failed",
+        ]);
+        if (!entry) {
+            return;
+        }
+
+        expect(matchesDayLog(entry, { window, minLevel: 40, tool: "ai", pid: 42, grep: "CMUX" }, line)).toBe(true);
+        expect(matchesDayLog(entry, { window, minLevel: 60 }, line)).toBe(false);
+        expect(matchesDayLog(entry, { window: { from: window.to, to: window.to } }, line)).toBe(false);
+        expect(parseDayLogLine("not json")).toBeNull();
+    });
+
+    it("picks the narrowest rg prefilter, and none for a plain window", () => {
+        expect(prefilterFor({ window, pid: 42, tool: "ai" })).toEqual({ pattern: '"pid":42,', fixed: true });
+        expect(prefilterFor({ window, minLevel: 50 })).toEqual({ pattern: '"level":(50|60)[,}]', fixed: false });
+        expect(prefilterFor({ window, minLevel: 30 })).toBeNull();
+    });
+});
+
+describe("profile log", () => {
+    it("reads milliseconds, seconds and a trace id, and skips a summary line", () => {
+        expect(
+            parseProfileLine("[profile:cli] claude info exit=0 cpu=254ms rss=78MB caller=shell 160.03ms pid=16615", "d")
+        ).toEqual({
+            day: "d",
+            scope: "cli",
+            label: "claude info exit=0 cpu=254ms rss=78MB caller=shell",
+            ms: 160.03,
+            traceId: null,
+            pid: 16615,
+        });
+        expect(parseProfileLine("[profile:agent-sessions] walk 1.5s trace=2e100b3a pid=9", "d")?.ms).toBe(1500);
+        expect(parseProfileLine("── cli ──", "d")).toBeNull();
+    });
+});
diff --git a/src/genesis-tools/lib/profile-log.ts b/src/genesis-tools/lib/profile-log.ts
new file mode 100644
index 0000000000..f800a21691
--- /dev/null
+++ b/src/genesis-tools/lib/profile-log.ts
@@ -0,0 +1,73 @@
+import { readLinesSync } from "@genesiscz/utils/fs/read-lines";
+import { listDayLogs } from "@genesiscz/utils/logger/day-logs";
+
+export interface ProfileEntry {
+    day: string;
+    scope: string;
+    /** The label with its details, `hub widget watch exit=0 cpu=… caller=app`. */
+    label: string;
+    ms: number;
+    traceId: string | null;
+    pid: number;
+}
+
+const LINE = /^\[profile:([\w.-]+)\] (.*) (\d+(?:\.\d+)?)(ms|s)(?: trace=(\S+))? pid=(\d+)$/;
+
+/** `[profile:<scope>] <label> <duration>(ms|s) [trace=<id>] pid=<n>`; a summary table or a wrapped label is null. */
+export function parseProfileLine(line: string, day: string): ProfileEntry | null {
+    const match = LINE.exec(line);
+    if (!match) {
+        return null;
+    }
+
+    const value = Number(match[3]);
+    return {
+        day,
+        scope: match[1],
+        label: match[2],
+        ms: match[4] === "s" ? value * 1000 : value,
+        traceId: match[5] ?? null,
+        pid: Number(match[6]),
+    };
+}
+
+export interface ProfileQuery {
+    days: string[];
+    minMs?: number;
+    scopes?: string[];
+    /** Case-insensitive substring of the label. */
+    grep?: string;
+    pid?: number;
+    /** `@name` lines are marks (a point in time since the process started), not durations. */
+    marks?: boolean;
+}
+
+export function queryProfileLog(query: ProfileQuery): ProfileEntry[] {
+    const wanted = new Set(query.days);
+    const found: ProfileEntry[] = [];
+    const needle = query.grep?.toLowerCase();
+
+    for (const file of listDayLogs({ profiling: true })) {
+        if (!wanted.has(file.day)) {
+            continue;
+        }
+
+        for (const line of readLinesSync(file.path)) {
+            const entry = parseProfileLine(line, file.day);
+            if (
+                !entry ||
+                (query.minMs !== undefined && entry.ms < query.minMs) ||
+                (query.scopes?.length && !query.scopes.includes(entry.scope)) ||
+                (needle && !entry.label.toLowerCase().includes(needle)) ||
+                (query.pid !== undefined && entry.pid !== query.pid) ||
+                (!query.marks && entry.label.startsWith("@"))
+            ) {
+                continue;
+            }
+
+            found.push(entry);
+        }
+    }
+
+    return found;
+}
diff --git a/src/genesis-tools/lib/window.ts b/src/genesis-tools/lib/window.ts
new file mode 100644
index 0000000000..dc522fa2dc
--- /dev/null
+++ b/src/genesis-tools/lib/window.ts
@@ -0,0 +1,58 @@
+import { formatLocalDate, parseSince } from "@genesiscz/utils/date";
+import { parseDuration } from "@genesiscz/utils/format";
+
+export interface TimeWindow {
+    from: Date;
+    to: Date;
+}
+
+/** `24h`, `7d`, `90m` back from now; else what `parseSince` reads (`HH:MM`, a date, an ISO time). */
+export function parsePointInTime(value: string, now: Date): Date | null {
+    const relative = /^\d+\s*[a-z]/i.test(value.trim()) ? parseDuration(value) : 0;
+    if (relative > 0) {
+        return new Date(now.getTime() - relative);
+    }
+
+    return parseSince(value, now);
+}
+
+export function resolveWindow({
+    since = "24h",
+    until,
+    now = new Date(),
+}: {
+    since?: string;
+    until?: string;
+    now?: Date;
+}): TimeWindow {
+    const from = parsePointInTime(since, now);
+    if (!from) {
+        throw new Error(`--since ${since} is not a time: use 30m, 24h, 7d, HH:MM or YYYY-MM-DD`);
+    }
+
+    const to = until ? parsePointInTime(until, now) : now;
+    if (!to) {
+        throw new Error(`--until ${until} is not a time: use 30m, 24h, 7d, HH:MM or YYYY-MM-DD`);
+    }
+
+    return { from, to };
+}
+
+/** Every local calendar day the window touches, oldest first. */
+export function daysIn(window: TimeWindow): string[] {
+    const days: string[] = [];
+    const cursor = new Date(window.from);
+    cursor.setHours(12, 0, 0, 0);
+
+    while (formatLocalDate(cursor) <= formatLocalDate(window.to)) {
+        days.push(formatLocalDate(cursor));
+        cursor.setDate(cursor.getDate() + 1);
+    }
+
+    return days;
+}
+
+export function inWindow(at: string, window: TimeWindow): boolean {
+    const time = Date.parse(at);
+    return time >= window.from.getTime() && time <= window.to.getTime();
+}

From 9ff042d53fa668f38ed66fd9c17a2e547089611a Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 16:55:48 +0200
Subject: [PATCH 08/30] docs(tools): the failures log and tools genesis-tools
 logs are where triage starts, and an entry without commander calls
 watchToolRun

---
 .claude/rules/tools.md | 4 ++--
 CLAUDE.md              | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.claude/rules/tools.md b/.claude/rules/tools.md
index e25f0acf3d..fccd95fc2f 100644
--- a/.claude/rules/tools.md
+++ b/.claude/rules/tools.md
@@ -109,7 +109,7 @@ When spawning tools from shell hooks, always background (`&`) — 86ms Bun start
 
 ## Debugging & Logging
 
-- **Triage from logs first.** When any tool misbehaves, the FIRST step is to read `~/.genesis-tools/logs/<today>.log` (and recent days) and `rg` for the tool name / error string — *before* forming hypotheses or reproducing. Logs are day-stamped pino JSON. This bug (`sqlite-vec extension failed to load`) was in the logs for weeks before it was triaged; checking them first collapses hours of guessing into one `rg`.
+- **Triage from logs first.** When any tool misbehaves, the FIRST step is to read `~/.genesis-tools/logs/<today>.log` (and recent days) and `rg` for the tool name / error string — *before* forming hypotheses or reproducing. Logs are day-stamped pino JSON. This bug (`sqlite-vec extension failed to load`) was in the logs for weeks before it was triaged; checking them first collapses hours of guessing into one `rg`. `tools genesis-tools logs failures` lists the failed runs (each with its stderr tail and caller), `logs day --level warn --tool <name>` filters the day log through rg, and `logs profile` lists slow timers.
 - **Days older than a week are compressed.** The daily pass (started by the logger once a day, `src/utils/logger/daily-trigger.ts`) stores `<date>.log` and `<date>-profiling.log` older than 7 days as `<name>.zst`. Search one with `rg -z <pattern> <file>.zst` (rg runs the `zstd` CLI) or `tools compress cat <file>.zst | rg <pattern>` (no CLI needed); `rg -z` also reads plain files, so `rg -z <pattern> ~/.genesis-tools/logs/2026-10-0*` covers both. Code that reads day logs goes through `dayLogPath` / `listDayLogs` (`@genesiscz/utils/logger/day-logs`) and the readers in `@genesiscz/utils/fs/read-lines`, which open either form; never build `<date>.log` by hand. Details: `.claude/rules/compress.md`.
 - **Profiling lines live in their own file:** `~/.genesis-tools/logs/<date>-profiling.log` (e.g. `2026-09-03-profiling.log`), one `[profile:<scope>] <label> <ms>` line per measurement plus a `── <title> ──` summary table per scope. Enable per run with `PROFILE=1`, `PROFILE=*` or `PROFILE=<scope,scope>` (scope names in `src/utils/profile/scopes.ts`); an env `PROFILE` also echoes to stderr, `PROFILE_TO_STDERR=0` silences that. Persistent profiling comes from `tools config profiling`.
 - **To ADD a measurement, use the shared profiler, never a hand-rolled `performance.now()` pair.** `import { profiler } from "@genesiscz/utils/profile"`, then one module-level `const prof = profiler.scope("<scope>")` (see `src/du/lib/engine.ts:21`). Verbs: `prof.measure(label, fn)` / `prof.measureAsync(label, fn)` wrap a call, `prof.start(label)` returns a stop function, `prof.section(label)` works with `using`, `prof.mark(label)` records a point in time, `prof.summary(title)` prints the table at the end. A disabled scope is a no-op, so a timer may sit in a hot path; put only work you would not otherwise do behind `prof.enabled`, and hide per-file or per-item timers behind `profiler.detail === "all"` so `--detail phases` stays readable. **A new scope name must be added to `PROFILER_SCOPE_NAMES` in `src/utils/profile/scopes.ts`**, or `--scopes` cannot offer it and `PROFILE=<name>` is a guess.
@@ -125,7 +125,7 @@ Two cleanly separated layers (the 2026-05 logger+out overhaul):
 - **`logger` — diagnostics.** `import { logger } from "@genesiscz/utils/logger"` (named only; there is **no** default export and no `consoleLog` — they were removed). Writes to the day-stamped file **always** (debug+), and to the console **on stderr**, gated by level. `logger.*` is **never** the result channel. Global `-v` promotes file-only `logger.debug` to the console; `-vv` → trace (only on tools that opted into `--trace`).
 - **`out` — user-facing.** `import { out } from "@genesiscz/utils/logger"` (or `const { log, out } = logger.scoped("comp")`). clack-shaped. **`out.result(data)` / `out.print(raw)` are the ONLY writers to stdout** (the machine result). `out.log.*` / spinners / notes / prompts → stderr. Never emit a serialized result via `logger.*` — that is `out.result()`'s job (CI guard enforces this).
 - **`const { log, out } = logger.scoped("comp")`:** `log.*` = logger-only (diagnostics); `log.out.*` / `log.tee.*` = both (component-tagged single mirror); destructured `out.*` = only-out (no logger mirror).
-- **Every commander entrypoint** ends with `await runTool(program, { tool })` (from `@genesiscz/utils/cli`) — it owns `-v`/`--readme`/help registration, console-level resolution, and the `{tool}` log binding, then `parseAsync`. The subprocess **spawner** is `execTool` (renamed from the old `runTool`).
+- **Every commander entrypoint** ends with `await runTool(program, { tool })` (from `@genesiscz/utils/cli`) — it owns `-v`/`--readme`/help registration, console-level resolution, and the `{tool}` log binding, then `parseAsync`. It also records each failed run into the failures log (`src/utils/cli/failures/`); an entry point without commander calls `watchToolRun({ tool })` itself and `noteUsageError(message)` when its own parser refuses the command line. The subprocess **spawner** is `execTool` (renamed from the old `runTool`).
 - **`scripts/ci/logging-guard.sh`** enforces this convention repo-wide in CI: no default/extension/relative-path/any-name import of the logger module (root `./tools` and `scripts/` included — not just `src/`), no bare `logger.*(SafeJSON.stringify(…))` result dumps, no reintroduced transitional shims, and that the browser-client isolation test exists. Browser-client trees never value-importing `@genesiscz/utils/logger` is authoritatively enforced by `src/logger/client-isolation.test.ts`.
 - **`@genesiscz/utils/cli/ui` — high-density CLI status.** For tools that emit many short status lines per command (e.g. `tools stash`), clack's `│ ◆ ●` box-drawing is the wrong texture. Import `{ ui }` from `@genesiscz/utils/cli/ui` to get plain stderr writes with chalk decoration (`ui.ok/info/warn/err/dim/header/kv/section/raw`). Use this INSTEAD of `out.log.*` for high-density status; keep `out.log.*` for clack-shaped task lifecycles. `out.print()` / `out.result()` are still the only writers to stdout for machine-readable output.
 - **CLI inventory tables (port-style) — prefer this for multi-column human output.** Canonical helpers live in `@genesiscz/utils/table` (not reimplemented per tool). Reference UIs: `tools port`, `tools ai-proxy models`, `tools macos swap`.
diff --git a/CLAUDE.md b/CLAUDE.md
index e2ddad716d..86a98a8be1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -60,7 +60,7 @@ Skipping any of these has cost real sessions hours; there are no exceptions.
 - `~/.genesis-tools/claude-history/index.db` holds Claude, Codex and Grok history, plus historical `usage_snapshots` and `spend_snapshots`. Never remove it as a disposable cache, never clear observation tables during a history rebuild, and never run unscoped history SQL across providers.
 - A diagnostic (`doctor`, `test`, `probe`, `health`, `check`, `status`, `list`, `show`, `--dry-run`) never mutates durable state and never spends a single-use credential such as an OAuth refresh token. Details: `.claude/rules/code.md`.
 - An empty result from a permission-gated tool (Calendar, Reminders, Contacts, Full Disk Access) is never proof of empty data. Run `tools macos permissions` first: it exits 1 while a grant is missing.
-- When a tool misbehaves, read `~/.genesis-tools/logs/<today>.log` (day-stamped pino JSON) and `rg` it for the tool name or the error before you form a hypothesis. A day older than a week is `<date>.log.zst` (seekable zstd, written by the daily pass): search it with `rg -z <pattern> <file>` (needs the `zstd` CLI) or `tools compress cat <file> | rg <pattern>`.
+- When a tool misbehaves, read `~/.genesis-tools/logs/<today>.log` (day-stamped pino JSON) and `rg` it for the tool name or the error before you form a hypothesis. A day older than a week is `<date>.log.zst` (seekable zstd, written by the daily pass): search it with `rg -z <pattern> <file>` (needs the `zstd` CLI) or `tools compress cat <file> | rg <pattern>`. Failed runs of every tool (usage errors, thrown actions, crashes, non-zero exits, with the agent, session and model that ran them) are in `<today>-failures.jsonl`: read them with `tools genesis-tools logs failures`, `logs show <id>` and `logs usage`.
 
 ## Git branch mechanics
 

From d58ffbaf81d9b464d5b2a3373a9e308b8f5d5994 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 16:56:46 +0200
Subject: [PATCH 09/30] fix(tools): a failure's message is the clack error line
 or the JSON error a --json run printed, not the hint after it

---
 src/utils/cli/failures/failures.test.ts | 8 ++++++++
 src/utils/cli/failures/watch.ts         | 9 +++++++--
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/src/utils/cli/failures/failures.test.ts b/src/utils/cli/failures/failures.test.ts
index c53617385a..b9b09db209 100644
--- a/src/utils/cli/failures/failures.test.ts
+++ b/src/utils/cli/failures/failures.test.ts
@@ -55,6 +55,14 @@ describe("messageOfTail", () => {
         ).toBe("error: missing required argument 'entry'");
     });
 
+    it("prefers clack's error line over the hints printed after it", () => {
+        expect(
+            messageOfTail(
+                "│\n■  pattern matches 2 tabs. Refusing to guess.\n│\n●  Narrow it:\n│\n●  tools x --match /a$/\n"
+            )
+        ).toBe("pattern matches 2 tabs. Refusing to guess.");
+    });
+
     it("falls back to the last non-empty line", () => {
         expect(messageOfTail("working…\nno such worktree: feat/x\n\n")).toBe("no such worktree: feat/x");
         expect(messageOfTail("")).toBeNull();
diff --git a/src/utils/cli/failures/watch.ts b/src/utils/cli/failures/watch.ts
index 893694ac92..128506b3e2 100644
--- a/src/utils/cli/failures/watch.ts
+++ b/src/utils/cli/failures/watch.ts
@@ -124,8 +124,13 @@ export function messageOfTail(tail: string): string | null {
         return "no subcommand given; the help was printed";
     }
 
-    const lines = tail.split("\n").filter((line) => line.trim());
-    return lines.at(-1)?.trim() ?? null;
+    // clack frames each line with `│` and marks an error with `■`; `ERROR:` is runTool's own prefix.
+    const lines = tail
+        .split("\n")
+        .map((line) => line.replace(/^[│\s]+/, "").trim())
+        .filter(Boolean);
+    const marked = lines.findLast((line) => /^(?:■|✖|✗|×|ERROR:|Error:|error:)/.test(line));
+    return (marked ?? lines.at(-1))?.replace(/^(?:■|✖|✗|×)\s*/, "") ?? null;
 }
 
 /**

From 534805e1a51b1ed989a44726df7693e2a4b5843e Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 17:33:02 +0200
Subject: [PATCH 10/30] fix(tools): the failure message pick compiles under the
 dashboard tsconfigs, which have no findLast

---
 src/utils/cli/failures/watch.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/utils/cli/failures/watch.ts b/src/utils/cli/failures/watch.ts
index 128506b3e2..d1926244f6 100644
--- a/src/utils/cli/failures/watch.ts
+++ b/src/utils/cli/failures/watch.ts
@@ -129,7 +129,8 @@ export function messageOfTail(tail: string): string | null {
         .split("\n")
         .map((line) => line.replace(/^[│\s]+/, "").trim())
         .filter(Boolean);
-    const marked = lines.findLast((line) => /^(?:■|✖|✗|×|ERROR:|Error:|error:)/.test(line));
+    // Not findLast: the dashboard tsconfigs that reach src/utils compile against an older lib.
+    const marked = [...lines].reverse().find((line) => /^(?:■|✖|✗|×|ERROR:|Error:|error:)/.test(line));
     return (marked ?? lines.at(-1))?.replace(/^(?:■|✖|✗|×)\s*/, "") ?? null;
 }
 

From fe8c00b827b1dbcc365afffd740b996bbcad4dd2 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 17:33:25 +0200
Subject: [PATCH 11/30] chore(tools): TypeScript 7.0 side by side, its native
 tsc as @typescript/native and the 6.0 API as typescript, since native-preview
 stopped at a July dev build and typescript 7 has no JavaScript API

---
 .claude/skills/babysit/scripts/fill-brief.ts  |  2 +-
 .claude/skills/babysit/scripts/integrate.ts   |  8 ++-
 .../skills/babysit/scripts/scripts.test.ts    |  2 +-
 .githooks/pre-commit                          | 26 +++++-----
 README.md                                     |  2 +-
 bun.lock                                      | 52 ++++++++++++++-----
 package.json                                  | 12 ++---
 scripts/tv-verify-all.sh                      |  6 +--
 src/artifact/lib/kit-types.ts                 |  6 +--
 src/jev/lib/compilers/typescript.ts           |  4 +-
 10 files changed, 76 insertions(+), 44 deletions(-)

diff --git a/.claude/skills/babysit/scripts/fill-brief.ts b/.claude/skills/babysit/scripts/fill-brief.ts
index 259a42aa47..11de17c346 100644
--- a/.claude/skills/babysit/scripts/fill-brief.ts
+++ b/.claude/skills/babysit/scripts/fill-brief.ts
@@ -44,7 +44,7 @@ const verify = run.verify ? run.verify.map((line) => `   - ${line}`).join("\n")
 function defaultVerify(): string {
     return [
         "   - `bun scripts/test.ts <the test file of every file you changed>` (never bare `bun test`; it must end with `[test] suite complete`)",
-        "   - `./node_modules/@typescript/native-preview-darwin-arm64/lib/tsgo --noEmit` (not `bunx tsgo`: it hangs in /tmp worktrees)",
+        "   - `./node_modules/@typescript/typescript-darwin-arm64/lib/tsc --noEmit` (TypeScript 7; not `bunx tsc`: it hangs in /tmp worktrees)",
         "   - `bunx biome check <each changed file>`",
         "   - `bun run lint:rules` and `bun scripts/ci/check-tool-commands.ts`",
         ...(has("--swift") && codexWorker()
diff --git a/.claude/skills/babysit/scripts/integrate.ts b/.claude/skills/babysit/scripts/integrate.ts
index 3ff41eb778..612ca604ad 100644
--- a/.claude/skills/babysit/scripts/integrate.ts
+++ b/.claude/skills/babysit/scripts/integrate.ts
@@ -244,8 +244,12 @@ async function main(): Promise<void> {
     }
 
     if (!skipGates && oldHead !== newHead) {
-        const tsgo = join(executionRoot, "node_modules/@typescript/native-preview-darwin-arm64/lib/tsgo");
-        must(existsSync(tsgo) ? [tsgo, "--noEmit"] : ["bunx", "tsgo", "--noEmit"], "tsgo");
+        // TypeScript 7's native compiler, called directly: `bunx` hangs in /tmp worktrees.
+        const tsc = join(
+            executionRoot,
+            `node_modules/@typescript/typescript-${process.platform}-${process.arch}/lib/tsc`
+        );
+        must(existsSync(tsc) ? [tsc, "--noEmit"] : ["bunx", "tsc", "--noEmit"], "tsc");
         // Biome by its exit code over the round's changed files: judging it by the tail of its output let a formatting
         // error through to the pre-push hook (2026-10-14, #502 round 6). The main checkout's binary is already assessed.
         const changed = must(
diff --git a/.claude/skills/babysit/scripts/scripts.test.ts b/.claude/skills/babysit/scripts/scripts.test.ts
index 7ac377fea8..80dcc144fd 100644
--- a/.claude/skills/babysit/scripts/scripts.test.ts
+++ b/.claude/skills/babysit/scripts/scripts.test.ts
@@ -3160,7 +3160,7 @@ describe("round 15 review regressions", () => {
                 mode === "correct" ? 0 : 1
             );
             if (mode !== "correct") {
-                expect(result.stdout.toString()).toContain(`${mode === "broken" ? "tsgo" : mode} failed`);
+                expect(result.stdout.toString()).toContain(`${mode === "broken" ? "tsc" : mode} failed`);
             } else {
                 expect(result.stdout.toString()).toContain("dry: push skipped");
             }
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index a41f28f1c1..d1a5fe40dc 100755
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -1,6 +1,6 @@
 #!/bin/sh
 
-# Pre-commit hook — mirrors CI checks (biome + tsgo typecheck).
+# Pre-commit hook — mirrors CI checks (biome + tsc typecheck, TypeScript 7).
 # Activate: git config core.hooksPath .githooks
 
 set -e
@@ -86,41 +86,41 @@ bun scripts/ci/check-json.ts --staged
 echo "▶ no comment deleted with an import..."
 bun scripts/ci/check-lost-comments.ts --staged
 
-echo "▶ tsgo --noEmit (failing on staged files only)..."
-# tsgo has no per-file mode (types cross files), so the whole project is checked
+echo "▶ tsc --noEmit (failing on staged files only)..."
+# tsc has no per-file mode (types cross files), so the whole project is checked
 # but only errors in STAGED files block the commit. Unstaged breakage — e.g. a
 # parallel agent mid-rewire in the same worktree — must not wedge an unrelated
 # commit; CI still gates the full tree.
-tsgo_output=$(bunx tsgo --noEmit 2>&1) && tsgo_status=0 || tsgo_status=$?
+tsc_output=$(bunx tsc --noEmit 2>&1) && tsc_status=0 || tsc_status=$?
 staged_files=$(git diff --cached --name-only --diff-filter=d | grep -E '\.(ts|tsx)$' || true)
 
 # Only per-file diagnostics are skippable. A non-zero exit with NO diagnostic
 # lines is a compiler crash, a bad tsconfig or a global error, and none of those
 # are "someone else's unstaged file" — swallowing them printed "pre-commit
 # passed" while the project did not build at all.
-diagnostics=$(printf '%s\n' "$tsgo_output" | grep -E '\([0-9]+,[0-9]+\): (error|warning) TS[0-9]+' || true)
+diagnostics=$(printf '%s\n' "$tsc_output" | grep -E '\([0-9]+,[0-9]+\): (error|warning) TS[0-9]+' || true)
 
-if [ "$tsgo_status" -ne 0 ] && [ -z "$diagnostics" ]; then
-    printf '%s\n' "$tsgo_output"
-    echo "✖ tsgo exited $tsgo_status with no file diagnostics (crash, config or global error)"
+if [ "$tsc_status" -ne 0 ] && [ -z "$diagnostics" ]; then
+    printf '%s\n' "$tsc_output"
+    echo "✖ tsc exited $tsc_status with no file diagnostics (crash, config or global error)"
     exit 1
 fi
 
-if [ -n "$staged_files" ] && [ -n "$tsgo_output" ]; then
+if [ -n "$staged_files" ] && [ -n "$tsc_output" ]; then
     patterns=$(mktemp)
     printf '%s\n' "$staged_files" | sed 's/$/(/' > "$patterns"
-    staged_errors=$(printf '%s\n' "$tsgo_output" | grep -F -f "$patterns" || true)
+    staged_errors=$(printf '%s\n' "$tsc_output" | grep -F -f "$patterns" || true)
     rm -f "$patterns"
 
     if [ -n "$staged_errors" ]; then
         printf '%s\n' "$staged_errors"
-        echo "✖ tsgo errors in staged files"
+        echo "✖ tsc errors in staged files"
         exit 1
     fi
 fi
 
-if [ "$tsgo_status" -ne 0 ]; then
-    echo "ℹ tsgo reported errors, none attributable to staged files — CI still gates the full tree"
+if [ "$tsc_status" -ne 0 ]; then
+    echo "ℹ tsc reported errors, none attributable to staged files — CI still gates the full tree"
 fi
 
 echo "✔ pre-commit passed"
diff --git a/README.md b/README.md
index 4192b611ea..7e92db559a 100644
--- a/README.md
+++ b/README.md
@@ -971,7 +971,7 @@ resolve against the main repo's dependency tree and fabricate failures.
 bun run lint                     # biome check .
 bun run lint:fix                 # biome check --write .
 bun run format                   # biome format --write .
-bun run tsgo                     # tsgo --noEmit
+bun run tsgo                     # tsc --noEmit (TypeScript 7; `bun run tsc` is the same)
 bun run typecheck:all            # plus the dashboard tsconfig
 ```
 
diff --git a/bun.lock b/bun.lock
index 9f5c64f522..b175e60f21 100644
--- a/bun.lock
+++ b/bun.lock
@@ -168,7 +168,7 @@
         "@types/qrcode-terminal": "^0.12.2",
         "@types/react": "^19.2.18",
         "@types/tar-stream": "^3.1.4",
-        "@typescript/native-preview": "7.0.0-dev.20260707.2",
+        "@typescript/native": "npm:typescript@^7.0.2",
         "@vitejs/plugin-react": "^6.1.1",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
@@ -179,12 +179,12 @@
         "tailwind-merge": "^3.6.0",
         "ts-morph": "^28.0.0",
         "tw-animate-css": "^1.4.0",
-        "typescript": "^5.9.3",
+        "typescript": "npm:@typescript/typescript6@^6.0.2",
         "vite-tsconfig-paths": "^6.1.1",
         "web-vitals": "^6.2.1",
       },
       "peerDependencies": {
-        "typescript": "^5.9.3",
+        "typescript": "npm:@typescript/typescript6@^6.0.2",
       },
     },
     "src/utils": {
@@ -1415,21 +1415,49 @@
 
     "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
 
-    "@typescript/native-preview": ["@typescript/native-preview@7.0.0-dev.20260707.2", "", { "optionalDependencies": { "@typescript/native-preview-darwin-arm64": "7.0.0-dev.20260707.2", "@typescript/native-preview-darwin-x64": "7.0.0-dev.20260707.2", "@typescript/native-preview-linux-arm": "7.0.0-dev.20260707.2", "@typescript/native-preview-linux-arm64": "7.0.0-dev.20260707.2", "@typescript/native-preview-linux-x64": "7.0.0-dev.20260707.2", "@typescript/native-preview-win32-arm64": "7.0.0-dev.20260707.2", "@typescript/native-preview-win32-x64": "7.0.0-dev.20260707.2" }, "bin": { "tsgo": "bin/tsgo" } }, "sha512-oUGp+Rep/hqMhPunyinsALUwSlzHINSxitifPiSaeqoKOKD2OlR9NE3TaPqwsl4NlGslsOSUXI1JotWQzpYCPg=="],
+    "@typescript/native": ["typescript@7.0.2", "", { "optionalDependencies": { "@typescript/typescript-aix-ppc64": "7.0.2", "@typescript/typescript-darwin-arm64": "7.0.2", "@typescript/typescript-darwin-x64": "7.0.2", "@typescript/typescript-freebsd-arm64": "7.0.2", "@typescript/typescript-freebsd-x64": "7.0.2", "@typescript/typescript-linux-arm": "7.0.2", "@typescript/typescript-linux-arm64": "7.0.2", "@typescript/typescript-linux-loong64": "7.0.2", "@typescript/typescript-linux-mips64el": "7.0.2", "@typescript/typescript-linux-ppc64": "7.0.2", "@typescript/typescript-linux-riscv64": "7.0.2", "@typescript/typescript-linux-s390x": "7.0.2", "@typescript/typescript-linux-x64": "7.0.2", "@typescript/typescript-netbsd-arm64": "7.0.2", "@typescript/typescript-netbsd-x64": "7.0.2", "@typescript/typescript-openbsd-arm64": "7.0.2", "@typescript/typescript-openbsd-x64": "7.0.2", "@typescript/typescript-sunos-x64": "7.0.2", "@typescript/typescript-win32-arm64": "7.0.2", "@typescript/typescript-win32-x64": "7.0.2" }, "bin": { "tsc": "bin/tsc" } }, "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA=="],
 
-    "@typescript/native-preview-darwin-arm64": ["@typescript/native-preview-darwin-arm64@7.0.0-dev.20260707.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-wny2pgKjGbiZtnOIHVa3tXC1UfDqxNEFzyPGmiqybedG8hipG2Nfp0l5UxbaKCjkLacUpH/W5bP2hBOMVhCOzg=="],
+    "@typescript/old": ["typescript@6.0.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw=="],
 
-    "@typescript/native-preview-darwin-x64": ["@typescript/native-preview-darwin-x64@7.0.0-dev.20260707.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-Afc7M5zOwo+GpfcYwz5Z8HMB2tPVsui7nNIqEuuFB73MPdVqNn/Wmpe4tP4MRri0AtJnJknoHBaTJ/VDAp/Jhw=="],
+    "@typescript/typescript-aix-ppc64": ["@typescript/typescript-aix-ppc64@7.0.2", "", { "os": "aix", "cpu": "ppc64" }, "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ=="],
 
-    "@typescript/native-preview-linux-arm": ["@typescript/native-preview-linux-arm@7.0.0-dev.20260707.2", "", { "os": "linux", "cpu": "arm" }, "sha512-hJm/UOqZTr9FHmR7uNm8VGX4oKtfWk0Jem0zPeJFNC8ckGUfSBueyiEYMZB+XmRc1aG4x1E46y3CplP4CLHvGQ=="],
+    "@typescript/typescript-darwin-arm64": ["@typescript/typescript-darwin-arm64@7.0.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA=="],
 
-    "@typescript/native-preview-linux-arm64": ["@typescript/native-preview-linux-arm64@7.0.0-dev.20260707.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-iITBa2WjjTI5N9t5l7Z4KoOSI+2zBlhbvFzsD/f8qX8QoKjz/Y4DPyBDgezYi8nkqjjksbgSOJ3/ykzhwrB9cg=="],
+    "@typescript/typescript-darwin-x64": ["@typescript/typescript-darwin-x64@7.0.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA=="],
 
-    "@typescript/native-preview-linux-x64": ["@typescript/native-preview-linux-x64@7.0.0-dev.20260707.2", "", { "os": "linux", "cpu": "x64" }, "sha512-du0dzi6y97Po5vDNdPJTyyijHCpaS22JLRnKZEJXBDaO9gCIymOv/5QQokFRuOlQm0bWl3i9PF4OVdGP6uAOQA=="],
+    "@typescript/typescript-freebsd-arm64": ["@typescript/typescript-freebsd-arm64@7.0.2", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ=="],
 
-    "@typescript/native-preview-win32-arm64": ["@typescript/native-preview-win32-arm64@7.0.0-dev.20260707.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-SsAwfhyHJ1akgBc+99z4+hwdbHsdWaKB8EwCNIMA6JfSLMeUjffrYvxu+vfMyxVtOVOz7RrRXRoiDiu4a2sCtg=="],
+    "@typescript/typescript-freebsd-x64": ["@typescript/typescript-freebsd-x64@7.0.2", "", { "os": "freebsd", "cpu": "x64" }, "sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw=="],
 
-    "@typescript/native-preview-win32-x64": ["@typescript/native-preview-win32-x64@7.0.0-dev.20260707.2", "", { "os": "win32", "cpu": "x64" }, "sha512-DL4u27stv0fo71sVhOzHSwE+YMZsbBijVI+kg5dLDLilSH79WFTJ8RSQ46vJrCMt+Gjlv/JOZP1PuLJDfioYeQ=="],
+    "@typescript/typescript-linux-arm": ["@typescript/typescript-linux-arm@7.0.2", "", { "os": "linux", "cpu": "arm" }, "sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ=="],
+
+    "@typescript/typescript-linux-arm64": ["@typescript/typescript-linux-arm64@7.0.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ=="],
+
+    "@typescript/typescript-linux-loong64": ["@typescript/typescript-linux-loong64@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ=="],
+
+    "@typescript/typescript-linux-mips64el": ["@typescript/typescript-linux-mips64el@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA=="],
+
+    "@typescript/typescript-linux-ppc64": ["@typescript/typescript-linux-ppc64@7.0.2", "", { "os": "linux", "cpu": "ppc64" }, "sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA=="],
+
+    "@typescript/typescript-linux-riscv64": ["@typescript/typescript-linux-riscv64@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ=="],
+
+    "@typescript/typescript-linux-s390x": ["@typescript/typescript-linux-s390x@7.0.2", "", { "os": "linux", "cpu": "s390x" }, "sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw=="],
+
+    "@typescript/typescript-linux-x64": ["@typescript/typescript-linux-x64@7.0.2", "", { "os": "linux", "cpu": "x64" }, "sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A=="],
+
+    "@typescript/typescript-netbsd-arm64": ["@typescript/typescript-netbsd-arm64@7.0.2", "", { "os": "none", "cpu": "arm64" }, "sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA=="],
+
+    "@typescript/typescript-netbsd-x64": ["@typescript/typescript-netbsd-x64@7.0.2", "", { "os": "none", "cpu": "x64" }, "sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA=="],
+
+    "@typescript/typescript-openbsd-arm64": ["@typescript/typescript-openbsd-arm64@7.0.2", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ=="],
+
+    "@typescript/typescript-openbsd-x64": ["@typescript/typescript-openbsd-x64@7.0.2", "", { "os": "openbsd", "cpu": "x64" }, "sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg=="],
+
+    "@typescript/typescript-sunos-x64": ["@typescript/typescript-sunos-x64@7.0.2", "", { "os": "sunos", "cpu": "x64" }, "sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g=="],
+
+    "@typescript/typescript-win32-arm64": ["@typescript/typescript-win32-arm64@7.0.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ=="],
+
+    "@typescript/typescript-win32-x64": ["@typescript/typescript-win32-x64@7.0.2", "", { "os": "win32", "cpu": "x64" }, "sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g=="],
 
     "@ungap/structured-clone": ["@ungap/structured-clone@1.4.0", "", {}, "sha512-1mEZtMKPM09vDmQt5y7YvmN2+DFTP7Tg0EWXdic8/C6VRnpb33e4ghisCIE3WZjsE2N8mf+QV1Zqh7ZFYLWInQ=="],
 
@@ -2773,7 +2801,7 @@
 
     "typedarray-to-buffer": ["typedarray-to-buffer@3.1.5", "", { "dependencies": { "is-typedarray": "^1.0.0" } }, "sha512-zdu8XMNEDepKKR+XYOXAVPtWui0ly0NtohUscw+UmaHiAWT8hrV1rr//H6V+0DvJ3OQ19S979M0laLfX8rm82Q=="],
 
-    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+    "typescript": ["@typescript/typescript6@6.0.2", "", { "dependencies": { "@typescript/old": "npm:typescript@^6" }, "bin": { "tsc6": "bin/tsc6" } }, "sha512-mbCddXd+jm7hfx7w2YU64/Av4/NqqeG3GoRZgxPcgoTxYjhrcfJRw9ULch71SS4G+Q3bOXFhRvPqjguN0Hyp5w=="],
 
     "uc.micro": ["uc.micro@3.0.0", "", {}, "sha512-U3PppEkleoTnIfi8BozMx3yju3qc/L6SwqWo2Sw+54PX+PX0q9I+r1Um5HCmqD7n9VDX5/v3vQH/AjA6deDdtw=="],
 
diff --git a/package.json b/package.json
index e924cefe70..47341424f0 100644
--- a/package.json
+++ b/package.json
@@ -8,9 +8,9 @@
     ],
     "scripts": {
         "prepare": "bun scripts/git/install-hooks.ts",
-        "typecheck:all": "tsgo --noEmit && tsgo -p src/claude-history-dashboard/tsconfig.json --noEmit && tsgo -p src/spotify/ui/tsconfig.json --noEmit && tsgo -p src/monitor/ui/tsconfig.json --noEmit && tsgo -p src/clarity/ui/tsconfig.json --noEmit && tsgo -p src/dev-dashboard/ui/tsconfig.json --noEmit && tsgo -p plugins/genesis-tools/skills/fable-replace/scripts/tsconfig.json --noEmit",
-        "tsgo": "tsgo --noEmit",
-        "tsc": "tsgo --noEmit",
+        "typecheck:all": "tsc --noEmit && tsc -p src/claude-history-dashboard/tsconfig.json --noEmit && tsc -p src/spotify/ui/tsconfig.json --noEmit && tsc -p src/monitor/ui/tsconfig.json --noEmit && tsc -p src/clarity/ui/tsconfig.json --noEmit && tsc -p src/dev-dashboard/ui/tsconfig.json --noEmit && tsc -p plugins/genesis-tools/skills/fable-replace/scripts/tsconfig.json --noEmit",
+        "tsgo": "tsc --noEmit",
+        "tsc": "tsc --noEmit",
         "lint": "bun run lint:biome && bun run lint:rules",
         "check:ui-palette": "bun scripts/check-ui-palette.ts",
         "lint:fix": "biome check --write . && bun scripts/ci/lint-rules.ts",
@@ -66,7 +66,7 @@
         "@types/qrcode-terminal": "^0.12.2",
         "@types/react": "^19.2.18",
         "@types/tar-stream": "^3.1.4",
-        "@typescript/native-preview": "7.0.0-dev.20260707.2",
+        "@typescript/native": "npm:typescript@^7.0.2",
         "@vitejs/plugin-react": "^6.1.1",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
@@ -77,12 +77,12 @@
         "tailwind-merge": "^3.6.0",
         "ts-morph": "^28.0.0",
         "tw-animate-css": "^1.4.0",
-        "typescript": "^5.9.3",
+        "typescript": "npm:@typescript/typescript6@^6.0.2",
         "vite-tsconfig-paths": "^6.1.1",
         "web-vitals": "^6.2.1"
     },
     "peerDependencies": {
-        "typescript": "^5.9.3"
+        "typescript": "npm:@typescript/typescript6@^6.0.2"
     },
     "dependencies": {
         "@ai-sdk/anthropic": "^4.0.49",
diff --git a/scripts/tv-verify-all.sh b/scripts/tv-verify-all.sh
index 8a229d414a..8f8a9bec92 100755
--- a/scripts/tv-verify-all.sh
+++ b/scripts/tv-verify-all.sh
@@ -56,8 +56,8 @@ if bun scripts/test.ts src/tradingview 2>&1 | tee /tmp/tv-verify-V1.1.log | tail
   record V1.1 "$CMD_LABEL" PASS ""
 else record V1.1 "$CMD_LABEL" FAIL ""; fi
 
-CMD_LABEL="tsgo --noEmit"
-if tsgo --noEmit 2>&1 | rg "src/tradingview" >/dev/null 2>&1; then
+CMD_LABEL="tsc --noEmit"
+if bunx tsc --noEmit 2>&1 | rg "src/tradingview" >/dev/null 2>&1; then
   record V1.2 "$CMD_LABEL" FAIL "type errors"
 else record V1.2 "$CMD_LABEL" PASS ""; fi
 
@@ -215,7 +215,7 @@ else record V5.3 "$CMD_LABEL" FAIL ""; fi
 
 echo "=== V6 Final ==="
 # V6.1 re-run V1 subset
-if bun scripts/test.ts src/tradingview 2>&1 | tail -3 | rg -q "0 fail" && ! tsgo --noEmit 2>&1 | rg -q "src/tradingview"; then record V6.1 "re-run V1" PASS ""
+if bun scripts/test.ts src/tradingview 2>&1 | tail -3 | rg -q "0 fail" && ! bunx tsc --noEmit 2>&1 | rg -q "src/tradingview"; then record V6.1 "re-run V1" PASS ""
 else record V6.1 "re-run V1" FAIL ""; fi
 
 COMMITS=$(git log --oneline master..feat/tradingview 2>/dev/null | wc -l | tr -d ' ')
diff --git a/src/artifact/lib/kit-types.ts b/src/artifact/lib/kit-types.ts
index 934f5987bf..11d6e1032a 100644
--- a/src/artifact/lib/kit-types.ts
+++ b/src/artifact/lib/kit-types.ts
@@ -96,12 +96,12 @@ export async function kitApiDts(): Promise<string> {
         )
     );
 
-    const tsgo = join(REPO_ROOT, "node_modules", ".bin", "tsgo");
-    const proc = Bun.spawnSync([tsgo, "-p", tsconfigPath], { cwd: cacheDir, stdout: "pipe", stderr: "pipe" });
+    const tsc = join(REPO_ROOT, "node_modules", ".bin", "tsc");
+    const proc = Bun.spawnSync([tsc, "-p", tsconfigPath], { cwd: cacheDir, stdout: "pipe", stderr: "pipe" });
 
     if (proc.exitCode !== 0) {
         const detail = `${proc.stdout.toString()}\n${proc.stderr.toString()}`.trim();
-        throw new Error(`kit declaration emit failed (tsgo exit ${proc.exitCode}):\n${detail}`);
+        throw new Error(`kit declaration emit failed (tsc exit ${proc.exitCode}):\n${detail}`);
     }
 
     const parts: string[] = [
diff --git a/src/jev/lib/compilers/typescript.ts b/src/jev/lib/compilers/typescript.ts
index d967f2457a..1d5feee225 100644
--- a/src/jev/lib/compilers/typescript.ts
+++ b/src/jev/lib/compilers/typescript.ts
@@ -10,9 +10,9 @@ export class TypeScriptCompiler implements LanguageCompiler {
             root,
             "node_modules",
             "@typescript",
-            `native-preview-${process.platform}-${process.arch}`,
+            `typescript-${process.platform}-${process.arch}`,
             "lib",
-            process.platform === "win32" ? "tsgo.exe" : "tsgo"
+            process.platform === "win32" ? "tsc.exe" : "tsc"
         );
         if (!(await Bun.file(checker).exists())) {
             throw new Error("TypeScript checker is missing. Run bun install in GenesisTools.");

From fe46a9cc2f6c1a52af1c032c6b0e291171ebb3d4 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 17:51:47 +0200
Subject: [PATCH 12/30] refactor(tools): the CLI helpers and the failure
 watcher no longer import the agent runtime; watch.ts loads agent-caller.ts by
 a runtime path when it writes a failure

---
 src/utils/cli/failures/agent-caller.ts | 14 +++++++++++
 src/utils/cli/failures/watch.ts        | 34 +++++++++++++++++---------
 2 files changed, 37 insertions(+), 11 deletions(-)
 create mode 100644 src/utils/cli/failures/agent-caller.ts

diff --git a/src/utils/cli/failures/agent-caller.ts b/src/utils/cli/failures/agent-caller.ts
new file mode 100644
index 0000000000..4be3bdbb2c
--- /dev/null
+++ b/src/utils/cli/failures/agent-caller.ts
@@ -0,0 +1,14 @@
+import { getAgentRuntimeContext } from "@genesiscz/utils/agent/runtime";
+import { env } from "@genesiscz/utils/env";
+import { failureCaller } from "./caller";
+import type { FailureCaller } from "./record";
+
+/**
+ * The agent, session, model and checkout of this process, for a failure record. watch.ts loads this module only when
+ * it writes a failure, by a path no bundler or type checker follows: the agent runtime reaches the history index, the
+ * AI config and the `ai` package, which the CLI helpers must not pull in.
+ */
+export function agentFailureCaller(): FailureCaller {
+    const processEnv = env.getProcessEnv();
+    return failureCaller({ context: getAgentRuntimeContext({}, processEnv), processEnv });
+}
diff --git a/src/utils/cli/failures/watch.ts b/src/utils/cli/failures/watch.ts
index d1926244f6..dd924080ee 100644
--- a/src/utils/cli/failures/watch.ts
+++ b/src/utils/cli/failures/watch.ts
@@ -1,12 +1,10 @@
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { format } from "node:util";
-import { env } from "@genesiscz/utils/env";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { logger } from "@genesiscz/utils/logger";
 import { stripAnsi } from "@genesiscz/utils/string";
 import { currentTraceId } from "@genesiscz/utils/trace";
 import { redactSecretsInText } from "@genesiscz/utils/transclude/redact";
-import { failureCaller } from "./caller";
 import { appendFailure, type FailureCaller, type FailureKind, type ToolFailure } from "./record";
 
 const TAIL_CHARS = 4000;
@@ -26,6 +24,8 @@ interface Run {
     tool: string;
     argv: string[];
     commandPath: () => string | null;
+    /** Who ran the tool, asked only when a failure is written (agent-caller.ts unless a test injects one). */
+    caller: () => FailureCaller | null;
     stderr: string;
     /** Only read for a JSON error object; never stored, since stdout is the tool's result. */
     stdout: string;
@@ -213,15 +213,25 @@ function tapStderr(): void {
     };
 }
 
+/**
+ * agent-caller.ts, loaded on a failure only (the exit event is synchronous, so the load is too). The path is built at
+ * run time so neither a bundler nor the type checker follows it into the agent runtime. A copy of these helpers
+ * without that module records failures with no caller.
+ */
+function agentCaller(): FailureCaller | null {
+    const loaded: unknown = require(join(import.meta.dir, "agent-caller"));
+    const lookup = (loaded as { agentFailureCaller?: unknown } | null)?.agentFailureCaller;
+    if (typeof lookup !== "function") {
+        return null;
+    }
+
+    const found: unknown = lookup();
+    return typeof found === "object" && found !== null && "agent" in found ? (found as FailureCaller) : null;
+}
+
 function caller(): FailureCaller | null {
     try {
-        // Loaded here, on a failure only: the runtime context pulls the history index reader, which every tool
-        // would otherwise import at start. The exit event is synchronous, so the load is too.
-        const {
-            getAgentRuntimeContext,
-        }: typeof import("@genesiscz/utils/agent/runtime") = require("@genesiscz/utils/agent/runtime");
-        const processEnv = env.getProcessEnv();
-        return failureCaller({ context: getAgentRuntimeContext({}, processEnv), processEnv });
+        return run?.caller() ?? null;
     } catch (error) {
         logger.debug({ error }, "failures: no caller context");
         return null;
@@ -332,16 +342,18 @@ export function watchToolRun({
     tool,
     argv = process.argv.slice(2),
     commandPath = () => null,
+    caller = agentCaller,
 }: {
     tool: string;
     argv?: string[];
     commandPath?: () => string | null;
+    caller?: () => FailureCaller | null;
 }): void {
     if (run) {
         return;
     }
 
-    run = { tool, argv, commandPath, stderr: "", stdout: "", noted: null, ended: false };
+    run = { tool, argv, commandPath, caller, stderr: "", stdout: "", noted: null, ended: false };
     tapStderr();
     process.on("uncaughtExceptionMonitor", (error) => {
         noteCrash(error, process.listenerCount("uncaughtException") === 0);

From c16b113da60cb5441c6805cd514b50c36a8bac0e Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 17:52:19 +0200
Subject: [PATCH 13/30] feat(ci): the typecheck runs incremental and only for
 the projects a change can reach, in CI against the PR base or the commit
 before a push with that commit's build info, locally against each project's
 last pass

---
 .githooks/pre-commit         |   5 +-
 .githooks/pre-push           |   5 +-
 .github/workflows/ci.yml     |  34 +++-
 README.md                    |   3 +-
 package.json                 |   3 +-
 scripts/ci/typecheck.test.ts |  46 +++++
 scripts/ci/typecheck.ts      | 313 +++++++++++++++++++++++++++++++++++
 7 files changed, 401 insertions(+), 8 deletions(-)
 create mode 100644 scripts/ci/typecheck.test.ts
 create mode 100644 scripts/ci/typecheck.ts

diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index d1a5fe40dc..1e3454e655 100755
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -91,7 +91,10 @@ echo "▶ tsc --noEmit (failing on staged files only)..."
 # but only errors in STAGED files block the commit. Unstaged breakage — e.g. a
 # parallel agent mid-rewire in the same worktree — must not wedge an unrelated
 # commit; CI still gates the full tree.
-tsc_output=$(bunx tsc --noEmit 2>&1) && tsc_status=0 || tsc_status=$?
+# Incremental, sharing the root project's build info with scripts/ci/typecheck.ts: about 1.5 s instead of 6 to 13.
+tsc_cache=$(git rev-parse --path-format=absolute --git-path genesis-typecheck)
+mkdir -p "$tsc_cache"
+tsc_output=$(bunx tsc --noEmit --incremental --tsBuildInfoFile "$tsc_cache/root.tsbuildinfo" 2>&1) && tsc_status=0 || tsc_status=$?
 staged_files=$(git diff --cached --name-only --diff-filter=d | grep -E '\.(ts|tsx)$' || true)
 
 # Only per-file diagnostics are skippable. A non-zero exit with NO diagnostic
diff --git a/.githooks/pre-push b/.githooks/pre-push
index 512834110b..5753d424ca 100755
--- a/.githooks/pre-push
+++ b/.githooks/pre-push
@@ -80,8 +80,9 @@ stage_done
 
 # A failed typecheck fails the push. It used to run `bun install` and retry, which turned a
 # real error report into a pass whenever the install happened to fix it, and hid the failure.
-echo "▶ bun run typecheck:all..."
-if ! bun run typecheck:all; then
+# Only the projects a change since their last passing run can reach, each incremental (scripts/ci/typecheck.ts).
+echo "▶ bun run typecheck..."
+if ! bun run typecheck; then
     echo "✖ typecheck failed: push refused. If the errors name a missing module, the dependency tree is"
     echo "  stale: run \`bun install\` and push again."
     exit 1
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9fb84f4d8a..879d787353 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -409,8 +409,9 @@ jobs:
       # `bun run lint` still runs both for humans; CI wants them separable,
       # because a combined number cannot say which half regressed.
       # Lint rules are per-file and syntactic, so on a PR only the diff needs
-      # checking — unlike the `TypeScript check` step further down, which must stay
-      # whole-tree because a type error travels across files a diff never names. The
+      # checking. The `TypeScript check` step further down still checks whole projects,
+      # because a type error travels across files a diff never names; it only skips a
+      # project none of whose files changed (scripts/ci/typecheck.ts). The
       # base commit is fetched at depth 1 because a full-history checkout would
       # pull 350+ MiB and cost more than the linting it saves. Both commands
       # fall back to a full scan if the diff is unavailable for any reason.
@@ -498,9 +499,36 @@ jobs:
         timeout-minutes: 5
         run: bun run test:dd-mobile
 
+      # The typecheck compares against the PR base, or the commit before a push. The PR base is
+      # fetched above; a push's parent is fetched here (a new branch has none: every project runs).
+      - name: Fetch the commit before this push
+        if: github.event_name == 'push' && github.event.before != '0000000000000000000000000000000000000000'
+        continue-on-error: true
+        run: git fetch --depth=1 origin ${{ github.event.before }}
+
+      # Build info saved by the green push run of that same base commit, and only that one: its
+      # file lists are what decides which projects a change can reach, so build info from another
+      # commit could skip a project that has since started importing a changed file. On a miss
+      # every project runs (still incremental), which is always correct.
+      - name: Restore TypeScript build info of the base commit
+        uses: actions/cache/restore@v4
+        with:
+          path: .git/genesis-typecheck
+          key: ${{ runner.os }}-typecheck-${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
+
       - name: TypeScript check
         timeout-minutes: 2
-        run: bun run typecheck:all
+        shell: bash
+        env:
+          TYPECHECK_BASE: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
+        run: bun scripts/ci/typecheck.ts --base "$TYPECHECK_BASE"
+
+      - name: Save TypeScript build info for the next push
+        if: github.event_name == 'push'
+        uses: actions/cache/save@v4
+        with:
+          path: .git/genesis-typecheck
+          key: ${{ runner.os }}-typecheck-${{ github.sha }}
 
       - name: Logging & output convention guard
         timeout-minutes: 1
diff --git a/README.md b/README.md
index 7e92db559a..bc612397b1 100644
--- a/README.md
+++ b/README.md
@@ -972,7 +972,8 @@ bun run lint                     # biome check .
 bun run lint:fix                 # biome check --write .
 bun run format                   # biome format --write .
 bun run tsgo                     # tsc --noEmit (TypeScript 7; `bun run tsc` is the same)
-bun run typecheck:all            # plus the dashboard tsconfig
+bun run typecheck                # the projects a change since their last pass reaches, incremental
+bun run typecheck:all            # every project (root, dashboards, fable-replace), incremental
 ```
 
 Formatting is Biome with a 120-column line width and 4-space indent. Imports are sorted by
diff --git a/package.json b/package.json
index 47341424f0..874011d37e 100644
--- a/package.json
+++ b/package.json
@@ -8,7 +8,8 @@
     ],
     "scripts": {
         "prepare": "bun scripts/git/install-hooks.ts",
-        "typecheck:all": "tsc --noEmit && tsc -p src/claude-history-dashboard/tsconfig.json --noEmit && tsc -p src/spotify/ui/tsconfig.json --noEmit && tsc -p src/monitor/ui/tsconfig.json --noEmit && tsc -p src/clarity/ui/tsconfig.json --noEmit && tsc -p src/dev-dashboard/ui/tsconfig.json --noEmit && tsc -p plugins/genesis-tools/skills/fable-replace/scripts/tsconfig.json --noEmit",
+        "typecheck": "bun scripts/ci/typecheck.ts",
+        "typecheck:all": "bun scripts/ci/typecheck.ts --all",
         "tsgo": "tsc --noEmit",
         "tsc": "tsc --noEmit",
         "lint": "bun run lint:biome && bun run lint:rules",
diff --git a/scripts/ci/typecheck.test.ts b/scripts/ci/typecheck.test.ts
new file mode 100644
index 0000000000..7d3952dd4a
--- /dev/null
+++ b/scripts/ci/typecheck.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it } from "bun:test";
+import { resolve } from "node:path";
+import { type Changes, type Project, reasonToRun } from "./typecheck";
+
+const PROJECTS: Project[] = [
+    { name: "root", tsconfig: "tsconfig.json" },
+    { name: "ui", tsconfig: "src/app/ui/tsconfig.json" },
+];
+
+const key = (file: string) => resolve(file).toLowerCase();
+const programs = new Map<string, Set<string> | null>([
+    ["root", new Set(["src/utils/date.ts", "src/app/index.ts"].map(key))],
+    ["ui", new Set(["src/app/ui/Page.tsx", "src/utils/date.ts"].map(key))],
+]);
+
+function reasons(changes: Changes, known = programs): Array<string | null> {
+    return PROJECTS.map((project) => reasonToRun({ project, changes, programs: known }));
+}
+
+describe("reasonToRun", () => {
+    it("runs every project a changed file is part of, and skips the others", () => {
+        expect(reasons({ files: ["src/utils/date.ts"], added: [] })).toEqual(["in its program", "in its program"]);
+        expect(reasons({ files: ["src/app/ui/Page.tsx"], added: [] })).toEqual([null, "in its program"]);
+        expect(reasons({ files: ["README.md", "src/macos/App.swift"], added: [] })).toEqual([null, null]);
+    });
+
+    it("runs everything for shared config, and a project with no build info", () => {
+        expect(reasons({ files: ["bun.lock"], added: [] })).toEqual(["shared config", "shared config"]);
+        expect(reasons({ files: ["src/app/ui/tsconfig.json"], added: [] })).toEqual(["shared config", "shared config"]);
+        const partial = new Map(programs);
+        partial.set("ui", null);
+        expect(reasons({ files: [], added: [] }, partial)).toEqual([null, "no build info"]);
+    });
+
+    it("runs everything for an added TypeScript file no program knows, but not for an added doc", () => {
+        expect(reasons({ files: ["src/app/lib/new.ts"], added: ["src/app/lib/new.ts"] })).toEqual([
+            "new file",
+            "new file",
+        ]);
+        expect(reasons({ files: ["docs/new.md"], added: ["docs/new.md"] })).toEqual([null, null]);
+    });
+
+    it("a deleted file still counts for the programs that held it", () => {
+        expect(reasons({ files: ["src/app/index.ts"], added: [] })).toEqual(["in its program", null]);
+    });
+});
diff --git a/scripts/ci/typecheck.ts b/scripts/ci/typecheck.ts
new file mode 100644
index 0000000000..973948d759
--- /dev/null
+++ b/scripts/ci/typecheck.ts
@@ -0,0 +1,313 @@
+#!/usr/bin/env bun
+/**
+ * Typechecks the repo's TypeScript projects with TypeScript 7's `tsc`, each with `--incremental` and its build info
+ * under the checkout's git folder, and by default only the projects a change can reach.
+ *
+ *   bun scripts/ci/typecheck.ts            # changed since the last passing run of each project (local default)
+ *   bun scripts/ci/typecheck.ts --base <sha>   # changed between <sha> and HEAD (CI: PR base or the commit before a push)
+ *   bun scripts/ci/typecheck.ts --all      # every project (still incremental)
+ *
+ * A project runs when no build info or state says what it holds, when a file that changes every project changed
+ * (`package.json`, `bun.lock`, a `tsconfig`), when a changed file is in its last program (the build info's
+ * `fileNames`), or when a changed TypeScript file sits in its folder (a new file is in no program yet). The root
+ * project also runs for any changed TypeScript file outside the other projects' folders. Build info is a cache only:
+ * `tsc` compares file hashes, so build info from another commit still gives the right answer, just slower.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { SafeJSON } from "@genesiscz/utils/json";
+import { out } from "@genesiscz/utils/logger";
+
+export interface Project {
+    name: string;
+    tsconfig: string;
+}
+
+/** The order `typecheck:all` had; the root project is the large one. */
+export const PROJECTS: Project[] = [
+    { name: "root", tsconfig: "tsconfig.json" },
+    { name: "claude-history-dashboard", tsconfig: "src/claude-history-dashboard/tsconfig.json" },
+    { name: "spotify-ui", tsconfig: "src/spotify/ui/tsconfig.json" },
+    { name: "monitor-ui", tsconfig: "src/monitor/ui/tsconfig.json" },
+    { name: "clarity-ui", tsconfig: "src/clarity/ui/tsconfig.json" },
+    { name: "dev-dashboard-ui", tsconfig: "src/dev-dashboard/ui/tsconfig.json" },
+    { name: "fable-replace", tsconfig: "plugins/genesis-tools/skills/fable-replace/scripts/tsconfig.json" },
+];
+
+const TS_FILE = /\.(?:[cm]?tsx?|json)$/;
+const EVERY_PROJECT = /(?:^|\/)(?:package\.json|bun\.lock|tsconfig[\w.-]*\.json|bunfig\.toml)$/;
+
+export type Reason =
+    | "no build info"
+    | "no passing run yet"
+    | "base not in this checkout"
+    | "shared config"
+    | "in its program"
+    | "new file"
+    | "--all";
+
+interface Selection {
+    project: Project;
+    reason: Reason | null;
+}
+
+export interface Changes {
+    /** Every changed, added or deleted path, from the repo top. */
+    files: string[];
+    /** The added ones (and untracked ones locally): no build info knows them yet. */
+    added: string[];
+}
+
+/**
+ * Why `project` must run for these changes, or null. `programs` holds each project's last program files (absolute,
+ * lowercased, as the build info stores them), null when nothing is known. An added TypeScript file that no program
+ * holds makes every project run: only tsc knows which include patterns take it (spotify-ui includes `../**`).
+ */
+export function reasonToRun({
+    project,
+    changes,
+    programs,
+}: {
+    project: Project;
+    changes: Changes;
+    programs: Map<string, Set<string> | null>;
+}): Reason | null {
+    const program = programs.get(project.name);
+    if (!program) {
+        return "no build info";
+    }
+
+    if (changes.files.some((file) => EVERY_PROJECT.test(file))) {
+        return "shared config";
+    }
+
+    const key = (file: string) => resolve(file).toLowerCase();
+    if (changes.files.some((file) => program.has(key(file)))) {
+        return "in its program";
+    }
+
+    const known = (file: string) => [...programs.values()].some((other) => other?.has(key(file)));
+    return changes.added.some((file) => TS_FILE.test(file) && !known(file)) ? "new file" : null;
+}
+
+function git(args: string[]): string | null {
+    const proc = Bun.spawnSync(["git", ...args], { stdout: "pipe", stderr: "pipe" });
+    return proc.exitCode === 0 ? proc.stdout.toString() : null;
+}
+
+function lines(text: string | null): string[] {
+    return (text ?? "").split("\n").filter(Boolean);
+}
+
+/** What changed between `base` and the working tree (in CI the same as HEAD), untracked files included. */
+export function changedSince(base: string): Changes | null {
+    const diff = git(["diff", "--name-status", "--no-renames", base]);
+    if (diff === null) {
+        return null;
+    }
+
+    const files: string[] = [];
+    const added: string[] = [];
+    for (const line of lines(diff)) {
+        const [status, path] = line.split("\t");
+        if (path) {
+            files.push(path);
+            if (status === "A") {
+                added.push(path);
+            }
+        }
+    }
+
+    const untracked = lines(git(["ls-files", "--others", "--exclude-standard"]));
+    return { files: [...new Set([...files, ...untracked])], added: [...new Set([...added, ...untracked])] };
+}
+
+interface Passed {
+    /** HEAD when the project last passed. */
+    sha: string;
+    /** Files that differed from that HEAD then: they were checked as they were, so they count as changed next time. */
+    dirty: string[];
+}
+
+interface State {
+    passed: Record<string, Passed>;
+}
+
+function isPassed(value: unknown): value is Passed {
+    const record = value as Partial<Passed> | null;
+    return (
+        typeof record?.sha === "string" &&
+        Array.isArray(record.dirty) &&
+        record.dirty.every((file) => typeof file === "string")
+    );
+}
+
+function cacheDir(): string {
+    const path = lines(git(["rev-parse", "--path-format=absolute", "--git-path", "genesis-typecheck"]))[0];
+    if (!path) {
+        throw new Error("typecheck: not inside a git checkout, so there is nowhere to keep build info");
+    }
+
+    mkdirSync(path, { recursive: true });
+    return path;
+}
+
+function readState(dir: string): State {
+    const file = join(dir, "state.json");
+    const passed: Record<string, Passed> = {};
+    if (!existsSync(file)) {
+        return { passed };
+    }
+
+    const parsed: unknown = SafeJSON.parse(readFileSync(file, "utf8"));
+    const entries = (parsed as { passed?: unknown } | null)?.passed;
+    for (const [name, value] of Object.entries(typeof entries === "object" && entries !== null ? entries : {})) {
+        if (isPassed(value)) {
+            passed[name] = value;
+        }
+    }
+
+    return { passed };
+}
+
+function buildInfoPath(dir: string, project: Project): string {
+    return join(dir, `${project.name}.tsbuildinfo`);
+}
+
+/** The files of the project's last program, from its build info; null when there is none to read. */
+export function programFiles(buildInfo: string): Set<string> | null {
+    if (!existsSync(buildInfo)) {
+        return null;
+    }
+
+    const parsed: unknown = SafeJSON.parse(readFileSync(buildInfo, "utf8"), { strict: true });
+    const names = (parsed as { fileNames?: unknown } | null)?.fileNames;
+    if (!Array.isArray(names)) {
+        return null;
+    }
+
+    const base = dirname(buildInfo);
+    return new Set(
+        names
+            .filter((name): name is string => typeof name === "string")
+            .map((name) => resolve(base, name).toLowerCase())
+    );
+}
+
+interface Outcome {
+    project: Project;
+    ok: boolean;
+    ms: number;
+    output: string;
+}
+
+async function check(project: Project, dir: string): Promise<Outcome> {
+    const started = performance.now();
+    const tsc = join(import.meta.dir, "../../node_modules/.bin/tsc");
+    const proc = Bun.spawn(
+        [tsc, "-p", project.tsconfig, "--noEmit", "--incremental", "--tsBuildInfoFile", buildInfoPath(dir, project)],
+        { stdout: "pipe", stderr: "pipe" }
+    );
+    const [stdout, stderr, code] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+    ]);
+    return { project, ok: code === 0, ms: performance.now() - started, output: `${stdout}${stderr}`.trim() };
+}
+
+function parseArgs(argv: string[]): { all: boolean; base: string | null } {
+    const at = argv.indexOf("--base");
+    const base = at === -1 ? null : (argv[at + 1] ?? null);
+    if (at !== -1 && !base) {
+        throw new Error("--base needs a commit");
+    }
+
+    return { all: argv.includes("--all"), base };
+}
+
+async function main(): Promise<void> {
+    const started = performance.now();
+    const { all, base } = parseArgs(process.argv.slice(2));
+    const root = lines(git(["rev-parse", "--show-toplevel"]))[0];
+    if (!root) {
+        throw new Error("typecheck: run it inside the GenesisTools checkout");
+    }
+
+    // git prints paths from the top for `diff` but from the cwd for `ls-files`, and the tsconfig paths are from the top.
+    process.chdir(root);
+    const dir = cacheDir();
+    const state = readState(dir);
+    const head = lines(git(["rev-parse", "HEAD"]))[0] ?? "";
+
+    // One `git diff` per distinct starting commit: locally most projects last passed at the same HEAD.
+    const diffs = new Map<string, Changes | null>();
+    const changedFrom = (sha: string) => {
+        if (!diffs.has(sha)) {
+            diffs.set(sha, changedSince(sha));
+        }
+
+        return diffs.get(sha) ?? null;
+    };
+
+    const programs = new Map(PROJECTS.map((project) => [project.name, programFiles(buildInfoPath(dir, project))]));
+    const selections = PROJECTS.map((project): Selection => {
+        if (all) {
+            return { project, reason: "--all" };
+        }
+
+        const passed = state.passed[project.name];
+        const since = base ?? passed?.sha;
+        if (!since) {
+            return { project, reason: "no passing run yet" };
+        }
+
+        const fromSince = changedFrom(since);
+        if (fromSince === null) {
+            return { project, reason: "base not in this checkout" };
+        }
+
+        const dirty = base ? [] : (passed?.dirty ?? []);
+        const changes = { files: [...new Set([...fromSince.files, ...dirty])], added: fromSince.added };
+        return { project, reason: reasonToRun({ project, changes, programs }) };
+    });
+
+    const chosen = selections.filter((selection) => selection.reason !== null);
+    const dirtyNow = chosen.length > 0 ? (changedFrom("HEAD")?.files ?? []) : [];
+    const outcomes = await Promise.all(chosen.map((selection) => check(selection.project, dir)));
+
+    for (const outcome of outcomes) {
+        if (outcome.ok) {
+            state.passed[outcome.project.name] = { sha: head, dirty: dirtyNow };
+        }
+    }
+
+    writeFileSync(join(dir, "state.json"), `${SafeJSON.stringify(state, null, 2)}\n`);
+
+    for (const selection of selections) {
+        const outcome = outcomes.find((candidate) => candidate.project === selection.project);
+        const where = relative(process.cwd(), selection.project.tsconfig);
+        if (!outcome) {
+            out.println(`· ${selection.project.name.padEnd(26)} skipped, nothing it holds changed  (${where})`);
+            continue;
+        }
+
+        const mark = outcome.ok ? "✔" : "✖";
+        out.println(
+            `${mark} ${selection.project.name.padEnd(26)} ${(outcome.ms / 1000).toFixed(1)} s, ${selection.reason}`
+        );
+        if (!outcome.ok) {
+            out.println(outcome.output);
+        }
+    }
+
+    const failed = outcomes.filter((outcome) => !outcome.ok).length;
+    out.println(
+        `typecheck: ${outcomes.length} of ${PROJECTS.length} projects checked, ${failed} failed, ${((performance.now() - started) / 1000).toFixed(1)} s`
+    );
+    process.exitCode = failed > 0 ? 1 : 0;
+}
+
+if (import.meta.main) {
+    await main();
+}

From b61160f4b0292ce865f737f1a42e7afc5f3a904b Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 17:53:45 +0200
Subject: [PATCH 14/30] refactor(tools): router-link and the link gate no
 longer import the router status chain; a stale gate loads status.ts by a
 runtime path

---
 src/utils/browser-router/link-gate.ts | 32 +++++++++++++++++++++++----
 1 file changed, 28 insertions(+), 4 deletions(-)

diff --git a/src/utils/browser-router/link-gate.ts b/src/utils/browser-router/link-gate.ts
index 7830761b3c..1e70954240 100644
--- a/src/utils/browser-router/link-gate.ts
+++ b/src/utils/browser-router/link-gate.ts
@@ -1,5 +1,5 @@
 import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { genesisToolsDir } from "@genesiscz/utils/storage/root";
 
@@ -62,6 +62,32 @@ function gateDiag(reason: string, err: unknown): void {
     logger.warn({ err, path: linkGatePath() }, reason);
 }
 
+/** The part of `routerStatus()` (./status) a gate keeps. */
+interface RouterStatusFacts {
+    installed: boolean;
+    defaultHandler: boolean;
+    httpsHandler: string | null;
+    configured: boolean;
+    linkHost: string | null;
+    presets: Array<{ id: string; available: boolean; enabled: boolean; routed: boolean; missing: string[] }>;
+}
+
+/**
+ * `routerStatus` from ./status, loaded only for a stale gate: it saves 32-70 ms of imports on every hook call
+ * (measured 2026-10-15). The path is built at run time so a bundler or the type checker that follows this file (a
+ * copy of the link helpers in another repo) does not pull in the router, its presets and the browser-extension
+ * profiles behind it.
+ */
+function loadRouterStatus(): () => RouterStatusFacts {
+    const loaded: unknown = require(join(import.meta.dir, "status"));
+    const routerStatus = (loaded as { routerStatus?: unknown } | null)?.routerStatus;
+    if (typeof routerStatus !== "function") {
+        throw new Error(`link gate: ${join(import.meta.dir, "status")} exports no routerStatus`);
+    }
+
+    return routerStatus as () => RouterStatusFacts;
+}
+
 function isGate(value: unknown): value is LinkGate {
     return (
         typeof value === "object" &&
@@ -94,9 +120,7 @@ export function linkGate({ now = Date.now() }: { now?: number } = {}): LinkGate
         }
     }
 
-    // lazy: saves 32-70 ms of imports on every hook call (require of ./status, measured 2026-10-15) — only a stale gate needs them
-    const { routerStatus } = require("./status") as typeof import("./status");
-    const status = routerStatus();
+    const status = loadRouterStatus()();
     const gate: LinkGate = {
         version: 2,
         at: now,

From 7710f6eb271fb08bf45edbfbdf13431f0d8bd983 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 18:00:03 +0200
Subject: [PATCH 15/30] refactor(tools): the app link strings and schemeLink
 live in app-links/targets, so the gitlab tool reaches no browser-router file;
 router-link adds only the routing facts

---
 scripts/ci/lint-rules.ts                 |   5 +-
 src/gitlab/commands/review-judgements.ts |   2 +-
 src/utils/app-links/targets.ts           | 141 +++++++++++++++++++++
 src/utils/browser-router/router-link.ts  | 148 ++++-------------------
 4 files changed, 167 insertions(+), 129 deletions(-)
 create mode 100644 src/utils/app-links/targets.ts

diff --git a/scripts/ci/lint-rules.ts b/scripts/ci/lint-rules.ts
index 276fc659c1..0468bac10a 100644
--- a/scripts/ci/lint-rules.ts
+++ b/scripts/ci/lint-rules.ts
@@ -131,10 +131,11 @@ const RULES: Rule[] = [
         message:
             "A genesis.tools link opens something only when GenesisTools.app is installed, is the https handler and " +
             "routes that preset, and a link on the genesis-md or genesis-tools scheme only when its app is installed. Build it " +
-            "with `routerLink()` (or `schemeLink()` to open it) from @genesiscz/utils/browser-router/router-link: the " +
+            "with `routerLink()` from @genesiscz/utils/browser-router/router-link (or `schemeLink()` from " +
+            "@genesiscz/utils/app-links/targets to open it): the " +
             "preset builds the link, and the caller gets its fallback with the reason instead of a dead link.",
         test: (text) => GENESIS_ROUTER_LINK.test(text),
-        allowedIn: /(^|\/)src\/utils\/browser-router\//,
+        allowedIn: /(^|\/)src\/utils\/(browser-router|app-links)\//,
     },
 ];
 
diff --git a/src/gitlab/commands/review-judgements.ts b/src/gitlab/commands/review-judgements.ts
index e767285364..7d53faf819 100644
--- a/src/gitlab/commands/review-judgements.ts
+++ b/src/gitlab/commands/review-judgements.ts
@@ -57,7 +57,7 @@ import {
 } from "@app/gitlab/lib/review-drafts";
 import { judgementsPath, reviewItems } from "@app/gitlab/lib/review-items";
 import { collectThreadContext } from "@app/gitlab/lib/review-render";
-import { schemeLink } from "@genesiscz/utils/browser-router/router-link";
+import { schemeLink } from "@genesiscz/utils/app-links/targets";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { out } from "@genesiscz/utils/logger";
diff --git a/src/utils/app-links/targets.ts b/src/utils/app-links/targets.ts
new file mode 100644
index 0000000000..7a99ac3624
--- /dev/null
+++ b/src/utils/app-links/targets.ts
@@ -0,0 +1,141 @@
+/**
+ * What a link to a GenesisTools app says: every preset, its actions, and the plain strings each builds, the router
+ * path and the app's own scheme link. No gate and no config: whether such a link opens anything on this Mac is the
+ * router's question (`routerLink()` in @genesiscz/utils/browser-router/router-link, which adds the routing facts).
+ * The lint rule `no-raw-genesis-link` allows these literals here and in the router only.
+ */
+
+/** The hub's query keys, in the order the app reads them (`HubRequest.linkKeys`). */
+export const HUB_LINK_KEYS = [
+    "mode",
+    "session",
+    "agent",
+    "pr",
+    "reveal",
+    "repo",
+    "commit",
+    "tab",
+    "filter",
+    "worktree",
+] as const;
+
+export type HubLinkQuery = Partial<Record<(typeof HUB_LINK_KEYS)[number], string>>;
+
+/** Every preset a link can target, its actions, and the data each action takes. */
+export interface LinkTargets {
+    "genesis-md": {
+        /** A file in Genesis Markdown; `range` highlights lines, `"12"` or `"12-30"`. */
+        open: { path: string; range?: string };
+    };
+    "genesis-hub": {
+        /** The GenesisTools hub on a PR, a commit in it, a repository or a session. */
+        open: HubLinkQuery;
+    };
+    "claude-find": {
+        /** Scroll to DECISION `decision`; oldest by default, or the requested position. */
+        decision: { session: string; decision: number; at?: "oldest" | "newest" };
+        /** Scroll it to `q`, the first (`oldest`) or the latest (`newest`, the default) match. */
+        text: { session: string; q: string; at?: "oldest" | "newest" };
+    };
+}
+
+export type LinkPreset = keyof LinkTargets;
+export type LinkAction<P extends LinkPreset> = Extract<keyof LinkTargets[P], string>;
+export type LinkData<P extends LinkPreset, A extends LinkAction<P>> = LinkTargets[P][A];
+
+export interface AppLink<D> {
+    /** The path after the link host. The preset's route turns it into `scheme(data)`. */
+    path: (data: D) => string;
+    /** Absent when only the router can serve the target: it runs a command, no app opens it. */
+    scheme?: (data: D) => string;
+}
+
+export type AppLinkTable = { [P in LinkPreset]: { [A in LinkAction<P>]: AppLink<LinkData<P, A>> } };
+
+/** A query, empty values left out. `keepSlash` leaves `/` readable, which a query value may hold. */
+function query(pairs: Array<readonly [string, string | undefined]>, { keepSlash }: { keepSlash: boolean }): string {
+    const items = pairs.flatMap(([key, value]) => {
+        if (value === undefined || value === "") {
+            return [];
+        }
+
+        const encoded = encodeURIComponent(value);
+
+        return [`${key}=${keepSlash ? encoded.replace(/%2F/g, "/") : encoded}`];
+    });
+
+    return items.length > 0 ? `?${items.join("&")}` : "";
+}
+
+export const APP_LINKS: AppLinkTable = {
+    "genesis-md": {
+        open: {
+            path: (data) =>
+                `md/open${query(
+                    [
+                        ["path", data.path],
+                        ["range", data.range],
+                    ],
+                    { keepSlash: true }
+                )}`,
+            scheme: (data) =>
+                `genesis-md://open${query(
+                    [
+                        ["path", data.path],
+                        ["range", data.range],
+                    ],
+                    { keepSlash: true }
+                )}`,
+        },
+    },
+    "genesis-hub": {
+        open: {
+            // `encodeURIComponent` in full: a `+` from URLSearchParams reads back as a literal plus in the app.
+            path: (data) =>
+                `hub${query(
+                    HUB_LINK_KEYS.map((key) => [key, data[key]] as const),
+                    { keepSlash: false }
+                )}`,
+            scheme: (data) =>
+                `genesis-tools://hub${query(
+                    HUB_LINK_KEYS.map((key) => [key, data[key]] as const),
+                    { keepSlash: false }
+                )}`,
+        },
+    },
+    "claude-find": {
+        decision: {
+            path: (data) =>
+                `claude/find/${encodeURIComponent(data.session)}/decision/${data.decision}${query([["at", data.at]], { keepSlash: false })}`,
+        },
+        text: {
+            path: (data) =>
+                `claude/find/${encodeURIComponent(data.session)}${query(
+                    [
+                        ["q", data.q],
+                        ["at", data.at],
+                    ],
+                    { keepSlash: false }
+                )}`,
+        },
+    },
+};
+
+/** The app's own link for a target, for a caller that opens it rather than prints it (`open genesis-md://…`). */
+export function schemeLink<P extends LinkPreset, A extends LinkAction<P>>({
+    preset,
+    action,
+    data,
+}: {
+    preset: P;
+    action: A;
+    data: LinkData<P, A>;
+}): string {
+    const { scheme } = APP_LINKS[preset][action];
+
+    if (!scheme) {
+        throw new Error(`${preset} ${action} has no app link; only the router serves it`);
+    }
+
+    return scheme(data);
+}
diff --git a/src/utils/browser-router/router-link.ts b/src/utils/browser-router/router-link.ts
index 89a55a7e1e..0a2a8d85eb 100644
--- a/src/utils/browser-router/router-link.ts
+++ b/src/utils/browser-router/router-link.ts
@@ -1,3 +1,10 @@
+import {
+    APP_LINKS,
+    type AppLink,
+    type LinkAction,
+    type LinkData,
+    type LinkPreset,
+} from "@genesiscz/utils/app-links/targets";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { type LinkGate, linkGate } from "./link-gate";
 
@@ -17,52 +24,14 @@ import { type LinkGate, linkGate } from "./link-gate";
  * ```
  */
 
-/** The hub's query keys, in the order the app reads them (`HubRequest.linkKeys`). */
-export const HUB_LINK_KEYS = [
-    "mode",
-    "session",
-    "agent",
-    "pr",
-    "reveal",
-    "repo",
-    "commit",
-    "tab",
-    "filter",
-    "worktree",
-] as const;
-
-export type HubLinkQuery = Partial<Record<(typeof HUB_LINK_KEYS)[number], string>>;
-
-/** Every preset a link can target, its actions, and the data each action takes. */
-export interface LinkTargets {
-    "genesis-md": {
-        /** A file in Genesis Markdown; `range` highlights lines, `"12"` or `"12-30"`. */
-        open: { path: string; range?: string };
-    };
-    "genesis-hub": {
-        /** The GenesisTools hub on a PR, a commit in it, a repository or a session. */
-        open: HubLinkQuery;
-    };
-    "claude-find": {
-        /** Scroll to DECISION `decision`; oldest by default, or the requested position. */
-        decision: { session: string; decision: number; at?: "oldest" | "newest" };
-        /** Scroll it to `q`, the first (`oldest`) or the latest (`newest`, the default) match. */
-        text: { session: string; q: string; at?: "oldest" | "newest" };
-    };
-}
-
-export type LinkPreset = keyof LinkTargets;
-export type LinkAction<P extends LinkPreset> = Extract<keyof LinkTargets[P], string>;
-export type LinkData<P extends LinkPreset, A extends LinkAction<P>> = LinkTargets[P][A];
+export type { HubLinkQuery, LinkAction, LinkData, LinkPreset, LinkTargets } from "@genesiscz/utils/app-links/targets";
+export { HUB_LINK_KEYS, schemeLink } from "@genesiscz/utils/app-links/targets";
 
 /** `router`: an https link on the link host, clickable everywhere. `scheme`: the app's own link, no router needed. */
 export type LinkVia = "router" | "scheme";
 
-interface Target<D> {
-    /** The path after the link host. The preset's route turns it into `scheme(data)`. */
-    path: (data: D) => string;
-    /** Absent when only the router can serve the target: it runs a command, no app opens it. */
-    scheme?: (data: D) => string;
+/** The routing facts a target adds to its app link strings (APP_LINKS). */
+interface Routing {
     /** Whether the app behind `scheme` is on this Mac. */
     appInstalled?: (gate: LinkGate) => boolean;
     /** Transports when the caller does not pass `via`. Default is the router. */
@@ -87,99 +56,26 @@ function markdownInstalled(gate: LinkGate): boolean {
     return row.missing.every((item) => !item.startsWith("app:"));
 }
 
-type TargetTable = { [P in LinkPreset]: { [A in LinkAction<P>]: Target<LinkData<P, A>> } };
+type RoutingTable = { [P in LinkPreset]: { [A in LinkAction<P>]: Routing } };
 
-/** A query, empty values left out. `keepSlash` leaves `/` readable, which a query value may hold. */
-function query(pairs: Array<readonly [string, string | undefined]>, { keepSlash }: { keepSlash: boolean }): string {
-    const items = pairs.flatMap(([key, value]) => {
-        if (value === undefined || value === "") {
-            return [];
-        }
-
-        const encoded = encodeURIComponent(value);
-
-        return [`${key}=${keepSlash ? encoded.replace(/%2F/g, "/") : encoded}`];
-    });
-
-    return items.length > 0 ? `?${items.join("&")}` : "";
-}
-
-const TARGETS: TargetTable = {
-    "genesis-md": {
-        open: {
-            path: (data) =>
-                `md/open${query(
-                    [
-                        ["path", data.path],
-                        ["range", data.range],
-                    ],
-                    { keepSlash: true }
-                )}`,
-            scheme: (data) =>
-                `genesis-md://open${query(
-                    [
-                        ["path", data.path],
-                        ["range", data.range],
-                    ],
-                    { keepSlash: true }
-                )}`,
-            appInstalled: markdownInstalled,
-        },
-    },
+const ROUTING: RoutingTable = {
+    "genesis-md": { open: { appInstalled: markdownInstalled } },
     "genesis-hub": {
         open: {
-            // `encodeURIComponent` in full: a `+` from URLSearchParams reads back as a literal plus in the app.
-            path: (data) =>
-                `hub${query(
-                    HUB_LINK_KEYS.map((key) => [key, data[key]] as const),
-                    { keepSlash: false }
-                )}`,
-            scheme: (data) =>
-                `genesis-tools://hub${query(
-                    HUB_LINK_KEYS.map((key) => [key, data[key]] as const),
-                    { keepSlash: false }
-                )}`,
             appInstalled: (gate) => gate.installed,
             // The router where the `genesis-hub` preset routes `/hub`, since every terminal makes an
             // https link clickable; else the app scheme. A version without that preset falls through.
             transports: ["router", "scheme"],
         },
     },
-    "claude-find": {
-        decision: {
-            path: (data) =>
-                `claude/find/${encodeURIComponent(data.session)}/decision/${data.decision}${query([["at", data.at]], { keepSlash: false })}`,
-        },
-        text: {
-            path: (data) =>
-                `claude/find/${encodeURIComponent(data.session)}${query(
-                    [
-                        ["q", data.q],
-                        ["at", data.at],
-                    ],
-                    { keepSlash: false }
-                )}`,
-        },
-    },
+    "claude-find": { decision: {}, text: {} },
 };
 
-/** The app's own link for a target, for a caller that opens it rather than prints it (`open genesis-md://…`). */
-export function schemeLink<P extends LinkPreset, A extends LinkAction<P>>({
-    preset,
-    action,
-    data,
-}: {
-    preset: P;
-    action: A;
-    data: LinkData<P, A>;
-}): string {
-    const { scheme } = TARGETS[preset][action];
-
-    if (!scheme) {
-        throw new Error(`${preset} ${action} has no app link; only the router serves it`);
-    }
-
-    return scheme(data);
+function targetOf<P extends LinkPreset, A extends LinkAction<P>>(
+    preset: P,
+    action: A
+): AppLink<LinkData<P, A>> & Routing {
+    return { ...APP_LINKS[preset][action], ...ROUTING[preset][action] };
 }
 
 export type LinkErrorCode =
@@ -283,7 +179,7 @@ function linkFor<P extends LinkPreset, A extends LinkAction<P>>({
     gate: LinkGate;
     via: LinkVia;
 }): { link: string } | { error: LinkError } {
-    const target = TARGETS[options.preset][options.action];
+    const target = targetOf(options.preset, options.action);
 
     if (via === "scheme") {
         if (!target.scheme) {
@@ -333,7 +229,7 @@ export function routerLink<P extends LinkPreset, A extends LinkAction<P>, R>(
         return { result: options.fallback({ ...ctx, error }), link: null, via: null, error };
     }
 
-    const transports = options.via ?? TARGETS[options.preset][options.action].transports ?? ["router"];
+    const transports = options.via ?? targetOf(options.preset, options.action).transports ?? ["router"];
     let first: LinkError | undefined;
 
     for (const via of transports) {

From 1f85100f19b160bf78e979f2b0e9f718dc8005a1 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 18:11:45 +0200
Subject: [PATCH 16/30] refactor(macos): notifications.ts keeps
 terminal-notifier and osascript, and the GenesisTools.app backend, its hints
 and app-only calls live in notifications-app.ts, loaded by a runtime path

---
 src/macos/lib/doctor/index.ts                 |   8 +-
 src/macos/lib/doctor/summarize.test.ts        |   2 +-
 src/macos/lib/doctor/summarize.ts             |   3 +-
 src/notify/index.ts                           |  12 +-
 src/question/lib/pending/notify.test.ts       |   2 +-
 src/question/lib/pending/notify.ts            |   2 +-
 .../bun/preload-test-host-effects.test.ts     |   3 +-
 src/utils/bun/preload-test-host-effects.ts    |  10 +
 src/utils/macos/notifications-app.ts          | 231 ++++++++++++++++
 src/utils/macos/notifications.ts              | 250 ++++--------------
 10 files changed, 304 insertions(+), 219 deletions(-)
 create mode 100644 src/utils/macos/notifications-app.ts

diff --git a/src/macos/lib/doctor/index.ts b/src/macos/lib/doctor/index.ts
index 7d0674aaea..47d535d42e 100644
--- a/src/macos/lib/doctor/index.ts
+++ b/src/macos/lib/doctor/index.ts
@@ -1,10 +1,6 @@
 import type { GenesisAppRpcOutcome } from "@genesiscz/utils/macos/genesis-app-rpc";
-import {
-    type NotificationCenterStatus,
-    type NotificationFallbackState,
-    notificationStatus,
-    resolveNotificationFallbackState,
-} from "@genesiscz/utils/macos/notifications";
+import { type NotificationFallbackState, resolveNotificationFallbackState } from "@genesiscz/utils/macos/notifications";
+import { type NotificationCenterStatus, notificationStatus } from "@genesiscz/utils/macos/notifications-app";
 import { type CalendarDoctorReport, runCalendarDoctor } from "../calendar/doctor";
 import { type PermissionsReport, permissionsReport } from "../permissions/report";
 import { type RemindersDoctorReport, runRemindersDoctor } from "../reminders/doctor";
diff --git a/src/macos/lib/doctor/summarize.test.ts b/src/macos/lib/doctor/summarize.test.ts
index 485223c77f..df44c3a1b9 100644
--- a/src/macos/lib/doctor/summarize.test.ts
+++ b/src/macos/lib/doctor/summarize.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import type { NotificationCenterStatus } from "@genesiscz/utils/macos/notifications";
+import type { NotificationCenterStatus } from "@genesiscz/utils/macos/notifications-app";
 import type { PermissionsReport } from "../permissions/report";
 import {
     combineDoctorChecks,
diff --git a/src/macos/lib/doctor/summarize.ts b/src/macos/lib/doctor/summarize.ts
index 38d88170a0..4dd581779e 100644
--- a/src/macos/lib/doctor/summarize.ts
+++ b/src/macos/lib/doctor/summarize.ts
@@ -1,5 +1,6 @@
 import type { GenesisAppRpcOutcome } from "@genesiscz/utils/macos/genesis-app-rpc";
-import type { NotificationCenterStatus, NotificationFallbackState } from "@genesiscz/utils/macos/notifications";
+import type { NotificationFallbackState } from "@genesiscz/utils/macos/notifications";
+import type { NotificationCenterStatus } from "@genesiscz/utils/macos/notifications-app";
 import type { CalendarDoctorReport } from "../calendar/doctor";
 import type { PermissionsReport } from "../permissions/report";
 import type { RemindersDoctorReport } from "../reminders/doctor";
diff --git a/src/notify/index.ts b/src/notify/index.ts
index 746b08d145..12c2e05267 100644
--- a/src/notify/index.ts
+++ b/src/notify/index.ts
@@ -7,19 +7,21 @@ import { SafeJSON } from "@genesiscz/utils/json";
 import { logger, out } from "@genesiscz/utils/logger";
 import type { GenesisAppRpcFailure, GenesisAppRpcOutcome } from "@genesiscz/utils/macos/genesis-app-rpc";
 import type { NotificationAction, NotificationOptions } from "@genesiscz/utils/macos/notifications";
+import {
+    launchdSession,
+    parseNotificationOptions,
+    postNotification,
+    resolveNotificationFallbackState,
+} from "@genesiscz/utils/macos/notifications";
 import {
     askNotification,
     authorizeNotifications,
-    launchdSession,
     listNotifications,
     notificationStatus,
     openNotificationSettings,
-    parseNotificationOptions,
-    postNotification,
     readNotificationReply,
     removeNotifications,
-    resolveNotificationFallbackState,
-} from "@genesiscz/utils/macos/notifications";
+} from "@genesiscz/utils/macos/notifications-app";
 import { genesisAppBuildHint } from "@genesiscz/utils/macos/xcode";
 import type { ChannelConfigs } from "@genesiscz/utils/notifications";
 import { dispatchNotification, notificationsConfig } from "@genesiscz/utils/notifications";
diff --git a/src/question/lib/pending/notify.test.ts b/src/question/lib/pending/notify.test.ts
index c829451552..ff5da90ac3 100644
--- a/src/question/lib/pending/notify.test.ts
+++ b/src/question/lib/pending/notify.test.ts
@@ -27,7 +27,7 @@ mock.module("@genesiscz/utils/notifications", () => ({
     },
 }));
 
-mock.module("@genesiscz/utils/macos/notifications", () => ({
+mock.module("@genesiscz/utils/macos/notifications-app", () => ({
     removeNotifications: async (target: { ids?: string[] }) => {
         removed.push(target);
 
diff --git a/src/question/lib/pending/notify.ts b/src/question/lib/pending/notify.ts
index 998c31b92e..98098d9255 100644
--- a/src/question/lib/pending/notify.ts
+++ b/src/question/lib/pending/notify.ts
@@ -1,7 +1,7 @@
 import { buildQaDeepLink } from "@app/dev-dashboard/lib/qa-deep-link";
 import { logger } from "@genesiscz/utils/logger";
 import type { NotificationAction } from "@genesiscz/utils/macos/notifications";
-import { removeNotifications } from "@genesiscz/utils/macos/notifications";
+import { removeNotifications } from "@genesiscz/utils/macos/notifications-app";
 import { dispatchNotification } from "@genesiscz/utils/notifications";
 import { shellCommandLine } from "@genesiscz/utils/shell/quote";
 import { hubItemClickCommand } from "../hub-link";
diff --git a/src/utils/bun/preload-test-host-effects.test.ts b/src/utils/bun/preload-test-host-effects.test.ts
index dfa88436cc..41e20db886 100644
--- a/src/utils/bun/preload-test-host-effects.test.ts
+++ b/src/utils/bun/preload-test-host-effects.test.ts
@@ -3,7 +3,8 @@ import { Browser } from "@genesiscz/utils/browser";
 import { copyToClipboard, readFromClipboard } from "@genesiscz/utils/clipboard";
 import { fullDiskAccessSubject, requestFullDiskAccess } from "@genesiscz/utils/macos/full-disk-access";
 import { escapeJxa, runJxa } from "@genesiscz/utils/macos/jxa";
-import { authorizeNotifications, NotificationBackend, sendNotification } from "@genesiscz/utils/macos/notifications";
+import { NotificationBackend, sendNotification } from "@genesiscz/utils/macos/notifications";
+import { authorizeNotifications } from "@genesiscz/utils/macos/notifications-app";
 import { settings } from "@genesiscz/utils/macos/system-settings";
 import {
     dispatchNotification,
diff --git a/src/utils/bun/preload-test-host-effects.ts b/src/utils/bun/preload-test-host-effects.ts
index e42d2e8c37..8ca3ca9698 100644
--- a/src/utils/bun/preload-test-host-effects.ts
+++ b/src/utils/bun/preload-test-host-effects.ts
@@ -4,6 +4,7 @@ import * as fullDiskAccess from "@genesiscz/utils/macos/full-disk-access";
 import * as genesisAppRpc from "@genesiscz/utils/macos/genesis-app-rpc";
 import * as jxa from "@genesiscz/utils/macos/jxa";
 import * as macosNotifications from "@genesiscz/utils/macos/notifications";
+import * as macosNotificationsApp from "@genesiscz/utils/macos/notifications-app";
 import { settings as macosSettings } from "@genesiscz/utils/macos/system-settings";
 import type { NotificationEvent, WebhookChannelConfig } from "@genesiscz/utils/notifications";
 import * as notifications from "@genesiscz/utils/notifications";
@@ -109,6 +110,7 @@ function installHostEffectGuards(): void {
     const realJxa = { ...jxa };
     const realGenesisAppRpc = { ...genesisAppRpc };
     const realMacosNotifications = { ...macosNotifications };
+    const realMacosNotificationsApp = { ...macosNotificationsApp };
     const realNotifications = { ...notifications };
     const realFullDiskAccess = { ...fullDiskAccess };
     const realTrashStaging = { ...trashStaging };
@@ -156,6 +158,14 @@ function installHostEffectGuards(): void {
         ...realMacosNotifications,
         sendNotification: blockedAsync("sendNotification", "Assert the notification payload instead of delivering it."),
         postNotification: blockedAsync("postNotification", "Assert the notification payload instead of delivering it."),
+    }));
+
+    mock.module("@genesiscz/utils/macos/notifications-app", () => ({
+        ...realMacosNotificationsApp,
+        sendViaGenesisApp: blockedAsync(
+            "sendViaGenesisApp",
+            "Assert the notification payload instead of delivering it."
+        ),
         // These reach GenesisTools.app, which mutates Notification Center for the whole user
         // session. A test that removes "its own" notification would clear the user's real ones.
         removeNotifications: blockedAsync("removeNotifications", "Assert the removal target instead of running it."),
diff --git a/src/utils/macos/notifications-app.ts b/src/utils/macos/notifications-app.ts
new file mode 100644
index 0000000000..f5dac8f09c
--- /dev/null
+++ b/src/utils/macos/notifications-app.ts
@@ -0,0 +1,231 @@
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { toolCommand } from "@genesiscz/utils/cli/tool-command";
+import { env } from "@genesiscz/utils/env";
+import { watchFileFeed } from "@genesiscz/utils/fs/file-feed-watcher";
+import { logger } from "@genesiscz/utils/logger";
+import { genesisAppDir } from "@genesiscz/utils/macos/genesis-app";
+import {
+    type GenesisAppRpcOutcome,
+    genesisAppRpc,
+    isGenesisAppRpcAvailable,
+    isNotifyPostResult,
+} from "@genesiscz/utils/macos/genesis-app-rpc";
+import {
+    isObject,
+    type NotificationAppBackend,
+    NotificationBackend,
+    type NotificationOptions,
+    type NotificationReply,
+    postNotification,
+} from "@genesiscz/utils/macos/notifications";
+import { genesisAppBuildHint } from "@genesiscz/utils/macos/xcode";
+
+/**
+ * The GenesisTools.app side of notifications: the `genesis-app` backend (first in the chain, with the app's icon,
+ * actions and replies), the hints that name the app, and what only the app can do (retract, list, ask, status,
+ * authorize). notifications.ts loads this module by a run-time path, so a copy of the notification helpers without
+ * it posts through terminal-notifier and osascript only and never mentions the app.
+ */
+
+/**
+ * Post through GenesisTools.app, so the banner carries our icon and identity.
+ * Returns the notification id, or null when the app could not take it and the chain should move on.
+ */
+export async function sendViaGenesisApp(opts: NotificationOptions): Promise<string | null> {
+    const outcome = await genesisAppRpc(
+        "notify.post",
+        {
+            message: opts.message,
+            title: opts.title,
+            subtitle: opts.subtitle,
+            sound: opts.sound,
+            group: opts.group,
+            open: opts.open,
+            execute: opts.execute,
+            appIcon: opts.appIcon,
+            attachments: opts.attachments,
+            ignoreDnD: opts.ignoreDnD,
+            id: opts.id,
+            actions: opts.actions,
+            replyDir: join(genesisAppDir(), "replies"),
+            genesisHome: env.tools.getHome(),
+        },
+        { isResult: isNotifyPostResult }
+    );
+
+    if (outcome.ok) {
+        return outcome.result.id;
+    }
+
+    if (outcome.error.code === "denied" || outcome.error.code === "not_determined") {
+        // Falling through means another bundle delivers instead, so the user still gets the banner
+        // and never learns the grant is missing. That is the documented contract for this function,
+        // so the warning is how the problem stays visible.
+        logger.warn(
+            { error: outcome.error },
+            outcome.error.code === "not_determined"
+                ? `GenesisTools.app has never been granted notifications; run ${toolCommand("notify authorize")}. Falling back to terminal-notifier.`
+                : "GenesisTools.app may not post notifications; grant it in System Settings > Notifications. Falling back to terminal-notifier."
+        );
+    }
+
+    return null;
+}
+
+/**
+ * Retract delivered notifications. Only notifications posted through GenesisTools.app can be
+ * addressed, since the other backends post under a different bundle.
+ *
+ * Returns the ids actually removed, `"all"`, or null when the app is unavailable.
+ */
+export async function removeNotifications(target: {
+    ids?: string[];
+    group?: string;
+    all?: boolean;
+}): Promise<string[] | "all" | null> {
+    const outcome = await genesisAppRpc<{ removed: string[] | "all" }>("notify.remove", target);
+
+    if (!outcome.ok) {
+        logger.debug({ error: outcome.error, target }, "Could not remove notifications");
+        return null;
+    }
+
+    return outcome.result.removed;
+}
+
+export interface DeliveredNotification {
+    id: string;
+    title: string;
+    subtitle: string;
+    message: string;
+    group: string;
+    /** Seconds since the epoch. */
+    deliveredAt: number;
+}
+
+/**
+ * Notifications still in Notification Center, posted by GenesisTools.app. Null when unavailable.
+ *
+ * ⚠️ A notification does not appear here the instant {@link postNotification} resolves. `usernoted`
+ * takes roughly a second to publish it, so a list taken straight after a post comes back without
+ * it. Measured 2026-09-16: absent immediately, present after 1s. Do not use this to confirm a post.
+ */
+export async function listNotifications(): Promise<DeliveredNotification[] | null> {
+    const outcome = await genesisAppRpc<{ notifications: DeliveredNotification[] }>("notify.list");
+
+    if (!outcome.ok) {
+        logger.debug({ error: outcome.error }, "Could not list notifications");
+        return null;
+    }
+
+    return outcome.result.notifications;
+}
+
+/**
+ * The answer to a notification, if the user has given one. Null when unanswered or unavailable.
+ *
+ * Non-blocking. Pass `consume` to delete the answer as you read it, so two callers cannot act on
+ * the same reply.
+ */
+export async function readNotificationReply(
+    id: string,
+    opts: { consume?: boolean } = {}
+): Promise<NotificationReply | null> {
+    const outcome = await genesisAppRpc<{ answered: boolean } & NotificationReply>("notify.reply", {
+        id,
+        consume: opts.consume,
+        replyDir: join(genesisAppDir(), "replies"),
+    });
+
+    if (!outcome.ok || !outcome.result.answered) {
+        return null;
+    }
+
+    return outcome.result;
+}
+
+/**
+ * Ask a question in a notification and wait for the answer.
+ *
+ * Give one action an `input` field and the user gets a text box; give plain buttons and you learn
+ * which was pressed. Resolves null on timeout, on a dismissed notification, or when the app is
+ * unavailable — an unanswered question is a normal outcome, not an error.
+ *
+ * ⚠️ The wait uses `watchFileFeed` (directory/file watch plus a poll fallback). bun 1.3.13 goes
+ * deaf after the first `FSWatcher.close()` in a process; a watch without a poll sits out the
+ * full timeout even though the user answered. The answer arrives from a process macOS launches,
+ * minutes later, so this must not spin a tight loop while they think.
+ */
+export async function askNotification(
+    opts: NotificationOptions,
+    waitOpts: { timeoutMs?: number } = {}
+): Promise<NotificationReply | null> {
+    const replyDir = join(genesisAppDir(), "replies");
+    mkdirSync(replyDir, { recursive: true });
+
+    if (opts.id) {
+        // A leftover reply for a reused id would satisfy the watch at once.
+        rmSync(join(replyDir, `${opts.id}.json`), { force: true });
+    }
+
+    const posted = await postNotification(opts);
+
+    if (posted.backend !== NotificationBackend.GenesisApp || !posted.id) {
+        logger.debug({ backend: posted.backend }, "askNotification: only the genesis-app backend can carry a reply");
+        return null;
+    }
+
+    const timeoutMs = waitOpts.timeoutMs ?? 5 * 60_000;
+    const replyPath = join(replyDir, `${posted.id}.json`);
+    await watchFileFeed({
+        path: replyPath,
+        deadlineAt: Date.now() + timeoutMs,
+        debounceMs: 0,
+        pollFallbackMs: 500,
+        onChange: () => (existsSync(replyPath) ? { done: true } : undefined),
+    });
+
+    return readNotificationReply(posted.id, { consume: true });
+}
+
+export interface NotificationCenterStatus {
+    authorization: string;
+    alertSetting: string;
+    alertStyle: string;
+    soundSetting: string;
+    badgeSetting: string;
+    notificationCenterSetting: string;
+    lockScreenSetting: string;
+    criticalAlertSetting: string;
+    timeSensitiveSetting: string;
+    bundleId: string;
+    bundlePath: string;
+    temporary: boolean;
+    settingsUrl: string;
+}
+
+function isNotificationCenterStatus(value: unknown): value is NotificationCenterStatus {
+    return isObject(value) && typeof value.authorization === "string" && typeof value.temporary === "boolean";
+}
+
+export async function notificationStatus(): Promise<GenesisAppRpcOutcome<NotificationCenterStatus>> {
+    return genesisAppRpc("notify.status", undefined, { isResult: isNotificationCenterStatus });
+}
+
+export async function authorizeNotifications(): Promise<GenesisAppRpcOutcome<Record<string, unknown>>> {
+    return genesisAppRpc("notify.authorize", undefined, { timeoutMs: 120_000 });
+}
+
+export async function openNotificationSettings(): Promise<GenesisAppRpcOutcome<{ opened: string }>> {
+    return genesisAppRpc("notify.settings", undefined, {
+        isResult: (value: unknown): value is { opened: string } => isObject(value) && typeof value.opened === "string",
+    });
+}
+
+/** What notifications.ts asks of this module. */
+export const appNotificationBackend: NotificationAppBackend = {
+    available: isGenesisAppRpcAvailable,
+    send: sendViaGenesisApp,
+    terminalNotifierFixHint: () => `, or install GenesisTools.app (${genesisAppBuildHint()})`,
+};
diff --git a/src/utils/macos/notifications.ts b/src/utils/macos/notifications.ts
index 51c5823c97..d3b207245d 100644
--- a/src/utils/macos/notifications.ts
+++ b/src/utils/macos/notifications.ts
@@ -1,20 +1,10 @@
-import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { withTimeout } from "@genesiscz/utils/async";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
-import { env } from "@genesiscz/utils/env";
-import { watchFileFeed } from "@genesiscz/utils/fs/file-feed-watcher";
 import { logger } from "@genesiscz/utils/logger";
-import { genesisAppDir } from "@genesiscz/utils/macos/genesis-app";
-import {
-    type GenesisAppRpcOutcome,
-    genesisAppRpc,
-    isGenesisAppRpcAvailable,
-    isNotifyPostResult,
-} from "@genesiscz/utils/macos/genesis-app-rpc";
 import { escapeJxa } from "@genesiscz/utils/macos/jxa";
-import { genesisAppBuildHint } from "@genesiscz/utils/macos/xcode";
 import { boundedCommand } from "@genesiscz/utils/process/bounded-command";
 import { Storage } from "@genesiscz/utils/storage/storage";
 
@@ -326,7 +316,7 @@ export async function sendViaTerminalNotifier(
 
         if (exitCode !== 0) {
             logger.warn(
-                `terminal-notifier failed to deliver (exit ${exitCode}): ${stderr.trim() || "no stderr"}. Fix: open System Settings > Notifications > terminal-notifier, or install GenesisTools.app (${genesisAppBuildHint()})`
+                `terminal-notifier failed to deliver (exit ${exitCode}): ${stderr.trim() || "no stderr"}. Fix: open System Settings > Notifications > terminal-notifier${appBackend()?.terminalNotifierFixHint() ?? ""}`
             );
             return false;
         }
@@ -360,49 +350,50 @@ function sendViaOsascript(opts: NotificationOptions): void {
     });
 }
 
-/**
- * Post through GenesisTools.app, so the banner carries our icon and identity.
- * Returns the notification id, or null when the app could not take it and the chain should move on.
- */
-async function sendViaGenesisApp(opts: NotificationOptions): Promise<string | null> {
-    const outcome = await genesisAppRpc(
-        "notify.post",
-        {
-            message: opts.message,
-            title: opts.title,
-            subtitle: opts.subtitle,
-            sound: opts.sound,
-            group: opts.group,
-            open: opts.open,
-            execute: opts.execute,
-            appIcon: opts.appIcon,
-            attachments: opts.attachments,
-            ignoreDnD: opts.ignoreDnD,
-            id: opts.id,
-            actions: opts.actions,
-            replyDir: join(genesisAppDir(), "replies"),
-            genesisHome: env.tools.getHome(),
-        },
-        { isResult: isNotifyPostResult }
+/** The `genesis-app` backend as notifications-app.ts provides it. */
+export interface NotificationAppBackend {
+    available: () => boolean;
+    /** The notification id, or null when the app could not take it and the chain moves on. */
+    send: (opts: NotificationOptions) => Promise<string | null>;
+    /** Appended to the terminal-notifier failure's fix line. */
+    terminalNotifierFixHint: () => string;
+}
+
+let appBackendCache: NotificationAppBackend | null | undefined;
+
+function isAppBackend(value: unknown): value is NotificationAppBackend {
+    return (
+        isObject(value) &&
+        typeof value.available === "function" &&
+        typeof value.send === "function" &&
+        typeof value.terminalNotifierFixHint === "function"
     );
+}
 
-    if (outcome.ok) {
-        return outcome.result.id;
+/**
+ * notifications-app.ts, loaded on first use by a path built at run time, so neither a bundler nor the type checker
+ * follows it into GenesisTools.app's RPC, its build hints and `tools notify authorize`. A copy of this module
+ * without that file posts through terminal-notifier and osascript only.
+ */
+function appBackend(): NotificationAppBackend | null {
+    if (appBackendCache !== undefined) {
+        return appBackendCache;
     }
 
-    if (outcome.error.code === "denied" || outcome.error.code === "not_determined") {
-        // Falling through means another bundle delivers instead, so the user still gets the banner
-        // and never learns the grant is missing. That is the documented contract for this function,
-        // so the warning is how the problem stays visible.
-        logger.warn(
-            { error: outcome.error },
-            outcome.error.code === "not_determined"
-                ? `GenesisTools.app has never been granted notifications; run ${toolCommand("notify authorize")}. Falling back to terminal-notifier.`
-                : "GenesisTools.app may not post notifications; grant it in System Settings > Notifications. Falling back to terminal-notifier."
+    const path = join(import.meta.dir, "notifications-app");
+    try {
+        const loaded: unknown = require(path);
+        const backend = (loaded as { appNotificationBackend?: unknown } | null)?.appNotificationBackend;
+        appBackendCache = isAppBackend(backend) ? backend : null;
+    } catch (error) {
+        logger.debug(
+            { error, path },
+            "notifications: no GenesisTools.app backend here; terminal-notifier and osascript only"
         );
+        appBackendCache = null;
     }
 
-    return null;
+    return appBackendCache;
 }
 
 /**
@@ -410,7 +401,8 @@ async function sendViaGenesisApp(opts: NotificationOptions): Promise<string | nu
  * Always ends with osascript so a notification is always delivered.
  */
 function backendChain(preferred?: NotificationBackend): NotificationBackend[] {
-    const all = [NotificationBackend.GenesisApp, NotificationBackend.TerminalNotifier, NotificationBackend.Osascript];
+    const classic = [NotificationBackend.TerminalNotifier, NotificationBackend.Osascript];
+    const all = appBackend() ? [NotificationBackend.GenesisApp, ...classic] : classic;
 
     if (!preferred) {
         return all;
@@ -447,12 +439,14 @@ export async function postNotification(opts: NotificationOptions): Promise<Poste
 
     for (const backend of chain) {
         if (backend === NotificationBackend.GenesisApp) {
-            if (!isGenesisAppRpcAvailable()) {
+            const app = appBackend();
+
+            if (!app?.available()) {
                 logger.debug("GenesisTools.app unavailable; skipping the genesis-app backend");
                 continue;
             }
 
-            const id = await sendViaGenesisApp(opts);
+            const id = await app.send(opts);
 
             if (id) {
                 logger.debug(`Notification sent via GenesisTools.app: ${opts.message}`);
@@ -485,122 +479,6 @@ export async function postNotification(opts: NotificationOptions): Promise<Poste
     return { backend: NotificationBackend.Osascript, id: null, confirmed: false };
 }
 
-/**
- * Retract delivered notifications. Only notifications posted through GenesisTools.app can be
- * addressed, since the other backends post under a different bundle.
- *
- * Returns the ids actually removed, `"all"`, or null when the app is unavailable.
- */
-export async function removeNotifications(target: {
-    ids?: string[];
-    group?: string;
-    all?: boolean;
-}): Promise<string[] | "all" | null> {
-    const outcome = await genesisAppRpc<{ removed: string[] | "all" }>("notify.remove", target);
-
-    if (!outcome.ok) {
-        logger.debug({ error: outcome.error, target }, "Could not remove notifications");
-        return null;
-    }
-
-    return outcome.result.removed;
-}
-
-export interface DeliveredNotification {
-    id: string;
-    title: string;
-    subtitle: string;
-    message: string;
-    group: string;
-    /** Seconds since the epoch. */
-    deliveredAt: number;
-}
-
-/**
- * Notifications still in Notification Center, posted by GenesisTools.app. Null when unavailable.
- *
- * ⚠️ A notification does not appear here the instant {@link postNotification} resolves. `usernoted`
- * takes roughly a second to publish it, so a list taken straight after a post comes back without
- * it. Measured 2026-09-16: absent immediately, present after 1s. Do not use this to confirm a post.
- */
-export async function listNotifications(): Promise<DeliveredNotification[] | null> {
-    const outcome = await genesisAppRpc<{ notifications: DeliveredNotification[] }>("notify.list");
-
-    if (!outcome.ok) {
-        logger.debug({ error: outcome.error }, "Could not list notifications");
-        return null;
-    }
-
-    return outcome.result.notifications;
-}
-
-/**
- * The answer to a notification, if the user has given one. Null when unanswered or unavailable.
- *
- * Non-blocking. Pass `consume` to delete the answer as you read it, so two callers cannot act on
- * the same reply.
- */
-export async function readNotificationReply(
-    id: string,
-    opts: { consume?: boolean } = {}
-): Promise<NotificationReply | null> {
-    const outcome = await genesisAppRpc<{ answered: boolean } & NotificationReply>("notify.reply", {
-        id,
-        consume: opts.consume,
-        replyDir: join(genesisAppDir(), "replies"),
-    });
-
-    if (!outcome.ok || !outcome.result.answered) {
-        return null;
-    }
-
-    return outcome.result;
-}
-
-/**
- * Ask a question in a notification and wait for the answer.
- *
- * Give one action an `input` field and the user gets a text box; give plain buttons and you learn
- * which was pressed. Resolves null on timeout, on a dismissed notification, or when the app is
- * unavailable — an unanswered question is a normal outcome, not an error.
- *
- * ⚠️ The wait uses `watchFileFeed` (directory/file watch plus a poll fallback). bun 1.3.13 goes
- * deaf after the first `FSWatcher.close()` in a process; a watch without a poll sits out the
- * full timeout even though the user answered. The answer arrives from a process macOS launches,
- * minutes later, so this must not spin a tight loop while they think.
- */
-export async function askNotification(
-    opts: NotificationOptions,
-    waitOpts: { timeoutMs?: number } = {}
-): Promise<NotificationReply | null> {
-    const replyDir = join(genesisAppDir(), "replies");
-    mkdirSync(replyDir, { recursive: true });
-
-    if (opts.id) {
-        // A leftover reply for a reused id would satisfy the watch at once.
-        rmSync(join(replyDir, `${opts.id}.json`), { force: true });
-    }
-
-    const posted = await postNotification(opts);
-
-    if (posted.backend !== NotificationBackend.GenesisApp || !posted.id) {
-        logger.debug({ backend: posted.backend }, "askNotification: only the genesis-app backend can carry a reply");
-        return null;
-    }
-
-    const timeoutMs = waitOpts.timeoutMs ?? 5 * 60_000;
-    const replyPath = join(replyDir, `${posted.id}.json`);
-    await watchFileFeed({
-        path: replyPath,
-        deadlineAt: Date.now() + timeoutMs,
-        debounceMs: 0,
-        pollFallbackMs: 500,
-        onChange: () => (existsSync(replyPath) ? { done: true } : undefined),
-    });
-
-    return readNotificationReply(posted.id, { consume: true });
-}
-
 /**
  * Send a macOS notification.
  *
@@ -644,7 +522,7 @@ export interface ResolveNotificationFallbackStateDeps {
 export async function resolveNotificationFallbackState(
     deps: ResolveNotificationFallbackStateDeps = {}
 ): Promise<NotificationFallbackState> {
-    const isAppAvailable = deps.isAppAvailable ?? isGenesisAppRpcAvailable;
+    const isAppAvailable = deps.isAppAvailable ?? (() => appBackend()?.available() ?? false);
 
     if (isAppAvailable()) {
         return { kind: "genesis-app" };
@@ -690,44 +568,10 @@ function readLaunchdManagerName(): string | null {
     }
 }
 
-export interface NotificationCenterStatus {
-    authorization: string;
-    alertSetting: string;
-    alertStyle: string;
-    soundSetting: string;
-    badgeSetting: string;
-    notificationCenterSetting: string;
-    lockScreenSetting: string;
-    criticalAlertSetting: string;
-    timeSensitiveSetting: string;
-    bundleId: string;
-    bundlePath: string;
-    temporary: boolean;
-    settingsUrl: string;
-}
-
-function isObject(value: unknown): value is Record<string, unknown> {
+export function isObject(value: unknown): value is Record<string, unknown> {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function isNotificationCenterStatus(value: unknown): value is NotificationCenterStatus {
-    return isObject(value) && typeof value.authorization === "string" && typeof value.temporary === "boolean";
-}
-
-export async function notificationStatus(): Promise<GenesisAppRpcOutcome<NotificationCenterStatus>> {
-    return genesisAppRpc("notify.status", undefined, { isResult: isNotificationCenterStatus });
-}
-
-export async function authorizeNotifications(): Promise<GenesisAppRpcOutcome<Record<string, unknown>>> {
-    return genesisAppRpc("notify.authorize", undefined, { timeoutMs: 120_000 });
-}
-
-export async function openNotificationSettings(): Promise<GenesisAppRpcOutcome<{ opened: string }>> {
-    return genesisAppRpc("notify.settings", undefined, {
-        isResult: (value: unknown): value is { opened: string } => isObject(value) && typeof value.opened === "string",
-    });
-}
-
 function optionalString(value: unknown): string | undefined {
     return typeof value === "string" ? value : undefined;
 }

From 844c1af18f3c73222a04129f59c04df466f8e6c0 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 18:35:01 +0200
Subject: [PATCH 17/30] refactor(tools): json2md's rebuild command and the
 notification say command come from genesis-tools/tools/hints.ts through their
 GenesisTools callers, and lint-rules ratchets tools commands out of src/utils

---
 scripts/ci/lint-rules.test.ts          | 36 +++++++++++-
 scripts/ci/lint-rules.ts               | 77 ++++++++++++++++++++++++--
 scripts/ci/tool-command-ratchet.ts     | 62 +++++++++++++++++++++
 src/json2md/commands/document.ts       |  6 +-
 src/utils/genesis-tools/tools/hints.ts | 20 +++++++
 src/utils/json2md/document-file.ts     | 47 ++++++++++++----
 src/utils/json2md/json2md.test.ts      | 23 +++++++-
 src/utils/macos/notifications.ts       | 33 ++++++++---
 8 files changed, 274 insertions(+), 30 deletions(-)
 create mode 100644 scripts/ci/tool-command-ratchet.ts
 create mode 100644 src/utils/genesis-tools/tools/hints.ts

diff --git a/scripts/ci/lint-rules.test.ts b/scripts/ci/lint-rules.test.ts
index 1c184cfcf6..987ce18161 100644
--- a/scripts/ci/lint-rules.test.ts
+++ b/scripts/ci/lint-rules.test.ts
@@ -3,8 +3,10 @@ import { spawnSync } from "node:child_process";
 import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { Lang, parse } from "@ast-grep/napi";
 import { keptExecutable } from "@genesiscz/utils/test/kept-executable";
-import { checkSource, pluginsDisabledFor } from "./lint-rules";
+import { checkSource, namesToolCommand, pluginsDisabledFor } from "./lint-rules";
+import { TOOL_COMMAND_RATCHET } from "./tool-command-ratchet";
 
 /**
  * These pin the behaviour of the six GritQL plugins this checker replaced.
@@ -397,3 +399,35 @@ describe("no-raw-genesis-link", () => {
         );
     });
 });
+
+describe("no-tool-command-in-utils", () => {
+    const rule = "no-tool-command-in-utils";
+
+    test("flags a toolCommand call and a written-out tools command under src/utils", () => {
+        expect(rules('const h = `run ${toolCommand("question show")} <id>`;', "src/utils/x/a.ts")).toContain(rule);
+        expect(rules('const h = suggestCommand("tools notify", {});', "src/utils/x/a.ts")).toContain(rule);
+        expect(rules('const h = "run `tools json2md build` again";', "src/utils/x/a.ts")).toContain(rule);
+    });
+
+    test("passes prose, comments, hints.ts and code outside src/utils", () => {
+        expect(rules('const h = "the tools are slow";', "src/utils/x/a.ts")).not.toContain(rule);
+        expect(rules("// run tools json2md build\nconst a = 1;", "src/utils/x/a.ts")).not.toContain(rule);
+        expect(rules('const h = toolCommand("say");', "src/utils/genesis-tools/tools/hints.ts")).not.toContain(rule);
+        expect(rules('const h = toolCommand("say");', "src/notify/index.ts")).not.toContain(rule);
+    });
+
+    test("every ratchet entry still names a command, so a migrated file leaves the list", async () => {
+        const stale: string[] = [];
+
+        for (const file of TOOL_COMMAND_RATCHET) {
+            const root = parse(file.endsWith(".tsx") ? Lang.Tsx : Lang.TypeScript, await Bun.file(file).text()).root();
+            const literals = root.findAll({ rule: { any: [{ kind: "string" }, { kind: "template_string" }] } });
+
+            if (!literals.some((node) => namesToolCommand(node.text(), node))) {
+                stale.push(file);
+            }
+        }
+
+        expect(stale).toEqual([]);
+    });
+});
diff --git a/scripts/ci/lint-rules.ts b/scripts/ci/lint-rules.ts
index 0468bac10a..5da3c0c8b8 100644
--- a/scripts/ci/lint-rules.ts
+++ b/scripts/ci/lint-rules.ts
@@ -31,8 +31,11 @@
  * Full measurements and the decision record live in the author's notes, out of repo.
  */
 
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
 import { findInFiles, Lang, parse, type SgNode } from "@ast-grep/napi";
 import { SafeJSON } from "@genesiscz/utils/json";
+import { TOOL_COMMAND_RATCHET } from "./tool-command-ratchet";
 
 export type Severity = "error" | "warn";
 
@@ -52,10 +55,18 @@ interface Rule {
     message: string;
     /** Node kinds this rule inspects. Cheaper than walking the whole tree per rule. */
     kinds: string[];
-    /** Given the node's source text, does it violate? */
-    test: (text: string) => boolean;
+    /** Given the node's source text (and the node, for a rule that needs its parent), does it violate? */
+    test: (text: string, node: SgNode) => boolean;
     /** Files where the pattern is the implementation, not a violation. */
     allowedIn?: RegExp;
+    /** The rule runs only on these files. */
+    onlyIn?: RegExp;
+    /** Single files still allowed while they are migrated (a ratchet: an entry only ever leaves). */
+    allowedFiles?: ReadonlySet<string>;
+}
+
+function ruleApplies(rule: Rule, file: string): boolean {
+    return (rule.onlyIn?.test(file) ?? true) && !rule.allowedIn?.test(file) && !rule.allowedFiles?.has(file);
 }
 
 /**
@@ -99,6 +110,48 @@ const LITERAL_KINDS = ["string", "template_string"];
 /** A link to a GenesisTools app: on the browser router's host, or an app's own scheme. */
 const GENESIS_ROUTER_LINK = /genesis\.tools\/|genesis-(?:md|tools):\/\//;
 
+/** Every tool name: a `src/<name>/` folder or a `src/<name>.ts` file. */
+function toolNames(): Set<string> {
+    const names = new Set<string>();
+
+    for (const entry of readdirSync(join(import.meta.dir, "..", "..", "src"), { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            names.add(entry.name);
+        } else if (/\.tsx?$/.test(entry.name)) {
+            names.add(entry.name.replace(/\.tsx?$/, ""));
+        }
+    }
+
+    return names;
+}
+
+const TOOL_NAMES = toolNames();
+const TOOL_MENTION = /(?:^|[^\w./-])tools ([a-z][a-z0-9-]*)/g;
+const TOOL_COMMAND_CALLEES = new Set(["toolCommand", "suggestCommand"]);
+
+/**
+ * True for a literal that names a GenesisTools command: `tools <tool>` written out, where `<tool>` is a real tool (so
+ * prose such as "the tools are" passes), or the first argument of `toolCommand(…)`. Comments are not literals.
+ */
+export function namesToolCommand(text: string, node: SgNode): boolean {
+    for (const match of text.matchAll(TOOL_MENTION)) {
+        if (TOOL_NAMES.has(match[1])) {
+            return true;
+        }
+    }
+
+    const args = node.parent();
+    const callee = args?.kind() === "arguments" ? args.parent()?.field("function")?.text() : undefined;
+    const first = args?.children().find((child) => child.isNamed());
+
+    return (
+        callee !== undefined &&
+        TOOL_COMMAND_CALLEES.has(callee) &&
+        first !== undefined &&
+        first.range().start.index === node.range().start.index
+    );
+}
+
 const RULES: Rule[] = [
     {
         ...STORAGE_ROOT_RULE,
@@ -137,6 +190,20 @@ const RULES: Rule[] = [
         test: (text) => GENESIS_ROUTER_LINK.test(text),
         allowedIn: /(^|\/)src\/utils\/(browser-router|app-links)\//,
     },
+    {
+        name: "no-tool-command-in-utils",
+        severity: "error",
+        kinds: LITERAL_KINDS,
+        message:
+            "A module under src/utils names no `tools …` command: another repo copies these modules, and there " +
+            "`toolCommand()` names its own binary. Add a function to src/utils/genesis-tools/tools/hints.ts and have " +
+            "the GenesisTools caller pass its result into the util as an option; a util without the option prints " +
+            "no hint. scripts/ci/tool-command-ratchet.ts lists the files not migrated yet.",
+        test: namesToolCommand,
+        onlyIn: /(^|\/)src\/utils\//,
+        allowedIn: /(^|\/)src\/utils\/genesis-tools\/tools\/hints\.ts$/,
+        allowedFiles: TOOL_COMMAND_RATCHET,
+    },
 ];
 
 const PROMPT_BACKEND_RULE = {
@@ -764,7 +831,7 @@ export function checkSource(file: string, source: string): Finding[] {
         const text = node.text();
 
         for (const rule of RULES) {
-            if (rule.test(text) && !rule.allowedIn?.test(file)) {
+            if (ruleApplies(rule, file) && rule.test(text, node)) {
                 record(node, rule);
             }
         }
@@ -983,7 +1050,7 @@ async function scanAll(files: string[], options: { processToolOnly?: boolean } =
                         const text = node.text();
 
                         for (const rule of RULES) {
-                            if (rule.test(text) && !rule.allowedIn?.test(node.getRoot().filename())) {
+                            if (ruleApplies(rule, node.getRoot().filename()) && rule.test(text, node)) {
                                 push(node, rule);
                             }
                         }
@@ -1108,7 +1175,7 @@ if (import.meta.main) {
     const timing = `boot ${boot}ms, list ${listed - started}ms, scan ${scanned - listed}ms`;
 
     if (findings.length === 0) {
-        console.log(`lint-rules: OK (${files.length} files, 11 repo rules) [${timing}]`);
+        console.log(`lint-rules: OK (${files.length} files, 12 repo rules) [${timing}]`);
     } else {
         console.log(`\nlint-rules: ${errors} error(s), ${warnings} warning(s) across ${files.length} files`);
     }
diff --git a/scripts/ci/tool-command-ratchet.ts b/scripts/ci/tool-command-ratchet.ts
new file mode 100644
index 0000000000..9eb4ab5f46
--- /dev/null
+++ b/scripts/ci/tool-command-ratchet.ts
@@ -0,0 +1,62 @@
+/**
+ * The files under src/utils that still name a `tools …` command, counted 2026-10-22 when lint-rules
+ * `no-tool-command-in-utils` was added: 124 literals in 52 files, of which json2md and the notification `say`
+ * option were migrated at once. A ratchet: no file may join this list, and a file leaves it as soon as its hints
+ * come from src/utils/genesis-tools/tools/hints.ts through its GenesisTools caller. `lint-rules.test.ts` fails
+ * when a listed file no longer names a command, so the list cannot go stale.
+ *
+ * notifications-app.ts is GenesisTools-only by design (notifications.ts loads it by a runtime path, and a copy
+ * leaves it out), so its hints stay where they are.
+ */
+export const TOOL_COMMAND_RATCHET: ReadonlySet<string> = new Set<string>([
+    "src/utils/agent-sessions/history-cli.ts",
+    "src/utils/agent-sessions/open-service.ts",
+    "src/utils/ai/AIAccount.ts",
+    "src/utils/ai/config/account-ops.ts",
+    "src/utils/ai/config/doctor.ts",
+    "src/utils/ai/core/resolve.ts",
+    "src/utils/ai/evaluation/auth.ts",
+    "src/utils/ai/evaluation/cli.ts",
+    "src/utils/ai/evaluation/config-cli.ts",
+    "src/utils/ai/evaluation/errors.ts",
+    "src/utils/ai/evaluation/service.ts",
+    "src/utils/ai/gate/request.ts",
+    "src/utils/ai/github-copilot/auth-errors.ts",
+    "src/utils/ai/grok/account.ts",
+    "src/utils/ai/grok/stored-grant.ts",
+    "src/utils/ai/local/runtimes/transformers-js/index.ts",
+    "src/utils/ai/openai/account-binding.ts",
+    "src/utils/ai/providers/credentials.ts",
+    "src/utils/ai/providers/elevenlabs/AIElevenLabsTextToSpeechProvider.ts",
+    "src/utils/ai/providers/plugins/anthropic-sub/subscription.ts",
+    "src/utils/ai/providers/plugins/anthropic-sub/warmup.ts",
+    "src/utils/ai/providers/plugins/huggingface.ts",
+    "src/utils/ai/providers/plugins/openai-sub/usage.ts",
+    "src/utils/ai/providers/resolve.ts",
+    "src/utils/ai/statusline/config.ts",
+    "src/utils/ai/stt/resolve.ts",
+    "src/utils/ai/tasks/resolve-task.ts",
+    "src/utils/ai/warmup/index.ts",
+    "src/utils/browser-router/presets.ts",
+    "src/utils/browser-router/router-link.ts",
+    "src/utils/claude/subscription-auth.ts",
+    "src/utils/cmux/lib/health.ts",
+    "src/utils/cmux/tmux-host.ts",
+    "src/utils/DashboardApp/lifecycle.ts",
+    "src/utils/git/base-detect.ts",
+    "src/utils/ink/usage-dashboard/views/overview-view.tsx",
+    "src/utils/macos/apple-calendar.ts",
+    "src/utils/macos/full-disk-access.ts",
+    "src/utils/macos/notifications-app.ts",
+    "src/utils/macos/xcode.ts",
+    "src/utils/search/stores/sqlite-vector-store.ts",
+    "src/utils/security/MasterKey.ts",
+    "src/utils/security/SecretStore.ts",
+    "src/utils/security/vault-admin.ts",
+    "src/utils/transclude/describe.ts",
+    "src/utils/transclude/engine.ts",
+    "src/utils/transclude/kinds/cmd.ts",
+    "src/utils/ts/sourcemaps/find-commit.ts",
+    "src/utils/ui/dashboards.ts",
+    "src/utils/worker/contract.ts",
+]);
diff --git a/src/json2md/commands/document.ts b/src/json2md/commands/document.ts
index 8f22a28951..d03c22490f 100644
--- a/src/json2md/commands/document.ts
+++ b/src/json2md/commands/document.ts
@@ -2,6 +2,7 @@ import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { suggestCommand } from "@genesiscz/utils/cli";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
+import { json2mdBuild } from "@genesiscz/utils/genesis-tools/tools/hints";
 import { SafeJSON } from "@genesiscz/utils/json";
 import {
     checkDocument,
@@ -290,6 +291,7 @@ function registerBuild(program: Command): void {
                 const result = await writeDocument(modulePath, definition, {
                     force: flags.force,
                     dryRun: flags.dryRun,
+                    rebuildCommand: json2mdBuild,
                 });
 
                 logger.debug({ file: modulePath, outcome: result.outcome, out: result.outPath }, "json2md: build");
@@ -355,7 +357,7 @@ function registerCheck(program: Command): void {
                 }
 
                 const definition = await loadDocumentModule(modulePath);
-                results.push(await checkDocument(modulePath, definition));
+                results.push(await checkDocument(modulePath, definition, { rebuildCommand: json2mdBuild }));
             }
 
             // A document that was never generated reads as `unstamped`, which is not a failure for
@@ -465,7 +467,7 @@ function registerInit(program: Command): void {
             }
 
             const definition = await loadDocumentModule(modulePath);
-            const result = await writeDocument(modulePath, definition);
+            const result = await writeDocument(modulePath, definition, { rebuildCommand: json2mdBuild });
 
             if (result.outcome === "refused" && result.check) {
                 // A markdown file already sits at the output path. It is left alone.
diff --git a/src/utils/genesis-tools/tools/hints.ts b/src/utils/genesis-tools/tools/hints.ts
new file mode 100644
index 0000000000..2c72280113
--- /dev/null
+++ b/src/utils/genesis-tools/tools/hints.ts
@@ -0,0 +1,20 @@
+import { toolCommand } from "@genesiscz/utils/cli/tool-command";
+
+/**
+ * Every GenesisTools command that a shared module under `src/utils` shows or runs, in one place.
+ *
+ * A util never imports this file. A GenesisTools command, MCP server or other entry point calls one of these and
+ * passes the result into the util as an option, so a copy of the util in another repo, where `toolCommand()` names
+ * a different binary, gets no hint and prints none. lint-rules `no-tool-command-in-utils` allows a `tools …`
+ * command under `src/utils` only here (and in the files its ratchet list still names).
+ */
+
+/** The command json2md writes into a document's stamp, so a reader can rebuild it. */
+export function json2mdBuild(portable: string): string {
+    return `${toolCommand("json2md build")} ${portable}`;
+}
+
+/** The argv that speaks a notification's message aloud; the message is appended as the last word. */
+export function notificationSayCommand(): string[] {
+    return toolCommand("say").split(" ");
+}
diff --git a/src/utils/json2md/document-file.ts b/src/utils/json2md/document-file.ts
index 259d229ebd..83249e8887 100644
--- a/src/utils/json2md/document-file.ts
+++ b/src/utils/json2md/document-file.ts
@@ -9,7 +9,6 @@
  */
 
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { resolveIncludes } from "@genesiscz/utils/markdown/includes";
 import { hasTransclusionTokens } from "@genesiscz/utils/transclude";
@@ -29,7 +28,10 @@ export interface DocumentDefinition<T = unknown> {
     render: (data: T) => BlockInput;
     /** Title, front matter, provenance header and contents list. */
     options?: DocumentOptions;
-    /** The command a reader should run to regenerate. Defaults to `tools json2md build <file>`. */
+    /**
+     * The command a reader should run to regenerate. Defaults to {@link DocumentHints.rebuildCommand} of the
+     * build; with neither, the stamp records no command.
+     */
     command?: string;
     /** Skip the stamp. Only for a document that a person is expected to keep editing. */
     unstamped?: boolean;
@@ -148,7 +150,16 @@ export interface BuildResult {
     data: unknown;
 }
 
-export interface BuildOverrides {
+/**
+ * What only the caller knows: GenesisTools passes `json2mdBuild` from `@genesiscz/utils/genesis-tools/tools/hints`.
+ * A build without it writes no rebuild command, so a copy of this module never names a command its repo lacks.
+ */
+export interface DocumentHints {
+    /** The command that rebuilds the document, given its generator path relative to the cwd (or absolute). */
+    rebuildCommand?: (portable: string) => string;
+}
+
+export interface BuildOverrides extends DocumentHints {
     /**
      * Pins the generated-at timestamp instead of using now.
      *
@@ -209,11 +220,11 @@ export async function buildDocument<T>(
     // 🛑 The recorded command must not depend on where the generator happened to be run from.
     // A `relative(process.cwd(), …)` path is written into a DURABLE file that another person,
     // in another directory, is meant to be able to run: building a vault note from the repo
-    // recorded `tools json2md build ../../../../../…`, which works from exactly one place.
+    // recorded a `json2md build ../../../../../…` command, which works from exactly one place.
     // A path inside the current directory stays short; anything outside it goes in absolute.
     const fromCwd = relative(process.cwd(), modulePath);
     const portable = fromCwd !== "" && !fromCwd.startsWith("..") && !isAbsolute(fromCwd) ? fromCwd : modulePath;
-    const command = definition.command ?? `${toolCommand("json2md build")} ${portable}`;
+    const command = definition.command ?? overrides.rebuildCommand?.(portable);
     const markdown = stampMarkdown(body, {
         source: sourceHash,
         generator: relative(dirname(outPath), modulePath) || modulePath,
@@ -224,6 +235,10 @@ export async function buildDocument<T>(
     return { markdown, body, outPath, dataPath, sourceHash, data };
 }
 
+function hintsOf(hints: DocumentHints): DocumentHints {
+    return hints.rebuildCommand ? { rebuildCommand: hints.rebuildCommand } : {};
+}
+
 export type WriteOutcome = "written" | "unchanged" | "refused";
 
 export interface WriteResult extends BuildResult {
@@ -231,7 +246,7 @@ export interface WriteResult extends BuildResult {
     check: CheckResult | null;
 }
 
-export interface WriteOptions {
+export interface WriteOptions extends DocumentHints {
     /** Overwrite even when the file was edited by hand. */
     force?: boolean;
     /** Render and compare, but do not write. */
@@ -253,7 +268,7 @@ export async function writeDocument<T>(
     const existing = Bun.file(outPath);
 
     if (!(await existing.exists())) {
-        const built = await buildDocument(modulePath, definition);
+        const built = await buildDocument(modulePath, definition, hintsOf(options));
 
         if (!options.dryRun) {
             await Bun.write(built.outPath, built.markdown);
@@ -265,7 +280,10 @@ export async function writeDocument<T>(
     const current = await existing.text();
     // Rebuild at the previous timestamp first. Only if THAT still differs has something real
     // changed, so an unchanged document keeps its original generated-at and never re-diffs.
-    const pinned = await buildDocument(modulePath, definition, { generatedAt: stripStamp(current).stamp?.generated });
+    const pinned = await buildDocument(modulePath, definition, {
+        ...hintsOf(options),
+        generatedAt: stripStamp(current).stamp?.generated,
+    });
     const check = checkMarkdown({ current, regenerated: pinned.markdown, sourceHash: pinned.sourceHash });
 
     if (check.verdict === "clean") {
@@ -279,7 +297,7 @@ export async function writeDocument<T>(
         return { ...pinned, outcome: "refused", check };
     }
 
-    const fresh = await buildDocument(modulePath, definition);
+    const fresh = await buildDocument(modulePath, definition, hintsOf(options));
 
     if (!options.dryRun) {
         await Bun.write(fresh.outPath, fresh.markdown);
@@ -297,7 +315,11 @@ export interface DocumentCheck extends CheckResult {
 }
 
 /** Checks the written document against what the definition produces now. */
-export async function checkDocument<T>(modulePath: string, definition: DocumentDefinition<T>): Promise<DocumentCheck> {
+export async function checkDocument<T>(
+    modulePath: string,
+    definition: DocumentDefinition<T>,
+    hints: DocumentHints = {}
+): Promise<DocumentCheck> {
     const outPath = outputPathFor(modulePath, definition);
     const file = Bun.file(outPath);
 
@@ -315,7 +337,10 @@ export async function checkDocument<T>(modulePath: string, definition: DocumentD
 
     const current = await file.text();
     // Pinned to the file's own timestamp, so the generated-at line is never itself the change.
-    const built = await buildDocument(modulePath, definition, { generatedAt: stripStamp(current).stamp?.generated });
+    const built = await buildDocument(modulePath, definition, {
+        ...hintsOf(hints),
+        generatedAt: stripStamp(current).stamp?.generated,
+    });
     const check = checkMarkdown({ current, regenerated: built.markdown, sourceHash: built.sourceHash });
 
     return {
diff --git a/src/utils/json2md/json2md.test.ts b/src/utils/json2md/json2md.test.ts
index 871505cda2..cf61d7cc48 100644
--- a/src/utils/json2md/json2md.test.ts
+++ b/src/utils/json2md/json2md.test.ts
@@ -801,12 +801,31 @@ describe("three-file pattern", () => {
         const modulePath = join(dir, "doc.ts");
         await Bun.write(join(dir, "doc.json"), SafeJSONStringify({ items: [{ id: 1, name: "one" }] }));
 
-        const built = await writeDocument(modulePath, definitionFor("./doc.json"));
+        const built = await writeDocument(modulePath, definitionFor("./doc.json"), {
+            rebuildCommand: (portable) => `rebuild ${portable}`,
+        });
         const stamped = await Bun.file(built.outPath).text();
         const recorded = decodeURIComponent(stamped.match(/command=([^\s]+)/)?.[1] ?? "");
 
         expect(recorded).not.toContain("..");
-        expect(recorded).toBe(`tools json2md build ${modulePath}`);
+        expect(recorded).toBe(`rebuild ${modulePath}`);
+    });
+
+    test("a build without a rebuild command records none, and the definition's own command still wins", async () => {
+        const dir = await scratch();
+        const modulePath = join(dir, "doc.ts");
+        await Bun.write(join(dir, "doc.json"), SafeJSONStringify({ items: [{ id: 1, name: "one" }] }));
+
+        const bare = await buildDocument(modulePath, definitionFor("./doc.json"));
+        expect(bare.markdown).toContain("json2md:stamp");
+        expect(bare.markdown).not.toContain("command=");
+
+        const own = await buildDocument(
+            modulePath,
+            { ...definitionFor("./doc.json"), command: "make docs" },
+            { rebuildCommand: (portable) => `rebuild ${portable}` }
+        );
+        expect(own.markdown).toContain(`command=${encodeURIComponent("make docs")}`);
     });
 
     test("dry-run reports without touching the file", async () => {
diff --git a/src/utils/macos/notifications.ts b/src/utils/macos/notifications.ts
index d3b207245d..3e391942ce 100644
--- a/src/utils/macos/notifications.ts
+++ b/src/utils/macos/notifications.ts
@@ -2,7 +2,6 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { withTimeout } from "@genesiscz/utils/async";
-import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { logger } from "@genesiscz/utils/logger";
 import { escapeJxa } from "@genesiscz/utils/macos/jxa";
 import { boundedCommand } from "@genesiscz/utils/process/bounded-command";
@@ -26,7 +25,14 @@ export interface NotificationOptions {
      */
     attachments?: string[];
     ignoreDnD?: boolean;
+    /** Also speak the message through {@link NotificationOptions.sayCommand}. Nothing is spoken without one. */
     say?: boolean;
+    /**
+     * The argv that speaks the message, which is appended as its last word. GenesisTools passes
+     * `notificationSayCommand()` from `@genesiscz/utils/genesis-tools/tools/hints`; a copy of this module names no
+     * speech command of its own.
+     */
+    sayCommand?: string[];
     /**
      * Stable id, so the notification can be retracted later with {@link removeNotifications}, or
      * replaced in place by posting again with the same id. Generated when omitted.
@@ -490,19 +496,28 @@ export async function sendNotification(opts: NotificationOptions): Promise<Poste
     const posted = await postNotification(opts);
 
     if (opts.say) {
-        try {
-            Bun.spawn(["tools", "say", opts.message], {
-                stdout: "ignore",
-                stderr: "ignore",
-            });
-        } catch {
-            logger.debug(`${toolCommand("say")} failed for notification TTS`);
-        }
+        speak(opts.message, opts.sayCommand ?? []);
     }
 
     return posted;
 }
 
+function speak(message: string, command: string[]): void {
+    if (command.length === 0) {
+        logger.debug("notification TTS skipped: no say command was passed");
+        return;
+    }
+
+    try {
+        Bun.spawn([...command, message], {
+            stdout: "ignore",
+            stderr: "ignore",
+        });
+    } catch {
+        logger.debug(`${command.join(" ")} failed for notification TTS`);
+    }
+}
+
 export type NotificationFallbackState =
     | { kind: "genesis-app" }
     | { kind: "terminal-notifier"; path: string }

From 6675b661027a0cc445c041224b3ec4eea2ec96cf Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 18:39:16 +0200
Subject: [PATCH 18/30] feat(question): agents record chat answers and
 supersede decisions with a link; widget cards carry answers, inbox items
 carry titles, alert preferences

---
 .../genesis-tools/skills/question/SKILL.md    |   4 +
 src/genesis-tools-mcp/lib/server.ts           |   4 +-
 .../lib/tools/question-post.ts                |   4 +-
 .../lib/tools/question-update.ts              |  13 +-
 src/hub/lib/composer/outbox.test.ts           | 121 +++++++++++++++++-
 src/hub/lib/widget/snapshot.ts                |  99 +++++++++++++-
 src/hub/lib/widget/types.ts                   |   8 ++
 src/question/README.md                        |   8 ++
 src/question/commands/decisions.ts            |   2 +-
 src/question/lib/decisions/read.ts            |   4 +
 src/question/lib/decisions/schema.ts          |  28 +++-
 src/question/lib/decisions/store.test.ts      | 116 +++++++++++++++++
 src/question/lib/decisions/store.ts           |  84 ++++++++++--
 src/question/lib/inbox/build.ts               |  11 +-
 14 files changed, 479 insertions(+), 27 deletions(-)

diff --git a/plugins/genesis-tools/skills/question/SKILL.md b/plugins/genesis-tools/skills/question/SKILL.md
index 4d5d151ae0..058e12d01e 100644
--- a/plugins/genesis-tools/skills/question/SKILL.md
+++ b/plugins/genesis-tools/skills/question/SKILL.md
@@ -37,3 +37,7 @@ Then tell the user one line — "Logged ✓ (`<id>`)" — or, if the tool return
 ## Native inbox (only when your instructions mention it)
 
 Some Macs run the native GenesisTools widget, whose inbox shows these entries as cards. Your session is told about it by the genesis-tools MCP server instructions or a SessionStart note that starts with `INBOX:`. Follow that text for WHEN to post decisions, messages and screenshots, and whether you must also ask in the chat. If no `INBOX:` text reached you, this Mac has no native inbox: do not mention it and do not use `inbox_send` or `tools question message`.
+
+## Decisions you posted: record the answer
+
+When the user answers a ❓ DECISION in chat, or it is settled another way, record it in the same turn: `question_update { id, state: "acknowledged", option, answer: "<the user's words or a short copy>" }` (CLI: `tools question update`, the same JSON on stdin). When a later decision replaces it: `question_update { id, state: "superseded", supersededBy: "<new id>", comment: "<why>" }`. Never leave an answered decision open.
diff --git a/src/genesis-tools-mcp/lib/server.ts b/src/genesis-tools-mcp/lib/server.ts
index 1a00d68766..b4c4f97714 100644
--- a/src/genesis-tools-mcp/lib/server.ts
+++ b/src/genesis-tools-mcp/lib/server.ts
@@ -1,4 +1,5 @@
 import { loadConfig as loadQuestionConfig } from "@app/question/lib/config";
+import { DECISION_RECORD_RULE } from "@app/question/lib/decisions/schema";
 import { decisionNudge, inboxInstructions, inboxSendDescription } from "@app/question/lib/inbox-guidance";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { env } from "@genesiscz/utils/env/envVariables";
@@ -112,7 +113,8 @@ export function serverInstructions({ askViaQuestionTool, inboxState }: Instructi
         decisionNudge({ state: inboxState, askViaQuestionTool }) +
         "Record " +
         "progress (acknowledged, implemented, commit refs, verdict, comments, a copy of a chat answer) with " +
-        `\`question_update\`, several items per call. CLI: \`${toolCommand("question ask", "--json", "-")}\`, ` +
+        `\`question_update\`, several items per call. ${DECISION_RECORD_RULE} ` +
+        `CLI: \`${toolCommand("question ask", "--json", "-")}\`, ` +
         `\`${toolCommand("question")} list|update|answers|answer|draft|send\`.\n` +
         'INLINE TOKENS: item text may carry {{kind key="value"}} tokens (lines, file, symbol, diff, tail, json, ' +
         "cmd, url, image, pr-thread), resolved into real content when the item is saved; `question_tokens` lists " +
diff --git a/src/genesis-tools-mcp/lib/tools/question-post.ts b/src/genesis-tools-mcp/lib/tools/question-post.ts
index f42d923533..fcb4777b86 100644
--- a/src/genesis-tools-mcp/lib/tools/question-post.ts
+++ b/src/genesis-tools-mcp/lib/tools/question-post.ts
@@ -8,6 +8,7 @@ import {
     validateQuestionItems,
 } from "@app/question/lib/decisions/items";
 import { currentHarnessSession, decisionFiles, sessionAnswers } from "@app/question/lib/decisions/read";
+import { DECISION_RECORD_RULE } from "@app/question/lib/decisions/schema";
 import { type DecisionRecord, type PostDecisionDeps, readDecisions } from "@app/question/lib/decisions/store";
 import { decisionNudge } from "@app/question/lib/inbox-guidance";
 import {
@@ -501,7 +502,8 @@ export function questionPostDescription({
         'Items with type "decision" or "todo" are NOT a form: they are numbered in this session\'s decision log ' +
         "(numbers are session-wide and never reused) and the result is the markdown ❓ DECISION / TODO section to " +
         `paste into your reply. ${nudge}${answeredIn} reach you in a later prompt or through ` +
-        "question_poll, and you record progress with question_update. To correct an item nobody answered yet, " +
+        `question_poll, and you record progress with question_update. ${DECISION_RECORD_RULE} ` +
+        "To correct an item nobody answered yet, " +
         "post it again with supersedes: <its id>; it keeps its number and the old text is kept as a version.\n" +
         'SCREENSHOTS: any item may carry attachments: [{type: "image", path: "/abs/shot.png", label?}]; they are ' +
         `copied into the question store and ${native ? "shown as image previews on the inbox card" : "embedded in the item text"}.\n` +
diff --git a/src/genesis-tools-mcp/lib/tools/question-update.ts b/src/genesis-tools-mcp/lib/tools/question-update.ts
index ea4e43493b..f2f8f0ea4b 100644
--- a/src/genesis-tools-mcp/lib/tools/question-update.ts
+++ b/src/genesis-tools-mcp/lib/tools/question-update.ts
@@ -1,5 +1,5 @@
 import { decisionFiles } from "@app/question/lib/decisions/read";
-import { decisionBatchUpdateSchema } from "@app/question/lib/decisions/schema";
+import { DECISION_RECORD_RULE, decisionBatchUpdateSchema } from "@app/question/lib/decisions/schema";
 import { updateDecisions } from "@app/question/lib/decisions/store";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { z } from "zod";
@@ -10,10 +10,13 @@ export const QUESTION_UPDATE_INPUT_SCHEMA = z.toJSONSchema(decisionBatchUpdateSc
 export const QUESTION_UPDATE_DESCRIPTION =
     "Update decisions and todos you posted with question_post (type decision|todo), several per call, as ONE " +
     "change: a batch with an unknown id or an illegal move changes nothing. Per item: `state` (decision: open → " +
-    "answered|drafted, drafted → answered, answered → sent, sent → acknowledged, acknowledged → implemented; todo: " +
-    "open → acknowledged|implemented, acknowledged → implemented), `answer` (a copy of an answer the user gave in " +
-    "chat), `option` (the letter), `commitRefs`, `verdict`, `comment` (appended). Mark a delivered answer " +
-    "`acknowledged` once you act on it and `implemented` with commitRefs when it is done.";
+    "answered|drafted|acknowledged|superseded, drafted → answered|acknowledged|superseded, answered → sent, " +
+    "sent → acknowledged|superseded, acknowledged → implemented|superseded; todo: open → acknowledged|implemented, " +
+    "acknowledged → implemented), `answer` (a copy of an answer the user gave in chat), `option` (the letter), " +
+    "`supersededBy` (the id of the decision that replaces this one), `commitRefs`, `verdict`, `comment` (appended). " +
+    "open or drafted → acknowledged needs `option` or `answer` and delivers nothing; superseded needs " +
+    "`supersededBy` or `comment`. Mark a delivered answer `acknowledged` once you act on it and `implemented` with " +
+    `commitRefs when it is done. ${DECISION_RECORD_RULE}`;
 
 export async function handleQuestionUpdate(
     args: unknown,
diff --git a/src/hub/lib/composer/outbox.test.ts b/src/hub/lib/composer/outbox.test.ts
index f8b92a98d1..d6fba0282e 100644
--- a/src/hub/lib/composer/outbox.test.ts
+++ b/src/hub/lib/composer/outbox.test.ts
@@ -9,7 +9,13 @@ import { dirname, join, resolve } from "node:path";
 import { DeliveryUnknownError } from "@app/question/lib/decisions/deliver";
 import { livePaneTargets } from "@app/question/lib/decisions/deliver.fixtures";
 import { decisionFiles, deliverDecisions } from "@app/question/lib/decisions/read";
-import { createTodo, type DecisionRecord, postDecisions, readDecisions } from "@app/question/lib/decisions/store";
+import {
+    createTodo,
+    type DecisionRecord,
+    postDecisions,
+    readDecisions,
+    updateDecisions,
+} from "@app/question/lib/decisions/store";
 import { sendInboxMessage } from "@app/question/lib/message";
 import { postAskForm } from "@app/question/lib/pending/ask";
 import { MAX_ANSWER_IMAGE_BYTES } from "@app/question/lib/pending/form";
@@ -79,6 +85,7 @@ import {
     widgetForms,
     widgetResultNode,
     widgetSnapshot,
+    widgetTitle,
 } from "../widget/snapshot";
 import { MAX_WIDGET_STATE_BYTES, mutateWidgetState, readWidgetState } from "../widget/storage";
 import {
@@ -1601,6 +1608,118 @@ test("an open TODO does not mark its session as waiting for an answer", async ()
     expect(needsAnswer.sessions[0]?.status).toBe("waiting");
 });
 
+test("decision cards carry recorded answers and supersede links; only open decisions ask, with a title and number", async () => {
+    const directory = await root();
+    const file = join(directory, "decisions.jsonl");
+    const events = join(directory, "events.jsonl");
+    const [answered, old, replacement] = await postDecisions(
+        file,
+        events,
+        {
+            sessionId: "card-session",
+            provider: "codex",
+            decisions: [
+                { prompt: "Keep the cache?", options: ["keep", "drop"], reasoning: "It is slow." },
+                { prompt: "Old wording?", options: ["a"] },
+                { prompt: `Rename it? ${"long ".repeat(60)}`, options: ["yes", "no"] },
+            ],
+        },
+        { env: {} }
+    );
+    const [elsewhere] = await postDecisions(
+        file,
+        events,
+        {
+            sessionId: "other-card-session",
+            provider: "codex",
+            decisions: [{ title: "Other", prompt: "x", options: [] }],
+        },
+        { env: {} }
+    );
+    await updateDecisions(file, events, {
+        updates: [
+            { id: answered.id, state: "acknowledged", option: "b", answer: "drop it, said in chat" },
+            { id: old.id, state: "superseded", supersededBy: replacement.id, comment: "reworded" },
+        ],
+    });
+    const sources: WidgetSources = {
+        sessions: async () => [],
+        decisions: () => readDecisions(file),
+        forms: () => [],
+        answers: () => [],
+        agents: async () => ({ generatedAt: "", parents: [], orphans: [] }),
+    };
+    const snapshot = await widgetSnapshot({ root: directory, sources });
+    const card = (id: string) => snapshot.cards.find((entry) => entry.sourceId === id);
+    expect(card(answered.id)).toMatchObject({
+        status: "acknowledged",
+        option: "b",
+        answer: "drop it, said in chat",
+        answeredVia: "agent",
+    });
+    // The answer is its own field; the body no longer repeats it.
+    expect(card(answered.id)?.body).not.toContain("drop it");
+    expect(card(answered.id)?.body).toContain("It is slow.");
+    const sessionKey = snapshot.sessions.find((entry) => entry.target.sessionId === "card-session")?.key;
+    expect(card(old.id)).toMatchObject({
+        status: "superseded",
+        comments: ["reworded"],
+        supersededBy: { id: replacement.id, number: 3, sessionKey, title: widgetTitle(replacement.prompt) },
+    });
+    expect(card(old.id)?.supersededBy?.title?.length).toBe(160);
+    expect(card(replacement.id)?.supersededBy).toBeUndefined();
+
+    // Acknowledged and superseded decisions are not pending: only the replacement asks.
+    const session = snapshot.notifications?.sessions.find((entry) => entry.key === sessionKey);
+    expect(session?.needsAnswer).toBe(1);
+    expect(session?.pendingItem).toMatchObject({
+        id: `decision:${replacement.id}`,
+        number: 3,
+        title: widgetTitle(replacement.prompt),
+    });
+    expect(
+        snapshot.notifications?.sessions.find((entry) => entry.pendingItem?.sourceId === elsewhere.id)?.pendingItem
+    ).toMatchObject({ number: 1, title: "Other" });
+
+    await updateDecisions(file, events, {
+        updates: [{ id: replacement.id, state: "superseded", supersededBy: elsewhere.id, comment: "moved" }],
+    });
+    const moved = await widgetSnapshot({ root: directory, sources });
+    expect(moved.cards.find((entry) => entry.sourceId === replacement.id)?.supersededBy).toEqual({
+        id: elsewhere.id,
+        number: 1,
+        sessionKey: moved.sessions.find((entry) => entry.target.sessionId === "other-card-session")?.key,
+        title: "Other",
+    });
+    expect(moved.notifications?.sessions.find((entry) => entry.key === sessionKey)?.needsAnswer ?? 0).toBe(0);
+});
+
+test("alert preferences default on with the Glass sound, load from an older state, and refuse a bad sound", async () => {
+    const directory = await root();
+    await writeFile(
+        join(directory, "state.json"),
+        SafeJSON.stringify({ version: 1, preferences: { placement: "side" } })
+    );
+    expect((await readWidgetState(directory)).preferences).toMatchObject({
+        placement: "side",
+        alertDecisions: true,
+        alertAnswers: true,
+        alertSound: "Glass",
+        alertPopup: true,
+    });
+    await performWidgetAction({
+        root: directory,
+        input: { action: "preferences", patch: { alertSound: "none", alertPopup: false } },
+    });
+    expect((await readWidgetState(directory)).preferences).toMatchObject({ alertSound: "none", alertPopup: false });
+    for (const alertSound of ["", "x".repeat(41)]) {
+        await expect(
+            performWidgetAction({ root: directory, input: { action: "preferences", patch: { alertSound } } })
+        ).rejects.toThrow();
+    }
+    expect((await readWidgetState(directory)).preferences.alertSound).toBe("none");
+});
+
 test("failed post-copy video checks remove the unreferenced copy while successful imports stay durable", async () => {
     const directory = await root();
     const source = join(directory, "video.mp4");
diff --git a/src/hub/lib/widget/snapshot.ts b/src/hub/lib/widget/snapshot.ts
index 0d3ea1c242..e7da1eca7d 100644
--- a/src/hub/lib/widget/snapshot.ts
+++ b/src/hub/lib/widget/snapshot.ts
@@ -2,7 +2,7 @@ import { existsSync, statSync } from "node:fs";
 import { sessionChangesPath } from "@app/agents/lib/changes/log";
 import { type AgentSessionRow, listAgentSessionRows } from "@app/ai/lib/sessions/agent-session-rows";
 import { decisionFiles } from "@app/question/lib/decisions/read";
-import { type DecisionRecord, kindOf, readDecisions } from "@app/question/lib/decisions/store";
+import { type AnsweredVia, type DecisionRecord, kindOf, readDecisions } from "@app/question/lib/decisions/store";
 import { INBOX_STALE_MS } from "@app/question/lib/inbox/build";
 import { renderFormAnswer } from "@app/question/lib/pending/render";
 import { listFormsSnapshot, PENDING_MIGRATIONS } from "@app/question/lib/pending/store";
@@ -99,6 +99,33 @@ export interface WidgetCard {
     refs: { type: string; value: string }[];
     read: boolean;
     entryId?: string;
+    /** Decision cards: the chosen option letters and the answer text, however they were stored. */
+    option?: string;
+    answer?: string;
+    /** Decision cards: every comment, oldest first (a supersede reason, progress notes). */
+    comments?: string[];
+    /** Decision cards: who stored the answer, the user in an inbox (`inbox`) or an agent copying a chat answer. */
+    answeredVia?: AnsweredVia;
+    /** A superseded decision: the decision that replaced it, with the widget key of its session when known. */
+    supersededBy?: WidgetSupersededBy;
+}
+export interface WidgetSupersededBy {
+    id: string;
+    number: number;
+    sessionKey?: string;
+    /** The replacing decision's title, else its prompt, at most 160 characters. */
+    title?: string;
+}
+/** The longest inbox or link title the snapshot carries. */
+export const WIDGET_TITLE_MAX = 160;
+/** One line of at most {@link WIDGET_TITLE_MAX} characters, or undefined for an empty text. */
+export function widgetTitle(text: string | null | undefined): string | undefined {
+    const line = text?.replace(/\s+/g, " ").trim();
+    if (!line) {
+        return undefined;
+    }
+
+    return line.length > WIDGET_TITLE_MAX ? `${line.slice(0, WIDGET_TITLE_MAX - 1)}…` : line;
 }
 export interface WidgetSources {
     sessions(refresh: boolean): Promise<AgentSessionRow[]>;
@@ -127,6 +154,8 @@ export interface WidgetInboxGroup {
     /** The group's newest item. */
     at: number;
     count: number;
+    /** The newest item's own title: an answer's question, a form's first prompt. */
+    itemTitle?: string | null;
     /** Items after the window's `clearedAt`. */
     afterClear: number;
     /** Of those, the ones at or after `staleBefore`: what a quiet session counts. */
@@ -162,6 +191,10 @@ export interface WidgetInboxItem {
     key: string;
     at: number;
     needsAnswer: boolean;
+    /** The item's own title, at most 160 characters: a decision's title or prompt, a question, a form's prompt. */
+    title?: string;
+    /** A decision's number. */
+    number?: number;
 }
 export interface WidgetInboxSession {
     key: string;
@@ -202,7 +235,7 @@ function readInboxData(window: WidgetInboxWindow): WidgetInboxData {
                         CASE WHEN agent IN ('claude','claude-code') THEN 'claude'
                              WHEN agent IN ('codex','grok') THEN agent ELSE 'unknown' END AS provider,
                         COALESCE(session_title,session_id,id) AS title, COALESCE(project,'') AS project,
-                        COALESCE(cwd,'') AS cwd, ts AS at
+                        COALESCE(cwd,'') AS cwd, ts AS at, substr(question,1,400) AS itemTitle
                     FROM entries WHERE read_at IS NULL AND superseded_by IS NULL
                         AND NOT EXISTS (SELECT 1 FROM qa_pending WHERE entry_id=entries.id)
                 ), ranked AS (
@@ -210,7 +243,7 @@ function readInboxData(window: WidgetInboxWindow): WidgetInboxData {
                         ${INBOX_WINDOW_COUNTS},
                         ROW_NUMBER() OVER (PARTITION BY sessionId,provider ORDER BY at DESC,id DESC) AS position
                     FROM unseen
-                ) SELECT id,sessionId,provider,title,project,cwd,at,count,afterClear,recentAfterClear,recentAfterClearTotal
+                ) SELECT id,sessionId,provider,title,project,cwd,at,count,itemTitle,afterClear,recentAfterClear,recentAfterClearTotal
                   FROM ranked WHERE position=1 ORDER BY at DESC,id DESC LIMIT 257
             `)
                 .all(...bounds);
@@ -222,7 +255,8 @@ function readInboxData(window: WidgetInboxWindow): WidgetInboxData {
                     SELECT id, COALESCE(NULLIF(session_hint,''),id) AS sessionId,
                         CASE WHEN json_valid(poster_json) THEN NULLIF(json_extract(poster_json,'$.agent'),'unknown') END AS poster,
                         CASE WHEN json_valid(transcript_anchor_json) THEN json_extract(transcript_anchor_json,'$.provider') END AS anchor,
-                        COALESCE(source,'Question') AS title, project_path AS project, cwd, created_at AS at
+                        COALESCE(source,'Question') AS title, project_path AS project, cwd, created_at AS at,
+                        CASE WHEN json_valid(items_json) THEN substr(json_extract(items_json,'$[0].promptMarkdown'),1,400) END AS itemTitle
                     FROM qa_pending WHERE status='pending'
                 ), normalized AS (
                     SELECT *, CASE WHEN COALESCE(poster,anchor) IN ('claude','claude-code') THEN 'claude'
@@ -233,7 +267,7 @@ function readInboxData(window: WidgetInboxWindow): WidgetInboxData {
                         ${INBOX_WINDOW_COUNTS},
                         ROW_NUMBER() OVER (PARTITION BY sessionId,provider ORDER BY at DESC,id DESC) AS position
                     FROM normalized
-                ) SELECT id,sessionId,provider,title,project,cwd,at,count,afterClear,recentAfterClear,recentAfterClearTotal
+                ) SELECT id,sessionId,provider,title,project,cwd,at,count,itemTitle,afterClear,recentAfterClear,recentAfterClearTotal
                   FROM ranked WHERE position=1 ORDER BY at DESC,id DESC LIMIT 257
             `)
                       .all(...bounds)
@@ -643,6 +677,12 @@ function parseWidgetChanges(path: string, target: WidgetTarget): WidgetChanges {
     return { available: true, files: [...files.values()].sort((a, b) => b.at.localeCompare(a.at)).slice(0, 100) };
 }
 
+/** An inbox item's `title`, when the decision has text to show. */
+function decisionTitle(row: DecisionRecord): { title?: string } {
+    const title = widgetTitle(row.title ?? row.prompt);
+    return title ? { title } : {};
+}
+
 export async function widgetSnapshot({
     root,
     selectedKey,
@@ -734,6 +774,7 @@ export async function widgetSnapshot({
                   cwd: row.cwd,
                   at: row.ts,
                   count: 1,
+                  itemTitle: row.question,
                   ...inboxWindowCounts([row.ts], inboxWindow),
                   recentAfterClearTotal: rosterRecent.answers,
               })),
@@ -746,6 +787,7 @@ export async function widgetSnapshot({
                   cwd: form.cwd,
                   at: form.createdAt,
                   count: 1,
+                  itemTitle: form.items[0]?.promptMarkdown,
                   ...inboxWindowCounts([form.createdAt], inboxWindow),
                   recentAfterClearTotal: rosterRecent.forms,
               })),
@@ -991,6 +1033,7 @@ export async function widgetSnapshot({
             if (items === 0) {
                 continue;
             }
+            const title = widgetTitle(row.itemTitle);
             putInbox(
                 session,
                 {
@@ -1000,6 +1043,7 @@ export async function widgetSnapshot({
                     key: session.key,
                     at: row.at,
                     needsAnswer: kind === "form",
+                    ...(title ? { title } : {}),
                 },
                 items
             );
@@ -1027,6 +1071,8 @@ export async function widgetSnapshot({
                 key: session.key,
                 at: timeOf(row.updatedTs),
                 needsAnswer: true,
+                number: row.number,
+                ...decisionTitle(row),
             },
             1
         );
@@ -1057,7 +1103,20 @@ export async function widgetSnapshot({
             continue;
         }
         unreadResults += 1;
-        putInbox(session, { id, sourceId: node.id, kind: "result", key: session.key, at, needsAnswer: false }, 1);
+        const title = widgetTitle(node.name ?? node.description);
+        putInbox(
+            session,
+            {
+                id,
+                sourceId: node.id,
+                kind: "result",
+                key: session.key,
+                at,
+                needsAnswer: false,
+                ...(title ? { title } : {}),
+            },
+            1
+        );
     }
     const notifications: WidgetInboxSummary = {
         unread: inboxCount("answer", inboxData.answers) + unreadResults,
@@ -1145,6 +1204,26 @@ export async function widgetSnapshot({
             read: row.readAt !== null,
         });
     }
+    const decisionsById = new Map(decisions.map((row) => [row.id, row]));
+    /** The decision that replaced `row`, with the widget key of its session when the roster knows it. */
+    const supersededBy = (row: DecisionRecord): { supersededBy?: WidgetSupersededBy } => {
+        if (!row.supersededBy) {
+            return {};
+        }
+
+        const target = decisionsById.get(row.supersededBy);
+        const number = target?.number ?? Number(/^d_(\d+)_/.exec(row.supersededBy)?.[1] ?? 0);
+        const sessionKey = target ? findSession(target.sessionId, target.provider)?.key : undefined;
+        const title = target ? widgetTitle(target.title ?? target.prompt) : undefined;
+        return {
+            supersededBy: {
+                id: row.supersededBy,
+                number,
+                ...(sessionKey ? { sessionKey } : {}),
+                ...(title ? { title } : {}),
+            },
+        };
+    };
     for (const row of decisions) {
         const session = findSession(row.sessionId, row.provider);
         if (!session || (selectedKey && session.key !== selectedKey)) {
@@ -1156,7 +1235,8 @@ export async function widgetSnapshot({
             [
                 row.title ?? row.prompt,
                 cleanVisibleContext(
-                    [row.context, row.reasoning, row.proposal, row.answer, row.notes].filter(Boolean).join("\n\n")
+                    // The answer is not in the body: the card carries it as `answer` and the widget draws it itself.
+                    [row.context, row.reasoning, row.proposal, row.notes].filter(Boolean).join("\n\n")
                 ),
                 ...(row.title ? [cleanVisibleContext(row.prompt)] : []),
             ],
@@ -1198,6 +1278,11 @@ export async function widgetSnapshot({
             attachments: decisionImages.attachments,
             refs: (row.refs ?? []).map((ref) => ({ type: "file", value: ref.path })),
             read: true,
+            ...(row.option ? { option: row.option } : {}),
+            ...(row.answer?.trim() ? { answer: row.answer } : {}),
+            ...(row.comments?.length ? { comments: row.comments } : {}),
+            ...(row.answeredVia ? { answeredVia: row.answeredVia } : {}),
+            ...supersededBy(row),
         });
     }
     for (const form of forms) {
diff --git a/src/hub/lib/widget/types.ts b/src/hub/lib/widget/types.ts
index 858e7e2acb..7f19052541 100644
--- a/src/hub/lib/widget/types.ts
+++ b/src/hub/lib/widget/types.ts
@@ -59,6 +59,14 @@ export const widgetPreferencesSchema = z.object({
     voiceAccount: z.string().nullable().optional(),
     voiceModel: z.string().nullable().optional(),
     voiceLanguage: z.string().default(""),
+    /** Alert when a new decision reaches the inbox. */
+    alertDecisions: z.boolean().default(true),
+    /** Alert when a new answer or message reaches the inbox. */
+    alertAnswers: z.boolean().default(true),
+    /** The system sound an alert plays, by name; "none" plays no sound. */
+    alertSound: z.string().trim().min(1).max(40).default("Glass"),
+    /** Show the widget's own popup with an alert. */
+    alertPopup: z.boolean().default(true),
 });
 
 // Zod defaults also run inside partial objects; a patch must retain only supplied keys.
diff --git a/src/question/README.md b/src/question/README.md
index 0ba15e45e8..09fa769cb5 100644
--- a/src/question/README.md
+++ b/src/question/README.md
@@ -342,6 +342,14 @@ The MCP `question_post` item takes the same `supersedes` field.
 - Only an `open` or `drafted` item can be superseded; an answer must keep pointing at the text it answered, so an answered, sent or closed item is refused (`cannot supersede d_3_x: it is answered, and only an open or drafted item can be replaced; post a new item instead`). The kind must match, and a pending form is not superseded (cancel it and post a new one).
 - A post whose supersede is refused stores nothing, including its other items.
 
+## Recording a chat answer, and the state `superseded`
+
+Decision states: `open`, `drafted`, `answered` (stored, waiting for delivery), `sent`, `acknowledged`, `implemented`, `dismissed`, `superseded`. `tools question list --status` takes any of them (`waiting` is the printed name of `open`).
+
+- **The user answered in chat.** The agent records it in the same turn, so the inbox stops asking: `question_update { id, state: "acknowledged", option, answer: "<the user's words or a short copy>" }` (CLI: `tools question update` with the same JSON on stdin). `open` and `drafted` may move straight to `acknowledged` when the row then has `option` or `answer`. Nothing is delivered: every send reads `answered` rows only.
+- **A later decision replaced it.** `question_update { id, state: "superseded", supersededBy: "d_<n>_<session>", comment: "<why>" }`. `superseded` is legal from `open`, `drafted`, `sent` and `acknowledged`, for decisions only, and is terminal. It needs `supersededBy` or a `comment`. `supersededBy` must name another stored decision (any session). Unlike `supersedes` on a post, the old item keeps its text and number; the widget card links to the new one.
+- **`answeredVia`** on a stored row says who stored the answer: `inbox` (the move to `answered`: widget, hub, CLI `answer`) or `agent` (a move from `open` or `drafted` to `acknowledged`). The store sets it.
+
 ## Set up on a fresh clone
 
 How a new user's agent learns this grammar: from the genesis-tools MCP server (its instructions and the `question_post` description list every kind, and `question_tokens` returns the definitions), from `tools question ask --help`, and from `tools question tokens`. The MCP server is not registered by `install.sh`, so register it once:
diff --git a/src/question/commands/decisions.ts b/src/question/commands/decisions.ts
index d25bbd5b30..3e9c16ddf7 100644
--- a/src/question/commands/decisions.ts
+++ b/src/question/commands/decisions.ts
@@ -175,7 +175,7 @@ export function registerDecisionCommands(program: Command): void {
     program
         .command("update")
         .description(
-            "Update decisions and todos as one change. JSON on stdin: { updates: [{ id, state?, answer?, option?, draft?, commitRefs?, verdict?, comment? }] }, an array of those, or one"
+            "Update decisions and todos as one change. JSON on stdin: { updates: [{ id, state?, answer?, option?, draft?, commitRefs?, verdict?, comment?, supersededBy? }] }, an array of those, or one. Record a chat answer: state acknowledged with option or answer. Replace a decision: state superseded with supersededBy or comment"
         )
         .action(async () => {
             const { file, events } = decisionFiles();
diff --git a/src/question/lib/decisions/read.ts b/src/question/lib/decisions/read.ts
index 060c56f10e..fa05d1eba0 100644
--- a/src/question/lib/decisions/read.ts
+++ b/src/question/lib/decisions/read.ts
@@ -67,6 +67,7 @@ const STATUS: Record<DecisionState, string> = {
     acknowledged: "acknowledged",
     implemented: "implemented",
     dismissed: "dismissed",
+    superseded: "superseded",
 };
 
 /** Every status `listSessions` matches: the names it prints, then the stored state names (`open`). */
@@ -172,6 +173,9 @@ export function decisionsMarkdown(rows: DecisionRecord[]): string {
                     ? `revision ${row.revision} (earlier text: ${toolCommand("question show")} ${row.id} --versions)`
                     : null,
                 todo ? null : findLink(row),
+                row.state === "superseded"
+                    ? `superseded${row.supersededBy ? ` by ${row.supersededBy}` : ""}${row.comments?.length ? `: ${row.comments.at(-1)}` : ""}`
+                    : null,
             ].filter((part): part is string => part !== null);
 
             return [
diff --git a/src/question/lib/decisions/schema.ts b/src/question/lib/decisions/schema.ts
index 4d22b41362..9bc348499a 100644
--- a/src/question/lib/decisions/schema.ts
+++ b/src/question/lib/decisions/schema.ts
@@ -16,8 +16,22 @@ export const DECISION_STATES = [
     "acknowledged",
     "implemented",
     "dismissed",
+    "superseded",
 ] as const;
 
+/** How an answer reached the row: the user in the widget, hub or CLI, or an agent copying a chat answer. */
+export const ANSWERED_VIA = ["inbox", "agent"] as const;
+
+/**
+ * The rule every agent-facing text repeats (server instructions, question_post and question_update descriptions):
+ * an answer given in chat is recorded, and a replaced decision points at its replacement.
+ */
+export const DECISION_RECORD_RULE =
+    "When the user answers a ❓ DECISION in chat, or it is settled another way, record it in the same turn: " +
+    'question_update { id, state: "acknowledged", option, answer: "<the user\'s words or a short copy>" }. ' +
+    'When a later decision replaces it: question_update { id, state: "superseded", supersededBy: "<new id>", ' +
+    'comment: "<why>" }. Never leave an answered decision open.';
+
 /** The stored item kinds. A `question` item never reaches this store: it is a pending form. */
 export const DECISION_KINDS = ["decision", "todo"] as const;
 
@@ -101,7 +115,11 @@ export const decisionPatchSchema = z.object({
     state: z
         .enum(DECISION_STATES)
         .optional()
-        .describe("The next legal state. Decisions move forward; completed or dismissed TODOs may explicitly reopen."),
+        .describe(
+            "The next legal state. Decisions move forward; completed or dismissed TODOs may explicitly reopen. " +
+                "acknowledged straight from open or drafted records an answer the user gave in chat (needs option " +
+                "or answer); nothing is delivered. superseded (decisions only) needs supersededBy or comment."
+        ),
     answer: z.string().optional().describe("The answer text, or a copy of an answer the user gave in chat."),
     option: z
         .string()
@@ -117,6 +135,14 @@ export const decisionPatchSchema = z.object({
     commitRefs: z.array(z.string()).optional(),
     verdict: z.string().optional().describe("The outcome, e.g. what was implemented."),
     comment: z.string().optional().describe("Appended to the item's comments."),
+    supersededBy: z
+        .string()
+        .regex(/^d_\d+_.+$/)
+        .optional()
+        .describe(
+            "With state superseded: the id of the decision that replaces this one (d_<n>_<session>, any session). " +
+                "It must exist and must not be this item."
+        ),
 });
 
 export const decisionUpdateInputSchema = decisionPatchSchema.extend({
diff --git a/src/question/lib/decisions/store.test.ts b/src/question/lib/decisions/store.test.ts
index dff1dd4bf9..bc1cc580d4 100644
--- a/src/question/lib/decisions/store.test.ts
+++ b/src/question/lib/decisions/store.test.ts
@@ -1700,6 +1700,122 @@ test("an answer the agent got in chat moves to acknowledged and implemented with
     expect((await updateDecision(file, events, second.id, { state: "implemented" })).state).toBe("implemented");
 });
 
+describe("answers recorded by an agent, and superseded decisions", () => {
+    async function fixture(prompts: string[]) {
+        const dir = mkdtempSync(join(tmpdir(), "decision-recorded-"));
+        const file = join(dir, "decisions.jsonl");
+        const events = join(dir, "events.jsonl");
+        const rows = await postDecisions(file, events, {
+            sessionId: "recorded-session",
+            decisions: prompts.map((prompt) => ({ prompt, options: ["keep", "drop"] })),
+        });
+        return { file, events, rows };
+    }
+
+    test("open and drafted move straight to acknowledged with the chat answer, marked agent, and nothing is due", async () => {
+        const { file, events, rows } = await fixture(["Open one?", "Drafted one?", "No answer?"]);
+        const [open, drafted, bare] = rows;
+        await updateDecision(file, events, drafted.id, { state: "drafted", draft: "maybe", draftOption: "a" });
+
+        const fromOpen = await updateDecision(file, events, open.id, {
+            state: "acknowledged",
+            option: "b",
+            answer: "drop it, said in chat",
+        });
+        const [fromDrafted] = await updateDecisions(file, events, {
+            updates: [{ id: drafted.id, state: "acknowledged", option: "a" }],
+        });
+
+        expect(fromOpen).toMatchObject({ state: "acknowledged", option: "b", answeredVia: "agent" });
+        expect(fromDrafted).toMatchObject({ state: "acknowledged", option: "a", answeredVia: "agent" });
+        expect(fromDrafted.draft).toBeUndefined();
+        expect(fromDrafted.draftOption).toBeUndefined();
+        await expect(updateDecision(file, events, bare.id, { state: "acknowledged" })).rejects.toThrow(
+            "without the user's answer"
+        );
+        // Every send reads `answered` rows only: a recorded chat answer is never typed back into the agent.
+        expect(() => deliverDecisions(readDecisions(file), () => undefined)).toThrow("nothing to send");
+    });
+
+    test("the inbox answer path marks its answer inbox, and a later acknowledge keeps that mark", async () => {
+        const { file, events, rows } = await fixture(["Inbox?"]);
+        const answered = await updateDecision(file, events, rows[0].id, { state: "answered", option: "a" });
+        expect(answered.answeredVia).toBe("inbox");
+        const acknowledged = await updateDecision(file, events, rows[0].id, { state: "acknowledged" });
+        expect(acknowledged.answeredVia).toBe("inbox");
+    });
+
+    test("superseded needs a link or a reason, and the link must name another stored decision", async () => {
+        const { file, events, rows } = await fixture(["Old?", "New?"]);
+        const [old, replacement] = rows;
+        const [elsewhere] = await postDecisions(file, events, {
+            sessionId: "other-session",
+            decisions: [{ prompt: "Elsewhere?", options: [] }],
+        });
+
+        await expect(updateDecision(file, events, old.id, { state: "superseded" })).rejects.toThrow(
+            "without supersededBy or a comment"
+        );
+        await expect(
+            updateDecision(file, events, old.id, { state: "superseded", supersededBy: "d_99_recorded-session" })
+        ).rejects.toThrow("names no stored decision");
+        await expect(
+            updateDecision(file, events, old.id, { state: "superseded", supersededBy: old.id })
+        ).rejects.toThrow("superseded by itself");
+        await expect(updateDecision(file, events, old.id, { supersededBy: replacement.id })).rejects.toThrow(
+            "goes with state superseded"
+        );
+        expect(readDecisions(file).find((row) => row.id === old.id)?.state).toBe("open");
+
+        const moved = await updateDecision(file, events, old.id, {
+            state: "superseded",
+            supersededBy: elsewhere.id,
+            comment: "the other session decides it",
+        });
+        expect(moved).toMatchObject({
+            state: "superseded",
+            supersededBy: elsewhere.id,
+            comments: ["the other session decides it"],
+        });
+        // Terminal: nothing moves out of it.
+        await expect(updateDecision(file, events, old.id, { state: "acknowledged", option: "a" })).rejects.toThrow(
+            "cannot move"
+        );
+        expect(decisionsMarkdown([moved])).toContain(`superseded by ${elsewhere.id}: the other session decides it`);
+        expect(
+            listSessions(readDecisions(file), { status: ["superseded"] })[0]?.decisions.map((row) => row.id)
+        ).toEqual([old.id]);
+    });
+
+    test("superseded is legal from open, drafted, sent and acknowledged, and never for an answered row or a todo", async () => {
+        const { file, events, rows } = await fixture(["Open?", "Drafted?", "Sent?", "Acked?", "Answered?", "Done?"]);
+        const [open, drafted, sent, acked, answered, done] = rows;
+        await updateDecision(file, events, drafted.id, { state: "drafted", draftOption: "a" });
+        for (const row of [sent, acked, answered, done]) {
+            await updateDecision(file, events, row.id, { state: "answered", option: "a" });
+        }
+        await moveDecisions(file, events, [sent.id, acked.id], "sent");
+        await updateDecision(file, events, acked.id, { state: "acknowledged" });
+        await updateDecision(file, events, done.id, { state: "implemented" });
+
+        const why = { state: "superseded" as const, comment: "replaced" };
+        const moved = await updateDecisions(file, events, {
+            updates: [open, drafted, sent, acked].map((row) => ({ id: row.id, ...why })),
+        });
+        expect(moved.map((row) => row.state)).toEqual(["superseded", "superseded", "superseded", "superseded"]);
+        expect(moved[1].draftOption).toBeUndefined();
+        for (const row of [answered, done]) {
+            await expect(updateDecision(file, events, row.id, why)).rejects.toThrow("cannot move");
+        }
+
+        const [todo] = await postDecisions(file, events, {
+            sessionId: "recorded-session",
+            decisions: [{ type: "todo", prompt: "Ship it", options: [] }],
+        });
+        await expect(updateDecision(file, events, todo.id, why)).rejects.toThrow("cannot move");
+    });
+});
+
 test("decision revisions preserve the source turn of each posted version", async () => {
     const dir = mkdtempSync(join(tmpdir(), "decision-provenance-"));
     const file = join(dir, "decisions.jsonl");
diff --git a/src/question/lib/decisions/store.ts b/src/question/lib/decisions/store.ts
index 8e7948c7fa..9047e666bf 100644
--- a/src/question/lib/decisions/store.ts
+++ b/src/question/lib/decisions/store.ts
@@ -17,6 +17,7 @@ import { withFileLock } from "@genesiscz/utils/storage/file-lock";
 import { isTestProcess } from "@genesiscz/utils/test-process";
 import type { z } from "zod";
 import {
+    type ANSWERED_VIA,
     type DECISION_KINDS,
     type DECISION_STATES,
     type DecisionPatch,
@@ -33,6 +34,7 @@ import {
 
 export type DecisionState = (typeof DECISION_STATES)[number];
 export type DecisionKind = (typeof DECISION_KINDS)[number];
+export type AnsweredVia = (typeof ANSWERED_VIA)[number];
 
 export interface DecisionRef {
     path: string;
@@ -100,6 +102,13 @@ export interface DecisionRecord {
     answer?: string;
     /** The chosen option letters, when the answer picked one or more (`"b"`, `"ac"`). */
     option?: string;
+    /**
+     * Who stored the answer, set by the store: `inbox` on the move to `answered` (the widget, the hub, the CLI),
+     * `agent` on a move from open or drafted straight to `acknowledged` (an answer the user gave in chat).
+     */
+    answeredVia?: AnsweredVia;
+    /** The decision that replaced this one (`superseded`); it exists in the store, in any session. */
+    supersededBy?: string;
     commitRefs?: string[];
     verdict?: string;
     comments?: string[];
@@ -176,17 +185,21 @@ const SUPERSEDABLE: ReadonlySet<DecisionState> = new Set(["open", "drafted"]);
 
 const NEXT: Record<DecisionKind, Record<DecisionState, DecisionState[]>> = {
     decision: {
-        open: ["answered", "drafted", "dismissed"],
+        // `acknowledged` straight from open or drafted: an agent records an answer the user gave in chat (patched()
+        // requires option or answer). Nothing is delivered: every send reads `answered` rows only.
+        // `superseded`: a later decision replaced it (patched() requires supersededBy or a comment). Terminal.
+        open: ["answered", "drafted", "dismissed", "acknowledged", "superseded"],
         // Saving a draft again replaces it: the user edits a draft more than once before sending.
         // Clearing the last pick puts it back to open; Dismiss drops it without an answer.
-        drafted: ["answered", "drafted", "open", "dismissed"],
+        drafted: ["answered", "drafted", "open", "dismissed", "acknowledged", "superseded"],
         // An agent that got the answer in chat records its progress without a send (patched() refuses it while a
-        // queued delivery holds the row).
+        // queued delivery holds the row). No `superseded` here: the answer waits for its delivery.
         answered: ["sent", "acknowledged", "implemented"],
-        sent: ["acknowledged", "implemented"],
-        acknowledged: ["implemented"],
+        sent: ["acknowledged", "implemented", "superseded"],
+        acknowledged: ["implemented", "superseded"],
         implemented: [],
         dismissed: [],
+        superseded: [],
     },
     // A todo is done, not answered: whoever it is for takes it and finishes it.
     todo: {
@@ -197,6 +210,7 @@ const NEXT: Record<DecisionKind, Record<DecisionState, DecisionState[]>> = {
         acknowledged: ["implemented", "dismissed"],
         implemented: ["open"],
         dismissed: ["open"],
+        superseded: [],
     },
 };
 
@@ -504,8 +518,16 @@ function sessionNumbers(rows: DecisionRecord[], sessionId: string): Record<Decis
     return numbers;
 }
 
-/** The patched row, or a thrown reason. Pure, so a batch can check every patch before it writes. */
-function patched(row: DecisionRecord, patch: DecisionPatch, ts: string): DecisionRecord {
+/**
+ * The patched row, or a thrown reason. Pure, so a batch can check every patch before it writes. `stored` names
+ * the decision ids a `supersededBy` may point at: every row of the log, in any session.
+ */
+function patched(
+    row: DecisionRecord,
+    patch: DecisionPatch,
+    ts: string,
+    stored: ReadonlyMap<string, DecisionRecord>
+): DecisionRecord {
     if (patch.expectedRevision !== undefined && patch.expectedRevision !== (row.revision ?? 1)) {
         throw new Error(`stale decision revision: ${row.id}`);
     }
@@ -538,6 +560,28 @@ function patched(row: DecisionRecord, patch: DecisionPatch, ts: string): Decisio
         throw new Error(`cannot move ${row.id} to answered without an answer`);
     }
 
+    // A decision acknowledged before anyone answered it in the inbox carries the answer the user gave in chat.
+    const recorded = kindOf(row) === "decision" && patch.state === "acknowledged" && SUPERSEDABLE.has(row.state);
+    if (recorded && !next.answer?.trim() && !next.option) {
+        throw new Error(
+            `cannot move ${row.id} from ${row.state} to acknowledged without the user's answer: pass option or answer`
+        );
+    }
+
+    if (patch.state === "superseded" && !patch.supersededBy && !comment?.trim()) {
+        throw new Error(`cannot move ${row.id} to superseded without supersededBy or a comment saying why`);
+    }
+
+    if (patch.supersededBy !== undefined) {
+        checkSupersededBy(row, next, patch.supersededBy, stored);
+    }
+
+    if (patch.state === "answered") {
+        next.answeredVia = "inbox";
+    } else if (recorded) {
+        next.answeredVia = "agent";
+    }
+
     // A letter past the options would be delivered as `DECISION 1: z)`, naming nothing.
     for (const pick of [patch.option, patch.draftOption]) {
         const past = [...(pick ?? "")].find((letter) => letter.charCodeAt(0) - 97 >= row.options.length);
@@ -549,7 +593,7 @@ function patched(row: DecisionRecord, patch: DecisionPatch, ts: string): Decisio
     }
 
     // The answer consumes the draft: a sent decision must not still show an unsent pick.
-    if (patch.state === "answered" || patch.state === "dismissed") {
+    if (patch.state === "answered" || patch.state === "dismissed" || patch.state === "superseded" || recorded) {
         delete next.draft;
         delete next.draftOption;
     }
@@ -557,6 +601,27 @@ function patched(row: DecisionRecord, patch: DecisionPatch, ts: string): Decisio
     return next;
 }
 
+/** Throws unless `target` names another stored decision and `next` is (becoming) superseded. */
+function checkSupersededBy(
+    row: DecisionRecord,
+    next: DecisionRecord,
+    target: string,
+    stored: ReadonlyMap<string, DecisionRecord>
+): void {
+    if (next.state !== "superseded") {
+        throw new Error(`${row.id}: supersededBy goes with state superseded`);
+    }
+
+    if (target === row.id) {
+        throw new Error(`${row.id} cannot be superseded by itself`);
+    }
+
+    const replacement = stored.get(target);
+    if (!replacement || kindOf(replacement) !== "decision") {
+        throw new Error(`${row.id}: supersededBy names no stored decision (${target}); post the new decision first`);
+    }
+}
+
 /** Moves one decision. The patch is validated first, and unknown keys are dropped. */
 export async function updateDecision(
     file: string,
@@ -828,7 +893,7 @@ function applyUpdates({
             }
 
             beforeUpdate?.(row);
-            byId.set(id, patched(row, patch, ts));
+            byId.set(id, patched(row, patch, ts, byId));
         }
 
         signal?.throwIfAborted();
@@ -1089,6 +1154,7 @@ export async function reconcileQueuedDecision({
             delete row.delivery;
             delete row.answer;
             delete row.option;
+            delete row.answeredVia;
         }
         rewrite(file, rows);
         appendEvent(events, { ev: received ? "sent" : "queue_cancelled", id, ts, state: row.state });
diff --git a/src/question/lib/inbox/build.ts b/src/question/lib/inbox/build.ts
index 8a904c0455..50c6748b1b 100644
--- a/src/question/lib/inbox/build.ts
+++ b/src/question/lib/inbox/build.ts
@@ -13,7 +13,15 @@ import type { AskForm } from "../pending/types";
  * write back.
  */
 
-export type InboxStatus = "waiting" | "drafted" | "answered" | "sent" | "acknowledged" | "implemented" | "dismissed";
+export type InboxStatus =
+    | "waiting"
+    | "drafted"
+    | "answered"
+    | "sent"
+    | "acknowledged"
+    | "implemented"
+    | "dismissed"
+    | "superseded";
 
 export interface InboxChoice {
     /** The option letter for a decision, the choice id for a form. */
@@ -316,6 +324,7 @@ const STATUS: Record<DecisionRecord["state"], InboxStatus> = {
     acknowledged: "acknowledged",
     implemented: "implemented",
     dismissed: "dismissed",
+    superseded: "superseded",
 };
 
 function isOpen(status: InboxStatus): boolean {

From ffa333e610179d2a6740e57ddccc808f65fcb5e1 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 18:43:45 +0200
Subject: [PATCH 19/30] feat(GenesisKit): decision cards take an own answer
 with the full composer, show the recorded answer and a superseded-by link,
 new items chime and pop up from the widget, and the Widgets page says when
 Visible edges hides the top notch

---
 .claude/skills/babysit/SKILL.md               |   2 +
 .../GenesisKit/Widgets/LiveWidgetView.swift   |  49 ++++-
 .../GenesisKit/Widgets/WidgetAlerts.swift     |  57 ++++++
 .../Widgets/WidgetCoordinator.swift           |  29 +++
 .../Widgets/WidgetDecisionOutcome.swift       |  86 +++++++++
 .../Widgets/WidgetFeatureSettings.swift       |  44 ++++-
 .../GenesisKit/Widgets/WidgetHostView.swift   |  39 ++++
 .../GenesisKit/Widgets/WidgetModel.swift      |  91 ++++++++-
 .../GenesisKit/Widgets/WidgetWireModels.swift |  21 +++
 .../EdgePanelGeometryTests.swift              | 174 ++++++++++++++++++
 10 files changed, 585 insertions(+), 7 deletions(-)
 create mode 100644 src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetAlerts.swift
 create mode 100644 src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetDecisionOutcome.swift

diff --git a/.claude/skills/babysit/SKILL.md b/.claude/skills/babysit/SKILL.md
index 7fdcbb36fb..de250c4449 100644
--- a/.claude/skills/babysit/SKILL.md
+++ b/.claude/skills/babysit/SKILL.md
@@ -43,6 +43,8 @@ Do all of these before the first dispatch, in this order:
 5. The owner check of every PR (step 3.1).
 6. Decisions: every ❓ DECISION of the run goes into the decision log under its chat number and into the chat, and
    gets a `decision` event in the run ledger (review-loop, "Decisions during a loop"). A later mention is a link.
+   Its answer is recorded in the same turn (`question_update`, state `acknowledged`, or `superseded` with
+   `supersededBy`), so the widget stops asking for it.
 
 ## 1. The run card: what to configure
 
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/LiveWidgetView.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/LiveWidgetView.swift
index 7cfa87106c..c42b03d0ba 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/LiveWidgetView.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/LiveWidgetView.swift
@@ -199,7 +199,8 @@ public struct LiveWidgetView: View {
                         // Outermost, so the scroll view's own anchor modifiers still sit directly on it.
                         .scrollOverflowHints()
                 }
-                if section != "Sessions" { composer }
+                // While a decision card holds the composer for an own answer, the bottom one would edit the same draft.
+                if section != "Sessions" && !(section == "Inbox" && model.ownAnswerCard != nil) { composer }
             }
         }
         .mediaPreviewHost()
@@ -461,6 +462,9 @@ public struct LiveWidgetView: View {
             if !card.attachments.isEmpty {
                 WidgetCardAttachments(card: card, height: 110, maxWidth: 260, compare: true, showMedia: showMedia)
             }
+            if card.kind == "decision" && !card.needsAnswer {
+                WidgetDecisionOutcome(card: card) { model.openDecision(id: $0.id, sessionKey: $0.sessionKey) }
+            }
             if card.needsAnswer {
                 if card.kind == "form" {
                     ForEach(card.formItems ?? []) { item in
@@ -495,6 +499,7 @@ public struct LiveWidgetView: View {
                                         + (index < 9 ? " · key \(index + 1)" : ""))
                         .accessibilityLabel("Answer \(choice.id): " + Self.choiceText(choice))
                     }
+                    ownAnswer(card)
                 }
             }
             HStack(spacing: 8) {
@@ -532,6 +537,29 @@ public struct LiveWidgetView: View {
         }
     }
 
+    /// "Write my own answer": a row under the options that opens the full composer (text, media, screenshot, voice)
+    /// inside the card; Send delivers the draft as the answer with no option picked.
+    @ViewBuilder private func ownAnswer(_ card: WidgetCard) -> some View {
+        if model.ownAnswerCard?.id == card.id {
+            VStack(alignment: .leading, spacing: 6) {
+                HStack {
+                    Text("Your own answer").font(.system(size: 11, weight: .semibold)).foregroundStyle(.secondary)
+                    Spacer(minLength: 0)
+                    Button("Back to the options") {
+                        GenMotion.perform(expanding: false, reduceMotion: reduceMotion) { model.ownAnswerCardID = nil }
+                    }.buttonStyle(.genHoverPlain()).font(.caption)
+                }
+                composer(ownAnswer: card).disabled(model.cardPending)
+            }
+            .transition(.genReveal)
+            .onAppear { editing = true }
+        } else {
+            WidgetOwnAnswerRow {
+                GenMotion.perform(expanding: true, reduceMotion: reduceMotion) { model.ownAnswerCardID = card.id }
+            }.disabled(model.importing > 0 || model.cardPending)
+        }
+    }
+
     static func kindSymbol(_ kind: String) -> String {
         switch kind {
         case "answer": return "text.bubble"
@@ -554,6 +582,12 @@ public struct LiveWidgetView: View {
         case "answer": return card.read ? "Answer" : "New answer"
         case "result": return card.read ? "Agent result" : "New agent result"
         case "todo": return "Task · " + WidgetTask.label(for: card.status)
+        case "decision":
+            if let replacement = card.supersededBy { return "Decision · Superseded by DECISION \(replacement.number)" }
+            if let option = card.option, !option.isEmpty, ["acknowledged", "implemented", "sent", "answered"].contains(card.status) {
+                return "Decision · Answered \(option) · " + card.status.capitalized
+            }
+            return "Decision · " + card.status.capitalized
         default: return card.kind.capitalized + " · " + card.status.capitalized
         }
     }
@@ -809,7 +843,10 @@ public struct LiveWidgetView: View {
             .background(.blue.opacity(0.12), in: RoundedRectangle(cornerRadius: 11))
     }
 
-    private var composer: some View {
+    private var composer: some View { composer(ownAnswer: nil) }
+
+    /// The reply composer. With `ownAnswer` it sits in that decision's card and sends the draft as the answer.
+    private func composer(ownAnswer: WidgetCard?) -> some View {
         VStack(alignment: .leading, spacing: 8) {
             if !model.draft.assetIds.isEmpty {
                 attachments(model.draft.assetIds, tile: CGSize(width: 88, height: 60), removable: true)
@@ -829,7 +866,8 @@ public struct LiveWidgetView: View {
                 ProgressView("Saving attachment…").controlSize(.small).font(.caption)
             }
             HStack(alignment: .bottom, spacing: 8) {
-                let placeholder = "Reply to " + (model.selected?.target.provider.capitalized ?? "agent") + "…"
+                let placeholder = ownAnswer.map { "Your own answer to DECISION \($0.number ?? 0)…" }
+                    ?? "Reply to " + (model.selected?.target.provider.capitalized ?? "agent") + "…"
                 if panelMoving, !editing, composerFieldHeight > 0 {
                     // While the panel's outline moves the composer rides its bottom edge; a drawn stand-in moves for
                     // free, the AppKit field would lay out and rebuild the key view loop on every frame.
@@ -842,7 +880,7 @@ public struct LiveWidgetView: View {
                     TextField(placeholder, text: Binding(get: { model.draft.text }, set: model.setText), axis: .vertical)
                         .textFieldStyle(.plain).font(.system(size: 12)).lineLimit(1...4).focused($editing)
                         .onSubmit { model.send() }
-                        .accessibilityLabel("Reply to selected agent")
+                        .accessibilityLabel(ownAnswer == nil ? "Reply to selected agent" : "Your own answer")
                         .onGeometryChange(for: CGFloat.self, of: { $0.size.height.rounded() }) { composerFieldHeight = $0 }
                 }
                 Button {
@@ -850,7 +888,8 @@ public struct LiveWidgetView: View {
                 } label: {
                     Image(systemName: "arrow.up.circle.fill").font(.system(size: 23)).foregroundStyle(.blue)
                 }.buttonStyle(.genHoverIcon(accent: .blue, diameter: 28)).disabled(model.importing > 0)
-                    .instantTooltip("Send (Return)").accessibilityLabel("Send reply")
+                    .instantTooltip(ownAnswer == nil ? "Send (Return)" : "Send as your answer (Return)")
+                    .accessibilityLabel(ownAnswer == nil ? "Send reply" : "Send your answer")
             }
             HStack(spacing: 15) {
                 Button(action: model.chooseFiles) { Image(systemName: "paperclip") }.instantTooltip(
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetAlerts.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetAlerts.swift
new file mode 100644
index 0000000000..ec37a3c67e
--- /dev/null
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetAlerts.swift
@@ -0,0 +1,57 @@
+import AppKit
+
+/// Which new inbox items alert the user, and the chime that goes with them (Widget settings → Alerts).
+public enum WidgetAlerts {
+    /// The macOS system sounds in /System/Library/Sounds, offered by the settings page.
+    public static let sounds = [
+        "Glass", "Ping", "Pop", "Purr", "Submarine", "Tink", "Hero", "Funk", "Blow", "Bottle", "Frog", "Morse",
+        "Basso", "Sosumi",
+    ]
+    public static let defaultSound = "Glass"
+
+    /// The arrivals the preferences ask to hear about: decisions and questions (anything that waits for an answer)
+    /// under `alertDecisions`, answers and messages under `alertAnswers`. Agent results never alert.
+    public static func wanted(_ items: [WidgetInboxItem], preferences: WidgetPreferences?) -> [WidgetInboxItem] {
+        items.filter { item in
+            if item.needsAnswer || item.kind == "decision" || item.kind == "form" {
+                return preferences?.alertDecisions ?? true
+            }
+            return item.kind == "answer" && (preferences?.alertAnswers ?? true)
+        }
+    }
+
+    /// The item a popup shows: the newest one that waits for an answer, else the newest one.
+    public static func popupItem(_ items: [WidgetInboxItem]) -> WidgetInboxItem? {
+        items.filter(\.needsAnswer).max { $0.at < $1.at } ?? items.max { $0.at < $1.at }
+    }
+
+    /// The popup's first line.
+    public static func kicker(_ item: WidgetInboxItem) -> String {
+        switch item.kind {
+        case "decision": return item.number.map { "New decision · DECISION \($0)" } ?? "New decision"
+        case "form": return "New question"
+        case "answer": return "New answer"
+        default: return "New in the inbox"
+        }
+    }
+
+    private static var lastChime = Date.distantPast
+
+    /// Plays `name` once; a burst of arrivals within 1.5 s chimes once. "none" or an unknown name is silent.
+    @MainActor public static func chime(_ name: String?, now: Date = Date()) {
+        let sound = name ?? defaultSound
+        guard sound != "none", now.timeIntervalSince(lastChime) >= 1.5 else { return }
+        lastChime = now
+        guard let player = NSSound(named: NSSound.Name(sound)) else {
+            PerfLog.mark("widget.alert unknown sound \(sound)")
+            return
+        }
+        player.play()
+    }
+
+    /// Plays `name` now, for the settings page's preview button.
+    @MainActor public static func preview(_ name: String) {
+        guard name != "none" else { return }
+        NSSound(named: NSSound.Name(name))?.play()
+    }
+}
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetCoordinator.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetCoordinator.swift
index d09436e0ce..c0933ba2bb 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetCoordinator.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetCoordinator.swift
@@ -167,6 +167,35 @@ public final class WidgetCoordinator: NSObject, NSWindowDelegate {
         }
         model.showSettings = { [weak self] in self?.showSettings() }
         model.showMedia = { [weak self] selection in self?.showMedia(selection) }
+        model.inboxArrived = { [weak self] items in self?.alert(items) }
+    }
+
+    /// Plays the alert chime. Tests replace it.
+    var playChime: (String?) -> Void = { WidgetAlerts.chime($0) }
+
+    /// New decisions, questions and answers: one chime, and the newest item pops up in the agents preview.
+    func alert(_ items: [WidgetInboxItem]) {
+        guard panelsEnabled else { return }
+        let preferences = model.snapshot?.state.preferences
+        let wanted = WidgetAlerts.wanted(items, preferences: preferences)
+        guard let item = WidgetAlerts.popupItem(wanted) else { return }
+        PerfLog.mark("widget.alert items=\(wanted.count) id=\(item.id) kind=\(item.kind)")
+        playChime(preferences?.alertSound)
+        guard preferences?.alertPopup ?? true, let surface = peekSurface() else { return }
+        if moduleIDs(for: surface).contains("agents"), model.moduleSelections[surface.key] != "agents" {
+            model.moduleSelections[surface.key] = "agents"
+        }
+        model.showPeek(item, on: surface)
+    }
+
+    /// The visible edge whose selected module is the agents inbox, else the first visible edge that has it.
+    private func peekSurface() -> WidgetSurfaceID? {
+        let visible = panels.keys.filter { surface in
+            let top = surface.edge == .top
+            return (model.placement == "both" || (model.placement == "top" ? top : !top))
+                && moduleIDs(for: surface).contains("agents")
+        }.sorted { $0.key < $1.key }
+        return visible.first { selectedModule(for: $0)?.id == "agents" } ?? visible.first
     }
 
     /// Without `showSettings`, a widget that is off opens the settings once the first snapshot arrives,
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetDecisionOutcome.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetDecisionOutcome.swift
new file mode 100644
index 0000000000..54e8372252
--- /dev/null
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetDecisionOutcome.swift
@@ -0,0 +1,86 @@
+import SwiftUI
+
+/// A settled decision's outcome in its inbox card: the recorded answer and who recorded it, the agent's comments, and
+/// the decision that replaced it, which `open` shows.
+struct WidgetDecisionOutcome: View {
+    let card: WidgetCard
+    let open: (WidgetCard.SupersededBy) -> Void
+
+    var body: some View {
+        let picked = (card.option ?? "").map(String.init).compactMap { letter in
+            card.choices.first { $0.id == letter }
+        }
+        VStack(alignment: .leading, spacing: 6) {
+            if let replacement = card.supersededBy {
+                Button {
+                    open(replacement)
+                } label: {
+                    HStack(alignment: .top, spacing: 6) {
+                        Image(systemName: "arrow.uturn.right").font(.system(size: 10.5, weight: .semibold))
+                            .padding(.top, 2)
+                        Text("Superseded by DECISION \(replacement.number)" + (replacement.title.map { ": " + $0 } ?? ""))
+                            .font(.system(size: 12, weight: .medium)).lineLimit(2).multilineTextAlignment(.leading)
+                        Spacer(minLength: 0)
+                        Image(systemName: "chevron.right").font(.system(size: 9, weight: .semibold)).padding(.top, 3)
+                    }.padding(8).frame(maxWidth: .infinity, alignment: .leading)
+                        .background(SessionPalette.blue.opacity(0.14), in: RoundedRectangle(cornerRadius: 8))
+                        .contentShape(RoundedRectangle(cornerRadius: 8))
+                }
+                .buttonStyle(RowButtonStyle(cornerRadius: 8))
+                .disabled(replacement.sessionKey == nil)
+                .instantTooltip(replacement.sessionKey == nil
+                    ? "That decision's session is not in the widget" : "Open DECISION \(replacement.number)")
+            } else if card.status == "superseded" {
+                Label("Superseded", systemImage: "arrow.uturn.right").font(.system(size: 11, weight: .medium))
+                    .foregroundStyle(.secondary)
+            }
+            if !picked.isEmpty || !(card.answer ?? "").isEmpty {
+                VStack(alignment: .leading, spacing: 4) {
+                    Text(card.answeredVia == "agent" ? "Answer recorded by the agent" : "Your answer")
+                        .font(.system(size: 10, weight: .semibold)).foregroundStyle(.secondary)
+                    ForEach(picked, id: \.id) { choice in
+                        HStack(alignment: .top, spacing: 6) {
+                            Text(verbatim: choice.id).font(.system(size: 10.5, weight: .semibold, design: .rounded))
+                                .frame(width: 18, height: 18).background(
+                                    Color.green.opacity(0.2), in: RoundedRectangle(cornerRadius: 5))
+                            Text(LiveWidgetView.choiceText(choice)).font(.system(size: 12)).fixedSize(horizontal: false, vertical: true)
+                        }
+                    }
+                    if let answer = card.answer, !answer.isEmpty {
+                        WidgetMarkdown(text: answer)
+                    }
+                }.padding(8).frame(maxWidth: .infinity, alignment: .leading)
+                    .background(Color.green.opacity(0.07), in: RoundedRectangle(cornerRadius: 8))
+            }
+            ForEach(Array((card.comments ?? []).enumerated()), id: \.offset) { _, comment in
+                HStack(alignment: .top, spacing: 6) {
+                    Image(systemName: "text.bubble").font(.system(size: 10)).foregroundStyle(.secondary).padding(.top, 2)
+                    Text(comment).font(.system(size: 11)).foregroundStyle(.secondary).textSelection(.enabled)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+            }
+        }
+    }
+}
+
+/// The row under a decision's options that opens the composer for the user's own answer.
+struct WidgetOwnAnswerRow: View {
+    let action: () -> Void
+
+    var body: some View {
+        Button(action: action) {
+            HStack(alignment: .top, spacing: 8) {
+                Image(systemName: "square.and.pencil").font(.system(size: 10.5, weight: .semibold))
+                    .frame(width: 20, height: 20).background(
+                        .white.opacity(0.07), in: RoundedRectangle(cornerRadius: 5))
+                Text("Write my own answer").font(.system(size: 12)).padding(.top, 2)
+                Spacer(minLength: 0)
+            }.padding(9).frame(maxWidth: .infinity, alignment: .leading)
+                .background(.white.opacity(0.035), in: RoundedRectangle(cornerRadius: 9))
+                .contentShape(RoundedRectangle(cornerRadius: 9))
+        }
+        .buttonStyle(RowButtonStyle(cornerRadius: 9))
+        .instantTooltip("Answer in your own words, with images, a screenshot or voice")
+        .accessibilityLabel("Write my own answer")
+    }
+}
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetFeatureSettings.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetFeatureSettings.swift
index bb1a2a0e3b..ff311cf3dc 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetFeatureSettings.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetFeatureSettings.swift
@@ -220,6 +220,31 @@ private struct WidgetGeneralSettings: View {
                     "Changed files", detail: "Show a session's working changes alongside its conversation.",
                     isOn: boolean("showChanges", prefs?.showChanges ?? true))
             }
+            NativeSettingsCard("Alerts", subtitle: "When an agent asks or answers while the widget is closed.") {
+                NativeSettingsToggle(
+                    "Decisions and questions", detail: "A new ❓ DECISION or question that waits for your answer.",
+                    identifier: "widget.alertDecisions", isOn: boolean("alertDecisions", prefs?.alertDecisions ?? true))
+                Divider()
+                NativeSettingsToggle(
+                    "Answers and messages", detail: "A new logged answer or a message an agent sent you.",
+                    identifier: "widget.alertAnswers", isOn: boolean("alertAnswers", prefs?.alertAnswers ?? true))
+                Divider()
+                NativeSettingsRow("Sound", detail: "One chime per burst of new items.") {
+                    HStack(spacing: 6) {
+                        Picker("Alert sound", selection: string("alertSound", prefs?.alertSound ?? WidgetAlerts.defaultSound)) {
+                            Text("None").tag("none")
+                            ForEach(WidgetAlerts.sounds, id: \.self) { Text($0).tag($0) }
+                        }.labelsHidden().frame(width: 140, alignment: .trailing)
+                        IconButton(systemName: "speaker.wave.2", tooltip: "Play the alert sound") {
+                            WidgetAlerts.preview(prefs?.alertSound ?? WidgetAlerts.defaultSound)
+                        }.disabled((prefs?.alertSound ?? WidgetAlerts.defaultSound) == "none")
+                    }
+                }
+                Divider()
+                NativeSettingsToggle(
+                    "Popup", detail: "The widget opens a short preview of the new item; a click on it answers.",
+                    identifier: "widget.alertPopup", isOn: boolean("alertPopup", prefs?.alertPopup ?? true))
+            }
             }
         }.task { model.refreshSettings() }
     }
@@ -437,7 +462,24 @@ private struct WidgetModuleSettings: View {
         }.task { model.refreshSettings() }
     }
     private func group(_ title: String, index: Int?) -> some View {
-        NativeSettingsCard(title) {
+        let placement = model.snapshot?.state.preferences.placement ?? "both"
+        // "Visible edges" hides this edge, so a module change here showed nothing (Martin, 2026-10-22).
+        let hidden = index == nil ? placement == "side" : placement == "top"
+        return NativeSettingsCard(title) {
+            if hidden {
+                HStack(spacing: 10) {
+                    Image(systemName: "eye.slash").foregroundStyle(.orange)
+                    Text(index == nil
+                         ? "The top notch is hidden: Visible edges is set to Side."
+                         : "The side groups are hidden: Visible edges is set to Top.")
+                        .font(.caption).frame(maxWidth: .infinity, alignment: .leading)
+                    Button(index == nil ? "Show the top notch" : "Show the side groups") {
+                        model.action(["action": "preferences", "patch": ["placement": "both"]])
+                    }.buttonStyle(.bordered).nativeSettingsPointer()
+                        .accessibilityIdentifier("widget.modules.\(index == nil ? "top" : "side").show")
+                }
+                Divider()
+            }
             ForEach(modules) { module in
                 let selected = index.map { model.layout.sideGroups[$0] } ?? model.layout.topModules
                 NativeSettingsToggle(
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetHostView.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetHostView.swift
index 7cc1442b6c..04a118c664 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetHostView.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetHostView.swift
@@ -460,6 +460,43 @@ struct WarmPaneVisibility: ViewModifier {
     }
 }
 
+/// The alert popup: what arrived and from which session. A click opens it in the inbox.
+struct WidgetPeekView: View {
+    @ObservedObject var model: WidgetModel
+    let item: WidgetInboxItem
+
+    var body: some View {
+        Button {
+            guard let surface = model.hoveredSurface else { return }
+            model.openInboxNotification(on: surface, key: item.key, needsAnswer: item.needsAnswer)
+        } label: {
+            VStack(alignment: .leading, spacing: 6) {
+                HStack(spacing: 6) {
+                    Image(systemName: item.needsAnswer ? "questionmark.bubble.fill" : "text.bubble.fill")
+                        .foregroundStyle(item.needsAnswer ? Color.orange : SessionPalette.blue)
+                    Text(WidgetAlerts.kicker(item)).font(.system(size: 11, weight: .semibold))
+                        .foregroundStyle(item.needsAnswer ? Color.orange : .secondary)
+                    Spacer(minLength: 0)
+                    LiveAgo(date: Date(timeIntervalSince1970: item.at / 1000), style: .brief)
+                        .font(.system(size: 10)).foregroundStyle(.secondary)
+                }
+                Text(item.title ?? "Open the inbox to see it.").font(.system(size: 12.5, weight: .medium))
+                    .lineLimit(3).multilineTextAlignment(.leading).fixedSize(horizontal: false, vertical: true)
+                if let session = model.session(forKey: item.key) {
+                    Text(session.title + " · " + session.project).font(.system(size: 10.5)).foregroundStyle(.secondary)
+                        .lineLimit(1).truncationMode(.middle)
+                }
+                Text(item.needsAnswer ? "Click to answer" : "Click to read").font(.system(size: 10))
+                    .foregroundStyle(.tertiary)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .contentShape(Rectangle())
+        }
+        .buttonStyle(RowButtonStyle(cornerRadius: 10))
+        .accessibilityLabel(WidgetAlerts.kicker(item) + ": " + (item.title ?? ""))
+    }
+}
+
 struct AgentWidgetModuleView: View {
     @ObservedObject var model: WidgetModel
     let presentation: WidgetModulePresentation
@@ -467,6 +504,8 @@ struct AgentWidgetModuleView: View {
     var body: some View {
         if presentation == .expanded {
             LiveWidgetView(model: model, edge: model.expanded ?? model.side, embedded: true)
+        } else if presentation == .preview, let item = model.peekItem {
+            WidgetPeekView(model: model, item: item)
         } else {
             VStack(alignment: .leading, spacing: 10) {
                 Text(model.selected?.title ?? "Your agent inbox").font(.system(size: 13, weight: .semibold))
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift
index e084e58e5c..3c1195c690 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift
@@ -50,6 +50,15 @@ public final class WidgetModel: ObservableObject {
     @Published public var expanded: EdgePanelPlacement?
     @Published public var activeSideGroup = 0
     @Published public var hoveredSurface: WidgetSurfaceID?
+    /// A new inbox item the widget pops up by itself (an alert). The agents preview shows it until `showPeek`'s
+    /// timer ends, or until the pointer leaves the panel when the user moved onto it.
+    @Published public private(set) var peekItem: WidgetInboxItem?
+    private var peekTask: Task<Void, Never>?
+    /// Surfaces the pointer is in now, without the hover delay: a popup never opens under the user's pointer.
+    private var pointerInside: Set<String> = []
+    /// Called with the items that arrived in a complete inbox snapshot (never the first one).
+    public var inboxArrived: (([WidgetInboxItem]) -> Void)?
+    public func session(forKey key: String) -> WidgetSession? { sessionIndex[key] }
     @Published public var moduleSelections: [String: String] = [:]
     @Published public var draggedSidePosition: Double?
     @Published public var draggingSide = false
@@ -258,6 +267,13 @@ public final class WidgetModel: ObservableObject {
         guard let card, card.kind == "decision", card.needsAnswer, !foldedCardIDs.contains(card.id) else { return nil }
         return card
     }
+    /// The decision whose card shows the composer for the user's own answer instead of the options.
+    @Published public var ownAnswerCardID: String?
+    /// `ownAnswerCardID` while that decision is still the one the composer answers.
+    public var ownAnswerCard: WidgetCard? {
+        guard let card = answerCard, card.id == ownAnswerCardID else { return nil }
+        return card
+    }
     public var draft: WidgetDraft { drafts[selectedKey] ?? WidgetDraft() }
     public var outgoing: [WidgetOutgoing] {
         WidgetOutgoing.shown(snapshot?.state.outgoing.filter { $0.target.hasSameIdentity(as: selected?.target) } ?? [])
@@ -398,6 +414,7 @@ public final class WidgetModel: ObservableObject {
     }
 
     public func stop() {
+        peekTask?.cancel()
         preferenceTask?.cancel()
         flushPreferences()
         settingsTask?.cancel()
@@ -539,6 +556,8 @@ public final class WidgetModel: ObservableObject {
         activeSideGroup = surface.group
         hoveredSurface = nil
         hoverTask?.cancel()
+        peekTask?.cancel()
+        peekItem = nil
         open(surface.edge)
     }
 
@@ -569,8 +588,46 @@ public final class WidgetModel: ObservableObject {
         hoveredSession = nil
     }
 
+    /// Pops `item` up in `surface`'s preview for `seconds`, unless the user is in a panel, a window or a drag.
+    func showPeek(_ item: WidgetInboxItem, on surface: WidgetSurfaceID, seconds: Double = 7) {
+        guard !stopping, expanded == nil, !dialogOpen, !draggingSide, pointerInside.isEmpty,
+              hoveredSurface == nil || hoveredSurface == surface else { return }
+        hoverTask?.cancel()
+        peekItem = item
+        hoveredSurface = surface
+        presentationChanged?()
+        peekTask?.cancel()
+        peekTask = Task { [weak self] in
+            do { try await Task.sleep(for: .seconds(seconds)) } catch { return }
+            guard let self, self.peekItem == item, !self.pointerInside.contains(surface.key) else { return }
+            self.endPeek()
+        }
+    }
+
+    private func endPeek() {
+        peekTask?.cancel()
+        peekTask = nil
+        guard let item = peekItem else { return }
+        peekItem = nil
+        if expanded == nil, let surface = hoveredSurface, !pointerInside.contains(surface.key) {
+            hoveredSurface = nil
+        }
+        PerfLog.mark("widget.peek end id=\(item.id)")
+        presentationChanged?()
+    }
+
     public func hover(_ surface: WidgetSurfaceID, inside: Bool) {
+        if inside { pointerInside.insert(surface.key) } else { pointerInside.remove(surface.key) }
         pointerChanged?(surface, inside)
+        if !inside, peekItem != nil, hoveredSurface == surface {
+            // The user moved onto the popup and away again: it closes like a hover preview.
+            hoverTask?.cancel()
+            hoverTask = Task { [weak self] in
+                do { try await Task.sleep(for: .milliseconds(220)) } catch { return }
+                self?.endPeek()
+            }
+            return
+        }
         guard layout.hoverPreviews, !dialogOpen else { return }
         if draggingSide {
             exitedDuringDrag = inside ? nil : surface
@@ -638,6 +695,7 @@ public final class WidgetModel: ObservableObject {
     func updateInbox(_ value: WidgetInboxSummary) {
         var arrived = false
         var arrivedKeys: Set<String> = []
+        var arrivals: [WidgetInboxItem] = []
         if !inboxObserved, value.complete { inboxStartedAt = Date().timeIntervalSince1970 * 1000 }
         for entry in value.sessions {
             for item in [entry.unreadItem, entry.pendingItem].compactMap({ $0 }) {
@@ -648,7 +706,7 @@ public final class WidgetModel: ObservableObject {
                 let previous = inboxWatermarks[token]
                 if previous == nil || item.at > previous!.at || (item.at == previous!.at && item.id > previous!.id) {
                     let isArrival = inboxObserved && value.complete && item.at > inboxStartedAt
-                    if isArrival { arrived = true; arrivedKeys.insert(entry.key) }
+                    if isArrival { arrived = true; arrivedKeys.insert(entry.key); arrivals.append(item) }
                     inboxWatermarks[token] = (item.at, item.id)
                     if isArrival, item.kind != "result", value.profile?.hostId == "local",
                         snapshot?.sessions.first(where: { $0.key == item.key })?.target.hostId == "local" {
@@ -660,6 +718,7 @@ public final class WidgetModel: ObservableObject {
         }
         inboxObserved = inboxObserved || value.complete
         if arrived { inboxPulse += 1 }
+        if !arrivals.isEmpty { inboxArrived?(arrivals) }
         for key in arrivedKeys { inboxSessionPulses[key, default: 0] += 1 }
         if inboxWatermarks.count > 4096 {
             let removed = inboxWatermarks.sorted { $0.value.at < $1.value.at }.prefix(inboxWatermarks.count - 3072)
@@ -704,6 +763,19 @@ public final class WidgetModel: ObservableObject {
         })
     }
 
+    /// Opens a decision's card by its id (`d_<n>_<session>`), in its own session when that is another one: the
+    /// "Superseded by" link. The card arrives with that session's snapshot, so the selection is set after `select`.
+    public func openDecision(id: String, sessionKey: String?) {
+        guard let sessionKey else {
+            notice = "That decision's session is not in the widget."
+            return
+        }
+        if sessionKey != selectedKey { select(sessionKey) }
+        section = "Inbox"
+        foldedCardIDs.remove("decision:" + id)
+        selectedCardID = "decision:" + id
+    }
+
     /// "Mark all read": every answer up to now is read, and older questions, decisions and results stop counting in
     /// the badges. Nothing is deleted or answered; each item stays in its session's inbox.
     public func markAllRead() {
@@ -763,6 +835,8 @@ public final class WidgetModel: ObservableObject {
         followedTranscript = nil
         hoveredSurface = nil
         hoverTask?.cancel()
+        peekTask?.cancel()
+        peekItem = nil
         voice?.finishInput()
         speechTask?.cancel()
         reading = false
@@ -1117,9 +1191,24 @@ public final class WidgetModel: ObservableObject {
 
     /// The composer's Send (Return): it answers the open decision, else it is a follow-up to the session.
     public func send() {
+        if ownAnswerCard != nil {
+            submitOwnAnswer()
+            return
+        }
         submit(answering: answerCard != nil && !cardPending)
     }
 
+    /// Sends the draft (text and media) as the answer to `ownAnswerCard`, with no option picked.
+    public func submitOwnAnswer() {
+        guard let card = ownAnswerCard else { return }
+        guard !draft.text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty || !draft.assetIds.isEmpty else {
+            error = "Write your answer or attach media first."
+            return
+        }
+        submit(answering: true)
+        if submittedCards.contains(card.id) { ownAnswerCardID = nil }
+    }
+
     public func submit(choice: String? = nil, answering: Bool = false) {
         guard let session = selected, importing == 0 else { return }
         let submitted = draft
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetWireModels.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetWireModels.swift
index 93685bc8a4..7eed9bbd47 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetWireModels.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetWireModels.swift
@@ -154,6 +154,19 @@ public struct WidgetCard: Codable, Identifiable, Equatable, Sendable {
     public var refs: [WidgetReference]
     public var read: Bool
     public var entryId: String?
+    /// The decision that replaced this one (`question_update` with `supersededBy`).
+    public struct SupersededBy: Codable, Equatable, Sendable {
+        public var id: String
+        public var number: Int
+        public var sessionKey: String?
+        public var title: String?
+    }
+    /// A decision's recorded answer: the option letters, the text, and who recorded it ("inbox" or "agent").
+    public var option: String? = nil
+    public var answer: String? = nil
+    public var answeredVia: String? = nil
+    public var comments: [String]? = nil
+    public var supersededBy: SupersededBy? = nil
     public var needsAnswer: Bool {
         (kind == "decision" && ["open", "drafted"].contains(status))
             || (kind == "form" && status == "pending")
@@ -268,6 +281,11 @@ public struct WidgetPreferences: Codable, Equatable, Sendable {
     public var glassEffect: Bool?
     public var display: String?
     public var providers: [String]?
+    /// Widget alerts for new items: a chime (`alertSound`, a system sound name or "none") and a popup.
+    public var alertDecisions: Bool?
+    public var alertAnswers: Bool?
+    public var alertSound: String?
+    public var alertPopup: Bool?
 
     public var layout: WidgetLayoutConfiguration {
         WidgetLayoutConfiguration(
@@ -354,6 +372,9 @@ public struct WidgetInboxItem: Codable, Equatable, Sendable {
     public var key: String
     public var at: Double
     public var needsAnswer: Bool
+    /// A short title (a decision's title or prompt, an answer's question) and a decision's number, for alerts.
+    public var title: String? = nil
+    public var number: Int? = nil
 }
 public struct WidgetInboxSession: Codable, Equatable, Sendable {
     public var key: String
diff --git a/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift b/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift
index 548d78c155..6f4f97255d 100644
--- a/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift
+++ b/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift
@@ -1,4 +1,5 @@
 import SwiftUI
+import Vision
 import XCTest
 
 @testable import GenesisKitBase
@@ -581,6 +582,179 @@ final class WidgetVisibilityTests: XCTestCase {
         XCTAssertFalse(coordinator.panelMonitorsInstalled)
     }
 
+    /// "Visible edges" decides whether the top notch panel shows; the "Top notch" module card alone never does.
+    @MainActor
+    func testVisibleEdgesShowAndHideTheTopNotchPanel() async throws {
+        try XCTSkipIf(NSScreen.screens.isEmpty, "Edge panels need a display")
+        let fixture = try fixture()
+        defer { cleanUp(fixture) }
+        let coordinator = fixture.coordinator
+        var shown: [EdgePanelPlacement] = []
+        coordinator.settingsPresenter = { _ in }
+        coordinator.orderFront = { shown.append($0.placement) }
+        coordinator.start(showSettings: true)
+        defer { coordinator.stop() }
+        try await waitFor { coordinator.model.snapshot != nil }
+
+        coordinator.model.updatePreferences(["showWidget": .bool(true), "placement": .string("both")])
+        XCTAssertTrue(shown.contains(.top), "placement both orders the top panel front")
+        XCTAssertTrue(shown.contains(.right), "placement both orders the side panels front")
+
+        shown = []
+        coordinator.model.updatePreferences(["placement": .string("top")])
+        XCTAssertTrue(shown.contains(.top))
+        XCTAssertFalse(shown.contains(.right), "placement top shows no side panel")
+
+        shown = []
+        coordinator.model.updatePreferences(["placement": .string("side")])
+        XCTAssertFalse(shown.contains(.top), "placement side shows no top panel")
+
+        shown = []
+        coordinator.model.updatePreferences(["placement": .string("both"), "topModules": .array([.string("capture")])])
+        XCTAssertTrue(shown.contains(.top), "a new top module set keeps the top panel")
+    }
+
+    /// A new decision chimes once and pops up in the agents preview; the preferences turn each part off.
+    @MainActor
+    func testANewDecisionChimesAndPopsUpUnlessTheAlertPreferencesSayNo() async throws {
+        try XCTSkipIf(NSScreen.screens.isEmpty, "Edge panels need a display")
+        let fixture = try fixture()
+        defer { cleanUp(fixture) }
+        let coordinator = fixture.coordinator
+        var chimes: [String?] = []
+        coordinator.settingsPresenter = { _ in }
+        coordinator.orderFront = { _ in }
+        coordinator.playChime = { chimes.append($0) }
+        coordinator.start(showSettings: true)
+        defer { coordinator.stop() }
+        try await waitFor { coordinator.model.snapshot != nil }
+        coordinator.model.updatePreferences(["showWidget": .bool(true), "placement": .string("side")])
+
+        let decision = WidgetInboxItem(id: "decision:d_4_s", sourceId: "d_4_s", kind: "decision", key: "local:claude:s:",
+            at: 2_000, needsAnswer: true, title: "Ship it?", number: 4)
+        let result = WidgetInboxItem(id: "result:x", sourceId: "x", kind: "result", key: "local:claude:s:",
+            at: 3_000, needsAnswer: false)
+        coordinator.alert([result])
+        XCTAssertEqual(chimes.count, 0, "an agent result never alerts")
+        XCTAssertNil(coordinator.model.peekItem)
+
+        coordinator.alert([result, decision])
+        XCTAssertEqual(chimes, [nil], "one chime with the default sound")
+        XCTAssertEqual(coordinator.model.peekItem, decision, "the item that waits for an answer pops up")
+        XCTAssertEqual(coordinator.model.hoveredSurface?.edge, .right)
+        XCTAssertEqual(coordinator.model.presentation(for: try XCTUnwrap(coordinator.model.hoveredSurface)), .preview)
+
+        coordinator.model.collapse()
+        XCTAssertNil(coordinator.model.peekItem)
+        coordinator.model.updatePreferences(["alertPopup": .bool(false), "alertSound": .string("Ping")])
+        coordinator.alert([decision])
+        XCTAssertEqual(chimes, [nil, "Ping"])
+        XCTAssertNil(coordinator.model.peekItem, "alertPopup off shows no popup")
+
+        coordinator.model.updatePreferences(["alertDecisions": .bool(false)])
+        coordinator.alert([decision])
+        XCTAssertEqual(chimes.count, 2, "alertDecisions off: a decision is silent")
+    }
+
+    /// What the inbox shows for an open decision with the own-answer composer, and for a superseded one with the
+    /// answer an agent recorded. Read back from an offscreen render; `GENESIS_WIDGET_RENDER_DIR` keeps the PNGs.
+    @MainActor
+    func testDecisionCardsShowTheOwnAnswerComposerAndTheRecordedOutcome() async throws {
+        let fixture = try fixture()
+        defer { cleanUp(fixture) }
+        let key = "local:claude:fixture-session:"
+        let session: [String: Any] = ["key": key, "target": ["hostId": "local", "provider": "claude",
+            "sessionId": "fixture-session", "sourceHome": "", "cwd": "/fixture"], "title": "Fixture session",
+            "project": "Fixture", "activityAt": 0, "status": "waiting", "pinned": true, "visible": true,
+            "hiddenByFilter": false]
+        func decision(_ number: Int, _ fields: [String: Any]) -> [String: Any] {
+            ["id": "decision:d_\(number)_fixture-session", "kind": "decision", "sourceId": "d_\(number)_fixture-session",
+             "sessionKey": key, "at": 1_000 * Double(number), "title": "Pick a parser for DECISION \(number)", "body": "",
+             "status": "open", "number": number, "revision": 1,
+             "choices": [["id": "a", "title": "Keep the current one", "recommended": true], ["id": "b", "title": "Switch now", "recommended": false]],
+             "attachments": [], "refs": [], "read": true].merging(fields) { _, new in new }
+        }
+        let cards = [
+            decision(7, ["status": "superseded", "option": "a", "answer": "Keep it until the next release.",
+                         "answeredVia": "agent", "comments": ["Replaced by a narrower question."],
+                         "supersededBy": ["id": "d_8_fixture-session", "number": 8, "sessionKey": key,
+                                          "title": "Pick a parser for DECISION 8"]]),
+            decision(8, [:]),
+        ]
+        let data = try JSONSerialization.data(withJSONObject: ["version": 1, "state": ["version": 1, "revision": 0,
+            "selectedKey": key, "preferences": ["excludedKeys": [], "projects": [], "sessions": [], "showChanges": false,
+                "showWidget": false, "placement": "side", "side": "right", "quietSeconds": 60, "voiceProvider": "xai",
+                "voiceLanguage": ""], "assets": [:], "drafts": [:], "outgoing": []],
+            "sessions": [session], "cards": cards, "manifests": [:], "errors": [], "selectedKey": key])
+        try data.write(to: fixture.directory.appendingPathComponent("saved.json"))
+        let model = fixture.coordinator.model
+        model.start()
+        defer { model.stop() }
+        try await waitFor { model.cards.count == 2 }
+        XCTAssertEqual(model.cards.count, 2)
+
+        func read<V: View>(_ name: String, _ content: V) throws -> String {
+            let renderer = ImageRenderer(content: content.frame(width: 440).padding(12)
+                .environment(\.colorScheme, .dark).background(Color.black))
+            renderer.scale = 2
+            let image = try XCTUnwrap(renderer.cgImage)
+            if let folder = ProcessInfo.processInfo.environment["GENESIS_WIDGET_RENDER_DIR"] {
+                try NSBitmapImageRep(cgImage: image).representation(using: .png, properties: [:])?.write(
+                    to: URL(fileURLWithPath: folder).appendingPathComponent(name + ".png"))
+            }
+            let request = VNRecognizeTextRequest()
+            request.recognitionLevel = .accurate
+            request.usesLanguageCorrection = false
+            try VNImageRequestHandler(cgImage: image).perform([request])
+            return (request.results ?? []).compactMap { $0.topCandidates(1).first?.string }.joined(separator: "\n")
+        }
+
+        model.selectedCardID = "decision:d_8_fixture-session"
+        XCTAssertNil(model.ownAnswerCard, "the options show until the user asks for an own answer")
+        var seen = try read("own-answer-row", WidgetOwnAnswerRow {})
+        XCTAssertTrue(seen.contains("Write my own answer"), "read: \(seen)")
+        model.ownAnswerCardID = "decision:d_8_fixture-session"
+        XCTAssertEqual(model.ownAnswerCard?.number, 8)
+        model.submitOwnAnswer()
+        XCTAssertEqual(model.error, "Write your answer or attach media first.", "an empty own answer is refused")
+        model.foldedCardIDs.insert("decision:d_8_fixture-session")
+        XCTAssertNil(model.ownAnswerCard, "a folded card gives the composer back to the bottom of the panel")
+        model.foldedCardIDs.remove("decision:d_8_fixture-session")
+        model.ownAnswerCardID = nil
+
+        let superseded = try XCTUnwrap(model.cards.first { $0.number == 7 })
+        var opened: [String] = []
+        seen = try read("superseded", WidgetDecisionOutcome(card: superseded) { opened.append($0.id) })
+        XCTAssertTrue(seen.contains("Superseded by DECISION 8"), "read: \(seen)")
+        XCTAssertTrue(seen.contains("Answer recorded by the agent"), "read: \(seen)")
+        XCTAssertTrue(seen.contains("Keep the current one"), "the picked option is named: \(seen)")
+        XCTAssertTrue(seen.contains("Replaced by a narrower question."), "read: \(seen)")
+
+        let peek = WidgetInboxItem(id: "decision:d_8_fixture-session", sourceId: "d_8_fixture-session",
+            kind: "decision", key: key, at: Date().timeIntervalSince1970 * 1000, needsAnswer: true,
+            title: "Pick a parser for DECISION 8", number: 8)
+        seen = try read("peek", WidgetPeekView(model: model, item: peek))
+        XCTAssertTrue(seen.contains("New decision"), "read: \(seen)")
+        XCTAssertTrue(seen.contains("Pick a parser"), "read: \(seen)")
+
+        model.openDecision(id: "d_8_fixture-session", sessionKey: key)
+        XCTAssertEqual(model.card?.id, "decision:d_8_fixture-session", "the link opens the newer decision")
+    }
+
+    func testAlertKickerAndOwnAnswerCardStates() {
+        let item = WidgetInboxItem(id: "a", sourceId: "a", kind: "decision", key: "k", at: 1, needsAnswer: true, number: 9)
+        XCTAssertEqual(WidgetAlerts.kicker(item), "New decision · DECISION 9")
+        var card = WidgetCard(id: "decision:d_9_s", kind: "decision", sessionKey: "k", sourceId: "d_9_s", at: 1,
+            title: "T", body: "", status: "superseded", choices: [], attachments: [], refs: [], read: true)
+        card.supersededBy = .init(id: "d_12_s", number: 12, sessionKey: "k", title: "Newer")
+        XCTAssertFalse(card.needsAnswer)
+        XCTAssertEqual(LiveWidgetView.kindLabel(card), "Decision · Superseded by DECISION 12")
+        card.supersededBy = nil
+        card.status = "acknowledged"
+        card.option = "a"
+        XCTAssertEqual(LiveWidgetView.kindLabel(card), "Decision · Answered a · Acknowledged")
+    }
+
     @MainActor
     func testPassivePanelsStayOpenThroughClicksElsewhereAndNormalOnesClose() async throws {
         try XCTSkipIf(NSScreen.screens.isEmpty, "Edge panels need a display")

From 28598030fd65d413bbb6edc302924afb6a322b13 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 18:42:27 +0200
Subject: [PATCH 20/30] refactor(tools): the transclude grammar, recheck line
 and cmd allow-list take GenesisTools' commands from hints.ts through the
 question, markdown, json2md and MCP callers

---
 scripts/ci/tool-command-ratchet.ts            |  12 +-
 .../lib/tools/question-post.ts                |   7 +-
 src/json2md/commands/document.ts              |  15 +-
 src/markdown/commands/tokens.ts               |   3 +-
 src/markdown/lib/resolve.ts                   |   3 +
 src/question/commands/tokens.ts               |   9 +-
 src/question/lib/transclude.ts                |   3 +-
 src/utils/genesis-tools/tools/hints.ts        |  60 ++++++
 src/utils/json2md/document-file.ts            |  18 +-
 src/utils/transclude/describe.ts              |  17 +-
 src/utils/transclude/engine.ts                |   9 +-
 src/utils/transclude/index.ts                 |   6 +-
 src/utils/transclude/kinds.test.ts            |  35 ++-
 src/utils/transclude/kinds/cmd.ts             | 200 ++++++++----------
 src/utils/transclude/kinds/index.ts           |  17 +-
 src/utils/transclude/registry.ts              |   9 +-
 src/utils/transclude/transclude.test.ts       |  14 +-
 src/utils/transclude/types.ts                 |  31 +++
 18 files changed, 307 insertions(+), 161 deletions(-)

diff --git a/scripts/ci/tool-command-ratchet.ts b/scripts/ci/tool-command-ratchet.ts
index 9eb4ab5f46..ecd3bd83ab 100644
--- a/scripts/ci/tool-command-ratchet.ts
+++ b/scripts/ci/tool-command-ratchet.ts
@@ -1,9 +1,10 @@
 /**
  * The files under src/utils that still name a `tools …` command, counted 2026-10-22 when lint-rules
- * `no-tool-command-in-utils` was added: 124 literals in 52 files, of which json2md and the notification `say`
- * option were migrated at once. A ratchet: no file may join this list, and a file leaves it as soon as its hints
- * come from src/utils/genesis-tools/tools/hints.ts through its GenesisTools caller. `lint-rules.test.ts` fails
- * when a listed file no longer names a command, so the list cannot go stale.
+ * `no-tool-command-in-utils` was added: 124 literals in 52 files, of which json2md, the notification `say` option
+ * and the transclude grammar, recheck line and `cmd` allow-list were migrated at once. A ratchet: no file may join
+ * this list, and a file leaves it as soon as its hints come from src/utils/genesis-tools/tools/hints.ts through its
+ * GenesisTools caller. `lint-rules.test.ts` fails when a listed file no longer names a command, so the list cannot
+ * go stale.
  *
  * notifications-app.ts is GenesisTools-only by design (notifications.ts loads it by a runtime path, and a copy
  * leaves it out), so its hints stay where they are.
@@ -53,9 +54,6 @@ export const TOOL_COMMAND_RATCHET: ReadonlySet<string> = new Set<string>([
     "src/utils/security/MasterKey.ts",
     "src/utils/security/SecretStore.ts",
     "src/utils/security/vault-admin.ts",
-    "src/utils/transclude/describe.ts",
-    "src/utils/transclude/engine.ts",
-    "src/utils/transclude/kinds/cmd.ts",
     "src/utils/ts/sourcemaps/find-commit.ts",
     "src/utils/ui/dashboards.ts",
     "src/utils/worker/contract.ts",
diff --git a/src/genesis-tools-mcp/lib/tools/question-post.ts b/src/genesis-tools-mcp/lib/tools/question-post.ts
index fcb4777b86..39d0734a75 100644
--- a/src/genesis-tools-mcp/lib/tools/question-post.ts
+++ b/src/genesis-tools-mcp/lib/tools/question-post.ts
@@ -34,9 +34,9 @@ import type { NativeInboxState } from "@genesiscz/utils/macos/native-inbox";
 import {
     describeTransclusions,
     formatTransclusionHelp,
-    TRANSCLUSION_GRAMMAR,
     type TranscludeOptions,
     transclude,
+    transclusionGrammar,
 } from "@genesiscz/utils/transclude";
 
 export interface QuestionPostArgs {
@@ -560,7 +560,10 @@ export const QUESTION_TOKENS_DESCRIPTION =
 export async function handleQuestionTokens(args: QuestionTokensArgs, deps: QuestionDeps = {}): Promise<string> {
     if (!args.text?.trim()) {
         return SafeJSON.stringify(
-            { grammar: TRANSCLUSION_GRAMMAR, kinds: describeTransclusions(questionTokenRegistry()) },
+            {
+                grammar: transclusionGrammar(questionTokenRegistry()),
+                kinds: describeTransclusions(questionTokenRegistry()),
+            },
             null,
             2
         );
diff --git a/src/json2md/commands/document.ts b/src/json2md/commands/document.ts
index d03c22490f..aeb3396d39 100644
--- a/src/json2md/commands/document.ts
+++ b/src/json2md/commands/document.ts
@@ -2,11 +2,12 @@ import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { suggestCommand } from "@genesiscz/utils/cli";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
-import { json2mdBuild } from "@genesiscz/utils/genesis-tools/tools/hints";
+import { json2mdBuild, transclusionHints } from "@genesiscz/utils/genesis-tools/tools/hints";
 import { SafeJSON } from "@genesiscz/utils/json";
 import {
     checkDocument,
     type DocumentCheck,
+    type DocumentHints,
     loadDocumentModule,
     writeDocument,
 } from "@genesiscz/utils/json2md/document-file";
@@ -20,6 +21,7 @@ import {
     shadowedByFor,
 } from "@genesiscz/utils/package-link";
 import { createBoxTable, formatDotStatus, renderCliHeader } from "@genesiscz/utils/table";
+import { defaultTransclusionRegistry } from "@genesiscz/utils/transclude";
 import type { Command } from "commander";
 import pc from "picocolors";
 
@@ -267,6 +269,11 @@ export default defineDocument<Data>({
 `;
 }
 
+/** The GenesisTools commands a document's stamp and its `{{kind …}}` tokens name. */
+function documentHints(): DocumentHints {
+    return { rebuildCommand: json2mdBuild, transclusions: defaultTransclusionRegistry(transclusionHints()) };
+}
+
 function registerBuild(program: Command): void {
     program
         .command("build")
@@ -291,7 +298,7 @@ function registerBuild(program: Command): void {
                 const result = await writeDocument(modulePath, definition, {
                     force: flags.force,
                     dryRun: flags.dryRun,
-                    rebuildCommand: json2mdBuild,
+                    ...documentHints(),
                 });
 
                 logger.debug({ file: modulePath, outcome: result.outcome, out: result.outPath }, "json2md: build");
@@ -357,7 +364,7 @@ function registerCheck(program: Command): void {
                 }
 
                 const definition = await loadDocumentModule(modulePath);
-                results.push(await checkDocument(modulePath, definition, { rebuildCommand: json2mdBuild }));
+                results.push(await checkDocument(modulePath, definition, documentHints()));
             }
 
             // A document that was never generated reads as `unstamped`, which is not a failure for
@@ -467,7 +474,7 @@ function registerInit(program: Command): void {
             }
 
             const definition = await loadDocumentModule(modulePath);
-            const result = await writeDocument(modulePath, definition, { rebuildCommand: json2mdBuild });
+            const result = await writeDocument(modulePath, definition, documentHints());
 
             if (result.outcome === "refused" && result.check) {
                 // A markdown file already sits at the output path. It is left alone.
diff --git a/src/markdown/commands/tokens.ts b/src/markdown/commands/tokens.ts
index 65847ca821..a90347de16 100644
--- a/src/markdown/commands/tokens.ts
+++ b/src/markdown/commands/tokens.ts
@@ -1,4 +1,5 @@
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
+import { transclusionHints } from "@genesiscz/utils/genesis-tools/tools/hints";
 import { out } from "@genesiscz/utils/logger";
 import { UNSUPPORTED_IN_NOTES } from "@genesiscz/utils/markdown/includes";
 import { createBoxTable, renderCliHeader } from "@genesiscz/utils/table";
@@ -12,7 +13,7 @@ export function registerTokensCommand(program: Command): void {
         .description("List the {{kind …}} tokens a markdown file may carry, and the ones it may not")
         .option("--json", "machine-readable output")
         .action((flags: { json?: boolean }) => {
-            const kinds = defaultTransclusionRegistry()
+            const kinds = defaultTransclusionRegistry(transclusionHints())
                 .list()
                 .map((definition) => ({
                     name: definition.name,
diff --git a/src/markdown/lib/resolve.ts b/src/markdown/lib/resolve.ts
index 181aaa1842..688c6cb381 100644
--- a/src/markdown/lib/resolve.ts
+++ b/src/markdown/lib/resolve.ts
@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { type BackupRecord, backupAndWrite } from "@app/markdown/lib/backup";
+import { transclusionHints } from "@genesiscz/utils/genesis-tools/tools/hints";
 import { logger } from "@genesiscz/utils/logger";
 import {
     type CodeLinksResult,
@@ -9,6 +10,7 @@ import {
     type IncludeOutcome,
     resolveIncludes,
 } from "@genesiscz/utils/markdown/includes";
+import { defaultTransclusionRegistry } from "@genesiscz/utils/transclude";
 
 export interface ResolveFileOptions {
     file: string;
@@ -50,6 +52,7 @@ export async function resolveMarkdownFile(options: ResolveFileOptions): Promise<
     const resolved = await resolveIncludes(start, {
         cwd: options.cwd ? resolve(options.cwd) : dirname(file),
         refresh: !options.newOnly,
+        registry: defaultTransclusionRegistry(transclusionHints()),
     });
     const after = resolved.text;
     const outcomes = resolved.outcomes;
diff --git a/src/question/commands/tokens.ts b/src/question/commands/tokens.ts
index 6376e18a4b..de8c96a1de 100644
--- a/src/question/commands/tokens.ts
+++ b/src/question/commands/tokens.ts
@@ -9,8 +9,8 @@ import {
     describeTransclusions,
     formatParamList,
     formatTransclusionHelp,
-    TRANSCLUSION_GRAMMAR,
     transclude,
+    transclusionGrammar,
 } from "@genesiscz/utils/transclude";
 import type { Command } from "commander";
 import pc from "picocolors";
@@ -53,7 +53,7 @@ function renderKinds(): void {
 
     out.println(table.toString());
 
-    for (const line of TRANSCLUSION_GRAMMAR) {
+    for (const line of transclusionGrammar(registry)) {
         out.println(pc.dim(line));
     }
 
@@ -81,7 +81,10 @@ export function registerTokensCommand(program: Command): void {
             if (format === "json") {
                 out.result(
                     SafeJSON.stringify(
-                        { grammar: TRANSCLUSION_GRAMMAR, kinds: describeTransclusions(questionTokenRegistry()) },
+                        {
+                            grammar: transclusionGrammar(questionTokenRegistry()),
+                            kinds: describeTransclusions(questionTokenRegistry()),
+                        },
                         null,
                         2
                     )
diff --git a/src/question/lib/transclude.ts b/src/question/lib/transclude.ts
index 4a6f73b785..c673ef95e1 100644
--- a/src/question/lib/transclude.ts
+++ b/src/question/lib/transclude.ts
@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { basename } from "node:path";
 import { gatherHarnessPoster } from "@genesiscz/utils/agent/runtime";
+import { transclusionHints } from "@genesiscz/utils/genesis-tools/tools/hints";
 import {
     type ImageAttachmentInput,
     parseImageAttachmentInputs,
@@ -38,7 +39,7 @@ let registry: TransclusionRegistry | null = null;
 
 /** The kinds `tools question` resolves. One registry for the CLI, the MCP server and the help. */
 export function questionTokenRegistry(): TransclusionRegistry {
-    registry ??= defaultTransclusionRegistry();
+    registry ??= defaultTransclusionRegistry(transclusionHints());
     return registry;
 }
 
diff --git a/src/utils/genesis-tools/tools/hints.ts b/src/utils/genesis-tools/tools/hints.ts
index 2c72280113..bafbee4806 100644
--- a/src/utils/genesis-tools/tools/hints.ts
+++ b/src/utils/genesis-tools/tools/hints.ts
@@ -1,4 +1,5 @@
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
+import type { CmdToolVerb, TransclusionHints } from "@genesiscz/utils/transclude";
 
 /**
  * Every GenesisTools command that a shared module under `src/utils` shows or runs, in one place.
@@ -18,3 +19,62 @@ export function json2mdBuild(portable: string): string {
 export function notificationSayCommand(): string[] {
     return toolCommand("say").split(" ");
 }
+
+/** The command that reports whether a question's `[verify]` tokens changed since capture. */
+export function questionShowRecheck(id = "<id>"): string {
+    return `${toolCommand("question show")} ${id} --recheck`;
+}
+
+/** The shell line that re-resolves one token, single-quoted so a `"` inside it survives. */
+export function questionTokensResolve(raw: string): string {
+    return `${toolCommand("question tokens resolve")} '${raw.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Read-only `tools` verbs the `cmd` token kind may run, matched on their leading words, each with the only flags it
+ * may take. A verb with a writing flag (`git merged --prune`) is read-only only without it, so every other dash
+ * argument is refused rather than a list of bad ones kept.
+ */
+export const CMD_TOOLS_VERBS: readonly CmdToolVerb[] = [
+    {
+        words: ["ts", "skeleton"],
+        flags: [
+            "--exported",
+            "--top-level",
+            "--types",
+            "--include-names",
+            "--include-hash",
+            "--include-locals",
+            "--function-context",
+            "--exact-tokens",
+            "--tests",
+            "--ignore",
+            "--format",
+            "--md",
+            "--json",
+            "--json-compact",
+            "--toon",
+        ],
+    },
+    { words: ["git", "base"], flags: ["-b", "--base", "--offline", "--json", "-C", "--cwd"] },
+    {
+        words: ["git", "merged"],
+        flags: ["-b", "--base", "--pr", "--json", "--all", "-d", "--stale-days", "-C", "--cwd"],
+    },
+    { words: ["question", "list"], flags: ["--type", "--all-sessions", "--session", "--status", "--json"] },
+    { words: ["question", "tokens"], flags: ["--format", "--cwd"] },
+];
+
+/** Everything a GenesisTools transclusion registry names: pass it to `defaultTransclusionRegistry()`. */
+export function transclusionHints(): TransclusionHints {
+    return {
+        verifyRecheck: questionShowRecheck(),
+        recheck: questionTokensResolve,
+        cmdTools: {
+            program: toolCommand("ts skeleton").split(" ")[0],
+            verbs: CMD_TOOLS_VERBS,
+            description: `, ${toolCommand("ts skeleton")}, ${toolCommand("git base")}|merged, ${toolCommand("question list")}|tokens`,
+            example: `{{cmd run="${toolCommand("ts skeleton")} src/utils/transclude/engine.ts"}}`,
+        },
+    };
+}
diff --git a/src/utils/json2md/document-file.ts b/src/utils/json2md/document-file.ts
index 83249e8887..7abd0f4a55 100644
--- a/src/utils/json2md/document-file.ts
+++ b/src/utils/json2md/document-file.ts
@@ -11,7 +11,7 @@
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { resolveIncludes } from "@genesiscz/utils/markdown/includes";
-import { hasTransclusionTokens } from "@genesiscz/utils/transclude";
+import { hasTransclusionTokens, type TransclusionRegistry } from "@genesiscz/utils/transclude";
 import TOML from "@iarna/toml";
 import { Json2mdError } from "./errors";
 import { type DocumentOptions, json2md } from "./index";
@@ -157,6 +157,8 @@ export interface BuildResult {
 export interface DocumentHints {
     /** The command that rebuilds the document, given its generator path relative to the cwd (or absolute). */
     rebuildCommand?: (portable: string) => string;
+    /** The registry `{{kind …}}` tokens resolve through; the default names no command of any CLI. */
+    transclusions?: TransclusionRegistry;
 }
 
 export interface BuildOverrides extends DocumentHints {
@@ -211,7 +213,14 @@ export async function buildDocument<T>(
     const body =
         definition.transclude === false || !hasTransclusionTokens(rendered)
             ? rendered
-            : (await resolveIncludes(rendered, { cwd: baseDir, refresh: true, now: () => capturedAt(generated) })).text;
+            : (
+                  await resolveIncludes(rendered, {
+                      cwd: baseDir,
+                      refresh: true,
+                      now: () => capturedAt(generated),
+                      ...(overrides.transclusions ? { registry: overrides.transclusions } : {}),
+                  })
+              ).text;
 
     if (definition.unstamped) {
         return { markdown: body, body, outPath, dataPath, sourceHash, data };
@@ -236,7 +245,10 @@ export async function buildDocument<T>(
 }
 
 function hintsOf(hints: DocumentHints): DocumentHints {
-    return hints.rebuildCommand ? { rebuildCommand: hints.rebuildCommand } : {};
+    return {
+        ...(hints.rebuildCommand ? { rebuildCommand: hints.rebuildCommand } : {}),
+        ...(hints.transclusions ? { transclusions: hints.transclusions } : {}),
+    };
 }
 
 export type WriteOutcome = "written" | "unchanged" | "refused";
diff --git a/src/utils/transclude/describe.ts b/src/utils/transclude/describe.ts
index 5680f0f4d6..930a8d4e42 100644
--- a/src/utils/transclude/describe.ts
+++ b/src/utils/transclude/describe.ts
@@ -1,18 +1,25 @@
-import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import type { TransclusionRegistry } from "./registry";
 import type { TransclusionDefinition, TransclusionParam } from "./types";
 
-/** The grammar in four lines, shared by the CLI help, the MCP description and the README check. */
-export const TRANSCLUSION_GRAMMAR = [
+/** The grammar, shared by the CLI help, the MCP description and the README check; see {@link transclusionGrammar}. */
+const GRAMMAR = [
     "{{<kind> key=\"value\" key='value' key=value}}: named params in any order, resolved when the text is saved.",
     "A token always has at least one key=value; a bare {{name}} is a prompt variable and stays literal.",
     "Inside quotes only \\\" \\' \\\\ are escapes, so C:\\path needs no doubling. \\{{ writes a literal {{.",
     "Tokens inside `code` or a fenced block stay literal. mdBook aliases: {{#include path}}, {{#include path:10:20}}, {{#include path:anchor}}.",
     "A token that fails is replaced by ⚠️ unresolved `{{…}}`: <reason>, never dropped.",
     "Each block ends with a footer: capture time, source, what is shown, and the token that re-checks it.",
-    `[verify] kinds stay live: ${toolCommand("question show")} <id> --recheck reports whether they changed since capture.`,
 ];
 
+/** The grammar lines, ending with how `[verify]` kinds are re-checked: the registry's command, or a plain sentence. */
+export function transclusionGrammar(registry: TransclusionRegistry): string[] {
+    const recheck = registry.hints.verifyRecheck;
+    const verify = recheck
+        ? `[verify] kinds stay live: ${recheck} reports whether they changed since capture.`
+        : "[verify] kinds stay live: a recheck reports whether they changed since capture.";
+    return [...GRAMMAR, verify];
+}
+
 export interface TransclusionDescription {
     name: string;
     description: string;
@@ -67,7 +74,7 @@ export function formatTransclusionHelp(
     { indent = "  ", descriptions = true }: { indent?: string; descriptions?: boolean } = {}
 ): string {
     const width = Math.max(...registry.list().map((definition) => definition.name.length));
-    const lines = TRANSCLUSION_GRAMMAR.map((line) => `${indent}${line}`);
+    const lines = transclusionGrammar(registry).map((line) => `${indent}${line}`);
     lines.push(`${indent}Kinds (* required, :type, =default):`);
 
     for (const definition of registry.list()) {
diff --git a/src/utils/transclude/engine.ts b/src/utils/transclude/engine.ts
index 55c5cf0595..999fa1eb64 100644
--- a/src/utils/transclude/engine.ts
+++ b/src/utils/transclude/engine.ts
@@ -1,5 +1,4 @@
 import { createHash } from "node:crypto";
-import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { type Logger, logger as rootLogger } from "@genesiscz/utils/logger";
 import { parseTranscludeText, type Segment, type TokenSegment } from "./parse";
 import { redactSecretsInText } from "./redact";
@@ -99,6 +98,7 @@ export async function transclude(text: string, options: TranscludeOptions): Prom
     const maxText = options.maxTextChars ?? DEFAULT_MAX_TEXT_CHARS;
     const maxToken = options.maxTokenChars ?? DEFAULT_MAX_TOKEN_CHARS;
     const redact = options.redact ?? redactSecretsInText;
+    const recheck = options.registry.hints.recheck;
     const capturedAt = (options.now?.() ?? new Date()).toISOString();
     const records: TransclusionToken[] = [];
     let added = 0;
@@ -129,7 +129,7 @@ export async function transclude(text: string, options: TranscludeOptions): Prom
                 capturedAt,
                 ...(entry.result.source ? { source: entry.result.source } : {}),
                 token: segment.raw,
-                recheck: recheckCommand(segment.raw),
+                ...(recheck ? { recheck: recheck(segment.raw) } : {}),
                 ...(entry.result.shown ? { shown: entry.result.shown } : {}),
                 ...(truncated ? { truncatedAt: maxToken } : {}),
             };
@@ -218,11 +218,6 @@ export function contentSignature(content: string): string {
     return createHash("sha256").update(content).digest("hex");
 }
 
-/** The shell line that re-resolves a token, single-quoted so a `"` inside it survives. */
-export function recheckCommand(raw: string): string {
-    return `${toolCommand("question tokens resolve")} '${raw.replace(/'/g, "'\\''")}'`;
-}
-
 function formatCaptureTime(iso: string): string {
     return `${iso.slice(0, 16).replace("T", " ")} UTC`;
 }
diff --git a/src/utils/transclude/index.ts b/src/utils/transclude/index.ts
index 96170de0c9..be86574d66 100644
--- a/src/utils/transclude/index.ts
+++ b/src/utils/transclude/index.ts
@@ -2,8 +2,8 @@ export {
     describeTransclusions,
     formatParamList,
     formatTransclusionHelp,
-    TRANSCLUSION_GRAMMAR,
     type TransclusionDescription,
+    transclusionGrammar,
 } from "./describe";
 export {
     capChars,
@@ -14,7 +14,6 @@ export {
     DEFAULT_TOKEN_TIMEOUT_MS,
     failureMarker,
     provenanceFooter,
-    recheckCommand,
     TranscludeFailedError,
     type TranscludeOptions,
     transclude,
@@ -42,12 +41,15 @@ export {
 } from "./registry";
 export { defaultRunner } from "./runner";
 export type {
+    CmdToolsHints,
+    CmdToolVerb,
     CommandOutput,
     LineRange,
     TranscludeResult,
     TransclusionAction,
     TransclusionContext,
     TransclusionDefinition,
+    TransclusionHints,
     TransclusionParam,
     TransclusionParams,
     TransclusionParamType,
diff --git a/src/utils/transclude/kinds.test.ts b/src/utils/transclude/kinds.test.ts
index 4f1b0c77a1..0989163bca 100644
--- a/src/utils/transclude/kinds.test.ts
+++ b/src/utils/transclude/kinds.test.ts
@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { transclude } from "./engine";
-import { checkAllowed, splitCommandLine } from "./kinds/cmd";
+import { checkAllowed, cmdTransclusion, createCmdTransclusion, splitCommandLine } from "./kinds/cmd";
 import { defaultTransclusionRegistry } from "./kinds/index";
 import { pointerSegments } from "./kinds/json";
 import { parseCommentRef } from "./kinds/pr-thread";
@@ -223,12 +223,35 @@ describe("cmd", () => {
         );
         expect(() => checkAllowed(["git", "diff", "--output=/tmp/x"])).toThrow('git flag "--output=/tmp/x"');
         expect(() => checkAllowed(["rm", "-rf"])).toThrow('cmd: "rm" is not allowed');
-        expect(() => checkAllowed(["tools", "ts", "skeleton", "a.ts"])).not.toThrow();
-        expect(() => checkAllowed(["tools", "git", "merged", "--json", "--base=origin/master"])).not.toThrow();
-        expect(() => checkAllowed(["tools", "git", "merged", "feat/x", "--prune"])).toThrow(
-            '"tools git merged" does not take "--prune"'
+    });
+
+    test("runs the caller's own read-only commands only when it passes them", () => {
+        const tools = {
+            program: "mytool",
+            verbs: [
+                { words: ["ts", "skeleton"], flags: [] },
+                { words: ["git", "merged"], flags: ["--json", "--base"] },
+            ],
+            description: ", mytool ts skeleton, mytool git merged",
+            example: '{{cmd run="mytool ts skeleton a.ts"}}',
+        };
+        expect(() => checkAllowed(["mytool", "ts", "skeleton", "a.ts"], tools)).not.toThrow();
+        expect(() => checkAllowed(["mytool", "git", "merged", "--json", "--base=origin/master"], tools)).not.toThrow();
+        expect(() => checkAllowed(["mytool", "git", "merged", "feat/x", "--prune"], tools)).toThrow(
+            '"mytool git merged" does not take "--prune"'
         );
-        expect(() => checkAllowed(["tools", "git", "merged", "--yes"])).toThrow('does not take "--yes"');
+        expect(() => checkAllowed(["mytool", "rm"], tools)).toThrow(
+            /"mytool rm" is not on the read-only list \(allowed: git log, .*git merge-base, mytool ts skeleton, mytool git merged\)$/
+        );
+        expect(() => checkAllowed(["mytool", "ts", "skeleton", "a.ts"])).toThrow(
+            /cmd: "mytool" is not allowed \(allowed: git log, .*git merge-base\)$/
+        );
+
+        const kind = createCmdTransclusion(tools);
+        expect(kind.description).toContain("merge-base, mytool ts skeleton, mytool git merged). No shell");
+        expect(kind.examples).toEqual(['{{cmd run="git log --oneline -5"}}', '{{cmd run="mytool ts skeleton a.ts"}}']);
+        expect(cmdTransclusion.description).toContain("merge-base). No shell");
+        expect(cmdTransclusion.examples).toEqual(['{{cmd run="git log --oneline -5"}}']);
     });
 });
 
diff --git a/src/utils/transclude/kinds/cmd.ts b/src/utils/transclude/kinds/cmd.ts
index ac60ad81cb..584e288c9f 100644
--- a/src/utils/transclude/kinds/cmd.ts
+++ b/src/utils/transclude/kinds/cmd.ts
@@ -1,5 +1,5 @@
-import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { defineTransclusion, TransclusionError } from "../registry";
+import type { CmdToolsHints, TransclusionDefinition } from "../types";
 import { codeBlock } from "./shared";
 
 const MAX_TIMEOUT_MS = 30_000;
@@ -24,41 +24,6 @@ export const CMD_GIT_SUBCOMMANDS = [
  */
 const GIT_FORBIDDEN_FLAG = /^(?:--output|--ext-diff|--textconv|--exec|--upload-pack|--receive-pack|--config)/;
 
-/**
- * Read-only `tools` verbs, matched on their leading words, each with the only flags it may take. A
- * verb with a writing flag (`git merged --prune`) is read-only only without it, so every other dash
- * argument is refused rather than a list of bad ones kept.
- */
-export const CMD_TOOLS_VERBS: readonly { words: readonly string[]; flags: readonly string[] }[] = [
-    {
-        words: ["ts", "skeleton"],
-        flags: [
-            "--exported",
-            "--top-level",
-            "--types",
-            "--include-names",
-            "--include-hash",
-            "--include-locals",
-            "--function-context",
-            "--exact-tokens",
-            "--tests",
-            "--ignore",
-            "--format",
-            "--md",
-            "--json",
-            "--json-compact",
-            "--toon",
-        ],
-    },
-    { words: ["git", "base"], flags: ["-b", "--base", "--offline", "--json", "-C", "--cwd"] },
-    {
-        words: ["git", "merged"],
-        flags: ["-b", "--base", "--pr", "--json", "--all", "-d", "--stale-days", "-C", "--cwd"],
-    },
-    { words: ["question", "list"], flags: ["--type", "--all-sessions", "--session", "--status", "--json"] },
-    { words: ["question", "tokens"], flags: ["--format", "--cwd"] },
-];
-
 /**
  * Splits a command line into argv the way a shell would for plain words and quotes, and refuses
  * everything that would need a shell: pipes, redirects, `;`, `&`, `$`, backticks, subshells.
@@ -121,11 +86,14 @@ export function splitCommandLine(line: string): string[] {
     return argv;
 }
 
-/** Throws with the allowed set when the argv is not an allowlisted read-only command. */
-export function checkAllowed(argv: string[]): void {
+/**
+ * Throws with the allowed set when the argv is not an allowlisted read-only command: a git subcommand, or one of the
+ * caller's own read-only commands it passed in `tools` (each with the only flags it may take).
+ */
+export function checkAllowed(argv: string[], tools?: CmdToolsHints): void {
     const allowedGit = CMD_GIT_SUBCOMMANDS.map((sub) => `git ${sub}`).join(", ");
-    const allowedTools = CMD_TOOLS_VERBS.map((verb) => `tools ${verb.words.join(" ")}`).join(", ");
-    const allowed = `allowed: ${allowedGit}, ${allowedTools}`;
+    const allowedTools = (tools?.verbs ?? []).map((verb) => `, ${tools?.program} ${verb.words.join(" ")}`).join("");
+    const allowed = `allowed: ${allowedGit}${allowedTools}`;
 
     if (argv[0] === "git") {
         const sub = argv[1] ?? "";
@@ -143,12 +111,12 @@ export function checkAllowed(argv: string[]): void {
         return;
     }
 
-    if (argv[0] === "tools") {
-        const verb = CMD_TOOLS_VERBS.find((entry) => entry.words.every((word, index) => argv[index + 1] === word));
+    if (tools && argv[0] === tools.program) {
+        const verb = tools.verbs.find((entry) => entry.words.every((word, index) => argv[index + 1] === word));
 
         if (!verb) {
             throw new TransclusionError(
-                `cmd: "tools ${argv.slice(1, 3).join(" ")}" is not on the read-only list (${allowed})`
+                `cmd: "${tools.program} ${argv.slice(1, 3).join(" ")}" is not on the read-only list (${allowed})`
             );
         }
 
@@ -158,7 +126,7 @@ export function checkAllowed(argv: string[]): void {
 
         if (bad) {
             throw new TransclusionError(
-                `cmd: "tools ${verb.words.join(" ")}" does not take "${bad}" here (read-only flags: ${verb.flags.join(" ")})`
+                `cmd: "${tools.program} ${verb.words.join(" ")}" does not take "${bad}" here (read-only flags: ${verb.flags.join(" ")})`
             );
         }
 
@@ -168,75 +136,83 @@ export function checkAllowed(argv: string[]): void {
     throw new TransclusionError(`cmd: "${argv[0] ?? ""}" is not allowed (${allowed})`);
 }
 
-export const cmdTransclusion = defineTransclusion({
-    name: "cmd",
-    description:
-        "The output of one allowlisted read-only command (git log/show/status/diff/blame/rev-parse/ls-files/" +
-        `shortlog/describe/merge-base, ${toolCommand("ts skeleton")}, ${toolCommand("git base")}|merged, ${toolCommand("question list")}|tokens). ` +
-        "No shell, a timeout, and the exit code is shown.",
-    params: [
-        { name: "run", type: "string", required: true, description: "The command line, e.g. git log --oneline -5." },
-        { name: "cwd", type: "path", description: "Run it here instead of the caller's cwd." },
-        {
-            name: "timeout",
-            type: "int",
-            default: 10_000,
-            description: `Milliseconds, at most ${MAX_TIMEOUT_MS} and never past the token's own deadline.`,
-        },
-    ],
-    examples: [
-        '{{cmd run="git log --oneline -5"}}',
-        `{{cmd run="${toolCommand("ts skeleton")} src/utils/transclude/engine.ts"}}`,
-    ],
-    action: "substitute",
-    async resolve(params, ctx) {
-        const line = params.string("run");
-        const argv = splitCommandLine(line);
-        checkAllowed(argv);
-        // Never past the token's own deadline: the engine aborts there anyway.
-        const timeoutMs = Math.max(
-            1,
-            Math.min(Math.max(100, params.int("timeout")), MAX_TIMEOUT_MS, ctx.deadline - Date.now())
-        );
-        const finalArgv =
-            argv[0] === "git" && ["diff", "show", "log"].includes(argv[1])
-                ? ["git", "--no-pager", argv[1], "--no-ext-diff", "--no-textconv", ...argv.slice(2)]
-                : argv[0] === "git"
-                  ? ["git", "--no-pager", ...argv.slice(1)]
-                  : argv;
-        const cwd = params.optionalString("cwd") ?? ctx.cwd;
-        const result = await ctx.run(finalArgv, {
-            cwd,
-            signal: ctx.signal,
-            timeoutMs,
-            env: { GIT_PAGER: "cat", PAGER: "cat", NO_COLOR: "1" },
-        });
-
-        if (result.code === 127 && !result.stdout) {
-            throw new TransclusionError(`cmd could not start "${argv[0]}": ${result.stderr.trim()}`);
-        }
+/** The `cmd` kind, allowing the caller's own read-only commands in `tools` beside git. */
+export function createCmdTransclusion(tools?: CmdToolsHints): TransclusionDefinition {
+    return defineTransclusion({
+        name: "cmd",
+        description:
+            "The output of one allowlisted read-only command (git log/show/status/diff/blame/rev-parse/ls-files/" +
+            `shortlog/describe/merge-base${tools?.description ?? ""}). ` +
+            "No shell, a timeout, and the exit code is shown.",
+        params: [
+            {
+                name: "run",
+                type: "string",
+                required: true,
+                description: "The command line, e.g. git log --oneline -5.",
+            },
+            { name: "cwd", type: "path", description: "Run it here instead of the caller's cwd." },
+            {
+                name: "timeout",
+                type: "int",
+                default: 10_000,
+                description: `Milliseconds, at most ${MAX_TIMEOUT_MS} and never past the token's own deadline.`,
+            },
+        ],
+        examples: ['{{cmd run="git log --oneline -5"}}', ...(tools ? [tools.example] : [])],
+        action: "substitute",
+        async resolve(params, ctx) {
+            const line = params.string("run");
+            const argv = splitCommandLine(line);
+            checkAllowed(argv, tools);
+            // Never past the token's own deadline: the engine aborts there anyway.
+            const timeoutMs = Math.max(
+                1,
+                Math.min(Math.max(100, params.int("timeout")), MAX_TIMEOUT_MS, ctx.deadline - Date.now())
+            );
+            const finalArgv =
+                argv[0] === "git" && ["diff", "show", "log"].includes(argv[1])
+                    ? ["git", "--no-pager", argv[1], "--no-ext-diff", "--no-textconv", ...argv.slice(2)]
+                    : argv[0] === "git"
+                      ? ["git", "--no-pager", ...argv.slice(1)]
+                      : argv;
+            const cwd = params.optionalString("cwd") ?? ctx.cwd;
+            const result = await ctx.run(finalArgv, {
+                cwd,
+                signal: ctx.signal,
+                timeoutMs,
+                env: { GIT_PAGER: "cat", PAGER: "cat", NO_COLOR: "1" },
+            });
+
+            if (result.code === 127 && !result.stdout) {
+                throw new TransclusionError(`cmd could not start "${argv[0]}": ${result.stderr.trim()}`);
+            }
 
-        if (result.code === 124) {
-            throw new TransclusionError(`cmd timed out after ${timeoutMs} ms: ${line}`);
-        }
+            if (result.code === 124) {
+                throw new TransclusionError(`cmd timed out after ${timeoutMs} ms: ${line}`);
+            }
 
-        const parts = [
-            codeBlock({
-                text: result.stdout.trimEnd() || "(no output)",
-                lang: "text",
-                title: `\`$ ${line}\` · exit ${result.code}${result.truncated ? " · output cut at 5 MB" : ""}`,
-            }),
-        ];
+            const parts = [
+                codeBlock({
+                    text: result.stdout.trimEnd() || "(no output)",
+                    lang: "text",
+                    title: `\`$ ${line}\` · exit ${result.code}${result.truncated ? " · output cut at 5 MB" : ""}`,
+                }),
+            ];
 
-        if (result.stderr.trim()) {
-            parts.push(codeBlock({ text: result.stderr.trimEnd(), lang: "text", title: "stderr:" }));
-        }
+            if (result.stderr.trim()) {
+                parts.push(codeBlock({ text: result.stderr.trimEnd(), lang: "text", title: "stderr:" }));
+            }
+
+            return {
+                markdown: parts.join("\n"),
+                meta: { argv: finalArgv, exit: result.code, cwd },
+                block: true,
+                source: `$ ${line} (exit ${result.code})`,
+            };
+        },
+    });
+}
 
-        return {
-            markdown: parts.join("\n"),
-            meta: { argv: finalArgv, exit: result.code, cwd },
-            block: true,
-            source: `$ ${line} (exit ${result.code})`,
-        };
-    },
-});
+/** The `cmd` kind without any caller's commands: git only. */
+export const cmdTransclusion = createCmdTransclusion();
diff --git a/src/utils/transclude/kinds/index.ts b/src/utils/transclude/kinds/index.ts
index 96672074cb..9b75812868 100644
--- a/src/utils/transclude/kinds/index.ts
+++ b/src/utils/transclude/kinds/index.ts
@@ -1,6 +1,6 @@
 import { createTransclusionRegistry, type TransclusionRegistry } from "../registry";
-import type { TransclusionDefinition } from "../types";
-import { cmdTransclusion } from "./cmd";
+import type { TransclusionDefinition, TransclusionHints } from "../types";
+import { cmdTransclusion, createCmdTransclusion } from "./cmd";
 import { diffTransclusion } from "./diff";
 import { fileTransclusion } from "./file";
 import { imageTransclusion } from "./image";
@@ -25,13 +25,20 @@ export const DEFAULT_TRANSCLUSIONS: readonly TransclusionDefinition[] = [
     prThreadTransclusion,
 ];
 
-/** A fresh registry with the built-in kinds; callers may `define` more on it. */
-export function defaultTransclusionRegistry(): TransclusionRegistry {
-    return createTransclusionRegistry([...DEFAULT_TRANSCLUSIONS]);
+/**
+ * A fresh registry with the built-in kinds; callers may `define` more on it. `hints` name the caller's own commands
+ * (see {@link TransclusionHints}); without them the registry names none.
+ */
+export function defaultTransclusionRegistry(hints: TransclusionHints = {}): TransclusionRegistry {
+    const kinds = DEFAULT_TRANSCLUSIONS.map((kind) =>
+        kind === cmdTransclusion && hints.cmdTools ? createCmdTransclusion(hints.cmdTools) : kind
+    );
+    return createTransclusionRegistry(kinds, hints);
 }
 
 export {
     cmdTransclusion,
+    createCmdTransclusion,
     diffTransclusion,
     fileTransclusion,
     imageTransclusion,
diff --git a/src/utils/transclude/registry.ts b/src/utils/transclude/registry.ts
index c33b6946f6..2900231ee8 100644
--- a/src/utils/transclude/registry.ts
+++ b/src/utils/transclude/registry.ts
@@ -4,6 +4,7 @@ import { levenshteinDistance } from "@genesiscz/utils/fuzzy-match";
 import type {
     LineRange,
     TransclusionDefinition,
+    TransclusionHints,
     TransclusionParam,
     TransclusionParams,
     TransclusionParamValue,
@@ -22,9 +23,14 @@ export interface TransclusionRegistry {
     list(): TransclusionDefinition[];
     /** Adds a kind; a name already taken throws, so two kinds cannot silently shadow each other. */
     define(definition: TransclusionDefinition): void;
+    /** The caller's commands the help, the stored provenance and the `cmd` kind name. Empty in a plain registry. */
+    readonly hints: TransclusionHints;
 }
 
-export function createTransclusionRegistry(definitions: TransclusionDefinition[] = []): TransclusionRegistry {
+export function createTransclusionRegistry(
+    definitions: TransclusionDefinition[] = [],
+    hints: TransclusionHints = {}
+): TransclusionRegistry {
     const byName = new Map<string, TransclusionDefinition>();
 
     const registry: TransclusionRegistry = {
@@ -38,6 +44,7 @@ export function createTransclusionRegistry(definitions: TransclusionDefinition[]
             checkDefinition(definition);
             byName.set(definition.name, definition);
         },
+        hints,
     };
 
     for (const definition of definitions) {
diff --git a/src/utils/transclude/transclude.test.ts b/src/utils/transclude/transclude.test.ts
index cc95e180fb..77aa390e2a 100644
--- a/src/utils/transclude/transclude.test.ts
+++ b/src/utils/transclude/transclude.test.ts
@@ -203,6 +203,12 @@ describe("registry", () => {
         expect(help).toContain("url [verify]");
         expect(help).toContain("pr-thread [verify]");
         expect(describeTransclusions(reg).find((entry) => entry.name === "lines")?.action).toBe("substitute");
+        expect(help).toContain("[verify] kinds stay live: a recheck reports whether they changed since capture.");
+
+        const hinted = formatTransclusionHelp(defaultTransclusionRegistry({ verifyRecheck: "mytool show <id>" }));
+        expect(hinted).toContain(
+            "[verify] kinds stay live: mytool show <id> reports whether they changed since capture."
+        );
     });
 });
 
@@ -366,7 +372,8 @@ describe("provenance, verify and fail-closed", () => {
                 shown: { shown: 40, total: 212, unit: "lines" },
             }),
         });
-        const result = await transclude("{{sourced n=1}}", { registry: registry(sourced), cwd: "/", now: clock });
+        const hinted = createTransclusionRegistry([sourced], { recheck: (raw) => `mytool resolve '${raw}'` });
+        const result = await transclude("{{sourced n=1}}", { registry: hinted, cwd: "/", now: clock });
         const footer = result.text.split("\n").at(-1);
         expect(footer).toBe(
             "_↳ captured 2026-09-30 17:11 UTC · a.ts@abc123 · showing 40 of 212 lines · re-check: `{{sourced n=1}}`_"
@@ -375,9 +382,12 @@ describe("provenance, verify and fail-closed", () => {
             capturedAt: "2026-09-30T17:11:00.000Z",
             source: "a.ts@abc123",
             token: "{{sourced n=1}}",
-            recheck: "tools question tokens resolve '{{sourced n=1}}'",
+            recheck: "mytool resolve '{{sourced n=1}}'",
             shown: { shown: 40, total: 212, unit: "lines" },
         });
+        const plain = await transclude("{{sourced n=1}}", { registry: registry(sourced), cwd: "/", now: clock });
+        expect(plain.text).toBe(result.text);
+        expect(plain.tokens[0].meta?.provenance).not.toHaveProperty("recheck");
         expect(result.tokens[0].action).toBe("substitute");
         expect(result.tokens[0].snapshot).toBeUndefined();
     });
diff --git a/src/utils/transclude/types.ts b/src/utils/transclude/types.ts
index e970cd8c60..2be3c6aa0c 100644
--- a/src/utils/transclude/types.ts
+++ b/src/utils/transclude/types.ts
@@ -137,6 +137,37 @@ export interface TransclusionToken {
     truncated?: boolean;
 }
 
+/** A command of the caller's own CLI that the `cmd` kind may run, matched on its leading words. */
+export interface CmdToolVerb {
+    words: readonly string[];
+    /** The only dash arguments it may take; every other one is refused. */
+    flags: readonly string[];
+}
+
+/** The caller's own read-only CLI commands for the `cmd` kind, beyond the git subcommands every copy allows. */
+export interface CmdToolsHints {
+    /** argv[0] of those commands. */
+    program: string;
+    verbs: readonly CmdToolVerb[];
+    /** Appended to the kind's list of allowed commands in its description, e.g. `, mytool show`. */
+    description: string;
+    /** A second example token that runs one of them. */
+    example: string;
+}
+
+/**
+ * What only the program that ships the CLI knows: GenesisTools passes `transclusionHints()` from
+ * `@genesiscz/utils/genesis-tools/tools/hints`. A registry without them names no command of any CLI: the grammar
+ * says how `[verify]` works in a plain sentence, a token records no `recheck` line, and `cmd` runs git only.
+ */
+export interface TransclusionHints {
+    /** The command that reports whether stored `[verify]` tokens changed, e.g. `mytool show <id> --recheck`. */
+    verifyRecheck?: string;
+    /** The shell line that re-resolves one token, stored as the token's `recheck` provenance. */
+    recheck?: (raw: string) => string;
+    cmdTools?: CmdToolsHints;
+}
+
 export interface TranscludeResult {
     text: string;
     tokens: TransclusionToken[];

From 158e428e1eaada9978d339c004ba61b8947d17a9 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 19:44:02 +0200
Subject: [PATCH 21/30] fix(tools): shared modules find their own folder and
 load sibling modules through fs/module-dir, so Vite SSR dashboards that
 import them no longer fail with HTTPError

---
 src/utils/ai/config/migration-guard.ts  |  5 +++--
 src/utils/audio/assets/manifest.ts      |  3 ++-
 src/utils/browser-extension/registry.ts |  3 ++-
 src/utils/browser-router/link-gate.ts   |  5 +++--
 src/utils/clearCache.ts                 |  3 ++-
 src/utils/cli/failures/watch.ts         |  7 ++++---
 src/utils/cli/tools.ts                  |  8 +++-----
 src/utils/fs/module-dir.ts              | 23 +++++++++++++++++++++++
 src/utils/logger/daily-trigger.ts       |  3 ++-
 src/utils/macos/notifications.ts        |  5 +++--
 src/utils/package-link.ts               |  3 ++-
 src/utils/packages.ts                   |  3 ++-
 src/utils/paths.ts                      |  3 ++-
 src/utils/services/stale.ts             |  3 ++-
 14 files changed, 55 insertions(+), 22 deletions(-)
 create mode 100644 src/utils/fs/module-dir.ts

diff --git a/src/utils/ai/config/migration-guard.ts b/src/utils/ai/config/migration-guard.ts
index f6b7f443c7..1d314a771f 100644
--- a/src/utils/ai/config/migration-guard.ts
+++ b/src/utils/ai/config/migration-guard.ts
@@ -1,4 +1,5 @@
 import { env } from "@genesiscz/utils/env";
+import { moduleDir } from "@genesiscz/utils/fs/module-dir";
 import { logger } from "@genesiscz/utils/logger";
 
 /**
@@ -23,7 +24,7 @@ const WORKTREE_MARKERS = ["/.worktrees/", "/.claude/worktrees/"];
  * innocent-looking cwd — which is exactly how the cwd-only version of this
  * guard let a worktree build migrate the real config anyway.
  */
-let codeDir = import.meta.dir;
+let codeDir = moduleDir(import.meta);
 
 export function isWorktreeCheckout(cwd: string = process.cwd()): boolean {
     return [cwd, codeDir].some((dir) => WORKTREE_MARKERS.some((marker) => dir.includes(marker)));
@@ -31,7 +32,7 @@ export function isWorktreeCheckout(cwd: string = process.cwd()): boolean {
 
 /** Test seam: fake the build location. Pass undefined to restore the real one. */
 export function _setCodeDirForTest(dir: string | undefined): void {
-    codeDir = dir ?? import.meta.dir;
+    codeDir = dir ?? moduleDir(import.meta);
 }
 
 /**
diff --git a/src/utils/audio/assets/manifest.ts b/src/utils/audio/assets/manifest.ts
index 78686667d5..016c763abf 100644
--- a/src/utils/audio/assets/manifest.ts
+++ b/src/utils/audio/assets/manifest.ts
@@ -1,6 +1,7 @@
 import { join } from "node:path";
+import { moduleDir } from "@genesiscz/utils/fs/module-dir";
 
-export const ASSETS_DIR = import.meta.dir;
+export const ASSETS_DIR = moduleDir(import.meta);
 
 /** Filenames present in this dir; keep in sync with CREDITS.md (CC0/PD only).
  *  Curated subset of Kenney "Interface Sounds" (CC0 1.0). `switch.wav` is the default. */
diff --git a/src/utils/browser-extension/registry.ts b/src/utils/browser-extension/registry.ts
index 2c9a39dee4..bfc4ad5fe2 100644
--- a/src/utils/browser-extension/registry.ts
+++ b/src/utils/browser-extension/registry.ts
@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { join } from "node:path";
+import { moduleDir } from "@genesiscz/utils/fs/module-dir";
 
 /** The checkout, which holds every extension's sources and `dist`. */
-const REPO = join(import.meta.dir, "..", "..", "..");
+const REPO = join(moduleDir(import.meta), "..", "..", "..");
 
 /**
  * An unpacked extension without a `key` gets its id from its folder: the first 32 hex digits of the
diff --git a/src/utils/browser-router/link-gate.ts b/src/utils/browser-router/link-gate.ts
index 1e70954240..e553e47e15 100644
--- a/src/utils/browser-router/link-gate.ts
+++ b/src/utils/browser-router/link-gate.ts
@@ -1,5 +1,6 @@
 import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { moduleDir, requireSibling } from "@genesiscz/utils/fs/module-dir";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { genesisToolsDir } from "@genesiscz/utils/storage/root";
 
@@ -79,10 +80,10 @@ interface RouterStatusFacts {
  * profiles behind it.
  */
 function loadRouterStatus(): () => RouterStatusFacts {
-    const loaded: unknown = require(join(import.meta.dir, "status"));
+    const loaded: unknown = requireSibling(import.meta, "status");
     const routerStatus = (loaded as { routerStatus?: unknown } | null)?.routerStatus;
     if (typeof routerStatus !== "function") {
-        throw new Error(`link gate: ${join(import.meta.dir, "status")} exports no routerStatus`);
+        throw new Error(`link gate: ${join(moduleDir(import.meta), "status")} exports no routerStatus`);
     }
 
     return routerStatus as () => RouterStatusFacts;
diff --git a/src/utils/clearCache.ts b/src/utils/clearCache.ts
index 6d20e0321e..e6ba2371f4 100644
--- a/src/utils/clearCache.ts
+++ b/src/utils/clearCache.ts
@@ -1,9 +1,10 @@
 #!/usr/bin/env bun
 import { existsSync, rmSync } from "node:fs";
 import { resolve } from "node:path";
+import { moduleDir } from "@genesiscz/utils/fs/module-dir";
 import { out } from "@genesiscz/utils/logger";
 
-const root = resolve(import.meta.dir, "../../..");
+const root = resolve(moduleDir(import.meta), "../../..");
 
 const cacheDirs = [
     resolve(root, "node_modules/.vite"),
diff --git a/src/utils/cli/failures/watch.ts b/src/utils/cli/failures/watch.ts
index dd924080ee..56872d28f5 100644
--- a/src/utils/cli/failures/watch.ts
+++ b/src/utils/cli/failures/watch.ts
@@ -1,5 +1,6 @@
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { format } from "node:util";
+import { moduleDir, requireSibling } from "@genesiscz/utils/fs/module-dir";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { logger } from "@genesiscz/utils/logger";
 import { stripAnsi } from "@genesiscz/utils/string";
@@ -8,7 +9,7 @@ import { redactSecretsInText } from "@genesiscz/utils/transclude/redact";
 import { appendFailure, type FailureCaller, type FailureKind, type ToolFailure } from "./record";
 
 const TAIL_CHARS = 4000;
-const TOOLS_ROOT = resolve(import.meta.dir, "../../../..");
+const TOOLS_ROOT = resolve(moduleDir(import.meta), "../../../..");
 const SECRET_FLAG = /^--?[\w-]*(?:token|secret|password|passwd|api[-_]?key|auth|cookie|credential)[\w-]*$/i;
 /** Commander's own refusals; each starts a stderr write with `error: `. */
 const USAGE_LINE =
@@ -219,7 +220,7 @@ function tapStderr(): void {
  * without that module records failures with no caller.
  */
 function agentCaller(): FailureCaller | null {
-    const loaded: unknown = require(join(import.meta.dir, "agent-caller"));
+    const loaded: unknown = requireSibling(import.meta, "agent-caller");
     const lookup = (loaded as { agentFailureCaller?: unknown } | null)?.agentFailureCaller;
     if (typeof lookup !== "function") {
         return null;
diff --git a/src/utils/cli/tools.ts b/src/utils/cli/tools.ts
index 06ad9bf306..0930639b44 100644
--- a/src/utils/cli/tools.ts
+++ b/src/utils/cli/tools.ts
@@ -1,6 +1,6 @@
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
 import { env } from "@genesiscz/utils/env";
+import { moduleDir } from "@genesiscz/utils/fs/module-dir";
 import { logger } from "@genesiscz/utils/logger";
 import { namedBunExecPath } from "./bun-link";
 import { DETACHED_ENV } from "./detached";
@@ -15,9 +15,7 @@ export function toolsEntrypoint(): string {
 }
 
 function getToolsPath(): string {
-    // import.meta.dir is Bun-specific; fall back to import.meta.url for Node/Vite SSR
-    const dir = typeof import.meta.dir === "string" ? import.meta.dir : dirname(fileURLToPath(import.meta.url));
-    return resolve(dir, "../../../tools");
+    return resolve(moduleDir(import.meta), "../../../tools");
 }
 
 export interface RunToolOptions {
diff --git a/src/utils/fs/module-dir.ts b/src/utils/fs/module-dir.ts
new file mode 100644
index 0000000000..c23eecaeab
--- /dev/null
+++ b/src/utils/fs/module-dir.ts
@@ -0,0 +1,23 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The folder of the module that passes its `import.meta`. Bun sets `import.meta.dir`; Vite's SSR module runner and
+ * Node do not, so a module-level `join(import.meta.dir, …)` threw there and broke every dashboard that imported it
+ * (`tools clarity ui` answered 500, 2026-10-22). `import.meta.url` is a file URL in all three.
+ */
+export function moduleDir(meta: ImportMeta): string {
+    return typeof meta.dir === "string" ? meta.dir : dirname(fileURLToPath(meta.url));
+}
+
+/**
+ * Loads a module beside the caller by a path built at run time, so neither a bundler nor the type checker follows it.
+ * Uses `require` where the runtime injects it (a Bun module) and `createRequire` elsewhere (Vite's SSR runner has no
+ * `require`). Throws like `require` when the file is missing or does not load; callers treat that as "not here".
+ */
+export function requireSibling(meta: ImportMeta, name: string): unknown {
+    const path = join(moduleDir(meta), name);
+    const load = typeof require === "function" ? require : createRequire(meta.url);
+    return load(path);
+}
diff --git a/src/utils/logger/daily-trigger.ts b/src/utils/logger/daily-trigger.ts
index bc27410646..b1f4df1373 100644
--- a/src/utils/logger/daily-trigger.ts
+++ b/src/utils/logger/daily-trigger.ts
@@ -2,9 +2,10 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { env } from "@genesiscz/utils/env";
+import { moduleDir } from "@genesiscz/utils/fs/module-dir";
 import { isTestProcess } from "@genesiscz/utils/test-process";
 
-const PASS_SCRIPT = path.join(import.meta.dir, "..", "compress", "daily-pass.ts");
+const PASS_SCRIPT = path.join(moduleDir(import.meta), "..", "compress", "daily-pass.ts");
 
 /**
  * Starts the daily compression pass (old day logs and ai-proxy transcripts become `.zst`) at most once per day per log
diff --git a/src/utils/macos/notifications.ts b/src/utils/macos/notifications.ts
index 3e391942ce..fef06bdd9a 100644
--- a/src/utils/macos/notifications.ts
+++ b/src/utils/macos/notifications.ts
@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { withTimeout } from "@genesiscz/utils/async";
+import { moduleDir, requireSibling } from "@genesiscz/utils/fs/module-dir";
 import { logger } from "@genesiscz/utils/logger";
 import { escapeJxa } from "@genesiscz/utils/macos/jxa";
 import { boundedCommand } from "@genesiscz/utils/process/bounded-command";
@@ -386,9 +387,9 @@ function appBackend(): NotificationAppBackend | null {
         return appBackendCache;
     }
 
-    const path = join(import.meta.dir, "notifications-app");
+    const path = join(moduleDir(import.meta), "notifications-app");
     try {
-        const loaded: unknown = require(path);
+        const loaded: unknown = requireSibling(import.meta, "notifications-app");
         const backend = (loaded as { appNotificationBackend?: unknown } | null)?.appNotificationBackend;
         appBackendCache = isAppBackend(backend) ? backend : null;
     } catch (error) {
diff --git a/src/utils/package-link.ts b/src/utils/package-link.ts
index 54a5f9e8a0..0ab99fcfe4 100644
--- a/src/utils/package-link.ts
+++ b/src/utils/package-link.ts
@@ -38,6 +38,7 @@
 import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, rmdirSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
+import { moduleDir } from "@genesiscz/utils/fs/module-dir";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { logger } from "@genesiscz/utils/logger";
 import { atomicWriteFileSync } from "@genesiscz/utils/storage/atomic-file";
@@ -54,7 +55,7 @@ const WILDCARD_KEY = `${PACKAGE_NAME}/*`;
  * makes the mapping point at the running checkout rather than at a path written down once.
  */
 export function utilsPackageDir(): string {
-    return import.meta.dir;
+    return moduleDir(import.meta);
 }
 
 /** `<root>/tsconfig.json` — the one file this module writes. */
diff --git a/src/utils/packages.ts b/src/utils/packages.ts
index e62141b036..d7228e2ef7 100644
--- a/src/utils/packages.ts
+++ b/src/utils/packages.ts
@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import * as p from "@clack/prompts";
 import { isInteractive } from "@genesiscz/utils/cli";
 import { env } from "@genesiscz/utils/env";
+import { moduleDir } from "@genesiscz/utils/fs/module-dir";
 import { logger } from "@genesiscz/utils/logger";
 import {
     isStorePackage,
@@ -15,7 +16,7 @@ import {
 import { withFileLock } from "@genesiscz/utils/storage/file-lock";
 import { Storage } from "@genesiscz/utils/storage/storage";
 
-const PROJECT_ROOT = resolve(import.meta.dirname, "../..");
+const PROJECT_ROOT = resolve(moduleDir(import.meta), "../..");
 
 const inflight = new Map<string, Promise<void>>();
 
diff --git a/src/utils/paths.ts b/src/utils/paths.ts
index 5019ea57ab..43d4428d4a 100644
--- a/src/utils/paths.ts
+++ b/src/utils/paths.ts
@@ -7,6 +7,7 @@
 import { mkdtempSync, realpathSync } from "node:fs";
 import { homedir, tmpdir as osTmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { moduleDir } from "@genesiscz/utils/fs/module-dir";
 import { env } from "./env.client";
 import { SafeJSON } from "./json";
 import { collapsePathForDisplay as collapsePathHeuristic } from "./paths.client";
@@ -124,7 +125,7 @@ export function canonicalPath(p: string): string {
 /**
  * Absolute path to the GenesisTools project root (where package.json lives).
  */
-export const PROJECT_ROOT = resolve(import.meta.dirname, "../..");
+export const PROJECT_ROOT = resolve(moduleDir(import.meta), "../..");
 
 /**
  * Replace the user's home directory prefix with `~`.
diff --git a/src/utils/services/stale.ts b/src/utils/services/stale.ts
index 10befb30ec..ee52a9c908 100644
--- a/src/utils/services/stale.ts
+++ b/src/utils/services/stale.ts
@@ -1,11 +1,12 @@
 import { statSync } from "node:fs";
 import { join } from "node:path";
+import { moduleDir } from "@genesiscz/utils/fs/module-dir";
 import { parseStatusPorcelainV2Z } from "@genesiscz/utils/git/porcelain";
 import { logger } from "@genesiscz/utils/logger";
 import { captureSync } from "@genesiscz/utils/process/ps";
 
 /** The checkout this code runs from; the services it lists run from the same tree. */
-export const REPO_ROOT = join(import.meta.dir, "..", "..", "..");
+export const REPO_ROOT = join(moduleDir(import.meta), "..", "..", "..");
 
 /** `src/<tool>/` from the paths in a command line (`.../GenesisTools/src/youtube/ui/vite.config.ts`), plus `src/utils/`. */
 export function sourceRoots(command: string): string[] {

From 69000114215457d8247ab2180c80b468ef0f0589 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 19:55:11 +0200
Subject: [PATCH 22/30] fix(ci): catch a dashboard that renders a server error
 at commit, launch and push time: lint-rules bans Bun-only import.meta paths
 and new bare requires, a launch reports a 5xx page with the server's error
 and exits 1, and pre-push boots the affected dashboards

---
 .claude/rules/ci.md                           |   5 +
 .claude/rules/tools.md                        |   1 +
 .githooks/pre-push                            |  16 ++
 scripts/ci/dashboard-smoke.test.ts            |  20 ++
 scripts/ci/dashboard-smoke.ts                 | 220 ++++++++++++++++++
 scripts/ci/lint-rules.test.ts                 |  52 ++++-
 scripts/ci/lint-rules.ts                      |  97 +++++++-
 src/utils/DashboardApp/lifecycle-serve.ts     |   6 +-
 src/utils/DashboardApp/lifecycle.ts           |  10 +-
 .../preview/runPreviewUiServer.ts             |   3 +-
 src/utils/DashboardApp/readiness.test.ts      |  80 ++++++-
 src/utils/DashboardApp/readiness.ts           | 143 +++++++++++-
 src/utils/e2e/helpers.ts                      |   3 +-
 13 files changed, 636 insertions(+), 20 deletions(-)
 create mode 100644 scripts/ci/dashboard-smoke.test.ts
 create mode 100644 scripts/ci/dashboard-smoke.ts

diff --git a/.claude/rules/ci.md b/.claude/rules/ci.md
index a7ac36dea5..4c42571f8e 100644
--- a/.claude/rules/ci.md
+++ b/.claude/rules/ci.md
@@ -15,4 +15,9 @@ Loaded by Claude Code when you read, write or edit a file under `.github/`, `scr
   - Use `git grep -P` in anything CI runs, never `rg`. Git is always present and searches tracked files only.
 - **Lint the diff, not the tree, and not with `biome --changed`.** Under CI's depth-1 checkout it finds zero files, and biome exits 1 on "No files were processed". `scripts/ci/lint-changed.sh` passes `git diff --name-only --diff-filter=ACMR <base> HEAD` to biome with an `[ -f ]` test per path. The base is `github.event.pull_request.base.sha`, which already is the merge base, so no history fetch is needed.
 - **Git runs the `.githooks/` scripts as config hooks** (`hook.genesis-tools-<name>`, through `/bin/sh -c`), set by `scripts/git/install-hooks.ts` from package.json `prepare`, never through `core.hooksPath`. Git executes a hook-folder file directly, macOS checks the first execution of every new file in syspolicyd, and a worktree's hooks are new files: on 2026-10-14 a stuck syspolicyd froze every such first execution at `_dyld_start`, and a rebase hung 41 minutes. A config hook runs only while `core.hooksPath` is unset, so `git -c core.hooksPath=/dev/null …` still turns every hook off. A new hook needs a `#!` line (its interpreter becomes the command) and one `bun install`. Check what runs with `git hook list <event>`.
+- **A dashboard that does not render fails the push.** `scripts/ci/dashboard-smoke.ts` boots each Vite dashboard a
+  push can reach (all of them when `src/utils/` changes) and fetches `/`; a 5xx or no answer fails it with the
+  server's own error from its log. Pre-push runs it after the typecheck, about 5 s for all eight. CI does not: the
+  dashboards read this Mac's config. It exists because `tools clarity ui` answered 500 for a day (2026-10-22) while
+  tsc, the tests and its own launch passed; a launch now also reports a 5xx page and exits 1 (`reportBrokenDashboard`).
 - **`lint-rules.ts` and `placeholder-check.sh` scan tracked files only** (`git ls-files`). Run them after the last commit, or after `git add` of every new file. A run before staging proves nothing about a new file.
diff --git a/.claude/rules/tools.md b/.claude/rules/tools.md
index fccd95fc2f..29c6cd3787 100644
--- a/.claude/rules/tools.md
+++ b/.claude/rules/tools.md
@@ -27,6 +27,7 @@ When creating a new tool and writing helper functions, check if the utility is *
 - `src/utils/string.ts` - String utilities (glob matching, ANSI stripping)
 - `src/utils/cli/executor.ts` - CLI helpers: `suggestCommand()`, `isInteractive()`, `buildCommand()`, `Executor`, `enhanceHelp()`
 - `src/utils/storage/storage.ts` - Config & cache management
+- `src/utils/fs/module-dir.ts` - `moduleDir(import.meta)` (this module's folder) and `requireSibling(import.meta, name)` (a lazy load beside it). Bun-only `import.meta.dir`/`.dirname` and a bare `require()` break every Vite dashboard that loads the module; lint-rules `no-bun-only-import-meta` and `no-bare-require-in-utils` fail them
 - `src/utils/storage/root.ts` - `toolDataDir(tool, ...)` / `genesisToolsDir(...)`: every `~/.genesis-tools/...` path (honours `GENESIS_TOOLS_HOME`, no logger import); `genesisToolsDirIn(home, ...)` for an explicit sandbox or fixture home. Never hand-join any home with `".genesis-tools"`: lint-rules `no-hand-joined-genesis-tools` fails it outside tests and `plugins/**`
 - `src/utils/async.ts` - Async helpers (concurrency, retry, etc.)
 - `src/utils/json-schema.ts` - JSON schema inference: `inferSchema()`, `formatSchema(value, "skeleton"|"typescript"|"schema")`
diff --git a/.githooks/pre-push b/.githooks/pre-push
index 5753d424ca..9a03df2101 100755
--- a/.githooks/pre-push
+++ b/.githooks/pre-push
@@ -89,6 +89,22 @@ if ! bun run typecheck; then
 fi
 stage_done
 
+# Every Vite dashboard this push can reach boots its dev server and must render `/` (scripts/ci/dashboard-smoke.ts,
+# about 5 s for all eight). `tools clarity ui` answered 500 on every page for a day (2026-10-22) while tsc, the tests
+# and its own launch all passed. Shared code (src/utils) reaches every dashboard.
+echo "▶ dashboard smoke..."
+if [ -n "$range_base" ]; then
+    smoke_args="--base $range_base --head $local_sha"
+else
+    smoke_args=""
+fi
+# shellcheck disable=SC2086 # two refs, split on purpose
+if ! bun scripts/ci/dashboard-smoke.ts $smoke_args; then
+    echo "✖ a dashboard does not render: push refused. The lines above name its server error and log."
+    exit 1
+fi
+stage_done
+
 # The repo guards from the CI "checks" job (ci.yml, after the TypeScript check). They used to run on
 # CI only, so a pid probe or a hard-coded command name reached every PR of a stack before anything
 # said so (2026-10-09). They run in parallel: about 13 s, the time of check-tool-commands alone.
diff --git a/scripts/ci/dashboard-smoke.test.ts b/scripts/ci/dashboard-smoke.test.ts
new file mode 100644
index 0000000000..fcb196425f
--- /dev/null
+++ b/scripts/ci/dashboard-smoke.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { affectedDashboards, SMOKE_DASHBOARDS } from "./dashboard-smoke";
+
+describe("dashboard-smoke", () => {
+    test("shared code and package files reach every dashboard; a dashboard's own folder reaches only it", () => {
+        const all = SMOKE_DASHBOARDS.map((dashboard) => dashboard.name);
+        const names = (changed: string[]) => affectedDashboards(changed).map((dashboard) => dashboard.name);
+
+        expect(names(["src/utils/logger/daily-trigger.ts"])).toEqual(all);
+        expect(names(["bun.lock"])).toEqual(all);
+        expect(names(["src/clarity/ui/src/routes/index.tsx"])).toEqual(["clarity"]);
+        expect(names(["src/du/index.ts", "README.md"])).toEqual([]);
+        expect(names(["src/youtube/extension/manifest.json"])).toEqual([]);
+    });
+
+    test("every listed dashboard has its Vite config", () => {
+        expect(SMOKE_DASHBOARDS.filter((dashboard) => !existsSync(dashboard.config))).toEqual([]);
+    });
+});
diff --git a/scripts/ci/dashboard-smoke.ts b/scripts/ci/dashboard-smoke.ts
new file mode 100644
index 0000000000..ad74dd775d
--- /dev/null
+++ b/scripts/ci/dashboard-smoke.ts
@@ -0,0 +1,220 @@
+#!/usr/bin/env bun
+/**
+ * Boots every Vite dashboard's dev server on a free port and fetches `/`. A dashboard whose page answers a server
+ * error, or that never answers, fails the run, with the server's own error from its log.
+ *
+ * Why: `tools clarity ui` answered 500 on every page for a day (2026-10-22) because a shared module used Bun's
+ * `import.meta.dir` at load time, which Vite's SSR runner does not set. tsc, the tests and the launch's readiness check
+ * all passed. lint-rules `no-bun-only-import-meta` now stops that one cause; this run catches any other way a
+ * dashboard's server stops rendering.
+ *
+ *   bun scripts/ci/dashboard-smoke.ts                       every dashboard
+ *   bun scripts/ci/dashboard-smoke.ts --only clarity,shops  these
+ *   bun scripts/ci/dashboard-smoke.ts --base <ref> [--head <ref>]
+ *                                                           only the dashboards that a change between the refs can
+ *                                                           reach (shared code and package files reach all of them)
+ */
+import { spawnSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { serverErrorExcerpt, waitForUrlReady } from "@genesiscz/utils/DashboardApp/readiness";
+import { isPortInUse } from "@genesiscz/utils/network";
+
+export interface SmokeDashboard {
+    name: string;
+    /** The Vite config, from the repository root. */
+    config: string;
+    /** Files under this folder reach only this dashboard. */
+    folder: string;
+}
+
+export const SMOKE_DASHBOARDS: SmokeDashboard[] = [
+    { name: "clarity", config: "src/clarity/ui/vite.config.ts", folder: "src/clarity/" },
+    {
+        name: "claude-history",
+        config: "src/claude-history-dashboard/vite.config.ts",
+        folder: "src/claude-history-dashboard/",
+    },
+    {
+        name: "debugging-master",
+        config: "src/debugging-master/dashboard/vite.config.ts",
+        folder: "src/debugging-master/",
+    },
+    { name: "dev-dashboard", config: "src/dev-dashboard/ui/vite.config.ts", folder: "src/dev-dashboard/" },
+    { name: "monitor", config: "src/monitor/ui/vite.config.ts", folder: "src/monitor/" },
+    { name: "shops", config: "src/shops/ui/vite.config.ts", folder: "src/shops/" },
+    { name: "spotify", config: "src/spotify/ui/vite.config.ts", folder: "src/spotify/" },
+    { name: "youtube", config: "src/youtube/ui/vite.config.ts", folder: "src/youtube/ui/" },
+];
+
+/** Changes that every dashboard's server can load: the shared modules, the shared UI and the dependency set. */
+const REACHES_ALL = /^(?:src\/utils\/|src\/dashboard\/|package\.json$|bun\.lock$|tsconfig[\w.-]*\.json$|bunfig\.toml$)/;
+const PARALLEL = 3;
+const READY_TIMEOUT_MS = 90_000;
+const BROKEN_GRACE_MS = 3_000;
+const FIRST_PORT = 39_300;
+
+/** The dashboards a set of changed files can reach. */
+export function affectedDashboards(
+    changed: string[],
+    dashboards: SmokeDashboard[] = SMOKE_DASHBOARDS
+): SmokeDashboard[] {
+    if (changed.some((file) => REACHES_ALL.test(file))) {
+        return dashboards;
+    }
+
+    return dashboards.filter((dashboard) => changed.some((file) => file.startsWith(dashboard.folder)));
+}
+
+interface SmokeResult {
+    name: string;
+    ok: boolean;
+    seconds: number;
+    detail: string;
+    excerpt: string[];
+    log: string;
+}
+
+async function freePort(taken: Set<number>): Promise<number> {
+    for (let port = FIRST_PORT; port < FIRST_PORT + 500; port++) {
+        if (!taken.has(port) && !(await isPortInUse(port))) {
+            taken.add(port);
+            return port;
+        }
+    }
+
+    throw new Error(`no free port from ${FIRST_PORT}`);
+}
+
+async function smoke(dashboard: SmokeDashboard, port: number, logDir: string): Promise<SmokeResult> {
+    const started = performance.now();
+    const log = join(logDir, `${dashboard.name}.log`);
+    const vite = resolve("node_modules/vite/bin/vite.js");
+    // One descriptor for both streams: Vite prints a server-side render error on stderr.
+    const logFd = openSync(log, "a");
+    const child = Bun.spawn(
+        [
+            "bun",
+            "--bun",
+            vite,
+            "dev",
+            "-c",
+            dashboard.config,
+            "--host",
+            "127.0.0.1",
+            "--port",
+            String(port),
+            "--strictPort",
+        ],
+        { stdout: logFd, stderr: logFd, stdin: "ignore", env: { ...process.env, BROWSER: "none" } }
+    );
+    closeSync(logFd);
+    const exited = new AbortController();
+    child.exited.then((code) => exited.abort(new Error(`vite exited with code ${code} before it answered`)));
+
+    try {
+        const result = await waitForUrlReady(`http://127.0.0.1:${port}/`, READY_TIMEOUT_MS, {
+            signal: exited.signal,
+            brokenGraceMs: BROKEN_GRACE_MS,
+        });
+        const seconds = (performance.now() - started) / 1000;
+
+        if (result.broken) {
+            return {
+                name: dashboard.name,
+                ok: false,
+                seconds,
+                detail: `/ answers ${result.broken.status}: ${result.broken.body}`,
+                excerpt: serverErrorExcerpt(log),
+                log,
+            };
+        }
+
+        if (!result.ready) {
+            return {
+                name: dashboard.name,
+                ok: false,
+                seconds,
+                detail: result.detail ?? "no answer",
+                excerpt: serverErrorExcerpt(log),
+                log,
+            };
+        }
+
+        return { name: dashboard.name, ok: true, seconds, detail: result.detail ?? "ready", excerpt: [], log };
+    } finally {
+        child.kill("SIGTERM");
+        const stopped = await Promise.race([child.exited.then(() => true), Bun.sleep(5_000).then(() => false)]);
+
+        if (!stopped) {
+            child.kill("SIGKILL");
+        }
+    }
+}
+
+function changedFiles(base: string, head: string): string[] {
+    const diff = spawnSync("git", ["diff", "--name-only", base, head], { encoding: "utf8" });
+
+    if (diff.status !== 0) {
+        throw new Error(`git diff ${base} ${head} failed: ${diff.stderr.trim()}`);
+    }
+
+    return diff.stdout.split("\n").filter(Boolean);
+}
+
+function option(args: string[], name: string): string | undefined {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+
+async function main(args: string[]): Promise<number> {
+    const only = option(args, "--only")?.split(",");
+    const base = option(args, "--base");
+    let chosen = SMOKE_DASHBOARDS.filter((dashboard) => existsSync(dashboard.config));
+
+    if (only) {
+        chosen = chosen.filter((dashboard) => only.includes(dashboard.name));
+    } else if (base) {
+        chosen = affectedDashboards(changedFiles(base, option(args, "--head") ?? "HEAD"), chosen);
+    }
+
+    if (chosen.length === 0) {
+        console.log("dashboard-smoke: no dashboard is affected");
+        return 0;
+    }
+
+    const logDir = join(tmpdir(), `dashboard-smoke-${process.pid}`);
+    mkdirSync(logDir, { recursive: true });
+    const taken = new Set<number>();
+    const queue = [...chosen];
+    const results: SmokeResult[] = [];
+    const workers = Array.from({ length: Math.min(PARALLEL, queue.length) }, async () => {
+        for (let next = queue.shift(); next; next = queue.shift()) {
+            const result = await smoke(next, await freePort(taken), logDir);
+            results.push(result);
+            const mark = result.ok ? "✓" : "✗";
+            console.log(`${mark} ${result.name} (${result.seconds.toFixed(1)}s): ${result.detail}`);
+            for (const line of result.excerpt) {
+                console.log(`    ${line}`);
+            }
+
+            if (!result.ok) {
+                console.log(`    log: ${result.log}`);
+            }
+        }
+    });
+    await Promise.all(workers);
+
+    const failed = results.filter((result) => !result.ok);
+    console.log(
+        failed.length === 0
+            ? `dashboard-smoke: ${results.length} dashboard(s) render`
+            : `dashboard-smoke: ${failed.length} of ${results.length} dashboard(s) do not render: ${failed.map((r) => r.name).join(", ")}`
+    );
+    return failed.length === 0 ? 0 : 1;
+}
+
+if (import.meta.main) {
+    process.exit(await main(Bun.argv.slice(2)));
+}
diff --git a/scripts/ci/lint-rules.test.ts b/scripts/ci/lint-rules.test.ts
index 987ce18161..0bd130d603 100644
--- a/scripts/ci/lint-rules.test.ts
+++ b/scripts/ci/lint-rules.test.ts
@@ -5,7 +5,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { Lang, parse } from "@ast-grep/napi";
 import { keptExecutable } from "@genesiscz/utils/test/kept-executable";
-import { checkSource, namesToolCommand, pluginsDisabledFor } from "./lint-rules";
+import { BARE_REQUIRE_RATCHET, checkSource, namesToolCommand, pluginsDisabledFor } from "./lint-rules";
 import { TOOL_COMMAND_RATCHET } from "./tool-command-ratchet";
 
 /**
@@ -431,3 +431,53 @@ describe("no-tool-command-in-utils", () => {
         expect(stale).toEqual([]);
     });
 });
+
+describe("no-bun-only-import-meta", () => {
+    const rule = "no-bun-only-import-meta";
+
+    test("flags the line that broke tools clarity ui, and every Bun-only member, in shared and dashboard code", () => {
+        const broke = 'const PASS_SCRIPT = path.join(import.meta.dir, "..", "compress", "daily-pass.ts");';
+        expect(rules(broke, "src/utils/logger/daily-trigger.ts")).toContain(rule);
+        for (const member of ["dir", "dirname", "filename", "path"]) {
+            expect(rules(`const a = import.meta.${member};`, "src/clarity/ui/src/server.ts")).toContain(rule);
+        }
+    });
+
+    test("passes module-dir.ts, tests, vite configs, import.meta.url and code no dashboard loads", () => {
+        expect(rules("const a = import.meta.dir;", "src/utils/fs/module-dir.ts")).not.toContain(rule);
+        expect(rules("const a = import.meta.dir;", "src/utils/x/a.test.ts")).not.toContain(rule);
+        expect(rules("const a = import.meta.dirname;", "src/monitor/ui/vite.config.ts")).not.toContain(rule);
+        expect(rules("const a = import.meta.url;", "src/utils/x/a.ts")).not.toContain(rule);
+        expect(rules("const a = import.meta.dir;", "src/du/index.ts")).not.toContain(rule);
+    });
+});
+
+describe("no-bare-require-in-utils", () => {
+    const rule = "no-bare-require-in-utils";
+
+    test("flags a bare require under src/utils, and passes createRequire, member calls and other folders", () => {
+        expect(rules('function f() { return require("./x"); }', "src/utils/x/a.ts")).toContain(rule);
+        expect(rules('const load = createRequire(import.meta.url); load("./x");', "src/utils/x/a.ts")).not.toContain(
+            rule
+        );
+        expect(rules('const r = module.require("./x");', "src/utils/x/a.ts")).not.toContain(rule);
+        expect(rules('const r = require("./x");', "src/du/index.ts")).not.toContain(rule);
+    });
+
+    test("every ratchet entry still calls require, so a migrated file leaves the list", async () => {
+        const stale: string[] = [];
+
+        for (const file of BARE_REQUIRE_RATCHET) {
+            const root = parse(Lang.TypeScript, await Bun.file(file).text()).root();
+            const calls = root.findAll({
+                rule: { kind: "call_expression", has: { field: "function", regex: "^require$" } },
+            });
+
+            if (calls.length === 0) {
+                stale.push(file);
+            }
+        }
+
+        expect(stale).toEqual([]);
+    });
+});
diff --git a/scripts/ci/lint-rules.ts b/scripts/ci/lint-rules.ts
index 5da3c0c8b8..9fcf87e784 100644
--- a/scripts/ci/lint-rules.ts
+++ b/scripts/ci/lint-rules.ts
@@ -33,7 +33,7 @@
 
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
-import { findInFiles, Lang, parse, type SgNode } from "@ast-grep/napi";
+import { findInFiles, Lang, type NapiConfig, parse, type SgNode } from "@ast-grep/napi";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { TOOL_COMMAND_RATCHET } from "./tool-command-ratchet";
 
@@ -55,6 +55,11 @@ interface Rule {
     message: string;
     /** Node kinds this rule inspects. Cheaper than walking the whole tree per rule. */
     kinds: string[];
+    /**
+     * The rule's own ast-grep matcher, for a rule that is not about string literals. Without one the rule rides the
+     * shared literal walk, which visits only `string` and `template_string` nodes.
+     */
+    matcher?: NapiConfig;
     /** Given the node's source text (and the node, for a rule that needs its parent), does it violate? */
     test: (text: string, node: SgNode) => boolean;
     /** Files where the pattern is the implementation, not a violation. */
@@ -152,6 +157,24 @@ export function namesToolCommand(text: string, node: SgNode): boolean {
     );
 }
 
+/** `import.meta` members only Bun sets; Vite's SSR runner and Node leave them undefined. */
+const BUN_ONLY_IMPORT_META = /^import\.meta\.(?:dir|dirname|filename|path)$/;
+/** Code a Vite dashboard can load server-side: the shared utils and the dashboards' own sources. */
+const SSR_REACHABLE = /(?:^|\/)src\/(?:utils\/|[^/]+\/ui\/|dashboard\/)/;
+/**
+ * Files under src/utils that still call a bare `require()`, each inside a function (a lazy load), counted 2026-10-22
+ * when lint-rules `no-bare-require-in-utils` was added. A ratchet: no file joins, and lint-rules.test.ts fails when a
+ * listed file no longer calls it.
+ */
+export const BARE_REQUIRE_RATCHET: ReadonlySet<string> = new Set<string>([
+    "src/utils/ai/local/runtimes/sherpa/diarize.ts",
+    "src/utils/browser-router/link-gate.ts",
+    "src/utils/date.ts",
+    "src/utils/search/drivers/sqlite-fts5/index.ts",
+    "src/utils/search/stores/sqlite-vec-loader.ts",
+    "src/utils/tokens.ts",
+]);
+
 const RULES: Rule[] = [
     {
         ...STORAGE_ROOT_RULE,
@@ -204,6 +227,34 @@ const RULES: Rule[] = [
         allowedIn: /(^|\/)src\/utils\/genesis-tools\/tools\/hints\.ts$/,
         allowedFiles: TOOL_COMMAND_RATCHET,
     },
+    {
+        name: "no-bun-only-import-meta",
+        severity: "error",
+        kinds: ["member_expression"],
+        matcher: { rule: { kind: "member_expression", regex: "^import\\.meta\\.(?:dir|dirname|filename|path)$" } },
+        message:
+            "`import.meta.dir`, `.dirname`, `.filename` and `.path` exist only in Bun. Vite's SSR runner loads these " +
+            "modules into every dashboard without them, and a module-level use broke `tools clarity ui` with a 500 " +
+            "(2026-10-22). Use `moduleDir(import.meta)` or `requireSibling(import.meta, name)` from " +
+            "@genesiscz/utils/fs/module-dir.",
+        test: (text) => BUN_ONLY_IMPORT_META.test(text),
+        onlyIn: SSR_REACHABLE,
+        allowedIn: /(?:^|\/)src\/utils\/fs\/module-dir\.ts$|\.test\.tsx?$|(?:^|\/)vite\.config\.ts$/,
+    },
+    {
+        name: "no-bare-require-in-utils",
+        severity: "error",
+        kinds: ["call_expression"],
+        matcher: { rule: { kind: "call_expression", has: { field: "function", regex: "^require$" } } },
+        message:
+            "A bare `require()` throws a ReferenceError under Vite's SSR runner, which has no `require`. Use a static " +
+            "import, or `requireSibling(import.meta, name)` / `createRequire(import.meta.url)` for a lazy load. " +
+            "BARE_REQUIRE_RATCHET lists the files not migrated yet.",
+        test: (_text, node) => node.field("function")?.text() === "require",
+        onlyIn: /(?:^|\/)src\/utils\//,
+        allowedIn: /\.test\.tsx?$|(?:^|\/)src\/utils\/test\//,
+        allowedFiles: BARE_REQUIRE_RATCHET,
+    },
 ];
 
 const PROMPT_BACKEND_RULE = {
@@ -831,7 +882,19 @@ export function checkSource(file: string, source: string): Finding[] {
         const text = node.text();
 
         for (const rule of RULES) {
-            if (ruleApplies(rule, file) && rule.test(text, node)) {
+            if (!rule.matcher && ruleApplies(rule, file) && rule.test(text, node)) {
+                record(node, rule);
+            }
+        }
+    }
+
+    for (const rule of RULES) {
+        if (!rule.matcher || !ruleApplies(rule, file)) {
+            continue;
+        }
+
+        for (const node of root.findAll(rule.matcher)) {
+            if (rule.test(node.text(), node)) {
                 record(node, rule);
             }
         }
@@ -1050,13 +1113,39 @@ async function scanAll(files: string[], options: { processToolOnly?: boolean } =
                         const text = node.text();
 
                         for (const rule of RULES) {
-                            if (ruleApplies(rule, node.getRoot().filename()) && rule.test(text, node)) {
+                            if (
+                                !rule.matcher &&
+                                ruleApplies(rule, node.getRoot().filename()) &&
+                                rule.test(text, node)
+                            ) {
                                 push(node, rule);
                             }
                         }
                     }
                 })
             ),
+            ...RULES.flatMap((rule) => {
+                const matcher = rule.matcher;
+                const scoped = paths.filter((path) => ruleApplies(rule, path));
+
+                if (!matcher || scoped.length === 0) {
+                    return [];
+                }
+
+                return [
+                    findInFiles(
+                        lang,
+                        { paths: scoped, matcher },
+                        guard((nodes) => {
+                            for (const node of nodes) {
+                                if (rule.test(node.text(), node)) {
+                                    push(node, rule);
+                                }
+                            }
+                        })
+                    ),
+                ];
+            }),
             findInFiles(
                 lang,
                 { paths, matcher: INTERVAL_CALL_MATCHER },
@@ -1175,7 +1264,7 @@ if (import.meta.main) {
     const timing = `boot ${boot}ms, list ${listed - started}ms, scan ${scanned - listed}ms`;
 
     if (findings.length === 0) {
-        console.log(`lint-rules: OK (${files.length} files, 12 repo rules) [${timing}]`);
+        console.log(`lint-rules: OK (${files.length} files, 14 repo rules) [${timing}]`);
     } else {
         console.log(`\nlint-rules: ${errors} error(s), ${warnings} warning(s) across ${files.length} files`);
     }
diff --git a/src/utils/DashboardApp/lifecycle-serve.ts b/src/utils/DashboardApp/lifecycle-serve.ts
index 95198f7d73..dc3d165eaf 100644
--- a/src/utils/DashboardApp/lifecycle-serve.ts
+++ b/src/utils/DashboardApp/lifecycle-serve.ts
@@ -11,7 +11,7 @@ import type { LifecycleContext } from "./lifecycle";
 import { clearPid, writePid } from "./pidFile";
 import { waitForPortFree } from "./portConflict";
 import { readPreferences, writePreferences } from "./preferences";
-import { waitForReady } from "./readiness";
+import { reportBrokenDashboard, waitForReady } from "./readiness";
 import type { DashboardAppConfig, DownOptions, DownResult, StatusResult, UpOptions, UpResult } from "./types";
 
 export function resolveSpawnCmd(config: DashboardAppConfig, opts: UpOptions = {}): string[] {
@@ -100,7 +100,9 @@ export async function runDev(input: {
             await startLaunchd(ctx.plistLabel);
             const ok = await waitForReady(config.readiness, { port, logFile: ctx.logFile });
 
-            if (ok.ready) {
+            if (ok.broken) {
+                reportBrokenDashboard(config, ok.broken, ctx.logFile);
+            } else if (ok.ready) {
                 out.log.success(`${config.name ?? config.key} back on http://localhost:${port} · launchd`);
             } else {
                 out.warn(
diff --git a/src/utils/DashboardApp/lifecycle.ts b/src/utils/DashboardApp/lifecycle.ts
index af0e5f788d..87eec83bb5 100644
--- a/src/utils/DashboardApp/lifecycle.ts
+++ b/src/utils/DashboardApp/lifecycle.ts
@@ -63,7 +63,7 @@ import {
 } from "./pidFile";
 import { checkPortConflict, killPortOwner, waitForPortFree } from "./portConflict";
 import { readPreferences, writePreferences } from "./preferences";
-import { waitForReady, waitForUrlReady } from "./readiness";
+import { reportBrokenDashboard, waitForReady, waitForUrlReady } from "./readiness";
 import type {
     DashboardAppConfig,
     DependencyStatus,
@@ -189,7 +189,9 @@ export async function up(ctx: LifecycleContext, opts: UpOptions = {}): Promise<U
         return { started: false, port, mode, pid, logPath: ctx.logFile };
     }
 
-    if (!readiness.ready) {
+    if (readiness.broken) {
+        reportBrokenDashboard(config, readiness.broken, ctx.logFile, pid);
+    } else if (!readiness.ready) {
         out.warn(
             `Readiness check failed: ${readiness.detail ?? "(no detail)"}\n  Started anyway — tail the log: tools ${config.key} ${config.commandName} attach`
         );
@@ -366,7 +368,9 @@ async function finishLaunchdStart(ctx: LifecycleContext, port: number, opts: UpO
         writePid(config.key, owner.pid);
     }
 
-    if (ok.ready) {
+    if (ok.broken) {
+        reportBrokenDashboard(config, ok.broken, ctx.logFile, pid);
+    } else if (ok.ready) {
         out.log.success(
             `${config.name ?? config.key} ready on http://localhost:${port}${pid ? ` (pid ${pid})` : ""} · launchd\n  logs → ${ctx.logFile}`
         );
diff --git a/src/utils/DashboardApp/preview/runPreviewUiServer.ts b/src/utils/DashboardApp/preview/runPreviewUiServer.ts
index 8a4f1058de..44a0663882 100644
--- a/src/utils/DashboardApp/preview/runPreviewUiServer.ts
+++ b/src/utils/DashboardApp/preview/runPreviewUiServer.ts
@@ -1,5 +1,6 @@
 import { resolve } from "node:path";
 import { env } from "@genesiscz/utils/env";
+import { moduleDir } from "@genesiscz/utils/fs/module-dir";
 import { logger, out } from "@genesiscz/utils/logger";
 import { PROJECT_ROOT } from "@genesiscz/utils/paths";
 import type { RolldownWatcher } from "rolldown";
@@ -26,7 +27,7 @@ function resolveBindHost(opts: DashboardPreviewUiOptions): DashboardBindHost {
     return DEFAULT_BIND_HOST;
 }
 
-const BUILD_ONCE_ENTRY = resolve(import.meta.dirname, "buildOnce.ts");
+const BUILD_ONCE_ENTRY = resolve(moduleDir(import.meta), "buildOnce.ts");
 
 /**
  * The one-off build of the static mode runs in a child, so its working set never lands in the
diff --git a/src/utils/DashboardApp/readiness.test.ts b/src/utils/DashboardApp/readiness.test.ts
index 9d12f87f69..1661046155 100644
--- a/src/utils/DashboardApp/readiness.test.ts
+++ b/src/utils/DashboardApp/readiness.test.ts
@@ -1,8 +1,9 @@
 import { describe, expect, test } from "bun:test";
+import { rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { spawnDetached } from "./detach";
-import { isHttpServingStatus, waitForReady } from "./readiness";
+import { isHttpServingStatus, serverErrorExcerpt, waitForReady, waitForUrlReady } from "./readiness";
 
 describe("isHttpServingStatus", () => {
     test("accepts 2xx–4xx", () => {
@@ -58,3 +59,80 @@ describe("waitForReady with a detached child", () => {
         }
     });
 });
+
+describe("a server that answers with an error", () => {
+    test("a page that keeps answering 500 is reported broken, with the body", async () => {
+        const server = Bun.serve({
+            port: 0,
+            fetch: () => Response.json({ status: 500, unhandled: true, message: "HTTPError" }, { status: 500 }),
+        });
+        try {
+            const url = `http://127.0.0.1:${server.port}/`;
+            const result = await waitForUrlReady(url, 5_000, { brokenGraceMs: 0 });
+            expect(result.ready).toBe(true);
+            expect(result.broken?.status).toBe(500);
+            expect(result.broken?.body).toContain("HTTPError");
+        } finally {
+            server.stop(true);
+        }
+    });
+
+    test("a first 500 that turns into a 200 is ready and not broken", async () => {
+        let calls = 0;
+        const server = Bun.serve({
+            port: 0,
+            fetch: () => (calls++ === 0 ? new Response("warming up", { status: 500 }) : new Response("ok")),
+        });
+        try {
+            const result = await waitForUrlReady(`http://127.0.0.1:${server.port}/`, 5_000, { brokenGraceMs: 2_000 });
+            expect(result.ready).toBe(true);
+            expect(result.broken).toBeUndefined();
+        } finally {
+            server.stop(true);
+        }
+    });
+
+    test("the server's error and the top of its stack come from the log, ANSI stripped", () => {
+        const logFile = join(tmpdir(), `readiness-excerpt-${process.pid}-${Date.now()}.log`);
+        writeFileSync(
+            logFile,
+            [
+                "  VITE v7 ready in 812 ms",
+                '\u001b[31mTypeError\u001b[39m: The "paths[0]" property must be of type string, got undefined',
+                "    at join (node:path:1:1)",
+                "    at /repo/src/utils/logger/daily-trigger.ts:15:55",
+                "12:00:01 [vite] page reload",
+            ].join("\n")
+        );
+        try {
+            expect(serverErrorExcerpt(logFile)).toEqual([
+                'TypeError: The "paths[0]" property must be of type string, got undefined',
+                "at join (node:path:1:1)",
+                "at /repo/src/utils/logger/daily-trigger.ts:15:55",
+            ]);
+            expect(serverErrorExcerpt(join(tmpdir(), "no-such-dashboard.log"))).toEqual([]);
+            // Bun's own shape, from the real clarity log: header, properties, blank line, stack, then the code frame.
+            writeFileSync(
+                logFile,
+                [
+                    "17 | export function startDailyCompressionOnce(logDir: string, today: string): boolean {",
+                    "     ^",
+                    'TypeError: The "paths[0]" property must be of type string, got undefined',
+                    ' code: "ERR_INVALID_ARG_TYPE"',
+                    "",
+                    "      at join (unknown:1:1)",
+                    "      at anonymous (/repo/src/utils/logger/daily-trigger.ts:17:55)",
+                    "",
+                ].join("\n")
+            );
+            expect(serverErrorExcerpt(logFile)).toEqual([
+                'TypeError: The "paths[0]" property must be of type string, got undefined',
+                'code: "ERR_INVALID_ARG_TYPE"',
+                "at join (unknown:1:1)",
+                "at anonymous (/repo/src/utils/logger/daily-trigger.ts:17:55)",
+            ]);
+        } finally {
+            rmSync(logFile, { force: true });
+        }
+    });
+});
diff --git a/src/utils/DashboardApp/readiness.ts b/src/utils/DashboardApp/readiness.ts
index 3cbee22733..f7ab4594ec 100644
--- a/src/utils/DashboardApp/readiness.ts
+++ b/src/utils/DashboardApp/readiness.ts
@@ -4,7 +4,8 @@
  * Three probe kinds match the `ReadinessProbe` union in `types.ts`:
  *  - **http** — fetch(`http://localhost:<port><path>`) until a serving response
  *    (2xx–4xx; 502/503/504 gateway statuses keep polling — front-proxy can bind
- *    before Vite/ttyd upstream is up).
+ *    before Vite/ttyd upstream is up). Any other 5xx is a server that answers but
+ *    fails: it is polled for `BROKEN_GRACE_MS` more, then reported `broken`.
  *  - **log** — tail the bg log until the regex matches.
  *  - **port** — wait for the TCP port to bind (simplest, used as fallback).
  *
@@ -16,25 +17,40 @@
  * child exits, so a crashed server is reported at once, not after the deadline.
  */
 import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
-import { logger } from "@genesiscz/utils/logger";
+import { logger, out } from "@genesiscz/utils/logger";
 import { isPortInUse } from "@genesiscz/utils/network";
 import { stripAnsi } from "@genesiscz/utils/string";
-import type { ReadinessProbe } from "./types";
+import type { DashboardAppConfig, ReadinessProbe } from "./types";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const POLL_INTERVAL_MS = 250;
 
 /** Gateway statuses: TCP listener is up but upstream is not serving yet. */
 const GATEWAY_UNAVAILABLE = new Set([502, 503, 504]);
+/**
+ * How long a server that answers 500 keeps being polled before it counts as broken. A Vite dashboard can fail its very
+ * first request while it optimizes dependencies; a module that throws at load time fails every request after that.
+ */
+const BROKEN_GRACE_MS = 5_000;
 
 export function isHttpServingStatus(status: number): boolean {
     return status > 0 && !GATEWAY_UNAVAILABLE.has(status);
 }
 
+/** A 5xx that is not a gateway status: the app itself answered with an error. */
+export function isHttpBrokenStatus(status: number): boolean {
+    return status >= 500 && !GATEWAY_UNAVAILABLE.has(status);
+}
+
 export interface ReadinessResult {
     ready: boolean;
     /** What we observed last (helpful when ready:false). */
     detail?: string;
+    /**
+     * The server answers, but with an error (`tools clarity ui` answered 500 on every page while its launch printed
+     * "ready", 2026-10-22). `ready` stays true, so callers that only need a listener keep working; a launch reports it.
+     */
+    broken?: { url: string; status: number; body: string };
 }
 
 export async function waitForReady(
@@ -92,12 +108,13 @@ async function waitForHttp(
 export async function waitForUrlReady(
     url: string,
     timeoutMs = DEFAULT_TIMEOUT_MS,
-    options: { signal?: AbortSignal } = {}
+    options: { signal?: AbortSignal; brokenGraceMs?: number } = {}
 ): Promise<ReadinessResult> {
-    const { signal } = options;
+    const { signal, brokenGraceMs = BROKEN_GRACE_MS } = options;
     const deadline = Date.now() + timeoutMs;
     let lastStatus: number | undefined;
     let lastError: unknown;
+    let broken: { since: number; status: number; body: string } | undefined;
 
     while (Date.now() < deadline) {
         if (signal?.aborted) {
@@ -112,8 +129,15 @@ export async function waitForUrlReady(
             });
             lastStatus = res.status;
 
-            // 4xx still means the app is serving; 502/503/504 means proxy-without-upstream.
-            if (isHttpServingStatus(res.status)) {
+            if (isHttpBrokenStatus(res.status)) {
+                const body = (await res.text()).replace(/\s+/g, " ").trim().slice(0, 300);
+                broken = { since: broken?.since ?? Date.now(), status: res.status, body };
+
+                if (Date.now() - broken.since >= brokenGraceMs) {
+                    return brokenResult(url, broken);
+                }
+            } else if (isHttpServingStatus(res.status)) {
+                // 4xx still means the app is serving; 502/503/504 means proxy-without-upstream.
                 return { ready: true, detail: `http ${res.status}` };
             }
         } catch (err) {
@@ -123,6 +147,10 @@ export async function waitForUrlReady(
         await Bun.sleep(POLL_INTERVAL_MS);
     }
 
+    if (broken) {
+        return brokenResult(url, broken);
+    }
+
     const statusSuffix = lastStatus !== undefined ? ` (last status ${lastStatus})` : "";
     const errorSuffix =
         lastError !== undefined
@@ -131,6 +159,15 @@ export async function waitForUrlReady(
     return { ready: false, detail: `${url} did not respond in ${timeoutMs}ms${statusSuffix}${errorSuffix}` };
 }
 
+function brokenResult(url: string, broken: { status: number; body: string }): ReadinessResult {
+    logger.warn({ url, status: broken.status, body: broken.body }, "dashboard answers with a server error");
+    return {
+        ready: true,
+        detail: `http ${broken.status}`,
+        broken: { url, status: broken.status, body: broken.body },
+    };
+}
+
 async function waitForLog(
     probe: { kind: "log"; regex: RegExp; timeoutMs?: number },
     logFile: string,
@@ -171,3 +208,95 @@ async function waitForLog(
 
     return { ready: false, detail: `log marker ${probe.regex} not seen in ${probe.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms` };
 }
+
+/** An error's first line: `TypeError: …`, `Error: …`, `Error [ERR_X]: …`. */
+const ERROR_HEADER = /^\s*(?:[A-Z]\w*)?Error(?:\s*\[[A-Z_]+\])?:\s/;
+/** Any line that names an error, for a log whose errors have no header line. */
+const ERROR_LINE = /\b(?:[A-Z]\w*Error|ERR_[A-Z_]+)\b/;
+const STACK_LINE = /^\s*at\s/;
+const ERROR_CODE_LINE = /^\s*code:\s/;
+
+/**
+ * The last error in a dashboard's log and the top of its stack (at most `maxLines`), ANSI stripped: what a broken
+ * page's server printed. Bun prints the header, then properties (`code: "ERR_…"`), a blank line and the stack; the
+ * code line is kept, the other properties are not. Reads only the last 64 KB; an absent or unreadable log gives none.
+ */
+export function serverErrorExcerpt(logFile: string, maxLines = 8): string[] {
+    if (!existsSync(logFile)) {
+        return [];
+    }
+
+    let text: string;
+    const fd = openSync(logFile, "r");
+    try {
+        const size = statSync(logFile).size;
+        const length = Math.min(size, 64 * 1024);
+        const buf = Buffer.alloc(length);
+        const read = readSync(fd, buf, 0, length, size - length);
+        text = stripAnsi(buf.subarray(0, read).toString());
+    } catch (err) {
+        logger.debug({ err, logFile }, "dashboard log unreadable for the error excerpt");
+        return [];
+    } finally {
+        closeSync(fd);
+    }
+
+    const lines = text.split("\n");
+    // A loop, not findLastIndex: the dashboards' tsconfigs predate ES2023.
+    const lastMatch = (pattern: RegExp): number => {
+        for (let index = lines.length - 1; index >= 0; index--) {
+            if (pattern.test(lines[index]) && !STACK_LINE.test(lines[index])) {
+                return index;
+            }
+        }
+
+        return -1;
+    };
+    const header = lastMatch(ERROR_HEADER);
+    const start = header >= 0 ? header : lastMatch(ERROR_LINE);
+
+    if (start < 0) {
+        return [];
+    }
+
+    const excerpt = [lines[start].trim()];
+    let inStack = false;
+    for (const line of lines.slice(start + 1)) {
+        if (excerpt.length >= maxLines) {
+            break;
+        }
+
+        if (STACK_LINE.test(line)) {
+            inStack = true;
+            excerpt.push(line.trim());
+        } else if (inStack && line.trim()) {
+            break;
+        } else if (!inStack && ERROR_CODE_LINE.test(line)) {
+            excerpt.push(line.trim());
+        }
+    }
+
+    return excerpt;
+}
+
+/**
+ * A dashboard that started but answers its pages with a server error: the error, the server's own message from its
+ * log, and exit code 1, so the run is a failure (the CLI failure log records it with this text). The server keeps
+ * running: a dev server reloads the fixed module.
+ */
+export function reportBrokenDashboard(
+    config: Pick<DashboardAppConfig, "key" | "name">,
+    broken: NonNullable<ReadinessResult["broken"]>,
+    logFile: string,
+    pid?: number
+): void {
+    const cause = serverErrorExcerpt(logFile);
+    out.error(
+        [
+            `${config.name ?? config.key} started${pid ? ` (pid ${pid})` : ""}, but ${broken.url} answers ${broken.status}: ${broken.body || "(empty body)"}`,
+            ...(cause.length > 0 ? ["  Server error:", ...cause.map((line) => `    ${line}`)] : []),
+            `  Log: ${logFile}`,
+        ].join("\n")
+    );
+    process.exitCode = 1;
+}
diff --git a/src/utils/e2e/helpers.ts b/src/utils/e2e/helpers.ts
index 831ff3c1c1..e73c8c81e4 100644
--- a/src/utils/e2e/helpers.ts
+++ b/src/utils/e2e/helpers.ts
@@ -1,7 +1,8 @@
 import { resolve } from "node:path";
 import { env } from "@genesiscz/utils/env";
+import { moduleDir } from "@genesiscz/utils/fs/module-dir";
 
-const TOOLS_PATH = resolve(import.meta.dir, "..", "..", "..", "tools");
+const TOOLS_PATH = resolve(moduleDir(import.meta), "..", "..", "..", "tools");
 
 // \x1B (ESC) is excluded from the control-char class so the CSI alternatives can match full sequences
 // biome-ignore lint/suspicious/noControlCharactersInRegex: needed for stripping ANSI

From b037ff4a12b18e12bfced818db8f772cb5ea8329 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 20:02:53 +0200
Subject: [PATCH 23/30] feat(tools): genesis-md links open only where an app
 handles them; openFileTarget falls back to the plain path, and
 app-links/open-file.ts stands alone so another repo can copy it

---
 src/gitlab/commands/review-judgements.ts |  9 ++--
 src/utils/app-links/open-file.test.ts    | 35 +++++++++++++
 src/utils/app-links/open-file.ts         | 65 ++++++++++++++++++++++++
 src/utils/app-links/query.ts             | 17 +++++++
 src/utils/app-links/targets.ts           | 37 ++++----------
 5 files changed, 131 insertions(+), 32 deletions(-)
 create mode 100644 src/utils/app-links/open-file.test.ts
 create mode 100644 src/utils/app-links/open-file.ts
 create mode 100644 src/utils/app-links/query.ts

diff --git a/src/gitlab/commands/review-judgements.ts b/src/gitlab/commands/review-judgements.ts
index 7d53faf819..9a7f2a8be3 100644
--- a/src/gitlab/commands/review-judgements.ts
+++ b/src/gitlab/commands/review-judgements.ts
@@ -57,7 +57,7 @@ import {
 } from "@app/gitlab/lib/review-drafts";
 import { judgementsPath, reviewItems } from "@app/gitlab/lib/review-items";
 import { collectThreadContext } from "@app/gitlab/lib/review-render";
-import { schemeLink } from "@genesiscz/utils/app-links/targets";
+import { openFileTarget } from "@genesiscz/utils/app-links/open-file";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { out } from "@genesiscz/utils/logger";
@@ -369,11 +369,12 @@ async function runRender(iid: string, opts: RenderOptions): Promise<void> {
     progress(`ℹ  full layout → ${reportPath}`);
 
     if (opts.open && platform === "darwin") {
-        const link = schemeLink({ preset: "genesis-md", action: "open", data: { path: reportPath } });
-        const opened = Bun.spawnSync(["open", link]);
+        // Genesis Markdown when it is installed, else the report's default app.
+        const target = openFileTarget(reportPath);
+        const opened = Bun.spawnSync(["open", target]);
 
         if (opened.exitCode !== 0) {
-            progress(`⚠  could not open ${link}: ${opened.stderr.toString().trim()}`);
+            progress(`⚠  could not open ${target}: ${opened.stderr.toString().trim()}`);
         }
     }
 
diff --git a/src/utils/app-links/open-file.test.ts b/src/utils/app-links/open-file.test.ts
new file mode 100644
index 0000000000..e7ba23eeb8
--- /dev/null
+++ b/src/utils/app-links/open-file.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { genesisMdHandlerPath, genesisMdLink, hasGenesisMdHandler, openFileTarget } from "./open-file";
+import { schemeLink } from "./targets";
+
+describe("open-file", () => {
+    const file = "/Users/alice/Notes/Weekly plan Č.md";
+
+    test("the genesis-md link is the one targets.ts builds, slashes kept", () => {
+        for (const range of [undefined, "12", "12-30"]) {
+            expect(genesisMdLink({ path: file, range })).toBe(
+                schemeLink({ preset: "genesis-md", action: "open", data: { path: file, range } })
+            );
+        }
+
+        expect(genesisMdLink({ path: file, range: "3-4" })).toBe(
+            "genesis-md://open?path=/Users/alice/Notes/Weekly%20plan%20%C4%8C.md&range=3-4"
+        );
+    });
+
+    test("with a handler the target is the link; without one it is the plain path for the default app", () => {
+        expect(openFileTarget(file, "5", { hasHandler: true })).toBe(genesisMdLink({ path: file, range: "5" }));
+        expect(openFileTarget(file, "5", { hasHandler: false })).toBe(file);
+    });
+
+    test("the probe's answer decides, and a passed probe is not cached", () => {
+        expect(hasGenesisMdHandler(() => null)).toBe(false);
+        expect(hasGenesisMdHandler(() => "/Applications/Genesis Markdown.app")).toBe(true);
+        expect(hasGenesisMdHandler(() => null)).toBe(false);
+    });
+
+    test.skipIf(process.platform !== "darwin")("the real probe answers an app path or null, never throws", () => {
+        const found = genesisMdHandlerPath();
+        expect(found === null || found.endsWith(".app")).toBe(true);
+    });
+});
diff --git a/src/utils/app-links/open-file.ts b/src/utils/app-links/open-file.ts
new file mode 100644
index 0000000000..c395a347e1
--- /dev/null
+++ b/src/utils/app-links/open-file.ts
@@ -0,0 +1,65 @@
+import { spawnSync } from "node:child_process";
+import { linkQuery } from "./query";
+
+/**
+ * Opening a file in Genesis Markdown when it is installed, and in the file's default app when it is not. Imports
+ * nothing but `./query`, so another repo can copy it without the router or the hub links in targets.ts.
+ */
+
+export interface GenesisMdFile {
+    path: string;
+    /** Lines to highlight, `"12"` or `"12-30"`. */
+    range?: string;
+}
+
+/** `genesis-md://open?path=…&range=…`, slashes kept. The one builder: targets.ts's genesis-md preset uses it too. */
+export function genesisMdLink(file: GenesisMdFile): string {
+    return `genesis-md://open${linkQuery(
+        [
+            ["path", file.path],
+            ["range", file.range],
+        ],
+        { keepSlash: true }
+    )}`;
+}
+
+// AppKit through osascript's JavaScript bridge, which every macOS has: about 80 ms, so it runs once per process.
+const HANDLER_PROBE =
+    'ObjC.import("AppKit"); const u = $.NSWorkspace.sharedWorkspace.URLForApplicationToOpenURL(' +
+    '$.NSURL.URLWithString("genesis-md://open")); u.isNil() ? "none" : ObjC.unwrap(u.path)';
+
+/** The app that opens genesis-md links (e.g. `/Applications/Genesis Markdown.app`), or null when none does. */
+export function genesisMdHandlerPath(): string | null {
+    if (process.platform !== "darwin") {
+        return null;
+    }
+
+    const probe = spawnSync("osascript", ["-l", "JavaScript", "-e", HANDLER_PROBE], {
+        encoding: "utf8",
+        timeout: 5_000,
+    });
+    const found = probe.stdout?.trim();
+
+    return probe.status === 0 && found && found !== "none" ? found : null;
+}
+
+let handlerKnown: boolean | undefined;
+
+/** Whether this Mac has an app for genesis-md links. Probed once per process; a passed `probe` is never cached. */
+export function hasGenesisMdHandler(probe?: () => string | null): boolean {
+    if (probe) {
+        return probe() !== null;
+    }
+
+    handlerKnown ??= genesisMdHandlerPath() !== null;
+    return handlerKnown;
+}
+
+/**
+ * What `open` should get for a file: the genesis-md link when an app handles it, else the plain absolute path, which
+ * `open` gives to the file's default app (`open genesis-md://…` with no handler fails: "could not open").
+ */
+export function openFileTarget(path: string, range?: string, options: { hasHandler?: boolean } = {}): string {
+    const handled = options.hasHandler ?? hasGenesisMdHandler();
+    return handled ? genesisMdLink({ path, range }) : path;
+}
diff --git a/src/utils/app-links/query.ts b/src/utils/app-links/query.ts
new file mode 100644
index 0000000000..1d0deea95c
--- /dev/null
+++ b/src/utils/app-links/query.ts
@@ -0,0 +1,17 @@
+/** A query, empty values left out. `keepSlash` leaves `/` readable, which a query value may hold. */
+export function linkQuery(
+    pairs: Array<readonly [string, string | undefined]>,
+    { keepSlash }: { keepSlash: boolean }
+): string {
+    const items = pairs.flatMap(([key, value]) => {
+        if (value === undefined || value === "") {
+            return [];
+        }
+
+        const encoded = encodeURIComponent(value);
+
+        return [`${key}=${keepSlash ? encoded.replace(/%2F/g, "/") : encoded}`];
+    });
+
+    return items.length > 0 ? `?${items.join("&")}` : "";
+}
diff --git a/src/utils/app-links/targets.ts b/src/utils/app-links/targets.ts
index 7a99ac3624..98deb7915e 100644
--- a/src/utils/app-links/targets.ts
+++ b/src/utils/app-links/targets.ts
@@ -1,3 +1,6 @@
+import { genesisMdLink } from "./open-file";
+import { linkQuery } from "./query";
+
 /**
  * What a link to a GenesisTools app says: every preset, its actions, and the plain strings each builds, the router
  * path and the app's own scheme link. No gate and no config: whether such a link opens anything on this Mac is the
@@ -52,52 +55,30 @@ export interface AppLink<D> {
 
 export type AppLinkTable = { [P in LinkPreset]: { [A in LinkAction<P>]: AppLink<LinkData<P, A>> } };
 
-/** A query, empty values left out. `keepSlash` leaves `/` readable, which a query value may hold. */
-function query(pairs: Array<readonly [string, string | undefined]>, { keepSlash }: { keepSlash: boolean }): string {
-    const items = pairs.flatMap(([key, value]) => {
-        if (value === undefined || value === "") {
-            return [];
-        }
-
-        const encoded = encodeURIComponent(value);
-
-        return [`${key}=${keepSlash ? encoded.replace(/%2F/g, "/") : encoded}`];
-    });
-
-    return items.length > 0 ? `?${items.join("&")}` : "";
-}
-
 export const APP_LINKS: AppLinkTable = {
     "genesis-md": {
         open: {
             path: (data) =>
-                `md/open${query(
-                    [
-                        ["path", data.path],
-                        ["range", data.range],
-                    ],
-                    { keepSlash: true }
-                )}`,
-            scheme: (data) =>
-                `genesis-md://open${query(
+                `md/open${linkQuery(
                     [
                         ["path", data.path],
                         ["range", data.range],
                     ],
                     { keepSlash: true }
                 )}`,
+            scheme: (data) => genesisMdLink(data),
         },
     },
     "genesis-hub": {
         open: {
             // `encodeURIComponent` in full: a `+` from URLSearchParams reads back as a literal plus in the app.
             path: (data) =>
-                `hub${query(
+                `hub${linkQuery(
                     HUB_LINK_KEYS.map((key) => [key, data[key]] as const),
                     { keepSlash: false }
                 )}`,
             scheme: (data) =>
-                `genesis-tools://hub${query(
+                `genesis-tools://hub${linkQuery(
                     HUB_LINK_KEYS.map((key) => [key, data[key]] as const),
                     { keepSlash: false }
                 )}`,
@@ -106,11 +87,11 @@ export const APP_LINKS: AppLinkTable = {
     "claude-find": {
         decision: {
             path: (data) =>
-                `claude/find/${encodeURIComponent(data.session)}/decision/${data.decision}${query([["at", data.at]], { keepSlash: false })}`,
+                `claude/find/${encodeURIComponent(data.session)}/decision/${data.decision}${linkQuery([["at", data.at]], { keepSlash: false })}`,
         },
         text: {
             path: (data) =>
-                `claude/find/${encodeURIComponent(data.session)}${query(
+                `claude/find/${encodeURIComponent(data.session)}${linkQuery(
                     [
                         ["q", data.q],
                         ["at", data.at],

From 5c1e669b0221c80dfa967169093ed02bf0084d93 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 20:12:05 +0200
Subject: [PATCH 24/30] fix(tools): genesis-tools logs names its follow-up
 commands through toolCommand

---
 src/genesis-tools/commands/logs.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/genesis-tools/commands/logs.ts b/src/genesis-tools/commands/logs.ts
index efb32fe9da..71921963f1 100644
--- a/src/genesis-tools/commands/logs.ts
+++ b/src/genesis-tools/commands/logs.ts
@@ -1,5 +1,6 @@
 import { parseVariadic } from "@genesiscz/utils/cli";
 import { FAILURE_KINDS, type FailureKind, failuresDir, type ToolFailure } from "@genesiscz/utils/cli/failures/record";
+import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { formatLocalDate } from "@genesiscz/utils/date";
 import { out } from "@genesiscz/utils/logger";
 import { dayLogsDir } from "@genesiscz/utils/logger/day-logs";
@@ -120,7 +121,7 @@ function printFailures(failures: ToolFailure[], window: TimeWindow): void {
         pc.dim(failure.id),
     ]);
     out.println(formatTable(rows, ["TIME", "KIND", "COMMAND", "EXIT", "WHO", "MESSAGE", "ID"]));
-    out.println(pc.dim(`\n${failures.length} failures. Details: tools genesis-tools logs show <id>`));
+    out.println(pc.dim(`\n${failures.length} failures. Details: ${toolCommand("genesis-tools logs show", "<id>")}`));
 }
 
 function registerFailures(logs: Command): void {
@@ -334,7 +335,7 @@ function registerDay(logs: Command): void {
 
 function registerProfile(logs: Command): void {
     withWindow(
-        logs.command("profile").description("Slow timers from the profiling log (tools config profiling)"),
+        logs.command("profile").description(`Slow timers from the profiling log (${toolCommand("config profiling")})`),
         "24h"
     )
         .option("--min-ms <ms>", "Only timers at least this long", "1000")

From 6fdf6efb2c9c4497f5d418a1f64d2e702a8894c1 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 22:04:45 +0200
Subject: [PATCH 25/30] fix(tools): #559 followup - review fixes, rounds 1 and
 2: pre-push times its stages without an undefined stage_done, the failures
 log masks short aliases, global-option, dash-led and positional secrets and
 every echoed value, a handled crash that exits is kept, day-log queries
 stream, typecheck counts new JS files, tmp-reclaim needs SwiftPM provenance,
 a refused alert keeps the widget module

---
 .../skills/babysit/scripts/scripts.test.ts    |  17 ++
 .claude/skills/babysit/scripts/tmp-reclaim.ts |  14 +-
 .githooks/pre-push                            |   3 +-
 scripts/ci/typecheck.test.ts                  |  10 +
 scripts/ci/typecheck.ts                       |  15 +-
 src/ai/README.md                              |   2 +-
 src/ai/commands/config/secret.ts              |   2 +-
 src/genesis-tools/commands/logs.ts            |  12 +-
 src/genesis-tools/lib/day-log.ts              |  64 ++++-
 src/genesis-tools/lib/logs.test.ts            |  29 +-
 .../Widgets/WidgetCoordinator.swift           |   3 +-
 .../GenesisKit/Widgets/WidgetModel.swift      |   9 +-
 .../EdgePanelGeometryTests.swift              |  11 +
 src/utils/cli/commander.ts                    |   3 +-
 src/utils/cli/failures/failures.test.ts       | 119 ++++++++-
 src/utils/cli/failures/watch.ts               | 249 ++++++++++++++++--
 src/utils/compress/compress.test.ts           |   9 +
 src/utils/compress/search.ts                  |  36 ++-
 18 files changed, 546 insertions(+), 61 deletions(-)

diff --git a/.claude/skills/babysit/scripts/scripts.test.ts b/.claude/skills/babysit/scripts/scripts.test.ts
index 80dcc144fd..48b994d119 100644
--- a/.claude/skills/babysit/scripts/scripts.test.ts
+++ b/.claude/skills/babysit/scripts/scripts.test.ts
@@ -5216,6 +5216,23 @@ describe("tmp-reclaim --own-session lists only the live session's build output",
         expect(buildOutputKind(join(dir, "pluggable/mc"))).toBe("module-cache");
     });
 
+    test("a triple folder counts only when SwiftPM made it: in a scratch path, holding configuration folders only", () => {
+        const { dir } = plantSession();
+        const saved = join(dir, "saved/arm64-apple-macosx");
+        fs.mkdirSync(join(saved, "debug"), { recursive: true });
+        fs.writeFileSync(join(saved, "debug/Old.o"), "x");
+        expect(buildOutputKind(saved)).toBeNull();
+        expect(ownBuildOutput(dir)).not.toContain(saved);
+        // A note dropped into a real triple folder, with its inode kept: it is no longer pure build output.
+        const triple = join(dir, "pluggable/b-notes/arm64-apple-macosx");
+        const before = fs.lstatSync(triple).ino;
+        fs.writeFileSync(join(triple, "kept.md"), "a note");
+        fs.writeFileSync(join(triple, "fix.patch"), "a patch");
+        expect(fs.lstatSync(triple).ino).toBe(before);
+        expect(buildOutputKind(triple)).toBeNull();
+        expect(judgeOwn(triple, { sessionDirs: [dir], open: [], minAgeMinutes: 0 })).toBe("not-build-output");
+    });
+
     test("judgeOwn keeps the guards: recent, open, FIFO, outside the session, not build output", () => {
         const { cc, dir } = plantSession();
         // A change time can sit a millisecond ahead of Date.now(); with a zero age limit that still reads as recent.
diff --git a/.claude/skills/babysit/scripts/tmp-reclaim.ts b/.claude/skills/babysit/scripts/tmp-reclaim.ts
index 17762822d7..caf8519d59 100644
--- a/.claude/skills/babysit/scripts/tmp-reclaim.ts
+++ b/.claude/skills/babysit/scripts/tmp-reclaim.ts
@@ -95,6 +95,10 @@ const SWIFTPM_SCRATCH_ENTRIES = new Set([
     "repositories",
     "workspace-state.json",
 ]);
+/** What SwiftPM writes into a triple folder: one folder per build configuration. */
+const SWIFTPM_TRIPLE_ENTRIES = new Set(["debug", "release"]);
+/** What only a SwiftPM scratch path holds; a triple folder counts only beside one of these (or inside `.build`). */
+const SWIFTPM_SCRATCH_MARKERS = ["workspace-state.json", "build.db", "debug.yaml", "release.yaml"];
 const MODULE_CACHE_FILES = [".pcm", ".swiftmodule", ".timestamp", ".modulevalidation", ".lock"];
 const MODULE_CACHE_MARKERS = [".pcm", ".swiftmodule", "modules.timestamp"];
 /** Never walked in an own-session scan: dependency trees, repositories and moved-aside files a user may restore. */
@@ -400,7 +404,15 @@ export function buildOutputKind(path: string): BuildOutputKind | null {
     const name = basename(path);
 
     if (SWIFTPM_TRIPLES.has(name)) {
-        return "swiftpm-triple";
+        // The name alone proves nothing: a saved or moved-aside folder can carry it. SwiftPM made it only when it sits
+        // in a scratch path and holds nothing but configuration folders.
+        const parent = dirname(path);
+        const children = childNames(path) ?? [];
+        const inScratch =
+            basename(parent) === ".build" ||
+            (childNames(parent) ?? []).some((child) => SWIFTPM_SCRATCH_MARKERS.includes(child));
+        const onlyConfigs = children.length > 0 && children.every((child) => SWIFTPM_TRIPLE_ENTRIES.has(child));
+        return inScratch && onlyConfigs ? "swiftpm-triple" : null;
     }
 
     const names = childNames(path) ?? [];
diff --git a/.githooks/pre-push b/.githooks/pre-push
index 9a03df2101..d9dcbaccfa 100755
--- a/.githooks/pre-push
+++ b/.githooks/pre-push
@@ -103,7 +103,8 @@ if ! bun scripts/ci/dashboard-smoke.ts $smoke_args; then
     echo "✖ a dashboard does not render: push refused. The lines above name its server error and log."
     exit 1
 fi
-stage_done
+# The stage timer arrives with #551's pre-push timing; until then the call is skipped.
+if command -v stage_done >/dev/null 2>&1; then stage_done; fi
 
 # The repo guards from the CI "checks" job (ci.yml, after the TypeScript check). They used to run on
 # CI only, so a pid probe or a hard-coded command name reached every PR of a stack before anything
diff --git a/scripts/ci/typecheck.test.ts b/scripts/ci/typecheck.test.ts
index 7d3952dd4a..deff09305a 100644
--- a/scripts/ci/typecheck.test.ts
+++ b/scripts/ci/typecheck.test.ts
@@ -38,6 +38,16 @@ describe("reasonToRun", () => {
             "new file",
         ]);
         expect(reasons({ files: ["docs/new.md"], added: ["docs/new.md"] })).toEqual([null, null]);
+        expect(reasons({ files: ["src/utils/new.js"], added: ["src/utils/new.js"] })).toEqual(["new file", "new file"]);
+    });
+
+    it("runs a project for an added file another project's cache already holds, since its own may take it too", () => {
+        const rootSawIt = new Map(programs);
+        rootSawIt.set("root", new Set([...(programs.get("root") ?? []), key("src/app/ui/new.ts")]));
+        expect(reasons({ files: ["src/app/ui/new.ts"], added: ["src/app/ui/new.ts"] }, rootSawIt)).toEqual([
+            "in its program",
+            "new file",
+        ]);
     });
 
     it("a deleted file still counts for the programs that held it", () => {
diff --git a/scripts/ci/typecheck.ts b/scripts/ci/typecheck.ts
index 973948d759..c5a2ed4d75 100644
--- a/scripts/ci/typecheck.ts
+++ b/scripts/ci/typecheck.ts
@@ -9,8 +9,8 @@
  *
  * A project runs when no build info or state says what it holds, when a file that changes every project changed
  * (`package.json`, `bun.lock`, a `tsconfig`), when a changed file is in its last program (the build info's
- * `fileNames`), or when a changed TypeScript file sits in its folder (a new file is in no program yet). The root
- * project also runs for any changed TypeScript file outside the other projects' folders. Build info is a cache only:
+ * `fileNames`), or when a TypeScript or JavaScript file was added that its program does not hold yet (only tsc knows
+ * which include patterns take a new file, so every such project runs). Build info is a cache only:
  * `tsc` compares file hashes, so build info from another commit still gives the right answer, just slower.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -34,7 +34,8 @@ export const PROJECTS: Project[] = [
     { name: "fable-replace", tsconfig: "plugins/genesis-tools/skills/fable-replace/scripts/tsconfig.json" },
 ];
 
-const TS_FILE = /\.(?:[cm]?tsx?|json)$/;
+/** What a project can take in: the root project has `allowJs`, so JavaScript inputs count too. */
+const TS_FILE = /\.(?:[cm]?[jt]sx?|json)$/;
 const EVERY_PROJECT = /(?:^|\/)(?:package\.json|bun\.lock|tsconfig[\w.-]*\.json|bunfig\.toml)$/;
 
 export type Reason =
@@ -60,8 +61,9 @@ export interface Changes {
 
 /**
  * Why `project` must run for these changes, or null. `programs` holds each project's last program files (absolute,
- * lowercased, as the build info stores them), null when nothing is known. An added TypeScript file that no program
- * holds makes every project run: only tsc knows which include patterns take it (spotify-ui includes `../**`).
+ * lowercased, as the build info stores them), null when nothing is known. An added TypeScript file this project's
+ * program does not hold makes it run: only tsc knows which include patterns take it (spotify-ui includes `../**`), and
+ * another project's program holding it says nothing about this one (a root run caches a file a dashboard also takes).
  */
 export function reasonToRun({
     project,
@@ -86,8 +88,7 @@ export function reasonToRun({
         return "in its program";
     }
 
-    const known = (file: string) => [...programs.values()].some((other) => other?.has(key(file)));
-    return changes.added.some((file) => TS_FILE.test(file) && !known(file)) ? "new file" : null;
+    return changes.added.some((file) => TS_FILE.test(file) && !program.has(key(file))) ? "new file" : null;
 }
 
 function git(args: string[]): string | null {
diff --git a/src/ai/README.md b/src/ai/README.md
index 9bda808331..752656e3c2 100644
--- a/src/ai/README.md
+++ b/src/ai/README.md
@@ -73,7 +73,7 @@ tools ai config default list
 
 tools ai config link                            # what references an account
 
-tools ai config secret set <path> [value]       # value comes from stdin or a file; does not link it to an account
+tools ai config secret set <path> [secret]      # value comes from stdin or a file; does not link it to an account
 tools ai config secret ls [prefix]              # paths only, never values
 tools ai config secret rotate                   # new master key, re-encrypt everything
 tools ai config secret export                   # passphrase-protected copy
diff --git a/src/ai/commands/config/secret.ts b/src/ai/commands/config/secret.ts
index b8a8e519cd..bf3be648b7 100644
--- a/src/ai/commands/config/secret.ts
+++ b/src/ai/commands/config/secret.ts
@@ -205,7 +205,7 @@ export function registerSecretCommands(config: Command): void {
         .command("set")
         .description("Store a secret; the value comes from stdin or a hidden prompt, never from argv")
         .argument("<path>", "Vault path, e.g. ai/acc_xai/apiKey")
-        .argument("[value]", "Not accepted — passing a secret on argv is refused")
+        .argument("[secret]", "Not accepted — passing a secret on argv is refused")
         .option("--stdin", "Read the value from stdin")
         .action(async (path: string, value: string | undefined, flags: { stdin?: boolean }) => {
             await cmdSecretSet(path, value, flags);
diff --git a/src/genesis-tools/commands/logs.ts b/src/genesis-tools/commands/logs.ts
index 71921963f1..bcf66852c5 100644
--- a/src/genesis-tools/commands/logs.ts
+++ b/src/genesis-tools/commands/logs.ts
@@ -335,7 +335,11 @@ function registerDay(logs: Command): void {
 
 function registerProfile(logs: Command): void {
     withWindow(
-        logs.command("profile").description(`Slow timers from the profiling log (${toolCommand("config profiling")})`),
+        logs
+            .command("profile")
+            .description(
+                `Slow timers from the profiling log (${toolCommand("config profiling")}). Its lines carry no time of day, so --since and --until select whole days`
+            ),
         "24h"
     )
         .option("--min-ms <ms>", "Only timers at least this long", "1000")
@@ -347,8 +351,9 @@ function registerProfile(logs: Command): void {
             (
                 options: WindowOptions & { minMs: string; scope?: string[]; grep?: string; pid?: string; top: string }
             ) => {
+                const days = daysIn(windowOf(options));
                 const entries = queryProfileLog({
-                    days: daysIn(windowOf(options)),
+                    days,
                     minMs: Number(options.minMs),
                     scopes: parseVariadic(options.scope),
                     grep: options.grep,
@@ -369,6 +374,9 @@ function registerProfile(logs: Command): void {
                     pc.dim(entry.day),
                 ]);
                 out.println(formatTable(rows, ["TIME", "SCOPE", "LABEL", "PID", "DAY"]));
+                out.println(
+                    pc.dim(`\nWhole days ${days[0]} to ${days[days.length - 1]}: profiling lines carry no time of day.`)
+                );
             }
         );
 }
diff --git a/src/genesis-tools/lib/day-log.ts b/src/genesis-tools/lib/day-log.ts
index 488ee461c1..43114b00ca 100644
--- a/src/genesis-tools/lib/day-log.ts
+++ b/src/genesis-tools/lib/day-log.ts
@@ -111,7 +111,40 @@ export function prefilterFor(query: DayLogQuery): { pattern: string; fixed: bool
     return null;
 }
 
-async function candidateLines(files: string[], query: DayLogQuery): Promise<string[]> {
+/**
+ * Keeps the newest `limit` entries (all of them without a limit) while lines stream past, holding at most twice
+ * `limit`: a week of day logs can be gigabytes, and `logs day --limit 100` needs 100 records of it.
+ */
+export function newestEntries(limit: number | undefined): {
+    add(entry: DayLogEntry): void;
+    held(): number;
+    result(): DayLogEntry[];
+} {
+    let entries: DayLogEntry[] = [];
+    const trim = () => {
+        entries.sort((a, b) => a.time.localeCompare(b.time));
+        if (limit) {
+            entries = entries.slice(-limit);
+        }
+    };
+
+    return {
+        add(entry) {
+            entries.push(entry);
+            if (limit && entries.length >= limit * 2) {
+                trim();
+            }
+        },
+        held: () => entries.length,
+        result() {
+            trim();
+            return entries;
+        },
+    };
+}
+
+/** Hands every line that may match to `onLine` as it is read: rg's prefiltered output, else every line. */
+async function eachCandidateLine(files: string[], query: DayLogQuery, onLine: (line: string) => void): Promise<void> {
     const prefilter = prefilterFor(query);
     const rg = ripgrepBinary();
 
@@ -120,16 +153,26 @@ async function candidateLines(files: string[], query: DayLogQuery): Promise<stri
             logger.debug("day log: rg is not on PATH, reading every line");
         }
 
-        return files.flatMap((file) => [...readLinesSync(file)]);
+        for (const file of files) {
+            for (const line of readLinesSync(file)) {
+                onLine(line);
+            }
+        }
+
+        return;
     }
 
     const args = ["--no-config", "--no-filename", "--no-line-number", ...(prefilter.fixed ? ["-F", "-i"] : [])];
-    const run = await ripgrepFiles({ rg, args: [...args, "-e", prefilter.pattern], files, timeoutMs: 120_000 });
+    const run = await ripgrepFiles({
+        rg,
+        args: [...args, "-e", prefilter.pattern],
+        files,
+        timeoutMs: 120_000,
+        onLine,
+    });
     if (run.signal || run.code > 1) {
         throw new Error(`rg over the day logs failed (${run.signal ?? `exit ${run.code}`}): ${run.stderr.trim()}`);
     }
-
-    return run.stdout.split("\n");
 }
 
 /** The newest `limit` matching records, oldest first. */
@@ -141,14 +184,13 @@ export async function queryDayLog(query: DayLogQuery): Promise<DayLogEntry[]> {
         .map((file) => file.path);
     logger.debug({ files, prefilter: prefilterFor(query) }, "day log: query");
 
-    const found: DayLogEntry[] = [];
-    for (const line of await candidateLines(files, query)) {
+    const found = newestEntries(query.limit);
+    await eachCandidateLine(files, query, (line) => {
         const entry = parseDayLogLine(line);
         if (entry && matchesDayLog(entry, query, line)) {
-            found.push(entry);
+            found.add(entry);
         }
-    }
+    });
 
-    found.sort((a, b) => a.time.localeCompare(b.time));
-    return query.limit ? found.slice(-query.limit) : found;
+    return found.result();
 }
diff --git a/src/genesis-tools/lib/logs.test.ts b/src/genesis-tools/lib/logs.test.ts
index 37383883ce..7c80d4a4e2 100644
--- a/src/genesis-tools/lib/logs.test.ts
+++ b/src/genesis-tools/lib/logs.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "bun:test";
 import type { FailureCaller, ToolFailure } from "@genesiscz/utils/cli/failures/record";
-import { matchesDayLog, parseDayLogLine, prefilterFor } from "./day-log";
+import { matchesDayLog, newestEntries, parseDayLogLine, prefilterFor } from "./day-log";
 import { groupFailures, matchesFailure, usageGaps } from "./failures";
 import { parseProfileLine } from "./profile-log";
 import { daysIn, resolveWindow } from "./window";
@@ -132,6 +132,33 @@ describe("day log", () => {
         expect(prefilterFor({ window, minLevel: 50 })).toEqual({ pattern: '"level":(50|60)[,}]', fixed: false });
         expect(prefilterFor({ window, minLevel: 30 })).toBeNull();
     });
+
+    it("keeps the newest records of a stream out of order, holding at most twice the limit", () => {
+        const entry = (second: number) => ({
+            time: `2026-10-22T13:00:${String(second).padStart(2, "0")}.000Z`,
+            level: 30,
+            pid: 1,
+            tool: null,
+            msg: String(second),
+            record: {},
+        });
+        const seconds = Array.from({ length: 60 }, (_, index) => (index * 37) % 60);
+        const newest = newestEntries(5);
+        let most = 0;
+        for (const second of seconds) {
+            newest.add(entry(second));
+            most = Math.max(most, newest.held());
+        }
+
+        expect(newest.result().map((kept) => kept.msg)).toEqual(["55", "56", "57", "58", "59"]);
+        expect(most).toBeLessThanOrEqual(10);
+        const all = newestEntries(undefined);
+        for (const second of [3, 1, 2]) {
+            all.add(entry(second));
+        }
+
+        expect(all.result().map((kept) => kept.msg)).toEqual(["1", "2", "3"]);
+    });
 });
 
 describe("profile log", () => {
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetCoordinator.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetCoordinator.swift
index c0933ba2bb..293504040a 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetCoordinator.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetCoordinator.swift
@@ -181,7 +181,8 @@ public final class WidgetCoordinator: NSObject, NSWindowDelegate {
         guard let item = WidgetAlerts.popupItem(wanted) else { return }
         PerfLog.mark("widget.alert items=\(wanted.count) id=\(item.id) kind=\(item.kind)")
         playChime(preferences?.alertSound)
-        guard preferences?.alertPopup ?? true, let surface = peekSurface() else { return }
+        // Checked before the module switch: a popup the user's interaction refuses must not swap the pane they use.
+        guard preferences?.alertPopup ?? true, let surface = peekSurface(), model.canPeek(on: surface) else { return }
         if moduleIDs(for: surface).contains("agents"), model.moduleSelections[surface.key] != "agents" {
             model.moduleSelections[surface.key] = "agents"
         }
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift
index 3c1195c690..54492bd94b 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift
@@ -588,10 +588,15 @@ public final class WidgetModel: ObservableObject {
         hoveredSession = nil
     }
 
+    /// Whether `showPeek` would pop an item up in `surface` now: never while the user is in a panel, a window or a drag.
+    func canPeek(on surface: WidgetSurfaceID) -> Bool {
+        !stopping && expanded == nil && !dialogOpen && !draggingSide && pointerInside.isEmpty
+            && (hoveredSurface == nil || hoveredSurface == surface)
+    }
+
     /// Pops `item` up in `surface`'s preview for `seconds`, unless the user is in a panel, a window or a drag.
     func showPeek(_ item: WidgetInboxItem, on surface: WidgetSurfaceID, seconds: Double = 7) {
-        guard !stopping, expanded == nil, !dialogOpen, !draggingSide, pointerInside.isEmpty,
-              hoveredSurface == nil || hoveredSurface == surface else { return }
+        guard canPeek(on: surface) else { return }
         hoverTask?.cancel()
         peekItem = item
         hoveredSurface = surface
diff --git a/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift b/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift
index 6f4f97255d..4f19b9e0b9 100644
--- a/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift
+++ b/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift
@@ -646,6 +646,17 @@ final class WidgetVisibilityTests: XCTestCase {
 
         coordinator.model.collapse()
         XCTAssertNil(coordinator.model.peekItem)
+        // The pointer is in a panel and another module is selected: the popup is refused and the pane stays.
+        let side = WidgetSurfaceID(edge: .right)
+        coordinator.model.moduleSelections[side.key] = "capture"
+        coordinator.model.hover(side, inside: true)
+        coordinator.alert([decision])
+        XCTAssertNil(coordinator.model.peekItem, "no popup while the pointer is in a panel")
+        XCTAssertEqual(coordinator.model.moduleSelections[side.key], "capture", "a refused popup keeps the selected module")
+        XCTAssertEqual(chimes, [nil, nil], "a refused popup still chimes")
+        coordinator.model.hover(side, inside: false)
+        coordinator.model.collapse()
+        chimes.removeLast()
         coordinator.model.updatePreferences(["alertPopup": .bool(false), "alertSound": .string("Ping")])
         coordinator.alert([decision])
         XCTAssertEqual(chimes, [nil, "Ping"])
diff --git a/src/utils/cli/commander.ts b/src/utils/cli/commander.ts
index 838cfe8583..b34c549ba8 100644
--- a/src/utils/cli/commander.ts
+++ b/src/utils/cli/commander.ts
@@ -6,7 +6,7 @@ import { consoleFloorFor } from "@genesiscz/utils/logging/tool-policy";
 import { type Command, CommanderError } from "commander";
 import { setCurrentCommand } from "./current-command";
 import { enhanceHelp, markRequiredOptionsDeep, setSuggestCommandProgram, showHelpAfterErrorDeep } from "./executor";
-import { commandPathFromArgv, noteToolError, watchToolRun } from "./failures/watch";
+import { commandPathFromArgv, noteToolError, secretsFromArgv, watchToolRun } from "./failures/watch";
 import { observeInterrupts } from "./interrupt";
 import { currentRunLabel, recordRunOnExit, setRunLabel } from "./run-record";
 
@@ -269,6 +269,7 @@ export async function runTool(
             tool,
             argv: argv.slice(2),
             commandPath: () => currentRunLabel() ?? commandPathFromArgv(program, argv.slice(2)),
+            secrets: () => secretsFromArgv(program, argv.slice(2)),
         });
     }
 
diff --git a/src/utils/cli/failures/failures.test.ts b/src/utils/cli/failures/failures.test.ts
index b9b09db209..0a0e0d75c6 100644
--- a/src/utils/cli/failures/failures.test.ts
+++ b/src/utils/cli/failures/failures.test.ts
@@ -2,9 +2,19 @@ import { describe, expect, it } from "bun:test";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { formatLocalDate } from "@genesiscz/utils/date";
+import { Command } from "commander";
 import { claudeProjectFolder, modelInTranscriptLines } from "./caller";
 import { appendFailure, readFailures, type ToolFailure } from "./record";
-import { classifyExit, commandPathFromArgv, jsonErrorMessage, messageOfTail, redactArgv } from "./watch";
+import {
+    classifyExit,
+    commandPathFromArgv,
+    jsonErrorMessage,
+    messageOfTail,
+    redactArgv,
+    redactRunText,
+    secretsFromArgv,
+} from "./watch";
 
 describe("redactArgv", () => {
     it("masks the value of a secret-named flag in both spellings and keeps the rest", () => {
@@ -23,6 +33,79 @@ describe("redactArgv", () => {
     });
 });
 
+describe("secret option aliases", () => {
+    const program = new Command("wakeup").option("-v, --verbose", "verbose").option("--log <file>", "log file");
+    program
+        .command("daemon")
+        .command("register")
+        .option("-t, --token <token>", "shared secret")
+        .option("-p, --port <port>", "port");
+    const args = ["daemon", "register", "-t", "fixture-password", "--port", "0"];
+    const secrets = secretsFromArgv(program, args);
+    const redacted = (argv: string[]) => redactArgv(argv, secretsFromArgv(program, argv));
+
+    it("names the short and long flag of a secret-named option on the command that ran, and nothing else", () => {
+        expect(secrets.flags).toEqual(["-t", "--token"]);
+        expect(secretsFromArgv(program, ["daemon"]).flags).toEqual([]);
+    });
+
+    it("masks the value after a declared short alias, attached or separate", () => {
+        expect(redactArgv(args, secrets)).toEqual(["daemon", "register", "-t", "[redacted]", "--port", "0"]);
+        expect(redacted(["daemon", "register", "-tfixture-password"])).toEqual(["daemon", "register", "-t[redacted]"]);
+    });
+
+    it("reaches the subcommand past a global option and its value before it", () => {
+        expect(redacted(["-v", "daemon", "register", "-t", "fixture-password", "--port", "0"])).toEqual([
+            "-v",
+            "daemon",
+            "register",
+            "-t",
+            "[redacted]",
+            "--port",
+            "0",
+        ]);
+        expect(redacted(["--log", "out.txt", "daemon", "-v", "register", "-t", "fixture-password"])).toEqual([
+            "--log",
+            "out.txt",
+            "daemon",
+            "-v",
+            "register",
+            "-t",
+            "[redacted]",
+        ]);
+    });
+
+    it("masks a declared secret value that starts with a dash, since commander takes it as the value", () => {
+        const dashed = ["daemon", "register", "--token", "-fixture-password", "--port", "0"];
+        expect(redacted(dashed)).toEqual(["daemon", "register", "--token", "[redacted]", "--port", "0"]);
+        expect(redactRunText("error: bad token -fixture-password", dashed, secretsFromArgv(program, dashed))).toBe(
+            "error: bad token [redacted]"
+        );
+    });
+
+    it("masks the value of a secret-named argument and keeps the others", () => {
+        const ai = new Command("ai");
+        ai.command("config").command("secret").command("set").argument("<path>").argument("[secret]");
+        const argv = ["config", "secret", "set", "ai/work/password", "correct-horse-battery-staple"];
+        expect(redactArgv(argv, secretsFromArgv(ai, argv))).toEqual([
+            "config",
+            "secret",
+            "set",
+            "ai/work/password",
+            "[redacted]",
+        ]);
+    });
+
+    it("masks the same values and any --secret=value where a message or stderr echoes them", () => {
+        expect(redactRunText("error: bad value fixture-password for -t", args, secrets)).toBe(
+            "error: bad value [redacted] for -t"
+        );
+        expect(redactRunText("error: unknown option '--token=fixture-password'", [])).toBe(
+            "error: unknown option '--token=[redacted]'"
+        );
+    });
+});
+
 describe("classifyExit", () => {
     const none = { noted: null, stderrTail: "" };
 
@@ -87,11 +170,13 @@ describe("commandPathFromArgv", () => {
         name(): string;
         aliases(): string[];
         commands: Node[];
+        options: [];
     }
     const node = (name: string, commands: Node[] = [], aliases: string[] = []): Node => ({
         name: () => name,
         aliases: () => aliases,
         commands,
+        options: [],
     });
     const program = node("ai", [node("usage", [node("sessions")], ["u"])]);
 
@@ -156,3 +241,35 @@ describe("failure records", () => {
         expect([...readFailures({ fromDay: "2026-10-23", toDay: "2026-10-24", dir })]).toEqual([]);
     });
 });
+
+describe("a crash another uncaughtException listener takes", () => {
+    function crashWith(handler: string): Array<[string, boolean, number | null, string | null]> {
+        const home = mkdtempSync(join(tmpdir(), "gt-failures-crash-"));
+        const script = [
+            `import { watchToolRun } from "${join(import.meta.dir, "watch.ts")}";`,
+            `watchToolRun({ tool: "fixture", argv: ["run"], caller: () => null });`,
+            `process.on("uncaughtException", () => { ${handler} });`,
+            `throw new Error("fixture crash");`,
+        ].join("\n");
+        const fromDay = formatLocalDate(new Date());
+        Bun.spawnSync([process.execPath, "-e", script], {
+            env: { ...process.env, GENESIS_TOOLS_HOME: home },
+            stdout: "ignore",
+            stderr: "ignore",
+        });
+        const records = readFailures({
+            fromDay,
+            toDay: formatLocalDate(new Date()),
+            dir: join(home, ".genesis-tools", "logs"),
+        });
+        return [...records].map((record) => [record.kind, record.fatal, record.exitCode, record.message]);
+    }
+
+    it("is the fatal cause of the exit when that listener ends the process", () => {
+        expect(crashWith("process.exit(1);")).toEqual([["crash", true, 1, "fixture crash"]]);
+    });
+
+    it("is written as non-fatal when that listener lets the process go on", () => {
+        expect(crashWith("")).toEqual([["crash", false, null, "fixture crash"]]);
+    });
+});
diff --git a/src/utils/cli/failures/watch.ts b/src/utils/cli/failures/watch.ts
index 56872d28f5..b9286cf050 100644
--- a/src/utils/cli/failures/watch.ts
+++ b/src/utils/cli/failures/watch.ts
@@ -10,7 +10,10 @@ import { appendFailure, type FailureCaller, type FailureKind, type ToolFailure }
 
 const TAIL_CHARS = 4000;
 const TOOLS_ROOT = resolve(moduleDir(import.meta), "../../../..");
-const SECRET_FLAG = /^--?[\w-]*(?:token|secret|password|passwd|api[-_]?key|auth|cookie|credential)[\w-]*$/i;
+const SECRET_WORD = "(?:token|secret|password|passwd|api[-_]?key|auth|cookie|credential)";
+const SECRET_FLAG = new RegExp(`^--?[\\w-]*${SECRET_WORD}[\\w-]*$`, "i");
+/** A positional argument whose declared name is secret-shaped (`[secret]`) takes a secret value. */
+const SECRET_ARGUMENT = new RegExp(SECRET_WORD, "i");
 /** Commander's own refusals; each starts a stderr write with `error: `. */
 const USAGE_LINE =
     /^error: (?:unknown option|unknown command|missing required argument|option .+ argument missing|required option|too many arguments|option .+ argument .+ is invalid|command-argument value .+ is invalid|option .+ cannot be used with)/m;
@@ -25,6 +28,8 @@ interface Run {
     tool: string;
     argv: string[];
     commandPath: () => string | null;
+    /** The secret flags and argv words of the command that ran (`-t` for `--token`); asked only when writing. */
+    secrets: () => ArgvSecrets;
     /** Who ran the tool, asked only when a failure is written (agent-caller.ts unless a test injects one). */
     caller: () => FailureCaller | null;
     stderr: string;
@@ -36,48 +41,218 @@ interface Run {
 
 let run: Run | null = null;
 
-/** Masks the value of a secret-named flag (`--token x`, `--api-key=x`) and any secret-shaped argument. */
-export function redactArgv(args: readonly string[]): string[] {
+/** What the command definition says is secret in one argv, beyond what a flag's name shows. */
+export interface ArgvSecrets {
+    /** Every flag, short and long, of a secret-named option on the commands the run reaches (`-t` for `--token`). */
+    flags: string[];
+    /** The argv indexes of a declared secret option's value (even `-x…`) and of a secret-named argument's value. */
+    indexes: number[];
+}
+
+/**
+ * Masks the value of a secret-named flag (`--token x`, `--api-key=x`), of a flag the command declares for a
+ * secret-named option (`-t x` and `-tx` when `-t` is `--token`), every word `secrets.indexes` names, and any
+ * secret-shaped argument.
+ */
+export function redactArgv(args: readonly string[], secrets: Partial<ArgvSecrets> = {}): string[] {
+    const secretFlags = secrets.flags ?? [];
+    const secretIndexes = new Set(secrets.indexes ?? []);
+    const isSecret = (flag: string) => SECRET_FLAG.test(flag) || secretFlags.includes(flag);
+    const shorts = secretFlags.filter((flag) => /^-[^-]$/.test(flag));
+
     return args.map((arg, index) => {
+        if (secretIndexes.has(index)) {
+            return "[redacted]";
+        }
+
         const assigned = /^(--?[\w-]+)=/.exec(arg);
-        if (assigned && SECRET_FLAG.test(assigned[1])) {
+        if (assigned && isSecret(assigned[1])) {
             return `${assigned[1]}=[redacted]`;
         }
 
-        if (index > 0 && SECRET_FLAG.test(args[index - 1]) && !arg.startsWith("-")) {
+        if (index > 0 && isSecret(args[index - 1]) && !arg.startsWith("-")) {
             return "[redacted]";
         }
 
+        const attached = shorts.find((flag) => arg.length > 2 && arg.startsWith(flag));
+        if (attached) {
+            return `${attached}[redacted]`;
+        }
+
         return redactSecretsInText(arg);
     });
 }
 
+/** The argument values `redactArgv` masks, so the same values can be masked where a message or stderr echoes them. */
+function secretValues(args: readonly string[], secrets: Partial<ArgvSecrets>): string[] {
+    const masked = redactArgv(args, secrets);
+    return args
+        .flatMap((arg, index) => {
+            if (masked[index] === arg) {
+                return [];
+            }
+
+            const kept = masked[index].replace(/\[redacted\]$/, "");
+            return [arg.startsWith(kept) ? arg.slice(kept.length) : arg];
+        })
+        .filter((value) => value.length >= 4);
+}
+
+/** `redactSecretsInText`, plus every `--secret-flag=value` and every secret argument value the text echoes. */
+export function redactRunText(text: string, args: readonly string[], secrets: Partial<ArgvSecrets> = {}): string {
+    const secretFlags = secrets.flags ?? [];
+    let out = redactSecretsInText(text).replace(/(--?[\w-]+)=([^\s'"`]+)/g, (whole, flag: string) =>
+        SECRET_FLAG.test(flag) || secretFlags.includes(flag) ? `${flag}=[redacted]` : whole
+    );
+
+    for (const value of secretValues(args, secrets)) {
+        out = out.split(value).join("[redacted]");
+    }
+
+    return out;
+}
+
+interface OptionNode {
+    short?: string;
+    long?: string;
+    /** `<value>`: the next word is the value, even one that starts with a dash. */
+    required?: boolean;
+    /** `[value]`: the next word is the value unless it starts with a dash. */
+    optional?: boolean;
+}
+
+interface ArgumentNode {
+    name(): string;
+    variadic?: boolean;
+}
+
 interface CommandNode {
     name(): string;
     aliases(): string[];
     readonly commands: readonly CommandNode[];
+    readonly options: readonly OptionNode[];
+    readonly registeredArguments?: readonly ArgumentNode[];
 }
 
-/** `ai usage sessions` for `tools ai usage sessions --bad`: the deepest subcommand the leading words name. */
-export function commandPathFromArgv(program: CommandNode, args: readonly string[]): string {
-    const names = [program.name()];
-    let current = program;
+function isSecretOption(option: OptionNode): boolean {
+    return option.long !== undefined && SECRET_FLAG.test(option.long);
+}
 
-    for (const word of args) {
-        if (word.startsWith("-")) {
-            break;
+/** The option a flag word ends with, and whether its value is the next word. Null for a flag no command declares. */
+function flagOption(word: string, chain: readonly CommandNode[]): { option: OptionNode; valueNext: boolean } | null {
+    const find = (flag: string) =>
+        chain.flatMap((command) => command.options).find((option) => option.short === flag || option.long === flag);
+
+    if (word.startsWith("--")) {
+        const option = find(word.split("=")[0]);
+        return option ? { option, valueNext: !word.includes("=") } : null;
+    }
+
+    // `-vt` is `-v -t` until one flag takes a value; the rest of the word is then that value.
+    for (let at = 1; at < word.length; at++) {
+        const option = find(`-${word[at]}`);
+        if (!option) {
+            return null;
         }
 
-        const next = current.commands.find((command) => command.name() === word || command.aliases().includes(word));
-        if (!next) {
+        if (option.required || option.optional || at === word.length - 1) {
+            return { option, valueNext: at === word.length - 1 };
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Reads `args` the way commander does: options of every command reached so far may come anywhere (`-v` before the
+ * subcommand), an option's value is skipped, and the first operand that names no subcommand ends the chain. Stops at
+ * a flag no command declares, since commander refuses that line and what follows has no known shape.
+ */
+function walkArgv(program: CommandNode, args: readonly string[]): { chain: CommandNode[]; secretIndexes: number[] } {
+    const chain = [program];
+    const secretIndexes: number[] = [];
+    const operands: number[] = [];
+    let commandsDone = false;
+
+    for (let index = 0; index < args.length; index++) {
+        const word = args[index];
+        if (word === "--") {
+            for (let rest = index + 1; rest < args.length; rest++) {
+                operands.push(rest);
+            }
+
             break;
         }
 
-        names.push(next.name());
-        current = next;
+        if (word.startsWith("-") && word !== "-") {
+            const found = flagOption(word, chain);
+            if (!found) {
+                break;
+            }
+
+            const next = args[index + 1];
+            const { option } = found;
+            if (
+                found.valueNext &&
+                next !== undefined &&
+                (option.required || (option.optional && !next.startsWith("-")))
+            ) {
+                index++;
+                if (isSecretOption(option)) {
+                    secretIndexes.push(index);
+                }
+            }
+
+            continue;
+        }
+
+        if (!commandsDone) {
+            const current = chain[chain.length - 1];
+            const sub = current.commands.find((command) => command.name() === word || command.aliases().includes(word));
+            if (sub) {
+                chain.push(sub);
+                continue;
+            }
+
+            commandsDone = true;
+        }
+
+        operands.push(index);
     }
 
-    return names.join(" ");
+    const declared = chain[chain.length - 1].registeredArguments ?? [];
+    const last = declared[declared.length - 1];
+    operands.forEach((argIndex, position) => {
+        const argument = position < declared.length ? declared[position] : last?.variadic ? last : undefined;
+        if (argument && SECRET_ARGUMENT.test(argument.name())) {
+            secretIndexes.push(argIndex);
+        }
+    });
+
+    return { chain, secretIndexes };
+}
+
+/** `ai usage sessions` for `tools ai usage sessions --bad`: the deepest subcommand the words name. */
+export function commandPathFromArgv(program: CommandNode, args: readonly string[]): string {
+    return walkArgv(program, args)
+        .chain.map((command) => command.name())
+        .join(" ");
+}
+
+/**
+ * The flags of every secret-named option on the commands `args` reaches (`-t` for `--token`), and the argv
+ * indexes of their values and of a secret-named argument's value (`<path> [secret]`).
+ */
+export function secretsFromArgv(program: CommandNode, args: readonly string[]): ArgvSecrets {
+    const { chain, secretIndexes } = walkArgv(program, args);
+    return {
+        flags: chain.flatMap((command) =>
+            command.options
+                .filter(isSecretOption)
+                .flatMap((option) => [option.short, option.long].filter((flag): flag is string => flag !== undefined))
+        ),
+        indexes: secretIndexes,
+    };
 }
 
 /** What a run that ends with `exitCode` was. Null when it is not a failure. */
@@ -247,7 +422,9 @@ function write(kind: FailureKind, exitCode: number | null, fatal: boolean): void
     try {
         const error = run.noted?.error;
         const err = error instanceof Error ? error : null;
-        const tail = redactSecretsInText(stripAnsi(run.stderr)).trim();
+        const secrets = run.secrets();
+        const redact = (text: string) => redactRunText(text, run?.argv ?? [], secrets);
+        const tail = redact(stripAnsi(run.stderr)).trim();
         const message = err
             ? err.message
             : error !== undefined && error !== null
@@ -260,11 +437,11 @@ function write(kind: FailureKind, exitCode: number | null, fatal: boolean): void
             kind,
             tool: run.tool,
             command: run.commandPath()?.replace(/^tools /, "") ?? null,
-            argv: redactArgv(run.argv),
+            argv: redactArgv(run.argv, secrets),
             exitCode,
-            message: message ? redactSecretsInText(stripAnsi(message)).slice(0, 2000) : null,
+            message: message ? redact(stripAnsi(message)).slice(0, 2000) : null,
             errorName: err?.name ?? null,
-            stack: err?.stack ? redactSecretsInText(err.stack).slice(0, 8000) : null,
+            stack: err?.stack ? redact(err.stack).slice(0, 8000) : null,
             stderrTail: tail || null,
             fatal,
             durationMs: Math.round(performance.now()),
@@ -287,6 +464,12 @@ function finish(code: number): void {
     }
 
     run.ended = true;
+    // A crash another listener took is still pending here when that listener ended the process (ai-proxy's
+    // `process.exit(1)`): it was fatal after all, and it is the cause of this exit.
+    if (run.noted?.kind === "crash") {
+        run.noted = { ...run.noted, fatal: true };
+    }
+
     const exitCode = code || (typeof process.exitCode === "number" ? process.exitCode : 0);
     const kind = classifyExit({ exitCode, noted: run.noted, stderrTail: stripAnsi(run.stderr) });
     if (kind) {
@@ -294,16 +477,24 @@ function finish(code: number): void {
     }
 }
 
-/** A crash some other listener handles: the process goes on, so it is written now, not at exit. */
+/**
+ * A crash. One some other listener handles is written once that listener has returned and the process went on;
+ * a listener that ends the process instead leaves it to the exit hook, which writes it as the fatal cause.
+ */
 function noteCrash(error: unknown, fatal: boolean): void {
     if (!run) {
         return;
     }
 
-    run.noted = { kind: "crash", error, fatal };
+    const noted: Noted = { kind: "crash", error, fatal };
+    run.noted = noted;
     if (!fatal) {
-        write("crash", null, false);
-        run.noted = null;
+        setImmediate(() => {
+            if (run && !run.ended && run.noted === noted) {
+                write("crash", null, false);
+                run.noted = null;
+            }
+        });
     }
 }
 
@@ -336,25 +527,29 @@ export function noteToolError(error: unknown): void {
 
 /**
  * Records every failed run of this process into `~/.genesis-tools/logs/<date>-failures.jsonl`: a usage error, a
- * thrown action, a crash, a plain non-zero exit, an interrupt. `runTool` calls it; an entry point without commander
+ * thrown action, a crash, a plain non-zero exit, an interrupt the tool handles itself (exit 130 or 143). A run the
+ * default SIGINT or SIGTERM action ends is not recorded: that action skips the exit event, and a JS signal handler
+ * would make a synchronous tool unkillable (interrupt.ts). `runTool` calls it; an entry point without commander
  * calls it itself. Once per process; only a real CLI run, never a test that passes its own argv.
  */
 export function watchToolRun({
     tool,
     argv = process.argv.slice(2),
     commandPath = () => null,
+    secrets = () => ({ flags: [], indexes: [] }),
     caller = agentCaller,
 }: {
     tool: string;
     argv?: string[];
     commandPath?: () => string | null;
+    secrets?: () => ArgvSecrets;
     caller?: () => FailureCaller | null;
 }): void {
     if (run) {
         return;
     }
 
-    run = { tool, argv, commandPath, caller, stderr: "", stdout: "", noted: null, ended: false };
+    run = { tool, argv, commandPath, secrets, caller, stderr: "", stdout: "", noted: null, ended: false };
     tapStderr();
     process.on("uncaughtExceptionMonitor", (error) => {
         noteCrash(error, process.listenerCount("uncaughtException") === 0);
diff --git a/src/utils/compress/compress.test.ts b/src/utils/compress/compress.test.ts
index 96cb88d8a8..87d6c6e327 100644
--- a/src/utils/compress/compress.test.ts
+++ b/src/utils/compress/compress.test.ts
@@ -664,6 +664,15 @@ describe("day logs", () => {
         expect(zstRun.stdout).toBe(plainRun.stdout);
         expect(zstRun.stdout.split("\n").filter(Boolean)).toHaveLength(2);
         expect(both.stdout).toBe(plainRun.stdout + zstRun.stdout);
+        const streamed: string[] = [];
+        const lineRun = await ripgrepFiles({
+            rg: ripgrepBinary()!,
+            args,
+            files: [plain, `${twin}.zst`],
+            onLine: (line) => streamed.push(line),
+        });
+        expect(lineRun.stdout).toBe("");
+        expect(streamed.sort()).toEqual(both.stdout.split("\n").filter(Boolean).sort());
         expect(absent.code).toBe(1);
     });
 });
diff --git a/src/utils/compress/search.ts b/src/utils/compress/search.ts
index 481b9034b3..f38d59d6e0 100644
--- a/src/utils/compress/search.ts
+++ b/src/utils/compress/search.ts
@@ -30,6 +30,7 @@ export function zstdContentStream(path: string, concurrency = FRAMES_AHEAD): Rea
 }
 
 export interface RipgrepRun {
+    /** Empty when the caller took each line through `onLine`. */
     stdout: string;
     stderr: string;
     /** The worst exit code of the runs (rg exits 1 when nothing matched). */
@@ -37,16 +38,37 @@ export interface RipgrepRun {
     signal: string | null;
 }
 
+/** Hands each line of `stream` to `onLine` as it arrives, so no more than one chunk of it is held at a time. */
+async function eachLine(stream: ReadableStream<Uint8Array>, onLine: (line: string) => void): Promise<void> {
+    const decoder = new TextDecoder();
+    let rest = "";
+
+    for await (const chunk of stream) {
+        const lines = (rest + decoder.decode(chunk, { stream: true })).split("\n");
+        rest = lines.pop() ?? "";
+        for (const line of lines) {
+            onLine(line);
+        }
+    }
+
+    rest += decoder.decode();
+    if (rest) {
+        onLine(rest);
+    }
+}
+
 async function runOne({
     rg,
     args,
     timeoutMs,
     zst,
+    onLine,
 }: {
     rg: string;
     args: string[];
     timeoutMs?: number;
     zst?: string;
+    onLine?: (line: string) => void;
 }): Promise<RipgrepRun> {
     const proc = Bun.spawn(zst ? [rg, ...args, "-"] : [rg, ...args], {
         stdin: zst ? zstdContentStream(zst) : "ignore",
@@ -54,7 +76,10 @@ async function runOne({
         stderr: "pipe",
         timeout: timeoutMs,
     });
-    const output = Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
+    const output = Promise.all([
+        onLine ? eachLine(proc.stdout, onLine).then(() => "") : new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+    ]);
 
     const [[stdout, stderr], code] = await Promise.all([output, proc.exited]);
     return { stdout, stderr, code, signal: proc.signalCode ?? null };
@@ -64,18 +89,21 @@ async function runOne({
  * Runs ripgrep with `args` over files that may be plain or `.zst`: one rg over all the plain files (they stay
  * arguments, so rg maps them as before) and, at the same time, one rg per `.zst` file fed its decompressed frames on
  * stdin. Needs no `zstd` CLI (unlike `rg -z`). Use `--no-filename` in `args`: stdin has no file name. The outputs are
- * joined, plain files first.
+ * joined, plain files first. With `onLine`, each output line goes there as it arrives (the runs interleave) and
+ * `stdout` stays empty, so a caller that keeps only some lines never holds the whole output.
  */
 export async function ripgrepFiles({
     rg,
     args,
     files,
     timeoutMs,
+    onLine,
 }: {
     rg: string;
     args: string[];
     files: string[];
     timeoutMs?: number;
+    onLine?: (line: string) => void;
 }): Promise<RipgrepRun> {
     const plain = files.filter((file) => !isZstdPath(file));
     const compressed = files.filter(isZstdPath);
@@ -84,13 +112,13 @@ export async function ripgrepFiles({
         const results: RipgrepRun[] = [];
 
         for (const zst of compressed) {
-            results.push(await runOne({ rg, args, timeoutMs, zst }));
+            results.push(await runOne({ rg, args, timeoutMs, zst, onLine }));
         }
 
         return results;
     })();
     const runs = [
-        ...(plain.length > 0 ? [await runOne({ rg, args: [...args, "--", ...plain], timeoutMs })] : []),
+        ...(plain.length > 0 ? [await runOne({ rg, args: [...args, "--", ...plain], timeoutMs, onLine })] : []),
         ...(await zstRuns),
     ];
 

From c15e51ca10df8aa3d1b0ba36068cd33eb6f8d9f1 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 22:48:37 +0200
Subject: [PATCH 26/30] feat(tools): #559 followup - the tools wrapper records
 a spawned tool that a signal killed, once, as interrupt or crash with the
 argv withheld

---
 src/genesis-tools/README.md             |   6 +
 src/utils/cli/failures/failures.test.ts | 152 ++++++++++++++++++++
 src/utils/cli/failures/launcher.ts      | 182 ++++++++++++++++++++++++
 src/utils/cli/failures/record.ts        |   5 +-
 src/utils/cli/failures/run-id.ts        |  16 +++
 src/utils/cli/failures/watch.ts         |  29 +++-
 tools                                   |  65 ++++++++-
 7 files changed, 442 insertions(+), 13 deletions(-)
 create mode 100644 src/utils/cli/failures/launcher.ts
 create mode 100644 src/utils/cli/failures/run-id.ts

diff --git a/src/genesis-tools/README.md b/src/genesis-tools/README.md
index 9ca1a7bbec..bbe05e9439 100644
--- a/src/genesis-tools/README.md
+++ b/src/genesis-tools/README.md
@@ -16,6 +16,12 @@ JSON line per failed run to `~/.genesis-tools/logs/<date>-failures.jsonl`
 | `exit` | a non-zero exit with none of the above (the tool printed its own message) |
 | `interrupt` | Ctrl-C or SIGTERM (130, 143), often a harness timeout; hidden unless `--interrupts` |
 
+A run the default signal action kills never reaches its own watcher. When the `tools` wrapper spawned the tool and
+waited for it, the wrapper writes that record (`src/utils/cli/failures/launcher.ts`): `interrupt` for SIGINT, SIGTERM,
+SIGHUP, SIGQUIT and SIGKILL, `crash` for a fault signal (SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGABRT, SIGTRAP). The
+wrapper has no command definition, so the arguments read `[withheld]` and the command is empty. A run the wrapper
+exec'd into (the default) has no waiting parent, so its signal death stays unrecorded.
+
 Each record carries the tool, the command path, the arguments with secrets masked, the exit code, the message, the
 stack, the last 4 KB of stderr, the cwd, the pid, the run time, the app trace id when GenesisTools.app started it, the
 checkout that ran it, and the caller: agent (Claude Code, Codex, Grok, Copilot, or a shell), session id and title,
diff --git a/src/utils/cli/failures/failures.test.ts b/src/utils/cli/failures/failures.test.ts
index 0a0e0d75c6..5190227423 100644
--- a/src/utils/cli/failures/failures.test.ts
+++ b/src/utils/cli/failures/failures.test.ts
@@ -5,7 +5,9 @@ import { join } from "node:path";
 import { formatLocalDate } from "@genesiscz/utils/date";
 import { Command } from "commander";
 import { claudeProjectFolder, modelInTranscriptLines } from "./caller";
+import { recordSignalEnd, signalEnd, signalOfStatus, WITHHELD_ARGV } from "./launcher";
 import { appendFailure, readFailures, type ToolFailure } from "./record";
+import { RUN_ID_ENV } from "./run-id";
 import {
     classifyExit,
     commandPathFromArgv,
@@ -273,3 +275,153 @@ describe("a crash another uncaughtException listener takes", () => {
         expect(crashWith("")).toEqual([["crash", false, null, "fixture crash"]]);
     });
 });
+
+describe("signalEnd", () => {
+    const direct = { status: null, viaLauncher: false };
+
+    it("records an outside signal as an interrupt and a fault signal as a crash", () => {
+        expect(signalEnd({ signal: "SIGINT", ...direct })).toEqual({
+            kind: "interrupt",
+            signal: "SIGINT",
+            exitCode: 130,
+        });
+        expect(signalEnd({ signal: "SIGTERM", ...direct })?.kind).toBe("interrupt");
+        expect(signalEnd({ signal: "SIGHUP", ...direct })?.kind).toBe("interrupt");
+        expect(signalEnd({ signal: "SIGKILL", ...direct })).toEqual({
+            kind: "interrupt",
+            signal: "SIGKILL",
+            exitCode: 137,
+        });
+        expect(signalEnd({ signal: "SIGSEGV", ...direct })?.kind).toBe("crash");
+        expect(signalEnd({ signal: "SIGABRT", ...direct })?.kind).toBe("crash");
+    });
+
+    it("is no failure for a signal that ends a run normally", () => {
+        expect(signalEnd({ signal: "SIGPIPE", ...direct })).toBeNull();
+        expect(signalEnd({ signal: null, ...direct })).toBeNull();
+    });
+
+    it("reads 128 + n as a signal only from the GenesisTools.app launcher", () => {
+        expect(signalEnd({ signal: null, status: 143, viaLauncher: true })).toEqual({
+            kind: "interrupt",
+            signal: "SIGTERM",
+            exitCode: 143,
+        });
+        expect(signalEnd({ signal: null, status: 134, viaLauncher: true })?.kind).toBe("crash");
+        expect(signalEnd({ signal: null, status: 143, viaLauncher: false })).toBeNull();
+        expect(signalEnd({ signal: null, status: 1, viaLauncher: true })).toBeNull();
+        expect(signalOfStatus(128)).toBeNull();
+        expect(signalOfStatus(130)).toBe("SIGINT");
+    });
+});
+
+describe("recordSignalEnd", () => {
+    const at = new Date(2026, 9, 22, 12);
+    const end = (dir: string, runId: string, overrides: { signal?: string | null; status?: number | null } = {}) =>
+        recordSignalEnd({
+            tool: "fixture",
+            runId,
+            startedAt: new Date(at.getTime() - 5000),
+            signal: overrides.signal === undefined ? "SIGINT" : overrides.signal,
+            status: overrides.status ?? null,
+            viaLauncher: true,
+            childPid: 4242,
+            toolsRoot: "/repo",
+            caller: () => null,
+            now: at,
+            dir,
+        });
+    const all = (dir: string) => [...readFailures({ fromDay: "2026-10-22", toDay: "2026-10-22", dir })];
+
+    it("writes one record with the argv withheld, no command and the signal named", () => {
+        const dir = mkdtempSync(join(tmpdir(), "gt-failures-signal-"));
+        const written = end(dir, "run-a");
+        expect(written).toMatchObject({
+            kind: "interrupt",
+            tool: "fixture",
+            command: null,
+            argv: WITHHELD_ARGV,
+            exitCode: 130,
+            message: "ended by SIGINT",
+            stderrTail: null,
+            pid: 4242,
+            durationMs: 5000,
+            runId: "run-a",
+        });
+        expect(all(dir)).toEqual([written as ToolFailure]);
+    });
+
+    it("writes nothing when the tool already recorded this run, and still writes for another run", () => {
+        const dir = mkdtempSync(join(tmpdir(), "gt-failures-signal-"));
+        const own: ToolFailure = {
+            v: 1,
+            id: "own-1",
+            at: at.toISOString(),
+            kind: "interrupt",
+            tool: "fixture",
+            command: "fixture run",
+            argv: ["run"],
+            exitCode: 130,
+            message: null,
+            errorName: null,
+            stack: null,
+            stderrTail: null,
+            fatal: true,
+            durationMs: 10,
+            pid: 4243,
+            ppid: 4242,
+            cwd: "/repo",
+            traceId: null,
+            toolsRoot: "/repo",
+            caller: null,
+            runId: "run-b",
+        };
+        appendFailure(own, dir);
+
+        expect(end(dir, "run-b", { signal: null, status: 130 })).toBeNull();
+        expect(end(dir, "run-c", { signal: null, status: 130 })?.message).toBe(
+            "ended by SIGINT (exit 130 from the GenesisTools.app launcher)"
+        );
+        expect(all(dir).map((failure) => failure.runId)).toEqual(["run-b", "run-c"]);
+    });
+});
+
+describe("a tool that handles its own interrupt under the tools wrapper", () => {
+    it("records the wrapper's run id, hides it from child tools, and the wrapper adds no second record", () => {
+        const home = mkdtempSync(join(tmpdir(), "gt-failures-runid-"));
+        const script = [
+            `import { watchToolRun } from "${join(import.meta.dir, "watch.ts")}";`,
+            `watchToolRun({ tool: "fixture", argv: ["run"], caller: () => null });`,
+            `process.stdout.write(process.env.${RUN_ID_ENV} ?? "gone");`,
+            "process.exit(130);",
+        ].join("\n");
+        const startedAt = new Date();
+        const child = Bun.spawnSync([process.execPath, "-e", script], {
+            env: { ...process.env, GENESIS_TOOLS_HOME: home, [RUN_ID_ENV]: "run-wrapped" },
+            stdout: "pipe",
+            stderr: "ignore",
+        });
+        const dir = join(home, ".genesis-tools", "logs");
+        const read = () =>
+            [...readFailures({ fromDay: formatLocalDate(startedAt), toDay: formatLocalDate(new Date()), dir })].map(
+                (record) => [record.kind, record.exitCode, record.runId]
+            );
+
+        expect(child.stdout.toString()).toBe("gone");
+        expect(read()).toEqual([["interrupt", 130, "run-wrapped"]]);
+        const second = recordSignalEnd({
+            tool: "fixture",
+            runId: "run-wrapped",
+            startedAt,
+            signal: null,
+            status: child.exitCode,
+            viaLauncher: true,
+            childPid: child.pid,
+            toolsRoot: "/repo",
+            caller: () => null,
+            dir,
+        });
+        expect(second).toBeNull();
+        expect(read()).toHaveLength(1);
+    });
+});
diff --git a/src/utils/cli/failures/launcher.ts b/src/utils/cli/failures/launcher.ts
new file mode 100644
index 0000000000..2a051a32bc
--- /dev/null
+++ b/src/utils/cli/failures/launcher.ts
@@ -0,0 +1,182 @@
+import { constants } from "node:os";
+import { formatLocalDate } from "@genesiscz/utils/date";
+import { logger } from "@genesiscz/utils/logger";
+import { currentTraceId } from "@genesiscz/utils/trace";
+import {
+    appendFailure,
+    type FailureCaller,
+    type FailureKind,
+    failuresDir,
+    readFailures,
+    type ToolFailure,
+} from "./record";
+import { agentCaller } from "./watch";
+
+/**
+ * A run the default SIGINT or SIGTERM action kills never reaches the tool's exit event, so watch.ts cannot record it.
+ * The `tools` wrapper records it instead, when it spawned the tool and waited for it. When the wrapper exec'd into
+ * the tool (the default, tool-exec.ts), no parent of ours is left to see the death, and such a run stays unrecorded.
+ *
+ * - `crash`: a signal a process raises on itself when it faults (a segfault, a Bun panic's abort or trap). The
+ *   runtime died, which is a bug.
+ * - `interrupt`: a signal sent from outside: Ctrl-C, a harness timeout's SIGTERM, a hangup, and also SIGKILL, which
+ *   is most often that timeout's escalation, `kill -9` or the orphan watchdog, not a fault of the tool.
+ * - Anything else (SIGPIPE from `tools x | head`, SIGUSR1) is a normal end, not a failure.
+ */
+const CRASH_SIGNALS: ReadonlySet<string> = new Set(["SIGSEGV", "SIGBUS", "SIGILL", "SIGFPE", "SIGABRT", "SIGTRAP"]);
+const INTERRUPT_SIGNALS: ReadonlySet<string> = new Set(["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT", "SIGKILL"]);
+
+/** The launcher has no command definition, so it cannot tell a secret argument from a plain one. */
+export const WITHHELD_ARGV = ["[withheld]"];
+
+const SIGNAL_NUMBERS: ReadonlyMap<string, number> = new Map(Object.entries(constants.signals));
+
+export interface SignalEnd {
+    kind: FailureKind;
+    signal: string;
+    /** The status the wrapper exits with: the launcher's own, or 128 + the signal number. */
+    exitCode: number;
+}
+
+/** The signal an exit status of 128 + n names, on this platform's numbering. */
+export function signalOfStatus(status: number): string | null {
+    const number = status - 128;
+    if (number <= 0) {
+        return null;
+    }
+
+    return [...SIGNAL_NUMBERS].find(([, value]) => value === number)?.[0] ?? null;
+}
+
+/**
+ * Whether a child's end is a signal death to record, and as what. `signal` is what Node reports for a child the
+ * signal killed. `status` counts only when the child is the GenesisTools.app launcher (`viaLauncher`): it exits
+ * 128 + n when its own child died of signal n. From a plain bun child, a status is the tool's own exit, which its
+ * watcher already judged.
+ */
+export function signalEnd({
+    signal,
+    status,
+    viaLauncher,
+}: {
+    signal: string | null;
+    status: number | null;
+    viaLauncher: boolean;
+}): SignalEnd | null {
+    const name = signal ?? (viaLauncher && status !== null ? signalOfStatus(status) : null);
+    if (!name) {
+        return null;
+    }
+
+    const kind: FailureKind | null = CRASH_SIGNALS.has(name)
+        ? "crash"
+        : INTERRUPT_SIGNALS.has(name)
+          ? "interrupt"
+          : null;
+    if (!kind) {
+        return null;
+    }
+
+    const exitCode = signal === null && status !== null ? status : 128 + (SIGNAL_NUMBERS.get(name) ?? 0);
+    return { kind, signal: name, exitCode };
+}
+
+/**
+ * Whether the tool itself already wrote a record for this run. It did when it handled the signal and exited 130 or
+ * 143, which the launcher then reports exactly like a signal death. The wrapper hands each spawned tool a run id
+ * (run-id.ts) and the watcher copies it into its record: a pid would not do, since the launcher sits between the
+ * wrapper and the tool, and a plain "last record" check would race other tools writing the same day file.
+ */
+export function childRecorded({
+    runId,
+    since,
+    now,
+    dir,
+}: {
+    runId: string;
+    since: Date;
+    now: Date;
+    dir: string;
+}): boolean {
+    for (const failure of readFailures({ fromDay: formatLocalDate(since), toDay: formatLocalDate(now), dir })) {
+        if (failure.runId === runId) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+function callerOrNull(caller: () => FailureCaller | null): FailureCaller | null {
+    try {
+        return caller();
+    } catch (error) {
+        logger.debug({ error }, "failures: no caller context for a signal death");
+        return null;
+    }
+}
+
+/**
+ * Records a spawned tool's signal death once: nothing when the end was no failure or the tool already recorded it.
+ * Returns the written record, or null.
+ */
+export function recordSignalEnd({
+    tool,
+    runId,
+    startedAt,
+    signal,
+    status,
+    viaLauncher,
+    childPid,
+    toolsRoot,
+    caller = agentCaller,
+    now = new Date(),
+    dir = failuresDir(),
+}: {
+    tool: string;
+    runId: string;
+    startedAt: Date;
+    signal: string | null;
+    status: number | null;
+    viaLauncher: boolean;
+    childPid: number;
+    toolsRoot: string;
+    caller?: () => FailureCaller | null;
+    now?: Date;
+    dir?: string;
+}): ToolFailure | null {
+    const end = signalEnd({ signal, status, viaLauncher });
+    if (!end || childRecorded({ runId, since: startedAt, now, dir })) {
+        return null;
+    }
+
+    const failure: ToolFailure = {
+        v: 1,
+        id: `${now.getTime().toString(36)}-${process.pid}`,
+        at: now.toISOString(),
+        kind: end.kind,
+        tool,
+        command: null,
+        argv: WITHHELD_ARGV,
+        exitCode: end.exitCode,
+        message:
+            signal === null
+                ? `ended by ${end.signal} (exit ${end.exitCode} from the GenesisTools.app launcher)`
+                : `ended by ${end.signal}`,
+        errorName: null,
+        stack: null,
+        // stderr may echo an argument; without the command definition the launcher cannot mask it reliably.
+        stderrTail: null,
+        fatal: true,
+        durationMs: now.getTime() - startedAt.getTime(),
+        pid: childPid,
+        ppid: process.pid,
+        cwd: process.cwd(),
+        traceId: currentTraceId() ?? null,
+        toolsRoot,
+        caller: callerOrNull(caller),
+        runId,
+    };
+    appendFailure(failure, dir);
+    return failure;
+}
diff --git a/src/utils/cli/failures/record.ts b/src/utils/cli/failures/record.ts
index 2f5d121de1..4d7a0abc37 100644
--- a/src/utils/cli/failures/record.ts
+++ b/src/utils/cli/failures/record.ts
@@ -12,7 +12,8 @@ import { genesisToolsDir } from "@genesiscz/utils/storage/root";
  * - `error`: the tool's action threw and runTool printed `ERROR: …`.
  * - `crash`: an uncaught exception or an unhandled rejection; `fatal` says whether it ended the process.
  * - `exit`: a non-zero exit with none of the above (the tool printed its own message and exited 1).
- * - `interrupt`: Ctrl-C or SIGTERM (130 / 143); often a harness timeout rather than a bug.
+ * - `interrupt`: Ctrl-C or SIGTERM (130 / 143); often a harness timeout rather than a bug. The `tools` wrapper also
+ *   writes it for a spawned tool a signal killed (launcher.ts), and `crash` for one that died of a fault signal.
  */
 export const FAILURE_KINDS = ["usage", "error", "crash", "exit", "interrupt"] as const;
 export type FailureKind = (typeof FAILURE_KINDS)[number];
@@ -59,6 +60,8 @@ export interface ToolFailure {
     /** The GenesisTools checkout that ran the tool: the main one or a worktree. */
     toolsRoot: string;
     caller: FailureCaller | null;
+    /** The `tools` wrapper's id for a run it spawned (run-id.ts); absent when the wrapper exec'd into the tool. */
+    runId?: string;
 }
 
 const FILE = /^(\d{4}-\d{2}-\d{2})-failures\.jsonl$/;
diff --git a/src/utils/cli/failures/run-id.ts b/src/utils/cli/failures/run-id.ts
new file mode 100644
index 0000000000..569ba6dcae
--- /dev/null
+++ b/src/utils/cli/failures/run-id.ts
@@ -0,0 +1,16 @@
+/**
+ * Set by the `tools` wrapper on a tool it spawns and waits for: the id of that one run. The tool's failure watcher
+ * copies it into any record it writes, so the wrapper can tell whether the tool already recorded its own end before
+ * it records a signal death itself (launcher.ts). Kept tiny: the wrapper imports it on every run.
+ */
+export const RUN_ID_ENV = "GENESIS_TOOLS_RUN_ID";
+
+/**
+ * The run id the wrapper gave this process. It is removed from the env, so a tool this one starts does not write
+ * records under the same id and make the wrapper skip a signal death it should record.
+ */
+export function takeRunId(processEnv: Record<string, string | undefined>): string | undefined {
+    const runId = processEnv[RUN_ID_ENV]?.trim() || undefined;
+    delete processEnv[RUN_ID_ENV];
+    return runId;
+}
diff --git a/src/utils/cli/failures/watch.ts b/src/utils/cli/failures/watch.ts
index b9286cf050..4b1104faa4 100644
--- a/src/utils/cli/failures/watch.ts
+++ b/src/utils/cli/failures/watch.ts
@@ -7,6 +7,7 @@ import { stripAnsi } from "@genesiscz/utils/string";
 import { currentTraceId } from "@genesiscz/utils/trace";
 import { redactSecretsInText } from "@genesiscz/utils/transclude/redact";
 import { appendFailure, type FailureCaller, type FailureKind, type ToolFailure } from "./record";
+import { takeRunId } from "./run-id";
 
 const TAIL_CHARS = 4000;
 const TOOLS_ROOT = resolve(moduleDir(import.meta), "../../../..");
@@ -37,6 +38,8 @@ interface Run {
     stdout: string;
     noted: Noted | null;
     ended: boolean;
+    /** The `tools` wrapper's id for this run, copied into every record so the wrapper never records it twice. */
+    runId: string | undefined;
 }
 
 let run: Run | null = null;
@@ -394,7 +397,7 @@ function tapStderr(): void {
  * run time so neither a bundler nor the type checker follows it into the agent runtime. A copy of these helpers
  * without that module records failures with no caller.
  */
-function agentCaller(): FailureCaller | null {
+export function agentCaller(): FailureCaller | null {
     const loaded: unknown = requireSibling(import.meta, "agent-caller");
     const lookup = (loaded as { agentFailureCaller?: unknown } | null)?.agentFailureCaller;
     if (typeof lookup !== "function") {
@@ -451,6 +454,7 @@ function write(kind: FailureKind, exitCode: number | null, fatal: boolean): void
             traceId: currentTraceId() ?? null,
             toolsRoot: TOOLS_ROOT,
             caller: caller(),
+            ...(run.runId ? { runId: run.runId } : {}),
         };
         appendFailure(failure);
     } catch (writeError) {
@@ -528,9 +532,10 @@ export function noteToolError(error: unknown): void {
 /**
  * Records every failed run of this process into `~/.genesis-tools/logs/<date>-failures.jsonl`: a usage error, a
  * thrown action, a crash, a plain non-zero exit, an interrupt the tool handles itself (exit 130 or 143). A run the
- * default SIGINT or SIGTERM action ends is not recorded: that action skips the exit event, and a JS signal handler
- * would make a synchronous tool unkillable (interrupt.ts). `runTool` calls it; an entry point without commander
- * calls it itself. Once per process; only a real CLI run, never a test that passes its own argv.
+ * default SIGINT or SIGTERM action ends never reaches the exit event, and a JS signal handler would make a
+ * synchronous tool unkillable (interrupt.ts); the `tools` wrapper records that death when it waits for the tool
+ * (launcher.ts). `runTool` calls it; an entry point without commander calls it itself. Once per process; only a
+ * real CLI run, never a test that passes its own argv.
  */
 export function watchToolRun({
     tool,
@@ -538,18 +543,32 @@ export function watchToolRun({
     commandPath = () => null,
     secrets = () => ({ flags: [], indexes: [] }),
     caller = agentCaller,
+    runId,
 }: {
     tool: string;
     argv?: string[];
     commandPath?: () => string | null;
     secrets?: () => ArgvSecrets;
     caller?: () => FailureCaller | null;
+    /** Defaults to the wrapper's id from the env (run-id.ts), which is then removed so child tools do not inherit it. */
+    runId?: string;
 }): void {
     if (run) {
         return;
     }
 
-    run = { tool, argv, commandPath, secrets, caller, stderr: "", stdout: "", noted: null, ended: false };
+    run = {
+        tool,
+        argv,
+        commandPath,
+        secrets,
+        caller,
+        stderr: "",
+        stdout: "",
+        noted: null,
+        ended: false,
+        runId: runId ?? takeRunId(process.env),
+    };
     tapStderr();
     process.on("uncaughtExceptionMonitor", (error) => {
         noteCrash(error, process.listenerCount("uncaughtException") === 0);
diff --git a/tools b/tools
index 4eeb990651..016cf6f1b9 100755
--- a/tools
+++ b/tools
@@ -5,6 +5,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { namedBunExecPath } from "@genesiscz/utils/cli/bun-link";
 import { takeDetachedMarker } from "@genesiscz/utils/cli/detached";
+import { RUN_ID_ENV } from "@genesiscz/utils/cli/failures/run-id";
 import { planToolExec, terminateOrphanedChild } from "@genesiscz/utils/cli/tool-exec";
 import { skipWorktreeInstall } from "@genesiscz/utils/cli/worktree-install";
 import { env } from "@genesiscz/utils/env";
@@ -273,13 +274,19 @@ async function executeTool(scriptId, scriptArgs) {
     const exitCode = await runWithReinstallGuard(
         ["--preload", solidPreload, "--preload", sqliteVecPreload, targetScript, ...scriptArgs],
         workspaceRoot,
-        namedBunExecPath(scriptId)
+        namedBunExecPath(scriptId),
+        scriptId
     );
     process.exit(exitCode);
 }
 
-async function runWithReinstallGuard(args: string[], workspaceRoot: string, execPath: string): Promise<number> {
-    const exitCode = await spawnAndCaptureStderr(args, workspaceRoot, execPath);
+async function runWithReinstallGuard(
+    args: string[],
+    workspaceRoot: string,
+    execPath: string,
+    tool: string
+): Promise<number> {
+    const exitCode = await spawnAndCaptureStderr(args, workspaceRoot, execPath, tool);
 
     if (exitCode === 0) {
         return 0;
@@ -326,7 +333,12 @@ async function runWithReinstallGuard(args: string[], workspaceRoot: string, exec
 
 let capturedStderr = "";
 
-async function spawnAndCaptureStderr(args: string[], workspaceRoot: string, execPath: string): Promise<number> {
+async function spawnAndCaptureStderr(
+    args: string[],
+    workspaceRoot: string,
+    execPath: string,
+    tool: string
+): Promise<number> {
     capturedStderr = "";
     const TAIL_BYTES = 64 * 1024;
 
@@ -338,6 +350,8 @@ async function spawnAndCaptureStderr(args: string[], workspaceRoot: string, exec
     // spawnToolDetached (a dashboard a link click starts) is orphaned on purpose; see DETACHED_ENV.
     const detached = takeDetachedMarker(process.env);
     const childEnv = env.withoutProxy({ INIT_CWD: process.cwd() });
+    // An id inherited from an outer wrapper would make that wrapper take this run's records for its own.
+    delete childEnv[RUN_ID_ENV];
     // Replace this wrapper with the launcher (or, under an app face, the worker) instead of waiting
     // as its parent; see src/utils/cli/tool-exec.ts for what moves where and when it still spawns.
     const plan = planToolExec({
@@ -363,6 +377,10 @@ async function spawnAndCaptureStderr(args: string[], workspaceRoot: string, exec
 
     const command = launcher ? launcher : execPath;
     const commandArgs = launcher ? [execPath, ...args] : args;
+    // Only a waiting wrapper sees a signal death, so only a spawned tool gets a run id (failures/launcher.ts).
+    const runId = `${process.pid}-${Date.now().toString(36)}`;
+    childEnv[RUN_ID_ENV] = runId;
+    const startedAt = new Date();
 
     return new Promise<number>((resolvePromise, reject) => {
         const child = spawn(command, commandArgs, {
@@ -438,16 +456,49 @@ async function spawnAndCaptureStderr(args: string[], workspaceRoot: string, exec
         });
         child.on("close", (code, signal) => {
             cleanup();
-            if (signal) {
-                resolvePromise(128 + (signalToNumber(signal) ?? 0));
+            const exitCode = signal ? 128 + (signalToNumber(signal) ?? 0) : (code ?? 1);
+            // The orphan watchdog's own TERM is the wrapper cleaning up after a dead shell, not a failed run.
+            if (orphanCleanup || (!signal && (code ?? 0) <= 128)) {
+                resolvePromise(exitCode);
                 return;
             }
 
-            resolvePromise(code ?? 1);
+            recordSignalDeath({
+                tool,
+                runId,
+                startedAt,
+                signal,
+                status: code,
+                viaLauncher: launcher !== null,
+                childPid: child.pid ?? 0,
+                toolsRoot: workspaceRoot,
+            }).finally(() => resolvePromise(exitCode));
         });
     });
 }
 
+/**
+ * A tool the default SIGINT or SIGTERM action killed never reached its own failure watcher; record it here, once.
+ * Loaded only on such an end, so a normal run pays nothing for it.
+ */
+async function recordSignalDeath(input: {
+    tool: string;
+    runId: string;
+    startedAt: Date;
+    signal: NodeJS.Signals | null;
+    status: number | null;
+    viaLauncher: boolean;
+    childPid: number;
+    toolsRoot: string;
+}): Promise<void> {
+    try {
+        const { recordSignalEnd } = await import("@genesiscz/utils/cli/failures/launcher");
+        recordSignalEnd(input);
+    } catch (err) {
+        logger.debug({ err }, "[tools] the signal death was not recorded");
+    }
+}
+
 /** Write out anything still buffered on stdout and stderr: an exec drops what the runtime holds. */
 function flushStdio(): Promise<void> {
     const flush = (stream: NodeJS.WriteStream) => new Promise<void>((done) => stream.write("", () => done()));

From 2b6b6c17bd98acd0c5283d07ac0605fee2ba8192 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 22:53:08 +0200
Subject: [PATCH 27/30] fix(GenesisKit, GenesisHub, widgets): #559 followup -
 an alert peek gives the user's widget module back when it ends, unless they
 picked one during it

---
 .../Widgets/WidgetCoordinator.swift           |  6 +-
 .../GenesisKit/Widgets/WidgetModel.swift      | 28 ++++++++-
 .../EdgePanelGeometryTests.swift              | 62 +++++++++++++++++++
 3 files changed, 90 insertions(+), 6 deletions(-)

diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetCoordinator.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetCoordinator.swift
index 293504040a..da49b5fb3f 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetCoordinator.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetCoordinator.swift
@@ -183,10 +183,8 @@ public final class WidgetCoordinator: NSObject, NSWindowDelegate {
         playChime(preferences?.alertSound)
         // Checked before the module switch: a popup the user's interaction refuses must not swap the pane they use.
         guard preferences?.alertPopup ?? true, let surface = peekSurface(), model.canPeek(on: surface) else { return }
-        if moduleIDs(for: surface).contains("agents"), model.moduleSelections[surface.key] != "agents" {
-            model.moduleSelections[surface.key] = "agents"
-        }
-        model.showPeek(item, on: surface)
+        // The peek shows the agents module and gives the user's own module back when it ends.
+        model.showPeek(item, on: surface, module: moduleIDs(for: surface).contains("agents") ? "agents" : nil)
     }
 
     /// The visible edge whose selected module is the agents inbox, else the first visible edge that has it.
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift
index 54492bd94b..cd5f5c26ed 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift
@@ -54,6 +54,9 @@ public final class WidgetModel: ObservableObject {
     /// timer ends, or until the pointer leaves the panel when the user moved onto it.
     @Published public private(set) var peekItem: WidgetInboxItem?
     private var peekTask: Task<Void, Never>?
+    /// The module a peek replaced on its surface (`previous`, nil when none was chosen) and the one it showed. The
+    /// end of the peek puts `previous` back, unless the selection is no longer `shown`: the user picked a module.
+    private var peekReplaced: (surface: WidgetSurfaceID, previous: String?, shown: String)?
     /// Surfaces the pointer is in now, without the hover delay: a popup never opens under the user's pointer.
     private var pointerInside: Set<String> = []
     /// Called with the items that arrived in a complete inbox snapshot (never the first one).
@@ -551,6 +554,8 @@ public final class WidgetModel: ObservableObject {
     }
 
     public func openModule(_ moduleID: String, on surface: WidgetSurfaceID) {
+        // The user picked this module (also by clicking the peek itself): it stays after the peek.
+        peekReplaced = nil
         moduleSelections[surface.key] = moduleID
         defaults.set(moduleSelections, forKey: "widget.moduleSelections")
         activeSideGroup = surface.group
@@ -594,9 +599,16 @@ public final class WidgetModel: ObservableObject {
             && (hoveredSurface == nil || hoveredSurface == surface)
     }
 
-    /// Pops `item` up in `surface`'s preview for `seconds`, unless the user is in a panel, a window or a drag.
-    func showPeek(_ item: WidgetInboxItem, on surface: WidgetSurfaceID, seconds: Double = 7) {
+    /// Pops `item` up in `surface`'s preview for `seconds`, unless the user is in a panel, a window or a drag. With
+    /// `module`, the surface shows that module for the peek and gets the user's own module back when the peek ends.
+    func showPeek(_ item: WidgetInboxItem, on surface: WidgetSurfaceID, module: String? = nil, seconds: Double = 7) {
         guard canPeek(on: surface) else { return }
+        if let module, moduleSelections[surface.key] != module {
+            if let replaced = peekReplaced, replaced.surface != surface { restorePeekModule() }
+            // A second alert during a peek keeps the module from before the first one.
+            peekReplaced = peekReplaced ?? (surface, moduleSelections[surface.key], module)
+            moduleSelections[surface.key] = module
+        }
         hoverTask?.cancel()
         peekItem = item
         hoveredSurface = surface
@@ -617,10 +629,21 @@ public final class WidgetModel: ObservableObject {
         if expanded == nil, let surface = hoveredSurface, !pointerInside.contains(surface.key) {
             hoveredSurface = nil
         }
+        // An open panel keeps the peek's module under the user; `collapse` restores it once the panel closes.
+        if expanded == nil { restorePeekModule() }
         PerfLog.mark("widget.peek end id=\(item.id)")
         presentationChanged?()
     }
 
+    /// Puts back the module a peek replaced, unless the user chose another one since. Not saved to the defaults:
+    /// the peek's own switch never was either.
+    private func restorePeekModule() {
+        guard let replaced = peekReplaced else { return }
+        peekReplaced = nil
+        guard moduleSelections[replaced.surface.key] == replaced.shown else { return }
+        moduleSelections[replaced.surface.key] = replaced.previous
+    }
+
     public func hover(_ surface: WidgetSurfaceID, inside: Bool) {
         if inside { pointerInside.insert(surface.key) } else { pointerInside.remove(surface.key) }
         pointerChanged?(surface, inside)
@@ -842,6 +865,7 @@ public final class WidgetModel: ObservableObject {
         hoverTask?.cancel()
         peekTask?.cancel()
         peekItem = nil
+        restorePeekModule()
         voice?.finishInput()
         speechTask?.cancel()
         reading = false
diff --git a/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift b/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift
index 4f19b9e0b9..d1ee14e303 100644
--- a/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift
+++ b/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift
@@ -450,6 +450,58 @@ final class WidgetInteractionTests: XCTestCase {
         XCTAssertNil(value.hoveredSurface)
         XCTAssertEqual(value.presentation(for: side), .compact)
     }
+
+    /// An alert peek shows the agents module and gives the user's own module back when it ends, unless the user
+    /// picked a module during the peek.
+    @MainActor
+    func testAPeekRestoresTheModuleTheUserHadUnlessTheyPickedAnother() async throws {
+        let domain = "widget-tests." + UUID().uuidString
+        let defaults = UserDefaults(suiteName: domain)!
+        defer { defaults.removePersistentDomain(forName: domain) }
+        let value = model(defaults: defaults)
+        defer { value.stop() }
+        let side = WidgetSurfaceID(edge: .right)
+        let item = WidgetInboxItem(id: "decision:d_5_s", sourceId: "d_5_s", kind: "decision", key: "local:claude:s:",
+            at: 2_000, needsAnswer: true, title: "Ship it?", number: 5)
+        func peekEnded() async throws {
+            let deadline = ContinuousClock.now + .seconds(5)
+            while value.peekItem != nil && ContinuousClock.now < deadline {
+                try await Task.sleep(for: .milliseconds(50))
+            }
+            XCTAssertNil(value.peekItem, "the peek did not end within 5 s")
+        }
+
+        value.moduleSelections[side.key] = "capture"
+        value.showPeek(item, on: side, module: "agents", seconds: 0.1)
+        XCTAssertEqual(value.peekItem, item)
+        XCTAssertEqual(value.moduleSelections[side.key], "agents", "the peek shows the agents module")
+        try await peekEnded()
+        XCTAssertEqual(value.moduleSelections[side.key], "capture", "the end of the peek gives the user's module back")
+
+        value.showPeek(item, on: side, module: "agents", seconds: 60)
+        value.showPeek(item, on: side, module: "agents", seconds: 60)
+        value.collapse()
+        XCTAssertEqual(value.moduleSelections[side.key], "capture", "a collapse ends a repeated peek the same way")
+
+        value.moduleSelections[side.key] = nil
+        value.showPeek(item, on: side, module: "agents", seconds: 60)
+        value.collapse()
+        XCTAssertNil(value.moduleSelections[side.key], "no module chosen before the peek: none after it")
+
+        value.moduleSelections[side.key] = "capture"
+        value.showPeek(item, on: side, module: "agents", seconds: 60)
+        value.openModule("tasks", on: side)
+        value.collapse()
+        XCTAssertEqual(value.moduleSelections[side.key], "tasks", "a module the user picked during the peek stays")
+
+        value.moduleSelections[side.key] = "capture"
+        value.showPeek(item, on: side, module: "agents", seconds: 0.1)
+        value.open(.right)
+        try await peekEnded()
+        XCTAssertEqual(value.moduleSelections[side.key], "agents", "an open panel keeps the peek's module under the user")
+        value.collapse()
+        XCTAssertEqual(value.moduleSelections[side.key], "capture", "closing that panel gives the user's module back")
+    }
 }
 
 /// "Show the widget": the coordinator builds and orders front edge panels only while the switch is on.
@@ -643,9 +695,19 @@ final class WidgetVisibilityTests: XCTestCase {
         XCTAssertEqual(coordinator.model.peekItem, decision, "the item that waits for an answer pops up")
         XCTAssertEqual(coordinator.model.hoveredSurface?.edge, .right)
         XCTAssertEqual(coordinator.model.presentation(for: try XCTUnwrap(coordinator.model.hoveredSurface)), .preview)
+        let peeked = try XCTUnwrap(coordinator.model.hoveredSurface)
+        XCTAssertEqual(coordinator.model.moduleSelections[peeked.key], "agents", "the popup shows the agents module")
 
         coordinator.model.collapse()
         XCTAssertNil(coordinator.model.peekItem)
+        // Another module was selected there: the popup switches to agents and gives that module back when it ends.
+        coordinator.model.moduleSelections[peeked.key] = "capture"
+        coordinator.alert([decision])
+        XCTAssertEqual(coordinator.model.hoveredSurface, peeked)
+        XCTAssertEqual(coordinator.model.moduleSelections[peeked.key], "agents", "the popup switched to agents")
+        coordinator.model.collapse()
+        XCTAssertEqual(coordinator.model.moduleSelections[peeked.key], "capture", "the end of the popup gives it back")
+        chimes.removeLast()
         // The pointer is in a panel and another module is selected: the popup is refused and the pane stays.
         let side = WidgetSurfaceID(edge: .right)
         coordinator.model.moduleSelections[side.key] = "capture"

From 7d50ea0cf9b0bb769e93e2dad485fe5f84cfc79e Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 23:01:03 +0200
Subject: [PATCH 28/30] feat(GenesisHub, tools): #559 followup - the app
 launcher records a tool run a signal killed

---
 src/genesis-tools/README.md                   |  12 +-
 .../GenesisTools/Sources/Host/Launcher.swift  |  14 +-
 .../Sources/Host/LauncherFailures.swift       | 165 +++++++++++++++++
 .../Tests/LauncherFailuresTests.swift         | 167 ++++++++++++++++++
 src/utils/cli/failures/launcher.ts            |   6 +-
 src/utils/cli/failures/run-id.ts              |   8 +
 tools                                         |  12 +-
 7 files changed, 373 insertions(+), 11 deletions(-)
 create mode 100644 src/macos/GenesisTools/Sources/Host/LauncherFailures.swift
 create mode 100644 src/macos/GenesisTools/Tests/LauncherFailuresTests.swift

diff --git a/src/genesis-tools/README.md b/src/genesis-tools/README.md
index bbe05e9439..7d51db8e66 100644
--- a/src/genesis-tools/README.md
+++ b/src/genesis-tools/README.md
@@ -16,11 +16,13 @@ JSON line per failed run to `~/.genesis-tools/logs/<date>-failures.jsonl`
 | `exit` | a non-zero exit with none of the above (the tool printed its own message) |
 | `interrupt` | Ctrl-C or SIGTERM (130, 143), often a harness timeout; hidden unless `--interrupts` |
 
-A run the default signal action kills never reaches its own watcher. When the `tools` wrapper spawned the tool and
-waited for it, the wrapper writes that record (`src/utils/cli/failures/launcher.ts`): `interrupt` for SIGINT, SIGTERM,
-SIGHUP, SIGQUIT and SIGKILL, `crash` for a fault signal (SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGABRT, SIGTRAP). The
-wrapper has no command definition, so the arguments read `[withheld]` and the command is empty. A run the wrapper
-exec'd into (the default) has no waiting parent, so its signal death stays unrecorded.
+A run the default signal action kills never reaches its own watcher. Its waiting parent writes that record instead:
+the GenesisTools.app launcher (`src/macos/GenesisTools/Sources/Host/LauncherFailures.swift`) on the default path, or
+the `tools` wrapper when it spawned a plain bun child (`src/utils/cli/failures/launcher.ts`). The kind is `interrupt`
+for SIGINT, SIGTERM, SIGHUP, SIGQUIT and SIGKILL, and `crash` for a fault signal (SIGSEGV, SIGBUS, SIGILL, SIGFPE,
+SIGABRT, SIGTRAP). Neither parent has the command definition, so the arguments read `[withheld]` and the command is
+empty; the launcher's record has no caller. Both use the run id in `GENESIS_TOOLS_RUN_ID`, so one run gets one record.
+A run exec'd straight into bun (`GENESIS_TOOLS_NO_APP=1`, Linux) has no waiting parent and stays unrecorded.
 
 Each record carries the tool, the command path, the arguments with secrets masked, the exit code, the message, the
 stack, the last 4 KB of stderr, the cwd, the pid, the run time, the app trace id when GenesisTools.app started it, the
diff --git a/src/macos/GenesisTools/Sources/Host/Launcher.swift b/src/macos/GenesisTools/Sources/Host/Launcher.swift
index 4734a1cbe0..4a30023b51 100644
--- a/src/macos/GenesisTools/Sources/Host/Launcher.swift
+++ b/src/macos/GenesisTools/Sources/Host/Launcher.swift
@@ -22,6 +22,8 @@ let inodeVariable = "GENESIS_TOOLS_APP_INODE"
 let fallbackBundleId = "com.genesiscz.genesistools"
 
 var childPid: pid_t = 0
+/// Set when the launcher stopped its child because its own parent died: cleanup after a dead shell, not a failed run.
+var stoppedForParentDeath = false
 
 func bundleVersion() -> String {
     Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "dev"
@@ -120,12 +122,14 @@ func watchParentDeath() {
         )
         var event = kevent()
         if kevent(kq, &change, 1, &event, 1, nil) > 0, childPid > 0 {
+            stoppedForParentDeath = true
             kill(childPid, SIGTERM)
         }
     }
 }
 
-func waitAndExit(_ pid: pid_t) -> Never {
+/// With `run` (a tool run `tools` handed over), a signal death is written to the failures log before the exit.
+func waitAndExit(_ pid: pid_t, run: LauncherFailures.Run? = nil) -> Never {
     var status: Int32 = 0
     while waitpid(pid, &status, 0) == -1 {
         if errno != EINTR {
@@ -136,6 +140,9 @@ func waitAndExit(_ pid: pid_t) -> Never {
 
     let signalNumber = status & 0x7f
     if signalNumber != 0 {
+        if let run, !stoppedForParentDeath {
+            LauncherFailures.recordSignalDeath(run: run, signal: signalNumber)
+        }
         exit(128 + signalNumber)
     }
 
@@ -144,6 +151,7 @@ func waitAndExit(_ pid: pid_t) -> Never {
 
 func runLauncher(_ arguments: [String]) -> Never {
     var environment = ProcessInfo.processInfo.environment
+    var run: LauncherFailures.Run?
     let bundleId = Bundle.main.bundleIdentifier ?? fallbackBundleId
 
     // Handlers go in before the spawn: a child inherits SIG_IGN but resets handlers to SIG_DFL,
@@ -166,9 +174,11 @@ func runLauncher(_ arguments: [String]) -> Never {
         if let me = Bundle.main.executablePath, stat(me, &info) == 0 {
             environment[inodeVariable] = String(info.st_ino)
         }
+        run = LauncherFailures.prepare(&environment)
         childPid = spawnChild(path: arguments[0], arguments: arguments, environment: environment, disclaim: false)
+        run?.childPid = childPid
     }
 
     watchParentDeath()
-    waitAndExit(childPid)
+    waitAndExit(childPid, run: run)
 }
diff --git a/src/macos/GenesisTools/Sources/Host/LauncherFailures.swift b/src/macos/GenesisTools/Sources/Host/LauncherFailures.swift
new file mode 100644
index 0000000000..bcf0a6d610
--- /dev/null
+++ b/src/macos/GenesisTools/Sources/Host/LauncherFailures.swift
@@ -0,0 +1,165 @@
+// The launcher's half of the CLI failures log (src/utils/cli/failures/). A tool that the default SIGINT or SIGTERM
+// action kills never reaches its own failure watcher. When `tools` exec'd into this launcher (the default path), the
+// launcher is the only parent left that sees the death, so it writes the record, in the same day file and the same
+// JSONL shape as `appendFailure` in src/utils/cli/failures/record.ts. LauncherFailuresTests reads the TypeScript
+// sources and fails when the file name, the field names or the signal table drift apart.
+
+import Darwin
+import Foundation
+
+enum LauncherFailures {
+    /// src/utils/cli/failures/run-id.ts `RUN_ID_ENV`: the run's id; a record that carries it is never written twice.
+    static let runIdVariable = "GENESIS_TOOLS_RUN_ID"
+    /// run-id.ts `RUN_TOOL_ENV`: set by `tools` only on a tool run it hands to this launcher; nothing else is recorded.
+    static let toolVariable = "GENESIS_TOOLS_RUN_TOOL"
+    /// run-id.ts `RUN_ROOT_ENV`: the GenesisTools checkout that runs the tool (the record's `toolsRoot`).
+    static let rootVariable = "GENESIS_TOOLS_RUN_ROOT"
+    static let traceVariable = "GENESIS_TOOLS_TRACE_ID"
+    static let homeVariable = "GENESIS_TOOLS_HOME"
+
+    /// src/utils/cli/failures/launcher.ts `CRASH_SIGNALS` and `INTERRUPT_SIGNALS`: a fault the process raised on
+    /// itself is a crash; a signal sent from outside (SIGKILL included, most often a timeout's escalation) is an
+    /// interrupt; anything else (SIGPIPE from `tools x | head`) is a normal end.
+    static let crashSignals: [Int32: String] = [
+        SIGSEGV: "SIGSEGV", SIGBUS: "SIGBUS", SIGILL: "SIGILL", SIGFPE: "SIGFPE", SIGABRT: "SIGABRT", SIGTRAP: "SIGTRAP",
+    ]
+    static let interruptSignals: [Int32: String] = [
+        SIGINT: "SIGINT", SIGTERM: "SIGTERM", SIGHUP: "SIGHUP", SIGQUIT: "SIGQUIT", SIGKILL: "SIGKILL",
+    ]
+
+    /// One tool run this launcher waits for.
+    struct Run {
+        let tool: String
+        let toolsRoot: String
+        let runId: String
+        var startedAt = Date()
+        var childPid: pid_t = 0
+    }
+
+    /// The tool run `environment` describes, or nil for any other program. The tool and root markers are removed, so
+    /// a program the tool starts under another launcher is not taken for a tool run. The run id stays for the tool's
+    /// own watcher, and is made here when the caller set none (the exec path: `tools` is gone by now).
+    static func prepare(_ environment: inout [String: String], pid: pid_t = getpid(), now: Date = Date()) -> Run? {
+        let tool = environment.removeValue(forKey: toolVariable)?.trimmingCharacters(in: .whitespaces) ?? ""
+        let root = environment.removeValue(forKey: rootVariable) ?? ""
+        guard !tool.isEmpty else { return nil }
+        let given = environment[runIdVariable]?.trimmingCharacters(in: .whitespaces) ?? ""
+        let runId = given.isEmpty ? "\(pid)-\(base36(now))" : given
+        environment[runIdVariable] = runId
+        return Run(tool: tool, toolsRoot: root, runId: runId, startedAt: now)
+    }
+
+    /// launcher.ts `signalEnd` for a signal death: the record's kind and the signal's name, or nil for no failure.
+    static func kind(of signal: Int32) -> (kind: String, name: String)? {
+        if let name = crashSignals[signal] { return ("crash", name) }
+        if let name = interruptSignals[signal] { return ("interrupt", name) }
+        return nil
+    }
+
+    /// record.ts `failuresDir()`: storage/root.ts `genesisToolsDir("logs")`, under GENESIS_TOOLS_HOME when it is set.
+    static func failuresDirectory(environment: [String: String]) -> URL {
+        let override = environment[homeVariable]?.trimmingCharacters(in: .whitespaces) ?? ""
+        let home = override.isEmpty ? NSHomeDirectory() : override
+        return URL(fileURLWithPath: home).appendingPathComponent(".genesis-tools").appendingPathComponent("logs")
+    }
+
+    /// record.ts `failureLogPath(day)`: `<dir>/<YYYY-MM-DD>-failures.jsonl`, the day in local time (date.ts
+    /// `formatLocalDate`).
+    static func failureLogURL(day: String, directory: URL) -> URL {
+        directory.appendingPathComponent("\(day)-failures.jsonl")
+    }
+
+    static func localDay(_ date: Date) -> String {
+        let parts = Calendar(identifier: .gregorian).dateComponents(in: TimeZone.current, from: date)
+        return String(format: "%04d-%02d-%02d", parts.year ?? 0, parts.month ?? 0, parts.day ?? 0)
+    }
+
+    static func base36(_ date: Date) -> String {
+        String(Int64((date.timeIntervalSince1970 * 1000).rounded(.down)), radix: 36)
+    }
+
+    /// launcher.ts `childRecorded`: whether a record of this run is already in a day file it could be in.
+    static func recorded(runId: String, since: Date, now: Date, directory: URL) -> Bool {
+        var day = since
+        let last = localDay(now)
+        while localDay(day) <= last {
+            let url = failureLogURL(day: localDay(day), directory: directory)
+            if let text = try? String(contentsOf: url, encoding: .utf8) {
+                for line in text.split(separator: "\n") {
+                    guard let object = try? JSONSerialization.jsonObject(with: Data(line.utf8)) as? [String: Any]
+                    else { continue }
+                    if object["runId"] as? String == runId { return true }
+                }
+            }
+            guard let next = Calendar(identifier: .gregorian).date(byAdding: .day, value: 1, to: day) else { break }
+            day = next
+        }
+        return false
+    }
+
+    /// The record `appendFailure` would write for this signal death (record.ts `ToolFailure`, v 1).
+    static func record(run: Run, name: String, kind: String, signal: Int32, now: Date, launcherPid: pid_t,
+                       cwd: String, environment: [String: String]) -> [String: Any] {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        let trace = environment[traceVariable]?.trimmingCharacters(in: .whitespaces) ?? ""
+        return [
+            "v": 1,
+            "id": "\(base36(now))-\(launcherPid)",
+            "at": formatter.string(from: now),
+            "kind": kind,
+            "tool": run.tool,
+            "command": NSNull(),
+            "argv": ["[withheld]"],
+            "exitCode": 128 + Int(signal),
+            "message": "ended by \(name)",
+            "errorName": NSNull(),
+            "stack": NSNull(),
+            "stderrTail": NSNull(),
+            "fatal": true,
+            "durationMs": Int((now.timeIntervalSince(run.startedAt) * 1000).rounded()),
+            "pid": Int(run.childPid),
+            "ppid": Int(launcherPid),
+            "cwd": cwd,
+            "traceId": trace.isEmpty ? NSNull() : trace,
+            "toolsRoot": run.toolsRoot,
+            // The agent, session and model come from the agent runtime in TypeScript; the launcher cannot know them.
+            "caller": NSNull(),
+            "runId": run.runId,
+        ]
+    }
+
+    /// Writes the record of a signal death once: nothing for a normal end, or when the tool (it handled the signal,
+    /// wrote its own record and re-raised it) or the spawning `tools` wrapper already recorded this run id.
+    /// Returns the record it wrote.
+    @discardableResult
+    static func recordSignalDeath(run: Run, signal: Int32, now: Date = Date(), launcherPid: pid_t = getpid(),
+                                  cwd: String = FileManager.default.currentDirectoryPath,
+                                  environment: [String: String] = ProcessInfo.processInfo.environment,
+                                  directory: URL? = nil) -> [String: Any]? {
+        guard let (kind, name) = kind(of: signal) else { return nil }
+        let directory = directory ?? failuresDirectory(environment: environment)
+        guard !recorded(runId: run.runId, since: run.startedAt, now: now, directory: directory) else { return nil }
+        let record = record(run: run, name: name, kind: kind, signal: signal, now: now, launcherPid: launcherPid,
+                            cwd: cwd, environment: environment)
+        guard var data = try? JSONSerialization.data(withJSONObject: record, options: [.withoutEscapingSlashes])
+        else { return nil }
+        data.append(0x0A)
+        do {
+            try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+        } catch {
+            warn("failures: cannot create \(directory.path): \(error.localizedDescription)")
+            return nil
+        }
+        // One write with O_APPEND, like appendFileSync: concurrent writers never interleave a record.
+        let path = failureLogURL(day: localDay(now), directory: directory).path
+        let fd = open(path, O_WRONLY | O_APPEND | O_CREAT, 0o644)
+        guard fd >= 0 else {
+            warn("failures: cannot open \(path): \(String(cString: strerror(errno)))")
+            return nil
+        }
+        defer { close(fd) }
+        let written = data.withUnsafeBytes { write(fd, $0.baseAddress, $0.count) }
+        return written == data.count ? record : nil
+    }
+}
diff --git a/src/macos/GenesisTools/Tests/LauncherFailuresTests.swift b/src/macos/GenesisTools/Tests/LauncherFailuresTests.swift
new file mode 100644
index 0000000000..b28423715f
--- /dev/null
+++ b/src/macos/GenesisTools/Tests/LauncherFailuresTests.swift
@@ -0,0 +1,167 @@
+import Darwin
+import XCTest
+@testable import GenesisToolsHost
+
+/// The launcher's signal-death records (Sources/Host/LauncherFailures.swift), and the pins that keep them in the
+/// shape `appendFailure` writes (src/utils/cli/failures/record.ts), so `tools genesis-tools logs` reads both alike.
+final class LauncherFailuresTests: XCTestCase {
+    private var directory: URL!
+
+    override func setUpWithError() throws {
+        directory = FileManager.default.temporaryDirectory.appendingPathComponent("launcher-failures-" + UUID().uuidString)
+    }
+
+    override func tearDownWithError() throws {
+        if FileManager.default.fileExists(atPath: directory.path) {
+            try FileManager.default.removeItem(at: directory)
+        }
+    }
+
+    private func run(_ runId: String, startedAt: Date) -> LauncherFailures.Run {
+        LauncherFailures.Run(tool: "fixture", toolsRoot: "/repo", runId: runId, startedAt: startedAt, childPid: 4242)
+    }
+
+    private func lines(on day: String) throws -> [[String: Any]] {
+        let url = LauncherFailures.failureLogURL(day: day, directory: directory)
+        return try String(contentsOf: url, encoding: .utf8).split(separator: "\n").compactMap {
+            try JSONSerialization.jsonObject(with: Data($0.utf8)) as? [String: Any]
+        }
+    }
+
+    func testOnlyAToolRunIsPreparedAndItKeepsOrGetsARunId() {
+        var plain = ["PATH": "/usr/bin"]
+        XCTAssertNil(LauncherFailures.prepare(&plain), "a program `tools` did not hand over is never recorded")
+        XCTAssertNil(plain[LauncherFailures.runIdVariable])
+
+        let now = Date(timeIntervalSince1970: 1_000)
+        var exec = [LauncherFailures.toolVariable: "watch", LauncherFailures.rootVariable: "/repo"]
+        let made = LauncherFailures.prepare(&exec, pid: 77, now: now)
+        XCTAssertEqual(made?.tool, "watch")
+        XCTAssertEqual(made?.toolsRoot, "/repo")
+        XCTAssertEqual(made?.runId, "77-\(String(1_000_000, radix: 36))", "the exec path gets a run id here")
+        XCTAssertEqual(exec, [LauncherFailures.runIdVariable: made?.runId ?? ""], "the markers never reach the tool")
+
+        var spawned = [LauncherFailures.toolVariable: "watch", LauncherFailures.runIdVariable: "wrapper-1"]
+        XCTAssertEqual(LauncherFailures.prepare(&spawned)?.runId, "wrapper-1", "a spawning wrapper's id is kept")
+    }
+
+    func testSignalTableMatchesSignalEnd() {
+        XCTAssertEqual(LauncherFailures.kind(of: SIGINT)?.kind, "interrupt")
+        XCTAssertEqual(LauncherFailures.kind(of: SIGKILL)?.name, "SIGKILL")
+        XCTAssertEqual(LauncherFailures.kind(of: SIGKILL)?.kind, "interrupt")
+        XCTAssertEqual(LauncherFailures.kind(of: SIGSEGV)?.kind, "crash")
+        XCTAssertEqual(LauncherFailures.kind(of: SIGABRT)?.kind, "crash")
+        XCTAssertNil(LauncherFailures.kind(of: SIGPIPE), "SIGPIPE ends `tools x | head` normally")
+    }
+
+    func testASignalDeathIsWrittenOnceInTheDayFile() throws {
+        let now = Date()
+        let day = LauncherFailures.localDay(now)
+        let started = now.addingTimeInterval(-2)
+        let written = try XCTUnwrap(LauncherFailures.recordSignalDeath(
+            run: run("run-a", startedAt: started), signal: SIGKILL, now: now, launcherPid: 4241, cwd: "/work",
+            environment: [:], directory: directory))
+        XCTAssertNil(LauncherFailures.recordSignalDeath(
+            run: run("run-a", startedAt: started), signal: SIGKILL, now: now, environment: [:], directory: directory),
+            "a second death of the same run id is not written again")
+        XCTAssertNil(LauncherFailures.recordSignalDeath(
+            run: run("run-b", startedAt: started), signal: SIGPIPE, now: now, environment: [:], directory: directory))
+
+        let records = try lines(on: day)
+        XCTAssertEqual(records.count, 1)
+        let record = try XCTUnwrap(records.first)
+        XCTAssertEqual(record["kind"] as? String, "interrupt")
+        XCTAssertEqual(record["argv"] as? [String], ["[withheld]"])
+        XCTAssertTrue(record["command"] is NSNull)
+        XCTAssertTrue(record["caller"] is NSNull)
+        XCTAssertEqual(record["message"] as? String, "ended by SIGKILL")
+        XCTAssertEqual(record["exitCode"] as? Int, 137)
+        XCTAssertEqual(record["pid"] as? Int, 4242)
+        XCTAssertEqual(record["ppid"] as? Int, 4241)
+        XCTAssertEqual(record["cwd"] as? String, "/work")
+        XCTAssertEqual(record["runId"] as? String, "run-a")
+        XCTAssertEqual(record["durationMs"] as? Int, 2000)
+        XCTAssertEqual(written["id"] as? String, record["id"] as? String)
+    }
+
+    /// The tool's watcher (it handled the signal and re-raised it) or the spawning `tools` wrapper wrote this run.
+    func testARunAnotherWriterAlreadyRecordedGetsNoSecondRecord() throws {
+        let now = Date()
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+        let own = #"{"v":1,"id":"x-1","kind":"interrupt","tool":"fixture","at":"2026-10-22T12:00:00.000Z","runId":"run-c"}"#
+        try (own + "\n").write(to: LauncherFailures.failureLogURL(day: LauncherFailures.localDay(now), directory: directory),
+                               atomically: true, encoding: .utf8)
+        XCTAssertNil(LauncherFailures.recordSignalDeath(
+            run: run("run-c", startedAt: now), signal: SIGTERM, now: now, environment: [:], directory: directory))
+        XCTAssertNotNil(LauncherFailures.recordSignalDeath(
+            run: run("run-d", startedAt: now), signal: SIGTERM, now: now, environment: [:], directory: directory))
+        XCTAssertEqual(try lines(on: LauncherFailures.localDay(now)).count, 2)
+    }
+
+    func testTheDirectoryFollowsGenesisToolsHome() {
+        XCTAssertEqual(LauncherFailures.failuresDirectory(environment: ["GENESIS_TOOLS_HOME": "/sandbox"]).path,
+                       "/sandbox/.genesis-tools/logs")
+        XCTAssertEqual(LauncherFailures.failuresDirectory(environment: [:]).path,
+                       NSHomeDirectory() + "/.genesis-tools/logs")
+    }
+
+    // MARK: - Pins against the TypeScript sources
+
+    private var src: URL {
+        URL(fileURLWithPath: #filePath).deletingLastPathComponent().deletingLastPathComponent()
+            .deletingLastPathComponent().deletingLastPathComponent()
+    }
+
+    private func source(_ path: String) throws -> String {
+        try String(contentsOf: src.appendingPathComponent(path), encoding: .utf8)
+    }
+
+    private func matches(_ pattern: String, in text: String) throws -> [String] {
+        let regex = try NSRegularExpression(pattern: pattern, options: [.anchorsMatchLines])
+        return regex.matches(in: text, range: NSRange(text.startIndex..., in: text)).compactMap {
+            Range($0.range(at: 1), in: text).map { String(text[$0]) }
+        }
+    }
+
+    func testTheRecordHasExactlyTheFieldsOfToolFailure() throws {
+        let record = try source("utils/cli/failures/record.ts")
+        let block = try XCTUnwrap(record.components(separatedBy: "export interface ToolFailure {").dropFirst().first?
+            .components(separatedBy: "\n}").first)
+        let fields = Set(try matches(#"^    (\w+)\??:"#, in: block))
+        XCTAssertTrue(fields.contains("runId"), "the pattern read the interface: \(fields.sorted())")
+        let written = LauncherFailures.record(run: run("r", startedAt: Date()), name: "SIGINT", kind: "interrupt",
+                                              signal: SIGINT, now: Date(), launcherPid: 1, cwd: "/", environment: [:])
+        XCTAssertEqual(Set(written.keys), fields)
+        XCTAssertTrue(block.contains("v: 1;"))
+        XCTAssertEqual(written["v"] as? Int, 1)
+    }
+
+    func testTheDayFileAndDirectoryMatchRecordTs() throws {
+        let record = try source("utils/cli/failures/record.ts")
+        XCTAssertTrue(record.contains("return join(dir, `${day}-failures.jsonl`);"), "record.ts failureLogPath changed")
+        XCTAssertTrue(record.contains(#"return genesisToolsDir("logs");"#), "record.ts failuresDir changed")
+        XCTAssertTrue(record.contains("formatLocalDate(new Date(failure.at))"), "the day is no longer the local day")
+        let root = try source("utils/storage/root.ts")
+        XCTAssertTrue(root.contains(#"join(env.tools.getHome(), ".genesis-tools", ...segments)"#))
+        let variables = try source("utils/env/envVariables.ts")
+        XCTAssertTrue(variables.contains(#"getHome: () => getTrimmed("GENESIS_TOOLS_HOME") ?? homedir(),"#))
+        XCTAssertEqual(LauncherFailures.failureLogURL(day: "2026-10-22", directory: URL(fileURLWithPath: "/d")).path,
+                       "/d/2026-10-22-failures.jsonl")
+    }
+
+    func testTheSignalTableAndVariablesMatchTheTypeScriptSide() throws {
+        let launcher = try source("utils/cli/failures/launcher.ts")
+        func set(_ name: String) throws -> Set<String> {
+            let line = try XCTUnwrap(launcher.components(separatedBy: "\n").first { $0.contains("const \(name)") })
+            return Set(try matches(#""(SIG\w+)""#, in: line))
+        }
+        XCTAssertEqual(try set("CRASH_SIGNALS"), Set(LauncherFailures.crashSignals.values))
+        XCTAssertEqual(try set("INTERRUPT_SIGNALS"), Set(LauncherFailures.interruptSignals.values))
+        XCTAssertTrue(launcher.contains(#"export const WITHHELD_ARGV = ["[withheld]"];"#))
+
+        let runId = try source("utils/cli/failures/run-id.ts")
+        XCTAssertTrue(runId.contains(#"RUN_ID_ENV = "\#(LauncherFailures.runIdVariable)""#))
+        XCTAssertTrue(runId.contains(#"RUN_TOOL_ENV = "\#(LauncherFailures.toolVariable)""#))
+        XCTAssertTrue(runId.contains(#"RUN_ROOT_ENV = "\#(LauncherFailures.rootVariable)""#))
+    }
+}
diff --git a/src/utils/cli/failures/launcher.ts b/src/utils/cli/failures/launcher.ts
index 2a051a32bc..9677ace4f3 100644
--- a/src/utils/cli/failures/launcher.ts
+++ b/src/utils/cli/failures/launcher.ts
@@ -14,8 +14,10 @@ import { agentCaller } from "./watch";
 
 /**
  * A run the default SIGINT or SIGTERM action kills never reaches the tool's exit event, so watch.ts cannot record it.
- * The `tools` wrapper records it instead, when it spawned the tool and waited for it. When the wrapper exec'd into
- * the tool (the default, tool-exec.ts), no parent of ours is left to see the death, and such a run stays unrecorded.
+ * Its waiting parent records it instead: the GenesisTools.app launcher (LauncherFailures.swift, which mirrors this
+ * table and the record shape) when one runs the tool, which covers the default path where `tools` exec'd into it,
+ * and the `tools` wrapper below when it spawned a plain bun child. Both share the run id, so one run gets one record.
+ * A run exec'd straight into bun (GENESIS_TOOLS_NO_APP=1, Linux) has no waiting parent and stays unrecorded.
  *
  * - `crash`: a signal a process raises on itself when it faults (a segfault, a Bun panic's abort or trap). The
  *   runtime died, which is a bug.
diff --git a/src/utils/cli/failures/run-id.ts b/src/utils/cli/failures/run-id.ts
index 569ba6dcae..998740ae4d 100644
--- a/src/utils/cli/failures/run-id.ts
+++ b/src/utils/cli/failures/run-id.ts
@@ -5,6 +5,14 @@
  */
 export const RUN_ID_ENV = "GENESIS_TOOLS_RUN_ID";
 
+/**
+ * Set by the `tools` wrapper when it hands a tool to the GenesisTools.app launcher (exec'd or spawned): the tool's
+ * name and checkout. The launcher records a signal death only for a run that carries them, removes both before it
+ * starts the tool, and makes a run id when none is set (LauncherFailures.swift).
+ */
+export const RUN_TOOL_ENV = "GENESIS_TOOLS_RUN_TOOL";
+export const RUN_ROOT_ENV = "GENESIS_TOOLS_RUN_ROOT";
+
 /**
  * The run id the wrapper gave this process. It is removed from the env, so a tool this one starts does not write
  * records under the same id and make the wrapper skip a signal death it should record.
diff --git a/tools b/tools
index 016cf6f1b9..f0b3b6f9d6 100755
--- a/tools
+++ b/tools
@@ -5,7 +5,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { namedBunExecPath } from "@genesiscz/utils/cli/bun-link";
 import { takeDetachedMarker } from "@genesiscz/utils/cli/detached";
-import { RUN_ID_ENV } from "@genesiscz/utils/cli/failures/run-id";
+import { RUN_ID_ENV, RUN_ROOT_ENV, RUN_TOOL_ENV } from "@genesiscz/utils/cli/failures/run-id";
 import { planToolExec, terminateOrphanedChild } from "@genesiscz/utils/cli/tool-exec";
 import { skipWorktreeInstall } from "@genesiscz/utils/cli/worktree-install";
 import { env } from "@genesiscz/utils/env";
@@ -352,6 +352,13 @@ async function spawnAndCaptureStderr(
     const childEnv = env.withoutProxy({ INIT_CWD: process.cwd() });
     // An id inherited from an outer wrapper would make that wrapper take this run's records for its own.
     delete childEnv[RUN_ID_ENV];
+    delete childEnv[RUN_TOOL_ENV];
+    delete childEnv[RUN_ROOT_ENV];
+    if (launcher) {
+        // The launcher is the parent that waits on the default (exec) path; it records the tool's signal death.
+        childEnv[RUN_TOOL_ENV] = tool;
+        childEnv[RUN_ROOT_ENV] = workspaceRoot;
+    }
     // Replace this wrapper with the launcher (or, under an app face, the worker) instead of waiting
     // as its parent; see src/utils/cli/tool-exec.ts for what moves where and when it still spawns.
     const plan = planToolExec({
@@ -377,7 +384,8 @@ async function spawnAndCaptureStderr(
 
     const command = launcher ? launcher : execPath;
     const commandArgs = launcher ? [execPath, ...args] : args;
-    // Only a waiting wrapper sees a signal death, so only a spawned tool gets a run id (failures/launcher.ts).
+    // A spawned child gets the wrapper's run id: a launcher child records under it, and the wrapper then finds that
+    // record and adds none (failures/launcher.ts). On the exec path the launcher makes the id itself.
     const runId = `${process.pid}-${Date.now().toString(36)}`;
     childEnv[RUN_ID_ENV] = runId;
     const startedAt = new Date();

From c862283f0c6a1c9bbe79575b4e2ed5cb3b674d52 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 22 Oct 2026 21:58:04 +0200
Subject: [PATCH 29/30] fix(skills, babysit): tmp-reclaim --own-session skips a
 plain file under /tmp/cc instead of crashing on ENOTDIR

---
 .claude/skills/babysit/scripts/scripts.test.ts | 3 +++
 .claude/skills/babysit/scripts/tmp-reclaim.ts  | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/.claude/skills/babysit/scripts/scripts.test.ts b/.claude/skills/babysit/scripts/scripts.test.ts
index 48b994d119..3fabc5d97b 100644
--- a/.claude/skills/babysit/scripts/scripts.test.ts
+++ b/.claude/skills/babysit/scripts/scripts.test.ts
@@ -5259,6 +5259,9 @@ describe("tmp-reclaim --own-session lists only the live session's build output",
         const { cc, dir } = plantSession();
         expect(ownSessionDirs(session, cc)).toEqual([dir]);
         expect(() => ownSessionDirs("1b4001ba", cc)).toThrow("full session uuid");
+        // A plain file beside the project folders (a stray install log) is no project: lstat of `<file>/<id>` is ENOTDIR.
+        fs.writeFileSync(join(cc, "stray-install.log"), "log");
+        expect(ownSessionDirs(session, cc)).toEqual([dir]);
     });
 
     test("apply removes the planned build output and refuses an entry that is no longer build output", () => {
diff --git a/.claude/skills/babysit/scripts/tmp-reclaim.ts b/.claude/skills/babysit/scripts/tmp-reclaim.ts
index caf8519d59..61dc1df228 100644
--- a/.claude/skills/babysit/scripts/tmp-reclaim.ts
+++ b/.claude/skills/babysit/scripts/tmp-reclaim.ts
@@ -438,7 +438,10 @@ export function ownSessionDirs(id: string, ccRoot: string): string[] {
         throw new Error(`--own-session needs the full session uuid, got ${SafeJSON.stringify(id)}`);
     }
 
+    // `/tmp/cc` also holds plain files (a stray install log): `lstat` of `<file>/<id>` throws ENOTDIR,
+    // which `throwIfNoEntry` does not cover, so only real project folders are joined.
     return (childNames(ccRoot) ?? [])
+        .filter((project) => lstatSync(join(ccRoot, project), { throwIfNoEntry: false })?.isDirectory() === true)
         .map((project) => join(ccRoot, project, id))
         .filter((dir) => {
             const st = lstatSync(dir, { throwIfNoEntry: false });

From 0ea516afbcab276b198f8279efa47833cdc2c9e6 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Fri, 23 Oct 2026 03:41:19 +0200
Subject: [PATCH 30/30] fix(tools): #559 followup - review fixes, rounds 3 and
 4: the failures log masks secrets past an unknown flag and in short flag
 groups and withholds text echoing a short secret, speech runs this checkout's
 say, dashboard smoke follows imported folders, --limit and --top bound the
 read, tmp-reclaim validates own-session plans, the wrapper exits with the
 platform signal status, and CI, lint and typecheck edge cases

---
 .claude/skills/babysit/scripts/policy.ts      |   8 +-
 .../skills/babysit/scripts/scripts.test.ts    |  62 +++++++++-
 .claude/skills/babysit/scripts/tmp-reclaim.ts |  47 +++++++-
 .githooks/pre-commit                          |   3 +-
 .github/workflows/ci.yml                      |   3 +-
 scripts/ci/dashboard-smoke.test.ts            |  38 +++++-
 scripts/ci/dashboard-smoke.ts                 |  48 ++++++--
 scripts/ci/lint-rules.test.ts                 |   3 +
 scripts/ci/lint-rules.ts                      |   3 +-
 scripts/ci/pre-commit-hook.test.ts            |   9 ++
 scripts/ci/typecheck.test.ts                  |  29 ++++-
 scripts/ci/typecheck.ts                       |  23 +++-
 src/genesis-tools/commands/logs.ts            |   3 +-
 src/genesis-tools/lib/failures.ts             |  12 +-
 src/genesis-tools/lib/logs.test.ts            |  39 ++++++-
 src/genesis-tools/lib/profile-log.ts          |  19 ++-
 src/genesis-tools/lib/window.ts               |   5 +
 .../GenesisKit/Widgets/WidgetModel.swift      |   9 +-
 .../EdgePanelGeometryTests.swift              |  10 ++
 src/utils/DashboardApp/readiness.test.ts      |   6 +-
 src/utils/DashboardApp/readiness.ts           |   7 +-
 .../bun/preload-test-host-effects.test.ts     |   9 +-
 src/utils/bun/preload-test-host-effects.ts    |   6 +
 src/utils/cli/failures/failures.test.ts       |  59 +++++++++-
 src/utils/cli/failures/launcher.ts            |   3 +-
 src/utils/cli/failures/signal-status.ts       |   9 ++
 src/utils/cli/failures/watch.ts               | 109 +++++++++++++++---
 src/utils/genesis-tools/tools/hints.ts        |  12 +-
 src/utils/macos/notifications.test.ts         |   9 ++
 src/utils/macos/notifications.ts              |  27 ++---
 tools                                         |   8 +-
 31 files changed, 546 insertions(+), 91 deletions(-)
 create mode 100644 src/utils/cli/failures/signal-status.ts

diff --git a/.claude/skills/babysit/scripts/policy.ts b/.claude/skills/babysit/scripts/policy.ts
index d5160e2e28..637ecd8b39 100644
--- a/.claude/skills/babysit/scripts/policy.ts
+++ b/.claude/skills/babysit/scripts/policy.ts
@@ -1,7 +1,7 @@
 /**
  * One policy for generated worker briefs, judging and reply disposition (review-loop "Round policy", Martin,
- * 2026-10-18): rounds 1 and 2 fix every valid finding whatever the PR's size; later rounds fix Critical, High and
- * security, plus a Medium or Low that is cheap or of an earlier fix's class. Dedicated user reviews are fixed in full.
+ * 2026-10-18): rounds 1 and 2 fix every valid finding whatever the PR's size; later rounds fix Critical, Major, High
+ * and security, plus a Medium or Low that is cheap or of an earlier fix's class. Dedicated user reviews are fixed in full.
  */
 export function roundPolicy(options: { round: number; changedFiles: number; dedicatedReview?: boolean }) {
     const { round, changedFiles, dedicatedReview = false } = options;
@@ -14,7 +14,7 @@ export function roundPolicy(options: { round: number; changedFiles: number; dedi
         `Round ${round} (${changedFiles} changed files${dedicatedReview ? ", dedicated user review" : ""}): ` +
             (fixAll
                 ? "fix EVERY valid finding, critical, high, medium and low."
-                : "fix Critical and High findings, and a valid Medium or Low only when the fix is cheap (about 20 changed lines) or the same class as an earlier round's fix."),
+                : "fix Critical, Major and High findings, and a valid Medium or Low only when the fix is cheap (about 20 changed lines) or the same class as an earlier round's fix."),
         "A valid security finding is always fixed, at any severity and in any round; use the reviewer's Security category.",
         fixAll
             ? "Fix every valid finding in this PR, including every file it needs; no deferral is accepted."
@@ -25,7 +25,7 @@ export function roundPolicy(options: { round: number; changedFiles: number; dedi
 }
 
 export function shouldFixFinding(policy: { fixAll: boolean }, severity: string, security = false): boolean {
-    return policy.fixAll || security || /^(critical|high)$/i.test(severity);
+    return policy.fixAll || security || /^(critical|major|high)$/i.test(severity);
 }
 
 /** Deferred replies are never included in the batch that resolves threads, regardless of reviewer. */
diff --git a/.claude/skills/babysit/scripts/scripts.test.ts b/.claude/skills/babysit/scripts/scripts.test.ts
index 3fabc5d97b..5d40f8780c 100644
--- a/.claude/skills/babysit/scripts/scripts.test.ts
+++ b/.claude/skills/babysit/scripts/scripts.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, spyOn, test } from "bun:test";
 import * as fs from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import type { execTool } from "@genesiscz/utils/cli";
 import { toolsEntrypoint } from "@genesiscz/utils/cli/tools";
 import { env } from "@genesiscz/utils/env";
@@ -4969,6 +4969,7 @@ describe("round 32 policy and landing routing", () => {
         const late = roundPolicy({ round: 32, changedFiles: 63 });
         expect(shouldFixFinding(late, "Low", true)).toBe(true);
         expect(shouldFixFinding(late, "High")).toBe(true);
+        expect(shouldFixFinding(late, "major")).toBe(true);
         expect(shouldFixFinding(late, "Medium")).toBe(false);
         expect(shouldFixFinding(roundPolicy({ round: 32, changedFiles: 120, dedicatedReview: true }), "Low")).toBe(
             true
@@ -5157,9 +5158,11 @@ describe("round 32 policy and landing routing", () => {
 describe("tmp-reclaim --own-session lists only the live session's build output", () => {
     const session = "1b4001ba-d479-40f2-9e25-b13cb2ef5a13";
 
-    function plantSession(): { cc: string; dir: string; nonBuild: string[] } {
-        const cc = fs.realpathSync(fs.mkdtempSync(join(tmpdir(), "babysit-own-")));
-        const dir = join(cc, "Project", session);
+    function plantSession(
+        cc = fs.realpathSync(fs.mkdtempSync(join(tmpdir(), "babysit-own-"))),
+        project = "Project"
+    ): { cc: string; dir: string; nonBuild: string[] } {
+        const dir = join(cc, project, session);
         const file = (path: string, text = "x") => {
             fs.mkdirSync(dirname(join(dir, path)), { recursive: true });
             fs.writeFileSync(join(dir, path), text);
@@ -5264,9 +5267,58 @@ describe("tmp-reclaim --own-session lists only the live session's build output",
         expect(ownSessionDirs(session, cc)).toEqual([dir]);
     });
 
-    test("apply removes the planned build output and refuses an entry that is no longer build output", () => {
+    /** A session under `<test TMPDIR>/cc/<unique project>/`, the only place an own-session plan may name. */
+    function plantInTmpCc(): ReturnType<typeof plantSession> {
+        const cc = join(fs.realpathSync(tmpdir()), "cc");
+        fs.mkdirSync(cc, { recursive: true });
+        return plantSession(cc, basename(fs.mkdtempSync(join(cc, "Project-"))));
+    }
+
+    function reclaim(args: string[], extraEnv: Record<string, string> = {}) {
+        return Bun.spawnSync([process.execPath, join(import.meta.dir, "tmp-reclaim.ts"), ...args], {
+            stdout: "pipe",
+            stderr: "pipe",
+            env: { ...process.env, ...extraEnv },
+        });
+    }
+
+    test("a missing or empty --own-session value is a usage error, never the regular dry run", () => {
+        const run = fs.mkdtempSync(join(tmpdir(), "babysit-own-run-"));
+        for (const args of [["--own-session"], ["--own-session", ""], ["--own-session", "   "]]) {
+            const result = reclaim(args, { BABYSIT_RUN: run });
+            expect(result.exitCode).toBe(2);
+            expect(result.stderr.toString()).toContain("--own-session needs the full session uuid");
+        }
+        expect(fs.existsSync(join(run, "logs"))).toBe(false);
+    });
+
+    test("apply refuses an own-session plan outside <tmp>/cc/<project>/<uuid> or with a bad age, and moves nothing", () => {
         const { dir } = plantSession();
         const hub = join(dir, "pluggable/b-hub");
+        const planned = [{ path: hub, ino: fs.lstatSync(hub).ino, bytes: 1, newest: 0 }];
+        const inCc = plantInTmpCc();
+        const inCcHub = join(inCc.dir, "pluggable/b-hub");
+        const cases = [
+            { candidates: planned, ownSession: { id: session, dirs: [dir], minAgeMinutes: 0 } },
+            {
+                candidates: [{ path: inCcHub, ino: fs.lstatSync(inCcHub).ino, bytes: 1, newest: 0 }],
+                ownSession: { id: session, dirs: [inCc.dir], minAgeMinutes: -1 },
+            },
+        ];
+        for (const [index, body] of cases.entries()) {
+            const plan = join(dir, "..", `bad-plan-${index}.json`);
+            fs.writeFileSync(plan, SafeJSON.stringify({ createdAt: Date.now(), minAgeHours: 0, ...body }));
+            const result = reclaim(["--apply", "--plan", plan]);
+            expect(result.exitCode).toBe(2);
+            expect(result.stderr.toString()).toContain("the plan's ownSession needs");
+        }
+        expect(fs.existsSync(hub)).toBe(true);
+        expect(fs.existsSync(inCcHub)).toBe(true);
+    });
+
+    test("apply removes the planned build output and refuses an entry that is no longer build output", () => {
+        const { dir } = plantInTmpCc();
+        const hub = join(dir, "pluggable/b-hub");
         const notesTriple = join(dir, "pluggable/b-notes/arm64-apple-macosx");
         const candidate = (path: string) => ({ path, ino: fs.lstatSync(path).ino, bytes: 1, newest: 0 });
         const planned = [candidate(hub), candidate(notesTriple)];
diff --git a/.claude/skills/babysit/scripts/tmp-reclaim.ts b/.claude/skills/babysit/scripts/tmp-reclaim.ts
index 61dc1df228..281605d4c9 100644
--- a/.claude/skills/babysit/scripts/tmp-reclaim.ts
+++ b/.claude/skills/babysit/scripts/tmp-reclaim.ts
@@ -615,10 +615,40 @@ function entries(): string[] {
     return out;
 }
 
+/**
+ * An own-session plan as the dry run writes it: a full uuid, each folder a canonical `<tmp root>/cc/<project>/<uuid>`,
+ * and a finite nonnegative age. A hand-edited or stale plan must not point apply at a `.build` outside `/tmp/cc`.
+ */
+function validOwnSession(own: unknown): own is NonNullable<Plan["ownSession"]> {
+    const { id, dirs, minAgeMinutes } = (typeof own === "object" && own !== null ? own : {}) as Record<string, unknown>;
+    if (typeof id !== "string" || !SESSION_UUID.test(id) || !Array.isArray(dirs) || dirs.length === 0) {
+        return false;
+    }
+
+    if (typeof minAgeMinutes !== "number" || !Number.isFinite(minAgeMinutes) || minAgeMinutes < 0) {
+        return false;
+    }
+
+    return dirs.every(
+        (dir) =>
+            typeof dir === "string" &&
+            basename(dir) === id &&
+            roots.some((root) => dirname(dirname(dir)) === join(root, "cc")) &&
+            existsSync(dir) &&
+            realpathSync(dir) === dir
+    );
+}
+
 const gb = (bytes: number) => `${(bytes / 1e9).toFixed(2)} GB`;
 
 function ownSessionDryRun(id: string): void {
-    const minAgeMinutes = Number(flag("--min-age-minutes") ?? 10);
+    if (!SESSION_UUID.test(id)) {
+        console.error(`✖ --own-session needs the full session uuid, got ${SafeJSON.stringify(id)}`);
+        process.exit(2);
+    }
+
+    const rawAge = flag("--min-age-minutes");
+    const minAgeMinutes = has("--min-age-minutes") && !rawAge?.trim() ? Number.NaN : Number(rawAge ?? 10);
 
     if (!Number.isFinite(minAgeMinutes) || minAgeMinutes < 1) {
         console.error("✖ --min-age-minutes must be at least 1");
@@ -667,10 +697,10 @@ function ownSessionDryRun(id: string): void {
 }
 
 function main(): void {
-    const ownSession = flag("--own-session");
-
-    if (!has("--apply") && ownSession) {
-        ownSessionDryRun(ownSession);
+    // A missing or empty value (an unset "$SESSION") is refused, never read as "no session": the regular run lists
+    // every other session's entries.
+    if (!has("--apply") && has("--own-session")) {
+        ownSessionDryRun(flag("--own-session") ?? "");
     }
 
     if (!has("--apply")) {
@@ -734,6 +764,13 @@ function main(): void {
     minAgeHours = validAge(plan.minAgeHours, "plan.minAgeHours");
 
     const own = plan.ownSession;
+    if (own !== undefined && !validOwnSession(own)) {
+        console.error(
+            "✖ the plan's ownSession needs a full session uuid, folders <tmp>/cc/<project>/<that uuid> and a finite nonnegative minAgeMinutes"
+        );
+        process.exit(2);
+    }
+
     // An own-session plan is re-checked by judgeOwn, which needs no live-session list (that scan reads every
     // agent's transcript folders).
     const protection = own ? null : protectedEntries();
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index 1e3454e655..902088efc0 100755
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -94,7 +94,8 @@ echo "▶ tsc --noEmit (failing on staged files only)..."
 # Incremental, sharing the root project's build info with scripts/ci/typecheck.ts: about 1.5 s instead of 6 to 13.
 tsc_cache=$(git rev-parse --path-format=absolute --git-path genesis-typecheck)
 mkdir -p "$tsc_cache"
-tsc_output=$(bunx tsc --noEmit --incremental --tsBuildInfoFile "$tsc_cache/root.tsbuildinfo" 2>&1) && tsc_status=0 || tsc_status=$?
+# The local binary, never `bunx`: a bunx call in a worktree can write a partial node_modules (README, tests.md).
+tsc_output=$(./node_modules/.bin/tsc --noEmit --incremental --tsBuildInfoFile "$tsc_cache/root.tsbuildinfo" 2>&1) && tsc_status=0 || tsc_status=$?
 staged_files=$(git diff --cached --name-only --diff-filter=d | grep -E '\.(ts|tsx)$' || true)
 
 # Only per-file diagnostics are skippable. A non-zero exit with NO diagnostic
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 879d787353..dca059d4ae 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -521,7 +521,8 @@ jobs:
         shell: bash
         env:
           TYPECHECK_BASE: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
-        run: bun scripts/ci/typecheck.ts --base "$TYPECHECK_BASE"
+        # A workflow_dispatch run has no base: then no --base, and every project is checked.
+        run: bun scripts/ci/typecheck.ts ${TYPECHECK_BASE:+--base "$TYPECHECK_BASE"}
 
       - name: Save TypeScript build info for the next push
         if: github.event_name == 'push'
diff --git a/scripts/ci/dashboard-smoke.test.ts b/scripts/ci/dashboard-smoke.test.ts
index fcb196425f..164a235b93 100644
--- a/scripts/ci/dashboard-smoke.test.ts
+++ b/scripts/ci/dashboard-smoke.test.ts
@@ -1,11 +1,13 @@
 import { describe, expect, test } from "bun:test";
-import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
 import { affectedDashboards, SMOKE_DASHBOARDS } from "./dashboard-smoke";
 
 describe("dashboard-smoke", () => {
+    const names = (changed: string[]) => affectedDashboards(changed).map((dashboard) => dashboard.name);
+
     test("shared code and package files reach every dashboard; a dashboard's own folder reaches only it", () => {
         const all = SMOKE_DASHBOARDS.map((dashboard) => dashboard.name);
-        const names = (changed: string[]) => affectedDashboards(changed).map((dashboard) => dashboard.name);
 
         expect(names(["src/utils/logger/daily-trigger.ts"])).toEqual(all);
         expect(names(["bun.lock"])).toEqual(all);
@@ -14,7 +16,37 @@ describe("dashboard-smoke", () => {
         expect(names(["src/youtube/extension/manifest.json"])).toEqual([]);
     });
 
-    test("every listed dashboard has its Vite config", () => {
+    test("a change in another tool's folder that a dashboard imports reaches that dashboard", () => {
+        expect(names(["src/azure-devops/config.ts"])).toEqual(["clarity"]);
+        expect(names(["src/youtube/lib/config.ts"])).toEqual(["youtube"]);
+        expect(names(["src/daemon/lib/launchd.ts"])).toEqual(["dev-dashboard", "shops"]);
+    });
+
+    test("every listed dashboard has its Vite config, and every @app import in its folder is under a root it lists", () => {
         expect(SMOKE_DASHBOARDS.filter((dashboard) => !existsSync(dashboard.config))).toEqual([]);
+
+        const listed = spawnSync("git", ["ls-files", "--", ...SMOKE_DASHBOARDS.map((d) => d.folder)], {
+            encoding: "utf8",
+            env: process.env,
+        });
+        expect(listed.status).toBe(0);
+        const sources = listed.stdout.split("\n").filter((file) => /\.tsx?$/.test(file) && !/\.test\.tsx?$/.test(file));
+
+        const unlisted = SMOKE_DASHBOARDS.flatMap((dashboard) => {
+            const files = sources.filter((file) => file.startsWith(dashboard.folder));
+            expect(files.length).toBeGreaterThan(0);
+
+            return files.flatMap((file) =>
+                [...readFileSync(file, "utf8").matchAll(/["']@app\/([\w.-]+(?:\/[\w.-]+)*)["']/g)]
+                    // `@app/yt` is youtube's alias for its own ui folder.
+                    .filter(([, spec]) => spec !== "yt" && !spec.startsWith("yt/"))
+                    .filter(
+                        ([, spec]) =>
+                            ![dashboard.folder, ...dashboard.uses].some((root) => `src/${spec}/`.startsWith(root))
+                    )
+                    .map(([, spec]) => `${dashboard.name}: ${file} imports @app/${spec}`)
+            );
+        });
+        expect(unlisted).toEqual([]);
     });
 });
diff --git a/scripts/ci/dashboard-smoke.ts b/scripts/ci/dashboard-smoke.ts
index ad74dd775d..33ac30dfd0 100644
--- a/scripts/ci/dashboard-smoke.ts
+++ b/scripts/ci/dashboard-smoke.ts
@@ -27,25 +27,55 @@ export interface SmokeDashboard {
     config: string;
     /** Files under this folder reach only this dashboard. */
     folder: string;
+    /**
+     * Other tools' folders its sources import from (`@app/azure-devops/…` is `src/azure-devops/`): a change there
+     * reaches this dashboard too. dashboard-smoke.test.ts checks every such import is listed.
+     */
+    uses: string[];
 }
 
 export const SMOKE_DASHBOARDS: SmokeDashboard[] = [
-    { name: "clarity", config: "src/clarity/ui/vite.config.ts", folder: "src/clarity/" },
+    { name: "clarity", config: "src/clarity/ui/vite.config.ts", folder: "src/clarity/", uses: ["src/azure-devops/"] },
     {
         name: "claude-history",
         config: "src/claude-history-dashboard/vite.config.ts",
         folder: "src/claude-history-dashboard/",
+        uses: ["src/claude/lib/"],
     },
     {
         name: "debugging-master",
         config: "src/debugging-master/dashboard/vite.config.ts",
         folder: "src/debugging-master/",
+        uses: ["src/log-viewer/"],
+    },
+    {
+        name: "dev-dashboard",
+        config: "src/dev-dashboard/ui/vite.config.ts",
+        folder: "src/dev-dashboard/",
+        uses: [
+            "src/ai/commands/usage/",
+            "src/ai-spend/lib/",
+            "src/claude/lib/",
+            "src/daemon/lib/",
+            "src/handoff/",
+            "src/macos/lib/swap/",
+            "src/question/",
+        ],
+    },
+    { name: "monitor", config: "src/monitor/ui/vite.config.ts", folder: "src/monitor/", uses: [] },
+    { name: "shops", config: "src/shops/ui/vite.config.ts", folder: "src/shops/", uses: ["src/daemon/lib/"] },
+    {
+        name: "spotify",
+        config: "src/spotify/ui/vite.config.ts",
+        folder: "src/spotify/",
+        uses: ["src/chrome-devtools/lib/"],
+    },
+    {
+        name: "youtube",
+        config: "src/youtube/ui/vite.config.ts",
+        folder: "src/youtube/ui/",
+        uses: ["src/youtube/lib/"],
     },
-    { name: "dev-dashboard", config: "src/dev-dashboard/ui/vite.config.ts", folder: "src/dev-dashboard/" },
-    { name: "monitor", config: "src/monitor/ui/vite.config.ts", folder: "src/monitor/" },
-    { name: "shops", config: "src/shops/ui/vite.config.ts", folder: "src/shops/" },
-    { name: "spotify", config: "src/spotify/ui/vite.config.ts", folder: "src/spotify/" },
-    { name: "youtube", config: "src/youtube/ui/vite.config.ts", folder: "src/youtube/ui/" },
 ];
 
 /** Changes that every dashboard's server can load: the shared modules, the shared UI and the dependency set. */
@@ -55,7 +85,7 @@ const READY_TIMEOUT_MS = 90_000;
 const BROKEN_GRACE_MS = 3_000;
 const FIRST_PORT = 39_300;
 
-/** The dashboards a set of changed files can reach. */
+/** The dashboards a set of changed files can reach: through its own folder, a folder it uses, or shared code. */
 export function affectedDashboards(
     changed: string[],
     dashboards: SmokeDashboard[] = SMOKE_DASHBOARDS
@@ -64,7 +94,9 @@ export function affectedDashboards(
         return dashboards;
     }
 
-    return dashboards.filter((dashboard) => changed.some((file) => file.startsWith(dashboard.folder)));
+    return dashboards.filter((dashboard) =>
+        changed.some((file) => [dashboard.folder, ...dashboard.uses].some((root) => file.startsWith(root)))
+    );
 }
 
 interface SmokeResult {
diff --git a/scripts/ci/lint-rules.test.ts b/scripts/ci/lint-rules.test.ts
index 0bd130d603..4b9061ac7c 100644
--- a/scripts/ci/lint-rules.test.ts
+++ b/scripts/ci/lint-rules.test.ts
@@ -441,6 +441,9 @@ describe("no-bun-only-import-meta", () => {
         for (const member of ["dir", "dirname", "filename", "path"]) {
             expect(rules(`const a = import.meta.${member};`, "src/clarity/ui/src/server.ts")).toContain(rule);
         }
+        // The two dashboards whose sources live outside a `ui/` folder.
+        expect(rules("const a = import.meta.dir;", "src/claude-history-dashboard/src/server.ts")).toContain(rule);
+        expect(rules("const a = import.meta.dir;", "src/debugging-master/dashboard/src/server.ts")).toContain(rule);
     });
 
     test("passes module-dir.ts, tests, vite configs, import.meta.url and code no dashboard loads", () => {
diff --git a/scripts/ci/lint-rules.ts b/scripts/ci/lint-rules.ts
index 9fcf87e784..1ec190da82 100644
--- a/scripts/ci/lint-rules.ts
+++ b/scripts/ci/lint-rules.ts
@@ -160,7 +160,8 @@ export function namesToolCommand(text: string, node: SgNode): boolean {
 /** `import.meta` members only Bun sets; Vite's SSR runner and Node leave them undefined. */
 const BUN_ONLY_IMPORT_META = /^import\.meta\.(?:dir|dirname|filename|path)$/;
 /** Code a Vite dashboard can load server-side: the shared utils and the dashboards' own sources. */
-const SSR_REACHABLE = /(?:^|\/)src\/(?:utils\/|[^/]+\/ui\/|dashboard\/)/;
+const SSR_REACHABLE =
+    /(?:^|\/)src\/(?:utils\/|[^/]+\/ui\/|dashboard\/|claude-history-dashboard\/|debugging-master\/dashboard\/)/;
 /**
  * Files under src/utils that still call a bare `require()`, each inside a function (a lazy load), counted 2026-10-22
  * when lint-rules `no-bare-require-in-utils` was added. A ratchet: no file joins, and lint-rules.test.ts fails when a
diff --git a/scripts/ci/pre-commit-hook.test.ts b/scripts/ci/pre-commit-hook.test.ts
index 1c71375895..d914a52637 100644
--- a/scripts/ci/pre-commit-hook.test.ts
+++ b/scripts/ci/pre-commit-hook.test.ts
@@ -642,3 +642,12 @@ describe("round 33 nested mirror configuration", () => {
         expect(readFileSync(join(repo, file), "utf8")).toContain("export const unstaged = 'kept';");
     });
 });
+
+describe("pre-commit hook: the typecheck binary", () => {
+    test("runs the checkout's own tsc, never bunx, which can write a partial node_modules in a worktree", () => {
+        const hook = readFileSync(join(ROOT, ".githooks/pre-commit"), "utf8");
+        const tscLine = hook.split("\n").find((line) => line.startsWith("tsc_output="));
+        expect(tscLine).toStartWith("tsc_output=$(./node_modules/.bin/tsc --noEmit");
+        expect(hook).not.toMatch(/^[^#]*\bbunx tsc\b/m);
+    });
+});
diff --git a/scripts/ci/typecheck.test.ts b/scripts/ci/typecheck.test.ts
index deff09305a..93ebae35d7 100644
--- a/scripts/ci/typecheck.test.ts
+++ b/scripts/ci/typecheck.test.ts
@@ -1,6 +1,8 @@
 import { describe, expect, it } from "bun:test";
-import { resolve } from "node:path";
-import { type Changes, type Project, reasonToRun } from "./typecheck";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { type Changes, type Project, programFiles, readState, reasonToRun } from "./typecheck";
 
 const PROJECTS: Project[] = [
     { name: "root", tsconfig: "tsconfig.json" },
@@ -54,3 +56,26 @@ describe("reasonToRun", () => {
         expect(reasons({ files: ["src/app/index.ts"], added: [] })).toEqual(["in its program", null]);
     });
 });
+
+describe("build info and the CI step", () => {
+    it("an unreadable state.json or build info counts as nothing known instead of crashing every later run", () => {
+        const dir = mkdtempSync(join(tmpdir(), "gt-typecheck-cut-"));
+        writeFileSync(join(dir, "state.json"), '{"passed":{"root":{"sha":"ab');
+        writeFileSync(join(dir, "root.tsbuildinfo"), '{"fileNames":["a.ts"');
+        expect(readState(dir)).toEqual({ passed: {} });
+        expect(programFiles(join(dir, "root.tsbuildinfo"))).toBeNull();
+    });
+
+    it("the CI step passes --base only when the event has a base (a workflow_dispatch run has none)", () => {
+        const workflow = readFileSync(resolve(import.meta.dir, "../../.github/workflows/ci.yml"), "utf8");
+        const step = workflow.slice(workflow.indexOf("- name: TypeScript check\n"));
+        const run = /\n\s+run: (.+)/.exec(step)?.[1] ?? "";
+        expect(run).toStartWith("bun scripts/ci/typecheck.ts");
+        const argv = (base: string) =>
+            Bun.spawnSync(["bash", "-c", run.replace("bun scripts/ci/typecheck.ts", "printf '[%s]'")], {
+                env: { ...process.env, TYPECHECK_BASE: base },
+            }).stdout.toString();
+        expect(argv("")).toBe("[]");
+        expect(argv("abc123")).toBe("[--base][abc123]");
+    });
+});
diff --git a/scripts/ci/typecheck.ts b/scripts/ci/typecheck.ts
index c5a2ed4d75..324908aabd 100644
--- a/scripts/ci/typecheck.ts
+++ b/scripts/ci/typecheck.ts
@@ -153,14 +153,22 @@ function cacheDir(): string {
     return path;
 }
 
-function readState(dir: string): State {
+/** What the last passing runs recorded; an unreadable file (a run killed mid-write) counts as nothing known. */
+export function readState(dir: string): State {
     const file = join(dir, "state.json");
     const passed: Record<string, Passed> = {};
     if (!existsSync(file)) {
         return { passed };
     }
 
-    const parsed: unknown = SafeJSON.parse(readFileSync(file, "utf8"));
+    let parsed: unknown;
+    try {
+        parsed = SafeJSON.parse(readFileSync(file, "utf8"));
+    } catch (err) {
+        out.println(`typecheck: ignoring unreadable ${file}: ${err instanceof Error ? err.message : String(err)}`);
+        return { passed };
+    }
+
     const entries = (parsed as { passed?: unknown } | null)?.passed;
     for (const [name, value] of Object.entries(typeof entries === "object" && entries !== null ? entries : {})) {
         if (isPassed(value)) {
@@ -175,13 +183,20 @@ function buildInfoPath(dir: string, project: Project): string {
     return join(dir, `${project.name}.tsbuildinfo`);
 }
 
-/** The files of the project's last program, from its build info; null when there is none to read. */
+/** The files of the project's last program, from its build info; null when there is none to read, or it is cut. */
 export function programFiles(buildInfo: string): Set<string> | null {
     if (!existsSync(buildInfo)) {
         return null;
     }
 
-    const parsed: unknown = SafeJSON.parse(readFileSync(buildInfo, "utf8"), { strict: true });
+    let parsed: unknown;
+    try {
+        parsed = SafeJSON.parse(readFileSync(buildInfo, "utf8"), { strict: true });
+    } catch (err) {
+        out.println(`typecheck: ignoring unreadable ${buildInfo}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+
     const names = (parsed as { fileNames?: unknown } | null)?.fileNames;
     if (!Array.isArray(names)) {
         return null;
diff --git a/src/genesis-tools/commands/logs.ts b/src/genesis-tools/commands/logs.ts
index bcf66852c5..50363e6613 100644
--- a/src/genesis-tools/commands/logs.ts
+++ b/src/genesis-tools/commands/logs.ts
@@ -129,7 +129,7 @@ function registerFailures(logs: Command): void {
         .option("--limit <n>", "Show the newest N", "40")
         .action((options: FilterOptions & { limit: string }) => {
             const window = windowOf(options);
-            const failures = loadFailures({ window, filter: filterOf(options) }).slice(-Number(options.limit));
+            const failures = loadFailures({ window, filter: filterOf(options), limit: Number(options.limit) });
             if (options.json) {
                 out.result(failures);
                 return;
@@ -358,6 +358,7 @@ function registerProfile(logs: Command): void {
                     scopes: parseVariadic(options.scope),
                     grep: options.grep,
                     pid: options.pid ? Number(options.pid) : undefined,
+                    top: Number(options.top),
                 })
                     .sort((a, b) => b.ms - a.ms)
                     .slice(0, Number(options.top));
diff --git a/src/genesis-tools/lib/failures.ts b/src/genesis-tools/lib/failures.ts
index 8f14e7b708..a78497134a 100644
--- a/src/genesis-tools/lib/failures.ts
+++ b/src/genesis-tools/lib/failures.ts
@@ -64,22 +64,32 @@ export function matchesFailure(failure: ToolFailure, filter: FailureFilter): boo
     return true;
 }
 
-/** The failures in the window that pass the filter, oldest first. */
+/**
+ * The failures in the window that pass the filter, oldest first. With a positive `limit`, only the newest that many
+ * are kept while reading, so a long window holds no more records than it shows; a command that counts all of them
+ * passes none.
+ */
 export function loadFailures({
     window,
     filter = {},
     dir,
+    limit,
 }: {
     window: TimeWindow;
     filter?: FailureFilter;
     dir?: string;
+    limit?: number;
 }): ToolFailure[] {
     const days = daysIn(window);
     const found: ToolFailure[] = [];
+    const bound = limit !== undefined && Number.isFinite(limit) && limit > 0 ? limit : null;
 
     for (const failure of readFailures({ fromDay: days[0], toDay: days.at(-1) ?? days[0], dir })) {
         if (inWindow(failure.at, window) && matchesFailure(failure, filter)) {
             found.push(failure);
+            if (bound !== null && found.length > bound) {
+                found.shift();
+            }
         }
     }
 
diff --git a/src/genesis-tools/lib/logs.test.ts b/src/genesis-tools/lib/logs.test.ts
index 7c80d4a4e2..1e1cf0d9b7 100644
--- a/src/genesis-tools/lib/logs.test.ts
+++ b/src/genesis-tools/lib/logs.test.ts
@@ -1,8 +1,11 @@
 import { describe, expect, it } from "bun:test";
-import type { FailureCaller, ToolFailure } from "@genesiscz/utils/cli/failures/record";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { appendFailure, type FailureCaller, type ToolFailure } from "@genesiscz/utils/cli/failures/record";
 import { matchesDayLog, newestEntries, parseDayLogLine, prefilterFor } from "./day-log";
-import { groupFailures, matchesFailure, usageGaps } from "./failures";
-import { parseProfileLine } from "./profile-log";
+import { groupFailures, loadFailures, matchesFailure, usageGaps } from "./failures";
+import { parseProfileLine, queryProfileLog } from "./profile-log";
 import { daysIn, resolveWindow } from "./window";
 
 const NOW = new Date(2026, 9, 22, 16, 0);
@@ -56,6 +59,7 @@ describe("window", () => {
         expect(daysIn(window)).toEqual(["2026-10-20", "2026-10-21", "2026-10-22"]);
         expect(resolveWindow({ since: "09:30", now: NOW }).from).toEqual(new Date(2026, 9, 22, 9, 30));
         expect(() => resolveWindow({ since: "soon", now: NOW })).toThrow("--since soon is not a time");
+        expect(() => resolveWindow({ since: "1h", until: "2h", now: NOW })).toThrow("--since 1h is after --until 2h");
     });
 });
 
@@ -83,6 +87,19 @@ describe("failure filters and groups", () => {
         expect(rows.filter((row) => matchesFailure(row, { grep: "--repo" })).map((row) => row.id)).toEqual(["a", "b"]);
     });
 
+    it("keeps only the newest N matches while reading when a limit is passed, and all of them without one", () => {
+        const dir = mkdtempSync(join(tmpdir(), "gt-logs-failures-"));
+        const at = (minute: number) => new Date(2026, 9, 22, 15, minute).toISOString();
+        for (const [index, row] of rows.entries()) {
+            appendFailure({ ...row, at: at(index) }, dir);
+        }
+
+        const window = resolveWindow({ since: "2h", now: NOW });
+        expect(loadFailures({ window, dir, limit: 2 }).map((row) => row.id)).toEqual(["b", "d"]);
+        expect(loadFailures({ window, dir }).map((row) => row.id)).toEqual(["a", "b", "d"]);
+        expect(loadFailures({ window, dir, limit: 0 }).map((row) => row.id)).toEqual(["a", "b", "d"]);
+    });
+
     it("counts groups and the sessions and models in each", () => {
         const groups = groupFailures(rows.slice(0, 2).concat(rows[3]), ["tool", "kind"]);
         expect(groups.map((group) => [group.key, group.count, group.sessions, group.models])).toEqual([
@@ -176,4 +193,20 @@ describe("profile log", () => {
         expect(parseProfileLine("[profile:agent-sessions] walk 1.5s trace=2e100b3a pid=9", "d")?.ms).toBe(1500);
         expect(parseProfileLine("── cli ──", "d")).toBeNull();
     });
+
+    it("keeps only the slowest N while reading when --top reaches it, in the order a full sort gives", () => {
+        const dir = mkdtempSync(join(tmpdir(), "gt-logs-profile-"));
+        const ms = [120, 900, 40, 900, 300, 5];
+        writeFileSync(
+            join(dir, "2026-10-22-profiling.log"),
+            `${ms.map((value, index) => `[profile:cli] step${index} ${value}ms pid=${index}`).join("\n")}\n`
+        );
+        const query = { days: ["2026-10-22"], minMs: 0, dir };
+        const all = queryProfileLog(query).sort((a, b) => b.ms - a.ms);
+        expect(queryProfileLog({ ...query, top: 3 }).map((entry) => entry.label)).toEqual(
+            all.slice(0, 3).map((entry) => entry.label)
+        );
+        expect(queryProfileLog({ ...query, top: 3 }).map((entry) => entry.label)).toEqual(["step1", "step3", "step4"]);
+        expect(queryProfileLog(query)).toHaveLength(6);
+    });
 });
diff --git a/src/genesis-tools/lib/profile-log.ts b/src/genesis-tools/lib/profile-log.ts
index f800a21691..6a8bb07e8e 100644
--- a/src/genesis-tools/lib/profile-log.ts
+++ b/src/genesis-tools/lib/profile-log.ts
@@ -40,14 +40,18 @@ export interface ProfileQuery {
     pid?: number;
     /** `@name` lines are marks (a point in time since the process started), not durations. */
     marks?: boolean;
+    /** Keep only the slowest N while reading, slowest first; without it every match comes back in log order. */
+    top?: number;
+    dir?: string;
 }
 
 export function queryProfileLog(query: ProfileQuery): ProfileEntry[] {
     const wanted = new Set(query.days);
     const found: ProfileEntry[] = [];
     const needle = query.grep?.toLowerCase();
+    const top = query.top !== undefined && Number.isFinite(query.top) && query.top > 0 ? query.top : null;
 
-    for (const file of listDayLogs({ profiling: true })) {
+    for (const file of listDayLogs({ profiling: true, dir: query.dir })) {
         if (!wanted.has(file.day)) {
             continue;
         }
@@ -65,7 +69,18 @@ export function queryProfileLog(query: ProfileQuery): ProfileEntry[] {
                 continue;
             }
 
-            found.push(entry);
+            if (top === null) {
+                found.push(entry);
+                continue;
+            }
+
+            // A bounded buffer, slowest first: an entry slots in after every one at least as slow, and the fastest
+            // falls off past N, so the result equals a stable sort of everything cut to N.
+            const at = found.findIndex((kept) => kept.ms < entry.ms);
+            found.splice(at === -1 ? found.length : at, 0, entry);
+            if (found.length > top) {
+                found.pop();
+            }
         }
     }
 
diff --git a/src/genesis-tools/lib/window.ts b/src/genesis-tools/lib/window.ts
index dc522fa2dc..a53187036c 100644
--- a/src/genesis-tools/lib/window.ts
+++ b/src/genesis-tools/lib/window.ts
@@ -35,6 +35,11 @@ export function resolveWindow({
         throw new Error(`--until ${until} is not a time: use 30m, 24h, 7d, HH:MM or YYYY-MM-DD`);
     }
 
+    // An inverted window has no days, and the readers would then scan every day file to keep nothing.
+    if (from.getTime() > to.getTime()) {
+        throw new Error(`--since ${since} is after --until ${until ?? "now"}`);
+    }
+
     return { from, to };
 }
 
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift
index cd5f5c26ed..5613ee104b 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Widgets/WidgetModel.swift
@@ -554,8 +554,13 @@ public final class WidgetModel: ObservableObject {
     }
 
     public func openModule(_ moduleID: String, on surface: WidgetSurfaceID) {
-        // The user picked this module (also by clicking the peek itself): it stays after the peek.
-        peekReplaced = nil
+        // The user picked this module (also by clicking the peek itself): it stays after the peek. A pick on another
+        // surface ends the peek here too, so the surface the peek switched gets its own module back first.
+        if peekReplaced?.surface == surface {
+            peekReplaced = nil
+        } else {
+            restorePeekModule()
+        }
         moduleSelections[surface.key] = moduleID
         defaults.set(moduleSelections, forKey: "widget.moduleSelections")
         activeSideGroup = surface.group
diff --git a/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift b/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift
index d1ee14e303..0b4b053585 100644
--- a/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift
+++ b/src/macos/GenesisKit/Tests/GenesisKitTests/EdgePanelGeometryTests.swift
@@ -494,6 +494,16 @@ final class WidgetInteractionTests: XCTestCase {
         value.collapse()
         XCTAssertEqual(value.moduleSelections[side.key], "tasks", "a module the user picked during the peek stays")
 
+        let top = WidgetSurfaceID(edge: .top)
+        value.moduleSelections[side.key] = "capture"
+        value.showPeek(item, on: side, module: "agents", seconds: 60)
+        value.openModule("tasks", on: top)
+        XCTAssertEqual(value.moduleSelections[side.key], "capture", "a pick on another surface gives the peeked one back")
+        XCTAssertEqual(value.moduleSelections[top.key], "tasks")
+        let saved = defaults.dictionary(forKey: "widget.moduleSelections") as? [String: String]
+        XCTAssertEqual(saved?[side.key], "capture", "the peek's module is never saved as the user's")
+        value.collapse()
+
         value.moduleSelections[side.key] = "capture"
         value.showPeek(item, on: side, module: "agents", seconds: 0.1)
         value.open(.right)
diff --git a/src/utils/DashboardApp/readiness.test.ts b/src/utils/DashboardApp/readiness.test.ts
index 1661046155..79dfff242d 100644
--- a/src/utils/DashboardApp/readiness.test.ts
+++ b/src/utils/DashboardApp/readiness.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { rmSync, writeFileSync } from "node:fs";
+import { chmodSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { spawnDetached } from "./detach";
@@ -111,6 +111,10 @@ describe("a server that answers with an error", () => {
                 "at /repo/src/utils/logger/daily-trigger.ts:15:55",
             ]);
             expect(serverErrorExcerpt(join(tmpdir(), "no-such-dashboard.log"))).toEqual([]);
+            // A log that exists but cannot be opened gives no excerpt rather than replacing the dashboard's report.
+            chmodSync(logFile, 0o000);
+            expect(serverErrorExcerpt(logFile)).toEqual([]);
+            chmodSync(logFile, 0o644);
             // Bun's own shape, from the real clarity log: header, properties, blank line, stack, then the code frame.
             writeFileSync(
                 logFile,
diff --git a/src/utils/DashboardApp/readiness.ts b/src/utils/DashboardApp/readiness.ts
index f7ab4594ec..1cf75f15e6 100644
--- a/src/utils/DashboardApp/readiness.ts
+++ b/src/utils/DashboardApp/readiness.ts
@@ -227,8 +227,9 @@ export function serverErrorExcerpt(logFile: string, maxLines = 8): string[] {
     }
 
     let text: string;
-    const fd = openSync(logFile, "r");
+    let fd: number | undefined;
     try {
+        fd = openSync(logFile, "r");
         const size = statSync(logFile).size;
         const length = Math.min(size, 64 * 1024);
         const buf = Buffer.alloc(length);
@@ -238,7 +239,9 @@ export function serverErrorExcerpt(logFile: string, maxLines = 8): string[] {
         logger.debug({ err, logFile }, "dashboard log unreadable for the error excerpt");
         return [];
     } finally {
-        closeSync(fd);
+        if (fd !== undefined) {
+            closeSync(fd);
+        }
     }
 
     const lines = text.split("\n");
diff --git a/src/utils/bun/preload-test-host-effects.test.ts b/src/utils/bun/preload-test-host-effects.test.ts
index 41e20db886..59b79df2a1 100644
--- a/src/utils/bun/preload-test-host-effects.test.ts
+++ b/src/utils/bun/preload-test-host-effects.test.ts
@@ -4,7 +4,7 @@ import { copyToClipboard, readFromClipboard } from "@genesiscz/utils/clipboard";
 import { fullDiskAccessSubject, requestFullDiskAccess } from "@genesiscz/utils/macos/full-disk-access";
 import { escapeJxa, runJxa } from "@genesiscz/utils/macos/jxa";
 import { NotificationBackend, sendNotification } from "@genesiscz/utils/macos/notifications";
-import { authorizeNotifications } from "@genesiscz/utils/macos/notifications-app";
+import { appNotificationBackend, authorizeNotifications } from "@genesiscz/utils/macos/notifications-app";
 import { settings } from "@genesiscz/utils/macos/system-settings";
 import {
     dispatchNotification,
@@ -101,6 +101,13 @@ describe("host-effect preload", () => {
             await expect(sendNotification({ message: "hi" })).rejects.toThrow(/sendNotification is blocked/);
         });
 
+        test("the app backend postNotification uses rejects instead of posting through GenesisTools.app", async () => {
+            await expect(appNotificationBackend.send({ message: "hi" })).rejects.toThrow(
+                /sendViaGenesisApp is blocked/
+            );
+            expect(typeof appNotificationBackend.terminalNotifierFixHint).toBe("function");
+        });
+
         test("authorizeNotifications rejects instead of raising the grant prompt", async () => {
             await expect(authorizeNotifications()).rejects.toThrow(/authorizeNotifications is blocked/);
         });
diff --git a/src/utils/bun/preload-test-host-effects.ts b/src/utils/bun/preload-test-host-effects.ts
index 8ca3ca9698..e507c3f9f4 100644
--- a/src/utils/bun/preload-test-host-effects.ts
+++ b/src/utils/bun/preload-test-host-effects.ts
@@ -166,6 +166,12 @@ function installHostEffectGuards(): void {
             "sendViaGenesisApp",
             "Assert the notification payload instead of delivering it."
         ),
+        // postNotification reaches the app through this object, built from the real sendViaGenesisApp when the
+        // module loaded, so replacing the export above alone does not cover that path.
+        appNotificationBackend: {
+            ...realMacosNotificationsApp.appNotificationBackend,
+            send: blockedAsync("sendViaGenesisApp", "Assert the notification payload instead of delivering it."),
+        },
         // These reach GenesisTools.app, which mutates Notification Center for the whole user
         // session. A test that removes "its own" notification would clear the user's real ones.
         removeNotifications: blockedAsync("removeNotifications", "Assert the removal target instead of running it."),
diff --git a/src/utils/cli/failures/failures.test.ts b/src/utils/cli/failures/failures.test.ts
index 5190227423..710f2a4890 100644
--- a/src/utils/cli/failures/failures.test.ts
+++ b/src/utils/cli/failures/failures.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "bun:test";
 import { mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { constants, tmpdir } from "node:os";
 import { join } from "node:path";
 import { formatLocalDate } from "@genesiscz/utils/date";
 import { Command } from "commander";
@@ -8,6 +8,7 @@ import { claudeProjectFolder, modelInTranscriptLines } from "./caller";
 import { recordSignalEnd, signalEnd, signalOfStatus, WITHHELD_ARGV } from "./launcher";
 import { appendFailure, readFailures, type ToolFailure } from "./record";
 import { RUN_ID_ENV } from "./run-id";
+import { signalExitStatus } from "./signal-status";
 import {
     classifyExit,
     commandPathFromArgv,
@@ -16,6 +17,7 @@ import {
     redactArgv,
     redactRunText,
     secretsFromArgv,
+    WITHHELD_TEXT,
 } from "./watch";
 
 describe("redactArgv", () => {
@@ -98,6 +100,54 @@ describe("secret option aliases", () => {
         ]);
     });
 
+    it("masks a secret value attached inside a group of short flags, in argv and where text echoes it", () => {
+        const grouped = ["daemon", "register", "-vtfixture-password", "--port", "0"];
+        const groupedSecrets = secretsFromArgv(program, grouped);
+        expect(redactArgv(grouped, groupedSecrets)).toEqual(["daemon", "register", "-vt[redacted]", "--port", "0"]);
+        expect(redactRunText("error: port 0 is invalid for fixture-password", grouped, groupedSecrets)).toBe(
+            "error: port 0 is invalid for [redacted]"
+        );
+    });
+
+    it("masks every operand past a flag no command declares when a command there takes a secret", () => {
+        const ai = new Command("ai");
+        ai.command("config").command("secret").command("set").argument("<path>").argument("[secret]");
+        ai.command("usage").argument("[day]");
+        const refused = ["config", "secret", "set", "--bogus", "ai/work/password", "correct-horse-battery-staple"];
+        const refusedSecrets = secretsFromArgv(ai, refused);
+        expect(redactArgv(refused, refusedSecrets)).toEqual([
+            "config",
+            "secret",
+            "set",
+            "--bogus",
+            "[redacted]",
+            "[redacted]",
+        ]);
+        expect(redactRunText("error: rejected correct-horse-battery-staple", refused, refusedSecrets)).toBe(
+            "error: rejected [redacted]"
+        );
+
+        const early = ["--bogus", "config", "secret", "set", "ai/work/password", "correct-horse-battery-staple"];
+        expect(redactArgv(early, secretsFromArgv(ai, early)).at(-1)).toBe("[redacted]");
+        expect(redacted(["--bogus", "daemon", "register", "-tfixture-password"])).toEqual([
+            "--bogus",
+            "[redacted]",
+            "[redacted]",
+            "-t[redacted]",
+        ]);
+
+        const plain = ["usage", "--bogus", "2026-10-22"];
+        expect(redactArgv(plain, secretsFromArgv(ai, plain))).toEqual(plain);
+    });
+
+    it("withholds a text that echoes a declared secret too short to replace, and keeps one that does not", () => {
+        const short = ["daemon", "register", "--token", "abc"];
+        const shortSecrets = secretsFromArgv(program, short);
+        expect(redactArgv(short, shortSecrets)).toEqual(["daemon", "register", "--token", "[redacted]"]);
+        expect(redactRunText("authentication rejected abc", short, shortSecrets)).toBe(WITHHELD_TEXT);
+        expect(redactRunText("authentication rejected", short, shortSecrets)).toBe("authentication rejected");
+    });
+
     it("masks the same values and any --secret=value where a message or stderr echoes them", () => {
         expect(redactRunText("error: bad value fixture-password for -t", args, secrets)).toBe(
             "error: bad value [redacted] for -t"
@@ -296,6 +346,13 @@ describe("signalEnd", () => {
         expect(signalEnd({ signal: "SIGABRT", ...direct })?.kind).toBe("crash");
     });
 
+    it("gives every fault signal the platform's status, which the tools wrapper exits with too", () => {
+        for (const name of ["SIGSEGV", "SIGBUS", "SIGABRT", "SIGILL", "SIGINT"] as const) {
+            expect(signalExitStatus(name)).toBe(128 + constants.signals[name]);
+        }
+        expect(signalEnd({ signal: "SIGSEGV", ...direct })?.exitCode).toBe(128 + constants.signals.SIGSEGV);
+    });
+
     it("is no failure for a signal that ends a run normally", () => {
         expect(signalEnd({ signal: "SIGPIPE", ...direct })).toBeNull();
         expect(signalEnd({ signal: null, ...direct })).toBeNull();
diff --git a/src/utils/cli/failures/launcher.ts b/src/utils/cli/failures/launcher.ts
index 9677ace4f3..a3bdf83e74 100644
--- a/src/utils/cli/failures/launcher.ts
+++ b/src/utils/cli/failures/launcher.ts
@@ -10,6 +10,7 @@ import {
     readFailures,
     type ToolFailure,
 } from "./record";
+import { signalExitStatus } from "./signal-status";
 import { agentCaller } from "./watch";
 
 /**
@@ -79,7 +80,7 @@ export function signalEnd({
         return null;
     }
 
-    const exitCode = signal === null && status !== null ? status : 128 + (SIGNAL_NUMBERS.get(name) ?? 0);
+    const exitCode = signal === null && status !== null ? status : signalExitStatus(name);
     return { kind, signal: name, exitCode };
 }
 
diff --git a/src/utils/cli/failures/signal-status.ts b/src/utils/cli/failures/signal-status.ts
new file mode 100644
index 0000000000..9fe84254d8
--- /dev/null
+++ b/src/utils/cli/failures/signal-status.ts
@@ -0,0 +1,9 @@
+import { constants } from "node:os";
+
+/**
+ * The status a shell reports for a process that signal `name` ended: 128 + its number on this platform (SIGSEGV is
+ * 139, SIGINT 130). 128 for a name the platform does not know. Kept tiny: the `tools` wrapper imports it on every run.
+ */
+export function signalExitStatus(name: string): number {
+    return 128 + ((constants.signals as Record<string, number | undefined>)[name] ?? 0);
+}
diff --git a/src/utils/cli/failures/watch.ts b/src/utils/cli/failures/watch.ts
index 4b1104faa4..6f0e39faab 100644
--- a/src/utils/cli/failures/watch.ts
+++ b/src/utils/cli/failures/watch.ts
@@ -50,16 +50,22 @@ export interface ArgvSecrets {
     flags: string[];
     /** The argv indexes of a declared secret option's value (even `-x…`) and of a secret-named argument's value. */
     indexes: number[];
+    /** A secret value attached inside a group of short flags (`-vtx`): the word's index and where the value starts. */
+    attached?: { index: number; at: number }[];
 }
 
+/** What a message, stack or stderr tail becomes when it echoes a declared secret too short to replace safely. */
+export const WITHHELD_TEXT = "[withheld: it echoes a short secret value]";
+
 /**
  * Masks the value of a secret-named flag (`--token x`, `--api-key=x`), of a flag the command declares for a
- * secret-named option (`-t x` and `-tx` when `-t` is `--token`), every word `secrets.indexes` names, and any
- * secret-shaped argument.
+ * secret-named option (`-t x` and `-tx` when `-t` is `--token`), every word `secrets.indexes` names, every value
+ * `secrets.attached` names (`-vtx`), and any secret-shaped argument.
  */
 export function redactArgv(args: readonly string[], secrets: Partial<ArgvSecrets> = {}): string[] {
     const secretFlags = secrets.flags ?? [];
     const secretIndexes = new Set(secrets.indexes ?? []);
+    const attachedAt = new Map((secrets.attached ?? []).map(({ index, at }) => [index, at]));
     const isSecret = (flag: string) => SECRET_FLAG.test(flag) || secretFlags.includes(flag);
     const shorts = secretFlags.filter((flag) => /^-[^-]$/.test(flag));
 
@@ -68,6 +74,11 @@ export function redactArgv(args: readonly string[], secrets: Partial<ArgvSecrets
             return "[redacted]";
         }
 
+        const valueAt = attachedAt.get(index);
+        if (valueAt !== undefined) {
+            return `${arg.slice(0, valueAt)}[redacted]`;
+        }
+
         const assigned = /^(--?[\w-]+)=/.exec(arg);
         if (assigned && isSecret(assigned[1])) {
             return `${assigned[1]}=[redacted]`;
@@ -98,20 +109,29 @@ function secretValues(args: readonly string[], secrets: Partial<ArgvSecrets>): s
             const kept = masked[index].replace(/\[redacted\]$/, "");
             return [arg.startsWith(kept) ? arg.slice(kept.length) : arg];
         })
-        .filter((value) => value.length >= 4);
+        .filter((value) => value.length > 0);
 }
 
-/** `redactSecretsInText`, plus every `--secret-flag=value` and every secret argument value the text echoes. */
+/**
+ * `redactSecretsInText`, plus every `--secret-flag=value` and every secret argument value the text echoes. A value
+ * shorter than four characters would mask unrelated text wherever it occurs, so a text that still echoes one is
+ * withheld whole ({@link WITHHELD_TEXT}).
+ */
 export function redactRunText(text: string, args: readonly string[], secrets: Partial<ArgvSecrets> = {}): string {
     const secretFlags = secrets.flags ?? [];
     let out = redactSecretsInText(text).replace(/(--?[\w-]+)=([^\s'"`]+)/g, (whole, flag: string) =>
         SECRET_FLAG.test(flag) || secretFlags.includes(flag) ? `${flag}=[redacted]` : whole
     );
 
-    for (const value of secretValues(args, secrets)) {
+    const values = secretValues(args, secrets);
+    for (const value of values.filter((candidate) => candidate.length >= 4)) {
         out = out.split(value).join("[redacted]");
     }
 
+    if (values.some((value) => value.length < 4 && out.includes(value))) {
+        return WITHHELD_TEXT;
+    }
+
     return out;
 }
 
@@ -141,8 +161,14 @@ function isSecretOption(option: OptionNode): boolean {
     return option.long !== undefined && SECRET_FLAG.test(option.long);
 }
 
-/** The option a flag word ends with, and whether its value is the next word. Null for a flag no command declares. */
-function flagOption(word: string, chain: readonly CommandNode[]): { option: OptionNode; valueNext: boolean } | null {
+/**
+ * The option a flag word ends with, whether its value is the next word, and where a value attached to it starts
+ * (`-vtx`: 3). Null for a flag no command declares.
+ */
+function flagOption(
+    word: string,
+    chain: readonly CommandNode[]
+): { option: OptionNode; valueNext: boolean; valueAt?: number } | null {
     const find = (flag: string) =>
         chain.flatMap((command) => command.options).find((option) => option.short === flag || option.long === flag);
 
@@ -158,24 +184,59 @@ function flagOption(word: string, chain: readonly CommandNode[]): { option: Opti
             return null;
         }
 
-        if (option.required || option.optional || at === word.length - 1) {
-            return { option, valueNext: at === word.length - 1 };
+        if (at === word.length - 1) {
+            return { option, valueNext: true };
+        }
+
+        if (option.required || option.optional) {
+            return { option, valueNext: false, valueAt: at + 1 };
         }
     }
 
     return null;
 }
 
+/** A command and every subcommand under it, at any depth. */
+function commandsUnder(command: CommandNode): CommandNode[] {
+    return [command, ...command.commands.flatMap(commandsUnder)];
+}
+
+function secretFlagsOf(commands: readonly CommandNode[]): string[] {
+    const flags = commands.flatMap((command) =>
+        command.options
+            .filter(isSecretOption)
+            .flatMap((option) => [option.short, option.long].filter((flag): flag is string => flag !== undefined))
+    );
+    return [...new Set(flags)];
+}
+
+function takesSecret(command: CommandNode): boolean {
+    return (
+        command.options.some(isSecretOption) ||
+        (command.registeredArguments ?? []).some((argument) => SECRET_ARGUMENT.test(argument.name()))
+    );
+}
+
+interface WalkedArgv {
+    chain: CommandNode[];
+    secretIndexes: number[];
+    attached: { index: number; at: number }[];
+    /** The index of the first flag no command declares; commander refuses that line. Null when every flag is known. */
+    refusedAt: number | null;
+}
+
 /**
  * Reads `args` the way commander does: options of every command reached so far may come anywhere (`-v` before the
  * subcommand), an option's value is skipped, and the first operand that names no subcommand ends the chain. Stops at
  * a flag no command declares, since commander refuses that line and what follows has no known shape.
  */
-function walkArgv(program: CommandNode, args: readonly string[]): { chain: CommandNode[]; secretIndexes: number[] } {
+function walkArgv(program: CommandNode, args: readonly string[]): WalkedArgv {
     const chain = [program];
     const secretIndexes: number[] = [];
+    const attached: { index: number; at: number }[] = [];
     const operands: number[] = [];
     let commandsDone = false;
+    let refusedAt: number | null = null;
 
     for (let index = 0; index < args.length; index++) {
         const word = args[index];
@@ -190,11 +251,16 @@ function walkArgv(program: CommandNode, args: readonly string[]): { chain: Comma
         if (word.startsWith("-") && word !== "-") {
             const found = flagOption(word, chain);
             if (!found) {
+                refusedAt = index;
                 break;
             }
 
             const next = args[index + 1];
             const { option } = found;
+            if (found.valueAt !== undefined && isSecretOption(option)) {
+                attached.push({ index, at: found.valueAt });
+            }
+
             if (
                 found.valueNext &&
                 next !== undefined &&
@@ -232,7 +298,7 @@ function walkArgv(program: CommandNode, args: readonly string[]): { chain: Comma
         }
     });
 
-    return { chain, secretIndexes };
+    return { chain, secretIndexes, attached, refusedAt };
 }
 
 /** `ai usage sessions` for `tools ai usage sessions --bad`: the deepest subcommand the words name. */
@@ -245,16 +311,23 @@ export function commandPathFromArgv(program: CommandNode, args: readonly string[
 /**
  * The flags of every secret-named option on the commands `args` reaches (`-t` for `--token`), and the argv
  * indexes of their values and of a secret-named argument's value (`<path> [secret]`).
+ *
+ * A line with a flag no command declares has no known shape past that flag. When a command at or under the deepest
+ * one reached takes a secret, every later word that is not a flag counts as secret, and the flags of every secret
+ * option under it count too: a refused line is still recorded, and its secret must not be.
  */
 export function secretsFromArgv(program: CommandNode, args: readonly string[]): ArgvSecrets {
-    const { chain, secretIndexes } = walkArgv(program, args);
+    const { chain, secretIndexes, attached, refusedAt } = walkArgv(program, args);
+    const below = refusedAt === null ? [] : commandsUnder(chain[chain.length - 1]);
+    if (refusedAt === null || !below.some(takesSecret)) {
+        return { flags: secretFlagsOf(chain), indexes: secretIndexes, attached };
+    }
+
+    const rest = args.flatMap((word, index) => (index > refusedAt && !word.startsWith("-") ? [index] : []));
     return {
-        flags: chain.flatMap((command) =>
-            command.options
-                .filter(isSecretOption)
-                .flatMap((option) => [option.short, option.long].filter((flag): flag is string => flag !== undefined))
-        ),
-        indexes: secretIndexes,
+        flags: secretFlagsOf([...chain, ...below]),
+        indexes: [...new Set([...secretIndexes, ...rest])],
+        attached,
     };
 }
 
diff --git a/src/utils/genesis-tools/tools/hints.ts b/src/utils/genesis-tools/tools/hints.ts
index bafbee4806..9ba9672615 100644
--- a/src/utils/genesis-tools/tools/hints.ts
+++ b/src/utils/genesis-tools/tools/hints.ts
@@ -1,4 +1,5 @@
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
+import { spawnToolDetached } from "@genesiscz/utils/cli/tools";
 import type { CmdToolVerb, TransclusionHints } from "@genesiscz/utils/transclude";
 
 /**
@@ -15,9 +16,14 @@ export function json2mdBuild(portable: string): string {
     return `${toolCommand("json2md build")} ${portable}`;
 }
 
-/** The argv that speaks a notification's message aloud; the message is appended as the last word. */
-export function notificationSayCommand(): string[] {
-    return toolCommand("say").split(" ");
+/**
+ * Speaks a notification's message through this checkout's `say` tool, by the shared runner rather than a `tools`
+ * found on PATH (the main checkout), and detached, so the speech outlives a sender that exits right after posting.
+ */
+export function notificationSpeaker(spawn: (args: string[]) => unknown = spawnToolDetached): (message: string) => void {
+    return (message) => {
+        spawn(["say", message]);
+    };
 }
 
 /** The command that reports whether a question's `[verify]` tokens changed since capture. */
diff --git a/src/utils/macos/notifications.test.ts b/src/utils/macos/notifications.test.ts
index 5e100f3a6d..35dd2e53ac 100644
--- a/src/utils/macos/notifications.test.ts
+++ b/src/utils/macos/notifications.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from "bun:test";
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { notificationSpeaker } from "@genesiscz/utils/genesis-tools/tools/hints";
 import { systemChannelDelivered } from "@genesiscz/utils/notifications/channels/system";
 import { setupStorageSandbox } from "@genesiscz/utils/storage/test-sandbox";
 import { keptExecutable } from "@genesiscz/utils/test/kept-executable";
@@ -209,3 +210,11 @@ describe("launchdSession", () => {
         expect(launchdSession(() => null)).toEqual({ gui: true, manager: null });
     });
 });
+
+describe("notificationSpeaker", () => {
+    it("hands the say tool and the whole message to the shared tool runner, not a tools argv from PATH", () => {
+        const runs: string[][] = [];
+        notificationSpeaker((args) => runs.push(args))("Build done, 3 warnings");
+        expect(runs).toEqual([["say", "Build done, 3 warnings"]]);
+    });
+});
diff --git a/src/utils/macos/notifications.ts b/src/utils/macos/notifications.ts
index fef06bdd9a..a8efabbae8 100644
--- a/src/utils/macos/notifications.ts
+++ b/src/utils/macos/notifications.ts
@@ -26,14 +26,14 @@ export interface NotificationOptions {
      */
     attachments?: string[];
     ignoreDnD?: boolean;
-    /** Also speak the message through {@link NotificationOptions.sayCommand}. Nothing is spoken without one. */
+    /** Also speak the message through {@link NotificationOptions.speak}. Nothing is spoken without one. */
     say?: boolean;
     /**
-     * The argv that speaks the message, which is appended as its last word. GenesisTools passes
-     * `notificationSayCommand()` from `@genesiscz/utils/genesis-tools/tools/hints`; a copy of this module names no
-     * speech command of its own.
+     * Speaks the message. GenesisTools passes `notificationSpeaker()` from
+     * `@genesiscz/utils/genesis-tools/tools/hints`, which runs this checkout's speech tool; a copy of this module
+     * names no speech command of its own.
      */
-    sayCommand?: string[];
+    speak?: (message: string) => void;
     /**
      * Stable id, so the notification can be retracted later with {@link removeNotifications}, or
      * replaced in place by posting again with the same id. Generated when omitted.
@@ -497,25 +497,22 @@ export async function sendNotification(opts: NotificationOptions): Promise<Poste
     const posted = await postNotification(opts);
 
     if (opts.say) {
-        speak(opts.message, opts.sayCommand ?? []);
+        speak(opts.message, opts.speak);
     }
 
     return posted;
 }
 
-function speak(message: string, command: string[]): void {
-    if (command.length === 0) {
-        logger.debug("notification TTS skipped: no say command was passed");
+function speak(message: string, speaker: ((message: string) => void) | undefined): void {
+    if (!speaker) {
+        logger.debug("notification TTS skipped: no speaker was passed");
         return;
     }
 
     try {
-        Bun.spawn([...command, message], {
-            stdout: "ignore",
-            stderr: "ignore",
-        });
-    } catch {
-        logger.debug(`${command.join(" ")} failed for notification TTS`);
+        speaker(message);
+    } catch (error) {
+        logger.debug({ error }, "notification TTS failed");
     }
 }
 
diff --git a/tools b/tools
index f0b3b6f9d6..9f70bd5dce 100755
--- a/tools
+++ b/tools
@@ -6,6 +6,7 @@ import { basename, join, resolve } from "node:path";
 import { namedBunExecPath } from "@genesiscz/utils/cli/bun-link";
 import { takeDetachedMarker } from "@genesiscz/utils/cli/detached";
 import { RUN_ID_ENV, RUN_ROOT_ENV, RUN_TOOL_ENV } from "@genesiscz/utils/cli/failures/run-id";
+import { signalExitStatus } from "@genesiscz/utils/cli/failures/signal-status";
 import { planToolExec, terminateOrphanedChild } from "@genesiscz/utils/cli/tool-exec";
 import { skipWorktreeInstall } from "@genesiscz/utils/cli/worktree-install";
 import { env } from "@genesiscz/utils/env";
@@ -464,7 +465,7 @@ async function spawnAndCaptureStderr(
         });
         child.on("close", (code, signal) => {
             cleanup();
-            const exitCode = signal ? 128 + (signalToNumber(signal) ?? 0) : (code ?? 1);
+            const exitCode = signal ? signalExitStatus(signal) : (code ?? 1);
             // The orphan watchdog's own TERM is the wrapper cleaning up after a dead shell, not a failed run.
             if (orphanCleanup || (!signal && (code ?? 0) <= 128)) {
                 resolvePromise(exitCode);
@@ -513,11 +514,6 @@ function flushStdio(): Promise<void> {
     return Promise.all([flush(process.stdout), flush(process.stderr)]).then(() => undefined);
 }
 
-function signalToNumber(signal: NodeJS.Signals): number | undefined {
-    const map: Record<string, number> = { SIGINT: 2, SIGTERM: 15, SIGKILL: 9, SIGHUP: 1, SIGQUIT: 3 };
-    return map[signal];
-}
-
 // --- Main Logic ---
 // #446 item 5: `tools --help` used to fall through to the tool-dispatch path, which reported
 // "Tool not found: --help" and exited 1 — the first thing a new user is likely to type. This