From a5f53a5cb2623dbdd7ced250cfee02105699adc8 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Tue, 13 Oct 2026 20:16:16 +0200
Subject: [PATCH 01/32] fix(mcp-manager): a global Claude disable denies the
 server in settings.json instead of deleting it, unless a project runs it
 through its own entry

(cherry picked from commit 763f503ecb28761a1c156a10af494497a9f5402c)
---
 src/mcp-manager/README.md                     | 115 +++--
 .../__tests__/claude-global-disable.test.ts   | 179 +++++--
 .../__tests__/claude-project-override.test.ts |  54 ++-
 src/mcp-manager/commands/rename.ts            |   9 +-
 src/mcp-manager/utils/providers/claude.ts     | 441 +++++++++++-------
 src/mcp-manager/utils/providers/grok.ts       |  46 ++
 6 files changed, 611 insertions(+), 233 deletions(-)

diff --git a/src/mcp-manager/README.md b/src/mcp-manager/README.md
index 71222353a1..abab3eda1a 100644
--- a/src/mcp-manager/README.md
+++ b/src/mcp-manager/README.md
@@ -157,16 +157,30 @@ The tool uses a unified configuration file at `~/.genesis-tools/mcp-manager/conf
 
 -   Supports global and project-specific server configurations
 -   Supports stdio, SSE, and HTTP transports
--   **Global disable = removal from `mcpServers`** (see below)
+-   **Global disable = a `deniedMcpServers` entry in `~/.claude/settings.json`**
+    (see below); the config stays in `mcpServers`
 
 #### Claude enable/disable semantics
 
-Verified against the Claude Code binary: Claude Code reads `disabledMcpServers`
-**only** from per-project entries (`.projects[<cwd>].disabledMcpServers`). The
-**top-level `disabledMcpServers` key is never read by Claude Code** — it is an
-mcp-manager-only marker. The only mechanism Claude Code honors globally
-(including future projects) is the server **not existing in `mcpServers` at
-all**.
+Verified on Claude Code 2.1.296 (research note
+`2026-10-13-ClaudeCodeGlobalMcpSwitch.md`): the only
+global switch for one server is a `deniedMcpServers: [{ "serverName": "<name>" }]`
+entry in `~/.claude/settings.json`. It covers every project, also one registered
+later, and the config stays in `mcpServers`. Claude Code reads
+`disabledMcpServers` **only** from the current project entry
+(`.projects[<cwd>].disabledMcpServers`); the **top-level `disabledMcpServers` key
+in `~/.claude.json` is never read**. mcp-manager no longer writes it, and `sync`
+removes it.
+
+What a denied server looks like in Claude Code:
+
+-   It is ABSENT from `claude mcp list` and `/mcp`, not shown as "disabled";
+    `claude mcp get <name>` says `No MCP server named "<name>"`.
+-   `/mcp` cannot turn it back on: the error blames "enterprise managed policy",
+    although the entry is in your user settings. Use `tools mcp-manager enable`.
+-   The deny matches the name in every scope, so a project-scope entry or a
+    `.mcp.json` server of the same name is blocked too. A per-project enable
+    therefore cannot override a global disable; the command warns about this.
 
 **Global means the global switch only.** A global disable, a global enable,
 an install and a `sync` never write the per-project `disabledMcpServers` lists
@@ -175,21 +189,22 @@ exception is `enable --clear-project-overrides` (below). A dry run of
 `sync` once wanted to add one disabled server to the lists of all 98 projects
 (about 640 diff lines). That is why the old sweep was removed on 2026-10-13.
 
-mcp-manager therefore implements a TRUE global disable for Claude:
-
 -   **Global disable** (`tools mcp-manager disable <server> --provider claude`):
-    1. Preserves the server's full config in the unified config with
-       `_meta.enabled.claude = false` (imports it there first if missing —
-       the entry is never removed unless it is safely preserved). If the
-       config cannot be preserved, the entry stays and Claude Code still loads
-       the server everywhere; a warning says so.
-    2. Keeps the top-level marker.
-    3. **Removes the entry from `mcpServers`** in `~/.claude.json`.
--   **Global enable** restores the entry into `mcpServers` from the unified
-    config and drops the top-level marker. It does not change project lists.
-    When some projects still list the server (old entries from the removed
-    sweep, or a per-project disable), the server stays off in those projects,
-    and one warning gives the count and the two commands below.
+    1. Adds `{ "serverName": "<server>" }` to `deniedMcpServers` in
+       `~/.claude/settings.json` (once; other keys and entries stay). This write
+       comes first: if you reject it, nothing else is written.
+    2. Records `_meta.enabled.claude = false` in the unified config (imports the
+       config there first if it is missing).
+    3. Keeps the entry in `mcpServers`. An entry that an older delete-based
+       disable removed is put back from the unified config, with one exception
+       for Grok (below).
+    4. Drops the name from the top-level marker.
+-   **Global enable** puts the entry back into `mcpServers` when it is missing,
+    then removes exactly the `serverName` deny entry (a `serverUrl` pattern is
+    never touched; the key goes when the list is empty). It does not change
+    project lists. When some projects still list the server (old entries from
+    the removed sweep, or a per-project disable), the server stays off in those
+    projects, and one warning gives the count and the two commands below.
 -   **Global enable with `--clear-project-overrides`**
     (`tools mcp-manager enable <server> -p claude --clear-project-overrides`)
     also takes the name off every `.projects[<path>].disabledMcpServers` list
@@ -202,42 +217,52 @@ mcp-manager therefore implements a TRUE global disable for Claude:
 -   **Per-project disable or enable** (`--project <path>`) is the only command
     that writes a project's `disabledMcpServers` list, and only for the named
     projects. The global entry stays in `mcpServers`.
--   **`list`** shows globally-disabled servers (absent from `~/.claude.json`)
-    as `disabled` for claude — sourced from the unified config — instead of
-    "not installed".
--   **`sync`** treats `_meta.enabled.claude === false` as disabled-by-absence:
-    such servers are never (re)installed into `mcpServers`, and drifted
-    entries are removed. For `true`, `false` or an unset state, `sync` writes
-    no project list. For a per-project map (`{ "/abs/path": false }`), it writes
-    only the lists of the projects the map names, and creates no project entry.
--   **`sync-from-providers`** does not interpret the absence of a
-    globally-disabled server as "user deleted it" — the unified config entry
-    and its `_meta.enabled.claude = false` flag are preserved.
+-   **`list` and `show`** read the global state from `deniedMcpServers`. A server
+    that is still absent from `~/.claude.json` with `_meta.enabled.claude = false`
+    shows as `disabled`, sourced from the unified config.
+-   **`sync`**: `_meta.enabled.claude === false` puts the config into
+    `mcpServers` and denies the name; `true` removes its `serverName` deny entry;
+    an unset state or a per-project map leaves the denylist as it is. The first
+    sync after this change therefore migrates every server the old
+    delete-based disable removed: config back, deny added, no change in what
+    Claude Code loads. The denylist is written first; if you reject that write,
+    `~/.claude.json` is not written either. For `true`, `false` or an unset
+    state, `sync` writes no project list. For a per-project map
+    (`{ "/abs/path": false }`), it writes only the lists of the projects the map
+    names, and creates no project entry.
+-   **Grok.** Grok loads `~/.claude.json` top-level `mcpServers` too, and
+    Claude's deny does not reach Grok. So an entry for a server that stays off in
+    Claude is put back only when Grok would not start it: Grok has its own
+    `config.toml` table for the name, lists it in `disabled_mcp_servers`, has
+    `[compat.claude] mcps = false`, or the unified config enables it for Grok.
+    Otherwise the entry stays out of `mcpServers` with a warning, and the deny
+    still keeps it off in Claude. A global ENABLE restores the entry
+    regardless: the server is meant to run, and Grok sees it as it always did.
+-   **`sync-from-providers`** keeps `_meta.enabled.claude = false` for a denied
+    server, and does not interpret a missing entry as "user deleted it".
+-   **`remove`** also removes the server's `serverName` deny entry, so a later
+    server of the same name is not blocked. **`rename`** moves the deny to the
+    new name.
 
 #### Per-project enable override (claude)
 
-A global disable can be overridden for individual projects:
-
 ```bash
 tools mcp-manager enable <server> -p claude --project /abs/path [--project /other] [-y]
 ```
 
 -   Installs the server's claude-format config into
-    `.projects[<path>].mcpServers.<name>` in `~/.claude.json` — Claude Code
-    DOES honor project-scope entries there (it's the same storage
-    `claude mcp add -s local` uses) — and removes the name from that project's
+    `.projects[<path>].mcpServers.<name>` in `~/.claude.json` when the global
+    entry is missing, and removes the name from that project's
     `disabledMcpServers` list.
--   The global state stays disabled: the server remains absent from the global
-    `mcpServers` and `_meta.enabled.claude` stays `false`. The override is
-    tracked solely by the presence of the project-scope entry — no extra
-    metadata.
--   **Override-awareness:** a global disable and `sync` never delete the
+-   ⚠️ Against a global disable this no longer helps: the deny blocks the name in
+    every scope, project-scope entries included, and the command warns. To run a
+    server in some projects only, enable it globally and disable it with
+    `--project` where you do not want it.
+-   The override is tracked solely by the presence of the project-scope entry —
+    no extra metadata. A global disable and `sync` never delete the
     project-scope entry, and never put the name back on that project's
     `disabledMcpServers` list (a per-project map in `sync` skips that project
     too). `sync` refreshes the entry's config from the unified config.
-    `sync-from-providers` keeps `_meta.enabled.claude === false` even though
-    the override projects report the server as enabled.
--   `list` shows such servers as `disabled globally, enabled in N project(s)`.
 -   Undo with `tools mcp-manager disable <server> -p claude --project <path>` —
     removes the project-scope entry and puts the name back on that project's
     disabled list.
diff --git a/src/mcp-manager/commands/__tests__/claude-global-disable.test.ts b/src/mcp-manager/commands/__tests__/claude-global-disable.test.ts
index 64572e1fd9..aa125aa3b7 100644
--- a/src/mcp-manager/commands/__tests__/claude-global-disable.test.ts
+++ b/src/mcp-manager/commands/__tests__/claude-global-disable.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, mock, spyOn } from "bun:test";
-import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { atomicWriteIo } from "@genesiscz/utils/storage/atomic-file";
@@ -75,6 +75,22 @@ describe("claude provider TRUE global disable", () => {
         return SafeJSON.parse(readFileSync(claudeJsonPath(), "utf-8")) as ClaudeGenericConfig & Record<string, unknown>;
     };
 
+    const userSettingsPath = () => join(homeDir, ".claude", "settings.json");
+
+    const writeUserSettings = (settings: Record<string, unknown>) => {
+        mkdirSync(join(homeDir, ".claude"), { recursive: true });
+        writeFileSync(userSettingsPath(), `${SafeJSON.stringify(settings, null, 2)}\n`);
+    };
+
+    /** `deniedMcpServers` of the user settings: the real global switch of Claude Code. */
+    const readDenied = (): unknown => {
+        if (!existsSync(userSettingsPath())) {
+            return undefined;
+        }
+
+        return (SafeJSON.parse(readFileSync(userSettingsPath(), "utf-8")) as Record<string, unknown>).deniedMcpServers;
+    };
+
     const writeUnified = async (config: UnifiedMCPConfig) => {
         const storage = new Storage("mcp-manager");
         await storage.ensureDirs();
@@ -113,20 +129,28 @@ describe("claude provider TRUE global disable", () => {
     });
 
     describe("disableServer(name, null) — global", () => {
-        // Intended change 2026-10-13: a global disable no longer sweeps the name into every
-        // project's disabledMcpServers list. Global means the global switch only.
-        it("removes the entry from mcpServers, keeps the top-level marker, leaves every project alone", async () => {
+        // Intended change 2026-10-13 (V-2): the global switch Claude Code honours is the
+        // user-settings deniedMcpServers list. The entry stays in mcpServers, and the top-level
+        // disabledMcpServers marker (which Claude Code never reads) is dropped.
+        it("denies the server in settings.json, keeps its entry, drops the marker, leaves every project alone", async () => {
             writeClaudeJson(claudeFixture());
             await writeUnified(unifiedFixture());
+            writeUserSettings({ theme: "dark" });
 
             const provider = new ClaudeProvider();
             await provider.disableServer("serena", null);
 
             const claude = readClaudeJson();
-            expect(claude.mcpServers?.serena).toBeUndefined(); // TRUE global disable
+            expect(claude.mcpServers?.serena).toEqual(SERENA); // config kept
+            expect(readDenied()).toEqual([{ serverName: "serena" }]); // the global switch
+            expect((SafeJSON.parse(readFileSync(userSettingsPath(), "utf-8")) as Record<string, unknown>).theme).toBe(
+                "dark"
+            );
             expect(claude.mcpServers?.github).toBeDefined(); // untouched sibling
-            expect(claude.disabledMcpServers).toContain("serena"); // mcp-manager marker
+            expect(claude.disabledMcpServers).toBeUndefined(); // the empty marker list is gone
             expect(claude.projects).toEqual(claudeFixture().projects as ClaudeGenericConfig["projects"]); // no sweep
+            expect((await provider.listServers()).find((row) => row.name === "serena")?.enabled).toBe(false);
+            expect(await provider.isServerEnabled("serena")).toBe(false);
             // Unrelated state preserved (read-modify-write)
             expect(claude.numStartups).toBe(5);
             expect((claude.projects?.["/proj/a"] as Record<string, unknown> | undefined)?.history).toEqual([
@@ -152,10 +176,11 @@ describe("claude provider TRUE global disable", () => {
             expect(unified.mcpServers.serena.args).toEqual(["serena"]);
             expect(unified.mcpServers.serena._meta?.enabled?.claude).toBe(false);
 
-            expect(readClaudeJson().mcpServers?.serena).toBeUndefined();
+            expect(readClaudeJson().mcpServers?.serena).toBeDefined(); // kept: the deny is the switch
+            expect(readDenied()).toEqual([{ serverName: "serena" }]);
         });
 
-        it("does NOT remove the entry when it cannot be preserved in the unified config", async () => {
+        it("still denies the server when the unified config write is rejected; nothing is removed", async () => {
             writeClaudeJson(claudeFixture());
             await writeUnified({ mcpServers: {} });
 
@@ -166,11 +191,59 @@ describe("claude provider TRUE global disable", () => {
             await provider.disableServer("serena", null);
 
             const claude = readClaudeJson();
-            expect(claude.mcpServers?.serena).toBeDefined(); // kept — no data loss
-            expect(claude.disabledMcpServers).toContain("serena"); // marker still applied
+            expect(claude.mcpServers?.serena).toBeDefined(); // the config never leaves ~/.claude.json
+            expect(readDenied()).toEqual([{ serverName: "serena" }]);
             expect(claude.projects).toEqual(claudeFixture().projects as ClaudeGenericConfig["projects"]);
-            expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("NOT removed"));
-            expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("still loads it in every project"));
+        });
+
+        it("puts back an entry an older delete-based disable removed, unless Grok would start it", async () => {
+            const claude = claudeFixture();
+            delete (claude.mcpServers as Record<string, unknown>).serena;
+            delete (claude.mcpServers as Record<string, unknown>).github;
+            writeClaudeJson(claude);
+            await writeUnified(unifiedFixture());
+            // Grok reads ~/.claude.json mcpServers: github has a Grok table (Grok runs that one),
+            // serena has none, so a serena entry in ~/.claude.json would start serena in Grok.
+            mkdirSync(join(homeDir, ".grok"), { recursive: true });
+            writeFileSync(
+                join(homeDir, ".grok", "config.toml"),
+                TOML.stringify({ mcp_servers: { github: { command: "bunx", enabled: false } } })
+            );
+
+            await new ClaudeProvider().disableServers(["serena", "github"], null);
+
+            expect(readClaudeJson().mcpServers?.github).toEqual(GITHUB); // put back
+            expect(readClaudeJson().mcpServers?.serena).toBeUndefined(); // kept out because of Grok
+            expect(readDenied()).toEqual([{ serverName: "serena" }, { serverName: "github" }]);
+            expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("'serena' stays out of mcpServers"));
+        });
+
+        it("a sync puts the entry back despite Grok when the unified config enables it for Grok", async () => {
+            const claude = claudeFixture();
+            delete (claude.mcpServers as Record<string, unknown>).serena;
+            writeClaudeJson(claude);
+            const unified = unifiedFixture();
+            unified.mcpServers.serena._meta = { enabled: { claude: false, grok: true } };
+            await writeUnified(unified);
+            mkdirSync(join(homeDir, ".grok"), { recursive: true });
+            writeFileSync(join(homeDir, ".grok", "config.toml"), TOML.stringify({ disabled_mcp_servers: ["other"] }));
+
+            await new ClaudeProvider().syncServers({ serena: unified.mcpServers.serena });
+
+            expect(readClaudeJson().mcpServers?.serena).toEqual(SERENA); // Grok is meant to run it
+            expect(readDenied()).toEqual([{ serverName: "serena" }]); // Claude keeps it off
+        });
+
+        it("writes nothing to ~/.claude.json when the deny write is rejected", async () => {
+            const claude = claudeFixture();
+            delete (claude.mcpServers as Record<string, unknown>).serena;
+            writeClaudeJson(claude);
+            await writeUnified(unifiedFixture());
+            const before = readFileSync(claudeJsonPath(), "utf-8");
+            setGlobalOptions({}); // no --yes: every confirmation is answered "no" in a non-TTY
+
+            expect(await new ClaudeProvider().disableServers(["serena"], null)).toBe(WriteResult.Rejected);
+            expect(readFileSync(claudeJsonPath(), "utf-8")).toBe(before); // no restore without its deny
         });
     });
 
@@ -220,6 +293,8 @@ describe("claude provider TRUE global disable", () => {
         it("restores the entry, drops the top-level marker, leaves project lists and warns with the count", async () => {
             const projects = await listedEverywhere();
 
+            writeUserSettings({ deniedMcpServers: [{ serverName: "serena" }, { serverUrl: "https://other.test/*" }] });
+
             const provider = new ClaudeProvider();
             await provider.enableServer("serena", null);
 
@@ -227,7 +302,8 @@ describe("claude provider TRUE global disable", () => {
             expect(result.mcpServers?.serena).toBeDefined(); // restored
             expect(result.mcpServers?.serena.command).toBe("uvx");
             expect((result.mcpServers?.serena as Record<string, unknown> | undefined)?._meta).toBeUndefined(); // no _meta leak
-            expect(result.disabledMcpServers).not.toContain("serena");
+            expect(result.disabledMcpServers).toBeUndefined(); // the marker is gone
+            expect(readDenied()).toEqual([{ serverUrl: "https://other.test/*" }]); // only its own entry lifted
             expect(result.projects).toEqual(projects as ClaudeGenericConfig["projects"]); // lists untouched
             expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("3 project(s)"));
             expect(logger.warn).toHaveBeenCalledWith(
@@ -287,7 +363,31 @@ describe("claude provider TRUE global disable", () => {
         });
     });
 
+    describe("remove command", () => {
+        it("removeServers lifts the deny entry too, so a later server of that name is not blocked", async () => {
+            writeClaudeJson(claudeFixture());
+            writeUserSettings({ deniedMcpServers: [{ serverName: "serena" }, { serverName: "other" }] });
+
+            await new ClaudeProvider().removeServers(["serena"]);
+
+            expect(readClaudeJson().mcpServers?.serena).toBeUndefined();
+            expect(readDenied()).toEqual([{ serverName: "other" }]);
+        });
+    });
+
     describe("listServers", () => {
+        it("reads the global state from deniedMcpServers, not from the top-level marker", async () => {
+            const claude = claudeFixture();
+            claude.disabledMcpServers = ["github"]; // ignored by Claude Code, and now by mcp-manager
+            writeClaudeJson(claude);
+            writeUserSettings({ deniedMcpServers: [{ serverName: "serena" }] });
+
+            const rows = await new ClaudeProvider().listServers();
+
+            expect(rows.find((row) => row.name === "serena")?.enabled).toBe(false);
+            expect(rows.find((row) => row.name === "github")?.enabled).toBe(true);
+        });
+
         it("reports a globally-disabled (absent) server as disabled, not missing", async () => {
             const claude = claudeFixture();
             delete (claude.mcpServers as Record<string, unknown>).serena;
@@ -309,8 +409,12 @@ describe("claude provider TRUE global disable", () => {
     });
 
     describe("syncServers (provider)", () => {
-        it("removes globally-disabled servers from mcpServers and keeps enabled ones", async () => {
-            writeClaudeJson(claudeFixture()); // serena still installed (drift)
+        // Intended change 2026-10-13 (V-2): false = in mcpServers AND denied; true lifts the deny.
+        it("denies a disabled server and keeps its entry, lifts the deny of an enabled one, drops the marker", async () => {
+            const claude = claudeFixture();
+            claude.disabledMcpServers = ["serena", "github", "old-name"];
+            writeClaudeJson(claude);
+            writeUserSettings({ deniedMcpServers: [{ serverName: "github" }] }); // stale deny of an enabled server
             const unified = unifiedFixture();
             unified.mcpServers.serena._meta = { enabled: { claude: false } };
             await writeUnified(unified);
@@ -318,11 +422,24 @@ describe("claude provider TRUE global disable", () => {
             const provider = new ClaudeProvider();
             await provider.syncServers(unified.mcpServers);
 
-            const claude = readClaudeJson();
-            expect(claude.mcpServers?.serena).toBeUndefined(); // drift corrected
-            expect(claude.mcpServers?.github).toBeDefined();
-            expect(claude.disabledMcpServers).toContain("serena");
-            expect(claude.disabledMcpServers).not.toContain("github");
+            const result = readClaudeJson();
+            expect(result.mcpServers?.serena).toEqual(SERENA);
+            expect(result.mcpServers?.github).toBeDefined();
+            expect(readDenied()).toEqual([{ serverName: "serena" }]);
+            expect(result.disabledMcpServers).toBeUndefined(); // Claude Code never read it
+        });
+
+        it("leaves the deny of a server with no claude decision as it is", async () => {
+            writeClaudeJson(claudeFixture());
+            writeUserSettings({ deniedMcpServers: [{ serverName: "unset" }] });
+            const unified = unifiedFixture();
+            unified.mcpServers.unset = { type: "stdio", command: "unset-mcp" };
+            await writeUnified(unified);
+
+            await new ClaudeProvider().syncServers({ unset: unified.mcpServers.unset });
+
+            expect(readDenied()).toEqual([{ serverName: "unset" }]);
+            expect(readClaudeJson().mcpServers?.unset).toBeDefined();
         });
     });
 
@@ -348,7 +465,9 @@ describe("claude provider TRUE global disable", () => {
             const claude = readClaudeJson();
             expect(claude.mcpServers?.github).toBeDefined(); // the sync really ran
             expect(claude.mcpServers?.unset).toBeDefined();
+            // /proj/o runs serena through a project-scope entry, so serena keeps the older switch.
             expect(claude.mcpServers?.serena).toBeUndefined();
+            expect(readDenied()).toBeUndefined();
             // The only project change: the override entry is refreshed from the unified config.
             const expected = {
                 ...projectsFixture(),
@@ -380,7 +499,7 @@ describe("claude provider TRUE global disable", () => {
     });
 
     describe("sync command", () => {
-        it("does not (re)install globally-disabled servers", async () => {
+        it("puts a disabled server back into mcpServers and denies it", async () => {
             writeClaudeJson({
                 numStartups: 5,
                 mcpServers: {},
@@ -396,7 +515,9 @@ describe("claude provider TRUE global disable", () => {
 
             const claude = readClaudeJson();
             expect(claude.mcpServers?.github).toBeDefined(); // enabled → installed
-            expect(claude.mcpServers?.serena).toBeUndefined(); // disabled → stays absent
+            expect(claude.mcpServers?.serena).toEqual(SERENA); // disabled → kept, denied
+            expect(readDenied()).toEqual([{ serverName: "serena" }]);
+            expect(claude.disabledMcpServers).toBeUndefined();
         });
     });
 
@@ -421,7 +542,7 @@ describe("claude provider TRUE global disable", () => {
     });
 
     describe("rename command", () => {
-        it("renames a globally-disabled server in the unified config without installing it in claude", async () => {
+        it("renames a globally-disabled server: the new name is kept and denied, the old deny goes", async () => {
             writeClaudeJson({
                 mcpServers: {},
                 disabledMcpServers: ["serena"],
@@ -431,6 +552,7 @@ describe("claude provider TRUE global disable", () => {
             await writeUnified({
                 mcpServers: { serena: { ...SERENA, _meta: { enabled: { claude: false } } } },
             });
+            writeUserSettings({ deniedMcpServers: [{ serverName: "serena" }] });
 
             const provider = new ClaudeProvider();
             await renameServer("serena", "serena-x", [provider]);
@@ -441,20 +563,22 @@ describe("claude provider TRUE global disable", () => {
             expect(unified.mcpServers.serena).toBeUndefined();
 
             const claude = readClaudeJson();
-            expect(claude.mcpServers?.["serena-x"]).toBeUndefined(); // still globally disabled = absent
+            expect(claude.mcpServers?.["serena-x"]).toEqual(SERENA); // kept under its new name
             expect(claude.mcpServers?.serena).toBeUndefined();
+            expect(readDenied()).toEqual([{ serverName: "serena-x" }]); // still off; no stale deny
         });
     });
 
     describe("disable/enable commands end-to-end (toggle flow)", () => {
-        it("disable --provider claude removes the entry and flips _meta to false", async () => {
+        it("disable --provider claude denies the server, keeps the entry and flips _meta to false", async () => {
             writeClaudeJson(claudeFixture());
             await writeUnified(unifiedFixture());
 
             const provider = new ClaudeProvider();
             await disableCommand("serena", [provider], { provider: "claude" });
 
-            expect(readClaudeJson().mcpServers?.serena).toBeUndefined();
+            expect(readClaudeJson().mcpServers?.serena).toEqual(SERENA);
+            expect(readDenied()).toEqual([{ serverName: "serena" }]);
             const unified = await readUnified();
             expect(unified.mcpServers.serena._meta?.enabled?.claude).toBe(false);
             expect(unified.mcpServers.serena.command).toBe("uvx");
@@ -475,7 +599,8 @@ describe("claude provider TRUE global disable", () => {
 
             const result = readClaudeJson();
             expect(result.mcpServers?.serena).toBeDefined();
-            expect(result.disabledMcpServers).not.toContain("serena");
+            expect(result.disabledMcpServers).toBeUndefined();
+            expect(readDenied()).toBeUndefined(); // nothing was denied, nothing is written
 
             const unifiedAfter = await readUnified();
             expect(unifiedAfter.mcpServers.serena._meta?.enabled?.claude).toBe(true);
diff --git a/src/mcp-manager/commands/__tests__/claude-project-override.test.ts b/src/mcp-manager/commands/__tests__/claude-project-override.test.ts
index c8b86c871d..5febda3668 100644
--- a/src/mcp-manager/commands/__tests__/claude-project-override.test.ts
+++ b/src/mcp-manager/commands/__tests__/claude-project-override.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, mock, spyOn } from "bun:test";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { setupStorageSandbox } from "@genesiscz/utils/storage/test-sandbox";
@@ -50,6 +50,13 @@ describe("claude per-project enable override for globally-disabled servers", ()
         return SafeJSON.parse(readFileSync(claudeJsonPath(), "utf-8")) as ClaudeGenericConfig & Record<string, unknown>;
     };
 
+    const readDenied = (): unknown => {
+        const settingsPath = join(homeDir, ".claude", "settings.json");
+        return existsSync(settingsPath)
+            ? (SafeJSON.parse(readFileSync(settingsPath, "utf-8")) as Record<string, unknown>).deniedMcpServers
+            : undefined;
+    };
+
     const writeUnified = async (config: UnifiedMCPConfig) => {
         const storage = new Storage("mcp-manager");
         await storage.ensureDirs();
@@ -147,6 +154,27 @@ describe("claude per-project enable override for globally-disabled servers", ()
     });
 
     // Intended change 2026-10-13: a global disable no longer sweeps project lists at all.
+    it("a later global disable keeps the older switch for an overridden server: no deny, entry absent", async () => {
+        writeClaudeJson({
+            mcpServers: { serena: { ...SERENA }, github: { ...GITHUB } },
+            projects: {
+                "/proj/a": { mcpServers: { serena: { ...SERENA } }, disabledMcpServers: [] },
+                "/proj/b": { mcpServers: {}, disabledMcpServers: [] },
+            },
+        });
+        await writeUnified(unifiedFixture());
+
+        await new ClaudeProvider().disableServers(["serena", "github"], null);
+
+        const claude = readClaudeJson();
+        expect(claude.mcpServers?.serena).toBeUndefined(); // overridden: absence is the switch
+        expect(claude.projects?.["/proj/a"].mcpServers?.serena).toBeDefined(); // the override keeps working
+        expect(claude.mcpServers?.github).toBeDefined(); // not overridden: kept and denied
+        expect(readDenied()).toEqual([{ serverName: "github" }]);
+        expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("'serena' keeps the older global switch"));
+        expect((await readUnified()).mcpServers.serena.command).toBe("uvx"); // config preserved
+    });
+
     it("a later global disable leaves every project entry alone, the override included", async () => {
         writeClaudeJson(globallyDisabledFixture());
         await writeUnified(unifiedFixture());
@@ -177,8 +205,10 @@ describe("claude per-project enable override for globally-disabled servers", ()
         expect(claude.projects?.["/proj/a"].mcpServers?.serena.command).toBe("uvx");
         // Name NOT re-added to the override project's disabled list
         expect(claude.projects?.["/proj/a"].disabledMcpServers).not.toContain("serena");
-        // Global disable still enforced (absent from mcpServers); other project lists untouched
+        // Global disable still enforced by absence: a deny (V-2) would match the project-scope
+        // entry too and switch /proj/a off, so an overridden server keeps the older switch.
         expect(claude.mcpServers?.serena).toBeUndefined();
+        expect(readDenied()).toBeUndefined();
         expect(claude.projects?.["/proj/b"].disabledMcpServers).toEqual(["serena"]);
         // Enabled sibling unaffected
         expect(claude.mcpServers?.github).toBeDefined();
@@ -218,6 +248,23 @@ describe("claude per-project enable override for globally-disabled servers", ()
         expect(unified.mcpServers.serena._meta?.enabled?.claude).toBe(false); // global state untouched
     });
 
+    it("a per-project enable of a DENIED server warns that the deny wins in every project", async () => {
+        writeClaudeJson({
+            mcpServers: { serena: { ...SERENA }, github: { ...GITHUB } },
+            projects: { "/proj/a": { mcpServers: {}, disabledMcpServers: [] } },
+        });
+        await writeUnified(unifiedFixture());
+        mkdirSync(join(homeDir, ".claude"), { recursive: true });
+        writeFileSync(
+            join(homeDir, ".claude", "settings.json"),
+            SafeJSON.stringify({ deniedMcpServers: [{ serverName: "serena" }] })
+        );
+
+        await enableCommand("serena", [new ClaudeProvider()], { provider: "claude", project: ["/proj/a"] });
+
+        expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("a per-project enable cannot turn it on"));
+    });
+
     it("listServers reports the global disable AND the per-project override", async () => {
         writeClaudeJson(globallyDisabledFixture());
         await writeUnified(unifiedFixture());
@@ -254,7 +301,8 @@ describe("claude per-project enable override for globally-disabled servers", ()
         await disableCommand("github", [provider, cursorProvider], { provider: "all" });
 
         const claude = readClaudeJson();
-        expect(claude.mcpServers?.github).toBeUndefined(); // globally disabled = removed
+        expect(claude.mcpServers?.github).toBeDefined(); // globally disabled = denied, config kept
+        expect(readDenied()).toEqual([{ serverName: "github" }]);
 
         const cursor = SafeJSON.parse(readFileSync(join(homeDir, ".cursor", "mcp.json"), "utf-8")) as {
             mcpServers?: Record<string, unknown>;
diff --git a/src/mcp-manager/commands/rename.ts b/src/mcp-manager/commands/rename.ts
index 2e452cf3a3..2a5c66f361 100644
--- a/src/mcp-manager/commands/rename.ts
+++ b/src/mcp-manager/commands/rename.ts
@@ -284,8 +284,10 @@ async function renameServerInProvider(
     }
 
     // IMPORTANT: syncServers only adds/updates servers, it doesn't remove servers not in the map
-    // We need to explicitly remove the old server name from the provider config after syncing
-    if (hasOldServer && oldName !== newName) {
+    // We need to explicitly remove the old server name from the provider config after syncing.
+    // Claude can hold the old name only as a deny entry in ~/.claude/settings.json (an older
+    // delete-based disable left no config), so Claude always gets the removal.
+    if (oldName !== newName && (hasOldServer || provider.getName() === "claude")) {
         await removeServerFromProvider(provider, oldName);
     }
 
@@ -327,6 +329,9 @@ async function removeServerFromProvider(provider: MCPProvider, serverName: strin
                 }
             }
             await provider.writeConfig(claudeConfig);
+            // The old name's deny entry in ~/.claude/settings.json would block a later server of
+            // that name; removeServers lifts it (the entries above are already gone).
+            await provider.removeServers([serverName]);
             break;
         }
         case "codex": {
diff --git a/src/mcp-manager/utils/providers/claude.ts b/src/mcp-manager/utils/providers/claude.ts
index 0ca59608c8..e3ef3754d3 100644
--- a/src/mcp-manager/utils/providers/claude.ts
+++ b/src/mcp-manager/utils/providers/claude.ts
@@ -12,6 +12,7 @@ import { atomicWriteFileSync } from "@genesiscz/utils/storage/atomic-file";
 import { matchGlob } from "@genesiscz/utils/string";
 import chalk from "chalk";
 import type { ClaudeGenericConfig, ClaudeMCPServerConfig } from "./claude.types.js";
+import { namesGrokWouldStartFromClaudeJson } from "./grok.js";
 import { claudeEnabledPluginServers, readClaudeSettings } from "./plugins.js";
 import type { EnableServersOptions, MCPServerInfo, UnifiedMCPServerConfig } from "./types.js";
 import { MCPProvider, WriteResult } from "./types.js";
@@ -46,18 +47,55 @@ function isDeniedByClaude(denied: unknown[], registeredName: string, url: string
     });
 }
 
+/** Applied when either write applied; otherwise the two writes changed nothing. */
+function combineWrites(first: WriteResult, second: WriteResult): WriteResult {
+    if (second === WriteResult.Rejected) {
+        return second;
+    }
+
+    return first === WriteResult.Applied || second === WriteResult.Applied
+        ? WriteResult.Applied
+        : WriteResult.NoChanges;
+}
+
+/** How many projects run `name` through their own project-scope entry (an `enable --project` override). */
+function projectsOverriding(config: ClaudeGenericConfig, name: string): number {
+    return Object.values(config.projects ?? {}).filter((project) => project.mcpServers?.[name]).length;
+}
+
+/** Drop names from the top-level `disabledMcpServers` marker, and the key once it is empty. */
+function dropTopLevelMarker(config: ClaudeGenericConfig, names: string[]): void {
+    if (!config.disabledMcpServers) {
+        return;
+    }
+
+    config.disabledMcpServers = config.disabledMcpServers.filter((name) => !names.includes(name));
+
+    if (config.disabledMcpServers.length === 0) {
+        delete config.disabledMcpServers;
+    }
+}
+
 /**
  * Claude Desktop MCP provider.
  * Manages MCP servers in ~/.claude.json
  *
- * IMPORTANT (verified against the Claude Code binary): Claude Code reads
- * `disabledMcpServers` ONLY from per-project entries
- * (`.projects[<cwd>].disabledMcpServers`). The TOP-LEVEL `disabledMcpServers`
- * key is NEVER read by Claude Code — it is an mcp-manager-only marker. The only
- * mechanism Claude Code honors globally (including future projects) is the
- * server NOT existing in `mcpServers` — so a TRUE global disable removes the
- * entry (after preserving its full config in the unified config with
- * `_meta.enabled.claude = false`), and a global enable restores it.
+ * The global switch (verified on Claude Code 2.1.296, research note
+ * 2026-10-13-ClaudeCodeGlobalMcpSwitch.md): a
+ * `deniedMcpServers: [{ "serverName": "<name>" }]` entry in
+ * `~/.claude/settings.json`. It covers every project, also one registered later,
+ * and the config stays in `mcpServers`. A denied server is ABSENT from
+ * `claude mcp list` and `/mcp` (not shown as disabled), and `/mcp` cannot turn
+ * it back on ("blocked by enterprise managed policy"). The deny matches the
+ * name in every scope, so a project-scope entry of the same name is blocked too.
+ * The top-level `disabledMcpServers` key in `~/.claude.json` does nothing;
+ * mcp-manager no longer writes it and removes it on sync. Claude Code reads
+ * `disabledMcpServers` only from the current project entry.
+ *
+ * Grok reads `~/.claude.json` top-level `mcpServers` too, and Claude's deny does
+ * not reach Grok. So a server that stays off in Claude is put back into
+ * `mcpServers` only when Grok would not start it from there (see
+ * `namesGrokWouldStartFromClaudeJson`) or the unified config enables it for Grok.
  *
  * Global means the global switch only. A global disable, a global enable, an
  * install and a sync of a boolean or unset `_meta.enabled.claude` never write a
@@ -83,10 +121,9 @@ export class ClaudeProvider extends MCPProvider {
     }
 
     shouldBeInstalled(serverConfig: UnifiedMCPServerConfig): boolean {
-        // A globally-disabled server (_meta.enabled.claude === false) must be
-        // ABSENT from ~/.claude.json — absence is the only global disable
-        // Claude Code honors. Everything else (enabled, per-project, unset)
-        // stays installed.
+        // A server with `_meta.enabled.claude === false` is put back into
+        // mcpServers by syncServers itself, which first checks that Grok would
+        // not start it from ~/.claude.json. Everything else installs up front.
         return serverConfig._meta?.enabled?.claude !== false;
     }
 
@@ -126,18 +163,18 @@ export class ClaudeProvider extends MCPProvider {
 
     async listServers(): Promise<MCPServerInfo[]> {
         const config = await this.readConfig();
+        const denied = await this.readDeniedEntries();
         const servers: MCPServerInfo[] = [];
         const globalNames = new Set<string>();
 
-        // Global servers
+        // Global servers: off when the user-settings denylist names them.
         if (config.mcpServers) {
-            const disabledServers = new Set(config.disabledMcpServers || []);
             for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
                 globalNames.add(name);
                 servers.push({
                     name,
                     config: this.claudeToUnified(serverConfig),
-                    enabled: !disabledServers.has(name),
+                    enabled: !isDeniedByClaude(denied, name, serverConfig.url),
                     provider: this.providerName,
                 });
             }
@@ -156,7 +193,8 @@ export class ClaudeProvider extends MCPProvider {
                             servers.push({
                                 name,
                                 config: this.claudeToUnified(serverConfig),
-                                enabled: !projectDisabled.has(name),
+                                enabled:
+                                    !projectDisabled.has(name) && !isDeniedByClaude(denied, name, serverConfig.url),
                                 provider: `${this.providerName}:${projectPath}`,
                             });
                         }
@@ -165,9 +203,9 @@ export class ClaudeProvider extends MCPProvider {
             }
         }
 
-        // Globally-disabled servers are absent from ~/.claude.json entirely
-        // (absence is the only global disable Claude Code honors). Surface them
-        // from the unified config as disabled so they don't look "not installed".
+        // A server an older delete-based disable removed from ~/.claude.json (or one
+        // kept out because Grok would start it): surface it from the unified config
+        // as disabled so it does not look "not installed".
         const unified = await readUnifiedConfig();
         for (const [name, entry] of Object.entries(unified.mcpServers)) {
             if (entry._meta?.enabled?.claude !== false) {
@@ -225,56 +263,85 @@ export class ClaudeProvider extends MCPProvider {
         }
     }
 
+    /** The `deniedMcpServers` entries of the user settings; an unreadable file counts as none, with a warning. */
+    private async readDeniedEntries(): Promise<unknown[]> {
+        try {
+            return deniedEntries(await this.readSettings());
+        } catch (error) {
+            logger.warn({ error, path: this.getSettingsPath() }, "mcp-manager: could not read Claude user settings");
+            return [];
+        }
+    }
+
     /**
-     * Claude Code's global switch for one plugin server is the user-settings denylist:
-     * `deniedMcpServers: [{ "serverName": "plugin:<plugin>:<server>" }]`. The plugin stays enabled
-     * (verified on Claude Code 2.1.296: `claude mcp get plugin:expo:expo` no longer finds it).
-     * Enabling removes exactly those `serverName` entries, and the key when it ends up empty.
+     * Edit the user-settings denylist in memory: add `{ serverName }` for each name in `deny` that no
+     * entry names yet, and remove exactly the `serverName` entries for the names in `allow` (a
+     * `serverUrl` pattern is never touched). The key goes when the list ends up empty. Returns
+     * whether anything changed.
      */
-    async setPluginServersEnabled(serverNames: string[], enabled: boolean): Promise<WriteResult> {
-        const settings = await this.readSettings();
-        const registered = new Set(
-            (await this.discoverPluginServers(settings))
-                .filter((server) => serverNames.includes(server.info.name))
-                .map((server) => server.registeredName)
-        );
+    private applyDenyChanges(settings: Record<string, unknown>, change: { deny: string[]; allow: string[] }): boolean {
+        const current = deniedEntries(settings);
+        const named = (entry: unknown): string | undefined =>
+            isObject(entry) && typeof entry.serverName === "string" ? entry.serverName : undefined;
+        const kept = current.filter((entry) => {
+            const name = named(entry);
+            return name === undefined || !change.allow.includes(name);
+        });
+        const present = new Set(kept.map(named));
+        const added = [...new Set(change.deny)].filter((name) => !present.has(name));
 
-        if (registered.size === 0) {
-            return WriteResult.NoChanges;
+        if (kept.length === current.length && added.length === 0) {
+            return false;
         }
 
-        const current = deniedEntries(settings);
-        const namedIn = (entry: unknown): boolean =>
-            isObject(entry) && typeof entry.serverName === "string" && registered.has(entry.serverName);
+        const next = [...kept, ...added.map((serverName) => ({ serverName }))];
 
-        if (enabled) {
-            const kept = current.filter((entry) => !namedIn(entry));
+        if (next.length === 0) {
+            delete settings.deniedMcpServers;
+        } else {
+            settings.deniedMcpServers = next;
+        }
 
-            if (kept.length === current.length) {
-                return WriteResult.NoChanges;
-            }
+        return true;
+    }
 
-            if (kept.length === 0) {
-                delete settings.deniedMcpServers;
-            } else {
-                settings.deniedMcpServers = kept;
-            }
-        } else {
-            const present = new Set(
-                current
-                    .filter(isObject)
-                    .flatMap((entry) => (typeof entry.serverName === "string" ? [entry.serverName] : []))
-            );
-            const missing = [...registered].filter((name) => !present.has(name));
+    /** Deny (`denied`) or allow the given registered server names in `~/.claude/settings.json`. */
+    private async setDeniedServerNames(names: string[], denied: boolean): Promise<WriteResult> {
+        const settings = await this.readSettings();
+        const changed = this.applyDenyChanges(
+            settings,
+            denied ? { deny: names, allow: [] } : { deny: [], allow: names }
+        );
 
-            if (missing.length === 0) {
-                return WriteResult.NoChanges;
-            }
+        return changed ? this.writeSettings(settings) : WriteResult.NoChanges;
+    }
 
-            settings.deniedMcpServers = [...current, ...missing.map((serverName) => ({ serverName }))];
+    /**
+     * Claude Code's global switch for one plugin server is the user-settings denylist:
+     * `deniedMcpServers: [{ "serverName": "plugin:<plugin>:<server>" }]`. The plugin stays enabled
+     * (verified on Claude Code 2.1.296: `claude mcp get plugin:expo:expo` no longer finds it).
+     * Enabling removes exactly those `serverName` entries, and the key when it ends up empty.
+     */
+    async setPluginServersEnabled(serverNames: string[], enabled: boolean): Promise<WriteResult> {
+        const settings = await this.readSettings();
+        const registered = [
+            ...new Set(
+                (await this.discoverPluginServers(settings))
+                    .filter((server) => serverNames.includes(server.info.name))
+                    .map((server) => server.registeredName)
+            ),
+        ];
+
+        if (registered.length === 0) {
+            return WriteResult.NoChanges;
         }
 
-        return this.writeSettings(settings);
+        const changed = this.applyDenyChanges(
+            settings,
+            enabled ? { deny: [], allow: registered } : { deny: registered, allow: [] }
+        );
+
+        return changed ? this.writeSettings(settings) : WriteResult.NoChanges;
     }
 
     /** Same flow as every harness write (diff, confirm or --yes, backup), aimed at settings.json. */
@@ -296,6 +363,7 @@ export class ClaudeProvider extends MCPProvider {
         }
 
         await this.backupManager.createBackup(settingsPath, this.providerName);
+        // Atomic like every harness write: a crash or a full disk leaves the old settings.json, never a short one.
         await mkdir(path.dirname(settingsPath), { recursive: true });
         atomicWriteFileSync(settingsPath, newContent, { mode: 0o600 });
         logger.info(chalk.green(`✓ Configuration written to ${settingsPath}`));
@@ -376,29 +444,11 @@ export class ClaudeProvider extends MCPProvider {
     }
 
     async enableServer(serverName: string, projectPath?: string | null): Promise<void> {
-        const config = await this.readConfig();
-
-        if (projectPath === null || projectPath === undefined) {
-            // Global enable (no project specified = global)
-            await this.applyGlobalEnable([serverName], config);
-        } else {
-            await this.applyProjectEnable([serverName], projectPath, config);
-        }
-
-        await this.writeConfig(config);
+        await this.enableServers([serverName], projectPath);
     }
 
     async disableServer(serverName: string, projectPath?: string | null): Promise<void> {
-        const config = await this.readConfig();
-
-        if (projectPath === null || projectPath === undefined) {
-            // Global disable (no project specified = global)
-            await this.applyGlobalDisable([serverName], config);
-        } else {
-            this.applyProjectDisable([serverName], projectPath, config);
-        }
-
-        await this.writeConfig(config);
+        await this.disableServers([serverName], projectPath);
     }
 
     async enableServerForAllProjects(serverName: string): Promise<void> {
@@ -409,6 +459,10 @@ export class ClaudeProvider extends MCPProvider {
         await this.disableServer(serverName, null);
     }
 
+    /**
+     * A global enable writes ~/.claude.json first (restore the entry), then lifts the deny in
+     * settings.json. A rejected second write leaves the server denied, so it stays off.
+     */
     async enableServers(
         serverNames: string[],
         projectPath?: string | null,
@@ -416,25 +470,45 @@ export class ClaudeProvider extends MCPProvider {
     ): Promise<WriteResult> {
         const config = await this.readConfig();
 
-        if (projectPath === null || projectPath === undefined) {
-            await this.applyGlobalEnable(serverNames, config, options);
-        } else {
+        if (projectPath !== null && projectPath !== undefined) {
             await this.applyProjectEnable(serverNames, projectPath, config);
+            return this.writeConfig(config);
+        }
+
+        await this.applyGlobalEnable(serverNames, config, options);
+        const written = await this.writeConfig(config);
+
+        if (written === WriteResult.Rejected) {
+            return written;
         }
 
-        return this.writeConfig(config);
+        return combineWrites(written, await this.setDeniedServerNames(serverNames, false));
     }
 
+    /**
+     * A global disable denies the server in settings.json FIRST, then fixes ~/.claude.json (entry
+     * kept or put back, top-level marker dropped). A rejected deny writes nothing, so a disable
+     * can never restore an entry without its deny and turn the server on. A server that some
+     * project runs through its own project-scope entry is not denied (see `applyGlobalDisable`).
+     */
     async disableServers(serverNames: string[], projectPath?: string | null): Promise<WriteResult> {
         const config = await this.readConfig();
 
-        if (projectPath === null || projectPath === undefined) {
-            await this.applyGlobalDisable(serverNames, config);
-        } else {
+        if (projectPath !== null && projectPath !== undefined) {
             this.applyProjectDisable(serverNames, projectPath, config);
+            return this.writeConfig(config);
+        }
+
+        const overridden = serverNames.filter((name) => projectsOverriding(config, name) > 0);
+        const deniable = serverNames.filter((name) => !overridden.includes(name));
+        const denied = deniable.length > 0 ? await this.setDeniedServerNames(deniable, true) : WriteResult.NoChanges;
+
+        if (denied === WriteResult.Rejected) {
+            return denied;
         }
 
-        return this.writeConfig(config);
+        await this.applyGlobalDisable(serverNames, config, overridden);
+        return combineWrites(denied, await this.writeConfig(config));
     }
 
     /**
@@ -454,6 +528,15 @@ export class ClaudeProvider extends MCPProvider {
         config: ClaudeGenericConfig
     ): Promise<void> {
         const existingProject = config.projects?.[projectPath];
+        const denied = await this.readDeniedEntries();
+
+        for (const name of serverNames.filter((server) => isDeniedByClaude(denied, server, undefined))) {
+            logger.warn(
+                chalk.yellow(
+                    `⚠ '${name}' is denied globally (deniedMcpServers), and Claude Code applies that in every project, project-scope entries included, so a per-project enable cannot turn it on. Enable it globally, then disable it in the projects where you do not want it: ${toolCommand("mcp-manager disable", name, "-p", "claude", "--project", "<path>")}`
+                )
+            );
+        }
 
         // Remove from the project's disabled list (Claude Code reads this list,
         // so an override entry only works when the name is NOT in it)
@@ -520,62 +603,66 @@ export class ClaudeProvider extends MCPProvider {
     }
 
     /**
-     * Apply a TRUE global disable to the in-memory Claude config:
-     * 1. Preserve each server's full config in the unified config with
-     *    `_meta.enabled.claude = false` (import it there if missing).
-     * 2. Keep the top-level marker (Claude Code ignores it; mcp-manager reads it).
-     * 3. Remove the entry from `mcpServers` — the only mechanism Claude Code
-     *    honors globally, including projects registered in the future.
-     * No project's `disabledMcpServers` list is written. Entries that could not
-     * be preserved are NOT removed (no data loss).
+     * The ~/.claude.json half of a global disable (the deny itself is in settings.json):
+     * 1. Record `_meta.enabled.claude = false` in the unified config (import the config there if
+     *    it is missing).
+     * 2. Keep the entry in `mcpServers`; put it back from the unified config when an older
+     *    delete-based disable removed it, unless Grok would then start it (`restoreMissing`).
+     * 3. Drop the names from the top-level `disabledMcpServers` marker, which Claude Code ignores.
+     * No project's `disabledMcpServers` list is written.
+     *
+     * Exception, `overridden`: a server that some project runs through its own project-scope entry.
+     * The deny matches the name in every scope and would switch those projects off too, so such a
+     * server keeps the older switch instead: absent from the global `mcpServers` (its config stays in
+     * the unified config and in the project entries), not denied.
      */
-    private async applyGlobalDisable(serverNames: string[], config: ClaudeGenericConfig): Promise<void> {
-        if (!config.disabledMcpServers) {
-            config.disabledMcpServers = [];
-        }
-
-        const safeToRemove = await this.preserveServersInUnifiedConfig(serverNames, config);
+    private async applyGlobalDisable(
+        serverNames: string[],
+        config: ClaudeGenericConfig,
+        overridden: string[] = []
+    ): Promise<void> {
+        const preserved = await this.preserveServersInUnifiedConfig(serverNames, config);
+        await this.restoreMissing(
+            serverNames.filter((name) => !overridden.includes(name)),
+            config,
+            { staysOffInClaude: true }
+        );
+        dropTopLevelMarker(config, serverNames);
 
-        for (const serverName of serverNames) {
-            // Top-level marker (ignored by Claude Code, kept for back-compat)
-            if (!config.disabledMcpServers.includes(serverName)) {
-                config.disabledMcpServers.push(serverName);
+        for (const name of overridden) {
+            if (config.mcpServers?.[name] && preserved.has(name)) {
+                delete config.mcpServers[name];
             }
 
-            // TRUE global disable: remove the entry from mcpServers
-            if (config.mcpServers?.[serverName]) {
-                if (safeToRemove.has(serverName)) {
-                    delete config.mcpServers[serverName];
-                } else {
-                    logger.warn(
-                        chalk.yellow(
-                            `⚠ '${serverName}' was NOT removed from mcpServers in ${this.configPath} because its config could not be preserved in the unified config, so Claude Code still loads it in every project.`
-                        )
-                    );
-                }
-            }
+            this.reportOverridden(name, config);
         }
     }
 
+    private reportOverridden(name: string, config: ClaudeGenericConfig): void {
+        logger.warn(
+            chalk.yellow(
+                `⚠ '${name}' keeps the older global switch (absent from mcpServers, not denied): ${projectsOverriding(config, name)} project(s) run it through a project-scope entry, and a deny would switch those projects off too.`
+            )
+        );
+    }
+
     /**
-     * Apply a global enable to the in-memory Claude config: restore the entry
-     * into `mcpServers` from the unified config (a TRUE global disable removed
-     * it) and drop the top-level marker. Project lists stay as they are unless
-     * `clearProjectOverrides` asks to take the name off every list that still
-     * names it; without it, one warning gives the count and the flag.
+     * The ~/.claude.json half of a global enable (the caller then lifts the deny): put the entry
+     * back into `mcpServers` when an older delete-based disable removed it, and drop the top-level
+     * marker. Grok sees a restored entry as well; that matches the old behaviour of a global
+     * enable, and the server is meant to run. Project lists stay as they are unless
+     * `clearProjectOverrides` asks to take the name off every list that still names it; without
+     * it, one warning gives the count and the flag.
      */
     private async applyGlobalEnable(
         serverNames: string[],
         config: ClaudeGenericConfig,
         options: EnableServersOptions = {}
     ): Promise<void> {
-        await this.restoreServersFromUnifiedConfig(serverNames, config);
+        await this.restoreMissing(serverNames, config, { staysOffInClaude: false });
+        dropTopLevelMarker(config, serverNames);
 
         for (const serverName of serverNames) {
-            if (config.disabledMcpServers) {
-                config.disabledMcpServers = config.disabledMcpServers.filter((name) => name !== serverName);
-            }
-
             const listing = Object.values(config.projects ?? {}).filter((project) =>
                 project.disabledMcpServers?.includes(serverName)
             );
@@ -604,11 +691,8 @@ export class ClaudeProvider extends MCPProvider {
     }
 
     /**
-     * Ensure full server configs are preserved in the unified config with
-     * `_meta.enabled.claude = false` BEFORE they are removed from
-     * ~/.claude.json. Returns the set of server names whose config body is
-     * safely stored in the unified config (pre-existing or successfully
-     * imported) — only those may be removed without data loss.
+     * Record `_meta.enabled.claude = false` in the unified config, importing a server's config
+     * there when it is missing. Returns the names whose config the unified config now holds.
      */
     private async preserveServersInUnifiedConfig(
         serverNames: string[],
@@ -649,21 +733,42 @@ export class ClaudeProvider extends MCPProvider {
     }
 
     /**
-     * Restore entries removed by a TRUE global disable: copy the server config
-     * back into `mcpServers` from the unified config (where it was preserved).
+     * Put entries an older delete-based disable removed back into `mcpServers`, from the unified
+     * config (or from `source` when the caller has the projected config). For a server that stays
+     * off in Claude (`staysOffInClaude`), Grok decides: it reads `mcpServers` too and Claude's deny
+     * does not reach it, so the entry is put back only when Grok would not start it or the unified
+     * config enables it for Grok. Otherwise it stays out, and Claude's deny still covers it.
      */
-    private async restoreServersFromUnifiedConfig(serverNames: string[], config: ClaudeGenericConfig): Promise<void> {
+    private async restoreMissing(
+        serverNames: string[],
+        config: ClaudeGenericConfig,
+        opts: { staysOffInClaude: boolean; source?: Record<string, UnifiedMCPServerConfig> }
+    ): Promise<void> {
         const missing = serverNames.filter((name) => !config.mcpServers?.[name]);
         if (missing.length === 0) {
             return;
         }
 
         const unified = await readUnifiedConfig();
+        const grokWouldStart = opts.staysOffInClaude
+            ? await namesGrokWouldStartFromClaudeJson(missing, unified)
+            : new Set<string>();
+
         for (const name of missing) {
-            const entry = unified.mcpServers[name];
+            const entry = opts.source?.[name] ?? unified.mcpServers[name];
             if (!entry) {
                 continue; // Not in unified config — nothing to restore
             }
+
+            if (grokWouldStart.has(name) && unified.mcpServers[name]?._meta?.enabled?.grok !== true) {
+                logger.warn(
+                    chalk.yellow(
+                        `⚠ '${name}' stays out of mcpServers in ${this.configPath}: Grok loads that list, has no table for it and would start it, and Claude's deny does not reach Grok. Claude's deny still keeps it off in Claude.`
+                    )
+                );
+                continue;
+            }
+
             if (!config.mcpServers) {
                 config.mcpServers = {};
             }
@@ -716,41 +821,66 @@ export class ClaudeProvider extends MCPProvider {
             }
         }
 
-        return this.writeConfig(config);
+        const written = await this.writeConfig(config);
+
+        if (written === WriteResult.Rejected) {
+            return written;
+        }
+
+        // A deny entry left behind would block a later server of the same name.
+        return combineWrites(written, await this.setDeniedServerNames(serverNames, false));
     }
 
+    /**
+     * `_meta.enabled.claude === false`: denied in settings.json, and the config kept in (or put back
+     * into) `mcpServers`, Grok permitting (`restoreMissing`). `true`: in `mcpServers`, and its
+     * `serverName` deny entry removed. Unset or a per-project map: in `mcpServers`, deny left as it
+     * is. The top-level `disabledMcpServers` marker is removed: Claude Code never reads it. The
+     * denylist is written first; when that write is rejected, ~/.claude.json is not written either,
+     * so a sync never puts an entry back without its deny.
+     */
     async syncServers(servers: Record<string, UnifiedMCPServerConfig>): Promise<WriteResult> {
+        const settings = await this.readSettings();
+        const current = await this.readConfig();
+        const disabled = Object.keys(servers).filter((name) => servers[name]._meta?.enabled?.claude === false);
+        // Same exception as a global disable: a server some project overrides keeps the older switch.
+        const overridden = disabled.filter((name) => projectsOverriding(current, name) > 0);
+        const deny = disabled.filter((name) => !overridden.includes(name));
+        const allow = Object.keys(servers).filter((name) => servers[name]._meta?.enabled?.claude === true);
+        let denyResult = WriteResult.NoChanges;
+
+        if (this.applyDenyChanges(settings, { deny, allow })) {
+            denyResult = await this.writeSettings(settings);
+
+            if (denyResult === WriteResult.Rejected) {
+                return denyResult;
+            }
+        }
+
         const config = await this.readConfig();
 
         if (!config.mcpServers) {
             config.mcpServers = {};
         }
-        if (!config.disabledMcpServers) {
-            config.disabledMcpServers = [];
+
+        delete config.disabledMcpServers;
+        await this.restoreMissing(deny, config, { staysOffInClaude: true, source: servers });
+
+        for (const name of overridden) {
+            delete config.mcpServers[name];
+            this.reportOverridden(name, config);
         }
 
         for (const [name, serverConfig] of Object.entries(servers)) {
             const cleanConfig = stripMeta(serverConfig);
-
             const enabledState = serverConfig._meta?.enabled?.claude;
-            const isGloballyEnabled = enabledState === true;
-            const isGloballyDisabled = enabledState === false;
 
-            if (isGloballyDisabled) {
-                // TRUE global disable = absent from mcpServers (Claude Code
-                // never reads the top-level disabledMcpServers key, and the
-                // per-project sweep misses projects registered later).
-                delete config.mcpServers[name];
-            } else {
+            // A disabled server keeps its config in mcpServers (the deny is the switch); one that
+            // restoreMissing kept out because of Grok, or an overridden one, stays out.
+            if (enabledState !== false || (config.mcpServers[name] && !overridden.includes(name))) {
                 config.mcpServers[name] = this.unifiedToClaude(cleanConfig);
             }
 
-            if (isGloballyEnabled) {
-                config.disabledMcpServers = config.disabledMcpServers.filter((n) => n !== name);
-            } else if (!config.disabledMcpServers.includes(name)) {
-                config.disabledMcpServers.push(name);
-            }
-
             // Per-project override entry (.projects[<path>].mcpServers.<name>):
             // refresh its config from the unified config, NEVER delete it.
             for (const projectConfig of Object.values(config.projects ?? {})) {
@@ -766,7 +896,7 @@ export class ClaudeProvider extends MCPProvider {
             }
         }
 
-        return this.writeConfig(config);
+        return combineWrites(denyResult, await this.writeConfig(config));
     }
 
     /**
@@ -819,9 +949,8 @@ export class ClaudeProvider extends MCPProvider {
      * Check if a server is enabled in this provider's config
      */
     async isServerEnabled(serverName: string): Promise<boolean> {
-        const config = await this.readConfig();
-        const disabledServers = new Set(config.disabledMcpServers || []);
-        return !disabledServers.has(serverName);
+        const url = (await this.readConfig()).mcpServers?.[serverName]?.url;
+        return !isDeniedByClaude(await this.readDeniedEntries(), serverName, url);
     }
 
     fromUnifiedConfig(servers: Record<string, UnifiedMCPServerConfig>): unknown {
diff --git a/src/mcp-manager/utils/providers/grok.ts b/src/mcp-manager/utils/providers/grok.ts
index 01c8b3410e..7e43e3aab3 100644
--- a/src/mcp-manager/utils/providers/grok.ts
+++ b/src/mcp-manager/utils/providers/grok.ts
@@ -75,6 +75,52 @@ function grokConfigPathForHome(home: string): string {
     return path.join(expanded, "config.toml");
 }
 
+/**
+ * Of `names`, the ones Grok would START if they appeared in `~/.claude.json` top-level `mcpServers`:
+ * Grok reads that list (unless `[compat.claude] mcps = false`), Claude's `deniedMcpServers` does not
+ * reach Grok, a config.toml table shadows the Claude copy, and `disabled_mcp_servers` stops it.
+ * Checked in every Grok home the unified config names; a home without a config.toml has no Grok.
+ * A config.toml that does not parse counts as "would start", the safe answer for the caller.
+ */
+export async function namesGrokWouldStartFromClaudeJson(
+    names: string[],
+    unified: UnifiedMCPConfig
+): Promise<Set<string>> {
+    const result = new Set<string>();
+
+    for (const home of resolveHarnessHomes(unified, "grok", "syncTo")) {
+        const configPath = grokConfigPathForHome(home);
+        if (!existsSync(configPath)) {
+            continue;
+        }
+
+        let config: GrokGenericConfig;
+        try {
+            config = TOML.parse(await readFile(configPath, "utf-8")) as GrokGenericConfig;
+        } catch (error) {
+            logger.warn({ error, configPath }, "mcp-manager: could not read a Grok config; assuming Grok would start");
+            for (const name of names) {
+                result.add(name);
+            }
+
+            continue;
+        }
+
+        if (!compatMcpsOn(config, "claude")) {
+            continue;
+        }
+
+        const disabled = stringList(config.disabled_mcp_servers);
+        for (const name of names) {
+            if (!config.mcp_servers?.[name] && !disabled.includes(name)) {
+                result.add(name);
+            }
+        }
+    }
+
+    return result;
+}
+
 export class GrokProvider extends MCPProvider {
     constructor() {
         const home = path.join(env.paths.getHome() || env.paths.getUserProfile() || "~", ".grok");

From 0b01fa0de9ce5437992c470b7e9e5466693b0e67 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Tue, 13 Oct 2026 20:35:48 +0200
Subject: [PATCH 02/32] fix(ai, statusline): a narrow pane shortens the branch
 in the middle instead of dropping it, and lines fit the COLUMNS - 4 cells
 Claude Code draws

(cherry picked from commit e00aceabea93957dd7d917642c907981218a7c48)
---
 src/utils/ai/statusline/layout.ts          | 26 +++++++++++++--
 src/utils/ai/statusline/render.ts          | 23 +++++++++----
 src/utils/ai/statusline/segments.ts        | 22 +++++++++++++
 src/utils/ai/statusline/statusline.test.ts | 38 +++++++++++++++++++++-
 4 files changed, 100 insertions(+), 9 deletions(-)

diff --git a/src/utils/ai/statusline/layout.ts b/src/utils/ai/statusline/layout.ts
index 6c93d7a99f..31b2386f12 100644
--- a/src/utils/ai/statusline/layout.ts
+++ b/src/utils/ai/statusline/layout.ts
@@ -9,8 +9,8 @@ export function visibleWidth(text: string): number {
 
 /**
  * Concatenate parts left to right, skipping any part that would push the line past
- * `maxWidth`. Later parts still get a chance, exactly like the shell `build_line`, so a long
- * branch name drops the branch and keeps the dirty count.
+ * `maxWidth`. Later parts still get a chance, exactly like the shell `build_line`. The branch
+ * is fitted to the room before it gets here (`fitBranch`), so only a too-narrow line drops it.
  */
 export function buildLine(parts: readonly string[], maxWidth: number): string {
     let result = "";
@@ -26,6 +26,28 @@ export function buildLine(parts: readonly string[], maxWidth: number): string {
     return result;
 }
 
+/**
+ * Cut the middle of `text` so it is at most `max` characters and both ends stay readable:
+ * `feat/2026-10-13-enhancements-unified` at 20 reads `feat/2026-…s-unified`. Counts code
+ * points like `visibleWidth`, and returns the text unchanged when it already fits.
+ */
+export function truncateMiddle(text: string, max: number): string {
+    const chars = Array.from(text);
+
+    if (chars.length <= max) {
+        return text;
+    }
+
+    if (max <= 1) {
+        return max === 1 ? "…" : "";
+    }
+
+    const tail = Math.floor((max - 1) / 2);
+    const head = max - 1 - tail;
+
+    return `${chars.slice(0, head).join("")}…${tail > 0 ? chars.slice(-tail).join("") : ""}`;
+}
+
 /**
  * The terminal width the host renders into. The statusline runs with piped stdio, so the
  * columns are read from stderr when it is still the terminal, then `COLUMNS`, then `tput`,
diff --git a/src/utils/ai/statusline/render.ts b/src/utils/ai/statusline/render.ts
index bd248bc17f..75a5f5cfc8 100644
--- a/src/utils/ai/statusline/render.ts
+++ b/src/utils/ai/statusline/render.ts
@@ -6,12 +6,13 @@ import { SafeJSON } from "@genesiscz/utils/json";
 import { logger } from "@genesiscz/utils/logger";
 import { killWithEscalation } from "@genesiscz/utils/process/killWithEscalation";
 import { StatuslineCache } from "./cache";
-import { buildLine, terminalWidth } from "./layout";
+import { buildLine, terminalWidth, visibleWidth } from "./layout";
 import {
     accountSegment,
     contextSegment,
     deltaSegment,
     dirtySegment,
+    fitBranch,
     gitSegment,
     modelDirSegment,
     modelLabel,
@@ -39,6 +40,13 @@ export interface GitInfo {
     dirty: number;
 }
 
+/**
+ * Claude Code draws the statusline 2 cells in from each edge and cuts a longer line with its own
+ * `…`: a 59-column pane showed 55 cells, a 53-column pane 49. A line built to `COLUMNS - 2` lost
+ * its last two cells, so the budget is `COLUMNS - 4`.
+ */
+const HOST_PADDING_COLUMNS = 4;
+
 /** A hung `git status` must not freeze every Claude statusline on the machine. */
 const GIT_STATUS_TIMEOUT_MS = 5_000;
 const SPAWN_KILL_GRACE_MS = 250;
@@ -85,10 +93,14 @@ export async function renderStatusline(raw: Record<string, unknown>, deps: Rende
         time("extension", async () => (config.extends ? runExtension(payload, config) : [])),
     ]);
 
-    const line1Parts = [
-        modelDirSegment(modelLabel(model, payload.modelDisplayName, config.modelStyle), basename(payload.cwd)),
-        gitSegment(git?.branch ?? null),
-    ];
+    const maxWidth = (deps.columns ?? terminalWidth(config.fallbackColumns)) - HOST_PADDING_COLUMNS;
+    const modelDir = modelDirSegment(
+        modelLabel(model, payload.modelDisplayName, config.modelStyle),
+        basename(payload.cwd)
+    );
+    // The git segment is a space plus the name, so the name gets what is left after that space.
+    const branch = fitBranch(git?.branch ?? null, maxWidth - visibleWidth(modelDir) - 1);
+    const line1Parts = [modelDir, gitSegment(branch)];
     const line2Parts: string[] = [config.showDirty ? dirtySegment(git?.branch ?? null, git?.dirty ?? 0) : ""];
 
     if (payload.contextWindowSize && payload.usage) {
@@ -112,7 +124,6 @@ export async function renderStatusline(raw: Record<string, unknown>, deps: Rende
         line2Parts.push(accountSegment(account, now()));
     }
 
-    const maxWidth = (deps.columns ?? terminalWidth(config.fallbackColumns)) - 2;
     const line1 = buildLine(line1Parts, maxWidth);
     const line2 = buildLine(line2Parts, maxWidth);
     const lines = line2 ? [line1, line2] : [line1];
diff --git a/src/utils/ai/statusline/segments.ts b/src/utils/ai/statusline/segments.ts
index 471e1869c6..6f0b07eba7 100644
--- a/src/utils/ai/statusline/segments.ts
+++ b/src/utils/ai/statusline/segments.ts
@@ -1,3 +1,4 @@
+import { truncateMiddle } from "./layout";
 import type { AccountSegmentData } from "./types";
 
 /**
@@ -103,6 +104,27 @@ export function gitSegment(branch: string | null): string {
     return branch ? ` ${ANSI.magenta}${branch}${ANSI.reset}` : "";
 }
 
+/** The fewest branch characters still worth printing; with less room the line goes without it. */
+export const MIN_BRANCH_WIDTH = 8;
+
+/**
+ * The branch as it fits in the `room` characters left after the model and the dir. Claude Code
+ * passes its own pane width as `COLUMNS`, so a 59-column pane leaves 55, and the raw model id
+ * plus the dir already take 28 of them. A branch that does not fit loses its middle instead of
+ * vanishing whole; below `MIN_BRANCH_WIDTH` it is still dropped.
+ */
+export function fitBranch(branch: string | null, room: number): string | null {
+    if (!branch) {
+        return null;
+    }
+
+    if (Array.from(branch).length <= room) {
+        return branch;
+    }
+
+    return room >= MIN_BRANCH_WIDTH ? truncateMiddle(branch, room) : null;
+}
+
 export function dirtySegment(branch: string | null, dirty: number): string {
     return branch && dirty > 0 ? `${ANSI.cyan}*${dirty}${ANSI.reset}` : "";
 }
diff --git a/src/utils/ai/statusline/statusline.test.ts b/src/utils/ai/statusline/statusline.test.ts
index 4fcb4eaf94..06098f8170 100644
--- a/src/utils/ai/statusline/statusline.test.ts
+++ b/src/utils/ai/statusline/statusline.test.ts
@@ -15,6 +15,7 @@ import { env } from "@genesiscz/utils/env";
 import * as gitCore from "@genesiscz/utils/git/core";
 import { TestRepo } from "@genesiscz/utils/git/test-repo";
 import { SafeJSON } from "@genesiscz/utils/json";
+import { stripAnsi } from "@genesiscz/utils/string";
 import { isolatedPreviewCache, isolatedPreviewCacheDir, StatuslineCache } from "./cache";
 import {
     defaultStatuslineConfig,
@@ -27,7 +28,7 @@ import {
     rememberPreviousCommand,
     saveStatuslineConfig,
 } from "./config";
-import { buildLine, visibleWidth } from "./layout";
+import { buildLine, truncateMiddle, visibleWidth } from "./layout";
 import { gitInfo, renderStatusline } from "./render";
 import {
     ANSI,
@@ -110,6 +111,13 @@ describe("statusline segments reproduce the shell script", () => {
         expect(visibleWidth(`${ANSI.red}abc${ANSI.reset}`)).toBe(3);
         expect(buildLine(["12345", "67890", "x"], 6)).toBe("12345x");
     });
+
+    test("truncateMiddle keeps both ends, counts code points, and leaves a fitting text alone", () => {
+        expect(truncateMiddle("feat/2026-10-13-enhancements-unified", 20)).toBe("feat/2026-…s-unified");
+        expect(truncateMiddle("main", 20)).toBe("main");
+        expect(truncateMiddle("🌿abcdef", 4)).toBe("🌿a…f");
+        expect(truncateMiddle("abcdef", 1)).toBe("…");
+    });
 });
 
 describe("Claude Code payload", () => {
@@ -188,6 +196,34 @@ describe("renderStatusline", () => {
         await second.settled;
     });
 
+    /**
+     * Claude Code passes its pane width as `COLUMNS`. In a 59-column pane the raw model id and
+     * the dir take 28 of the 55 usable columns, and a 36-character branch used to vanish whole.
+     */
+    test("a narrow pane keeps the branch by cutting its middle, and drops it only below eight characters", async () => {
+        const root = mkdtempSync(join(tmpdir(), "statusline-narrow-"));
+        const cwd = join(root, "GenesisTools");
+        mkdirSync(join(cwd, ".git"), { recursive: true });
+        writeFileSync(join(cwd, ".git", "HEAD"), "ref: refs/heads/feat/2026-10-13-enhancements-unified\n");
+        const cache = new StatuslineCache(join(root, "cache"));
+        const config = mergeStatuslineConfig(defaultStatuslineConfig(), {
+            graft: { enabled: false, shim: "", ttlMs: 0 },
+            metricsPost: { enabled: false, url: "", timeoutMs: 0 },
+        });
+        const narrowFeature: StatuslineFeature = { ...feature, resolveModel: async () => "claude-opus-5-5" };
+        const raw = { workspace: { current_dir: cwd, project_dir: cwd }, session_id: "1b4001ba-aaaa" };
+        const line1 = async (columns: number) => {
+            const result = await renderStatusline(raw, { feature: narrowFeature, config, cache, columns });
+
+            return stripAnsi(result.lines[0] ?? "");
+        };
+
+        expect(await line1(59)).toBe("claude-opus-5-5 GenesisTools feat/2026-10-…ents-unified");
+        expect(visibleWidth(await line1(59))).toBe(55);
+        expect(await line1(120)).toBe("claude-opus-5-5 GenesisTools feat/2026-10-13-enhancements-unified");
+        expect(await line1(36)).toBe("claude-opus-5-5 GenesisTools");
+    });
+
     test("a subagent frame renders nothing but the graft line", async () => {
         const config = mergeStatuslineConfig(defaultStatuslineConfig(), {
             graft: { enabled: false, shim: "", ttlMs: 0 },

From 5e2779a6150a75a5ccc7bc81c5a228f96a0101aa Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Wed, 14 Oct 2026 03:06:25 +0200
Subject: [PATCH 03/32] test(ai-spend): Claude prices are checked against
 Claude Code's own per-model bills from 12 real sessions, one-hour cache
 writes included

(cherry picked from commit 4fe5e2352fa14afebca15ba7b836e2bbd9bf5000)
---
 .../lib/fixtures/claude-code-bills.json       | 146 ++++++++++++++++++
 src/ai-spend/lib/pricing.test.ts              |  20 ++-
 2 files changed, 165 insertions(+), 1 deletion(-)
 create mode 100644 src/ai-spend/lib/fixtures/claude-code-bills.json

diff --git a/src/ai-spend/lib/fixtures/claude-code-bills.json b/src/ai-spend/lib/fixtures/claude-code-bills.json
new file mode 100644
index 0000000000..84ca4ae514
--- /dev/null
+++ b/src/ai-spend/lib/fixtures/claude-code-bills.json
@@ -0,0 +1,146 @@
+[
+    {
+        "model": "claude-opus-5-5",
+        "at": "2026-10-11",
+        "tokens": {
+            "input": 238,
+            "output": 67818,
+            "cacheRead": 21249331,
+            "cacheWrite": 232053,
+            "cacheWrite1h": 232053
+        },
+        "claudeCodeCostUsd": 7.4636022
+    },
+    {
+        "model": "claude-opus-5-5",
+        "at": "2026-10-11",
+        "tokens": {
+            "input": 118,
+            "output": 92109,
+            "cacheRead": 14891726,
+            "cacheWrite": 296648,
+            "cacheWrite1h": 296648
+        },
+        "claudeCodeCostUsd": 7.194181199999998
+    },
+    {
+        "model": "claude-opus-5-5",
+        "at": "2026-10-12",
+        "tokens": {
+            "input": 16,
+            "output": 9398,
+            "cacheRead": 428029,
+            "cacheWrite": 76394,
+            "cacheWrite1h": 76394
+        },
+        "claudeCodeCostUsd": 0.8847818
+    },
+    {
+        "model": "claude-sonnet-5-5",
+        "at": "2026-10-06",
+        "tokens": {
+            "input": 180,
+            "output": 110981,
+            "cacheRead": 21509927,
+            "cacheWrite": 346133,
+            "cacheWrite1h": 346133
+        },
+        "claudeCodeCostUsd": 6.796687400000002
+    },
+    {
+        "model": "claude-sonnet-5-5",
+        "at": "2026-10-11",
+        "tokens": {
+            "input": 67,
+            "output": 17888,
+            "cacheRead": 7655905,
+            "cacheWrite": 753726,
+            "cacheWrite1h": 753726
+        },
+        "claudeCodeCostUsd": 3.9595085
+    },
+    {
+        "model": "claude-sonnet-5-5",
+        "at": "2026-10-06",
+        "tokens": {
+            "input": 37,
+            "output": 20214,
+            "cacheRead": 2353059,
+            "cacheWrite": 156605,
+            "cacheWrite1h": 156605
+        },
+        "claudeCodeCostUsd": 1.2992458000000002
+    },
+    {
+        "model": "claude-fable-5-1",
+        "at": "2026-09-15",
+        "tokens": {
+            "input": 548,
+            "output": 35668,
+            "cacheRead": 3873257,
+            "cacheWrite": 475608,
+            "cacheWrite1h": 475608
+        },
+        "claudeCodeCostUsd": 12.269354250000003
+    },
+    {
+        "model": "claude-fable-5-1",
+        "at": "2026-09-08",
+        "tokens": {
+            "input": 454,
+            "output": 7325,
+            "cacheRead": 1770609,
+            "cacheWrite": 128526,
+            "cacheWrite1h": 128526
+        },
+        "claudeCodeCostUsd": 3.38396225
+    },
+    {
+        "model": "claude-fable-5-1",
+        "at": "2026-09-15",
+        "tokens": {
+            "input": 428,
+            "output": 6877,
+            "cacheRead": 1614573,
+            "cacheWrite": 93271,
+            "cacheWrite1h": 93271
+        },
+        "claudeCodeCostUsd": 2.617193250000001
+    },
+    {
+        "model": "claude-sonnet-5",
+        "at": "2026-09-16",
+        "tokens": {
+            "input": 36,
+            "output": 8337,
+            "cacheRead": 3383028,
+            "cacheWrite": 214393,
+            "cacheWrite1h": 214393
+        },
+        "claudeCodeCostUsd": 1.6176196000000003
+    },
+    {
+        "model": "claude-sonnet-5",
+        "at": "2026-10-01",
+        "tokens": {
+            "input": 4,
+            "output": 1890,
+            "cacheRead": 203321,
+            "cacheWrite": 206473,
+            "cacheWrite1h": 206473
+        },
+        "claudeCodeCostUsd": 0.8854642
+    },
+    {
+        "model": "claude-sonnet-5",
+        "at": "2026-09-29",
+        "tokens": {
+            "input": 10,
+            "output": 1165,
+            "cacheRead": 574176,
+            "cacheWrite": 147605,
+            "cacheWrite1h": 147605
+        },
+        "claudeCodeCostUsd": 0.7169251999999999
+    }
+]
diff --git a/src/ai-spend/lib/pricing.test.ts b/src/ai-spend/lib/pricing.test.ts
index ac31be9d46..ed43598b2b 100644
--- a/src/ai-spend/lib/pricing.test.ts
+++ b/src/ai-spend/lib/pricing.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { byId } from "@genesiscz/utils/ai/catalog";
-import { DEFAULT_PRICING, priceFor, resolvePrice } from "./pricing";
+import claudeCodeBills from "./fixtures/claude-code-bills.json";
+import { costOf, DEFAULT_PRICING, priceFor, resolvePrice } from "./pricing";
 import { eventCostEstimate } from "./reports/cost";
 import type { SpendEvent } from "./reports/types";
 
@@ -78,6 +79,23 @@ describe("pricing table", () => {
     });
 });
 
+describe("Claude Code's own bills", () => {
+    // Real per-model token sums from 12 local Claude Code sessions (2026-09-08 to 10-12), each next to the costUSD
+    // Claude Code itself recorded in that session's `cost-state` line. Only rows whose requests all sit in one price
+    // band and one dated rate were kept, so the sum prices like the requests did. Every row's cache writes are
+    // one-hour writes, which is what proves the 2x-input rate. Numbers only: no session id, path or content.
+    test.each(claudeCodeBills.map((bill) => [bill.model, bill.at, bill] as const))(
+        "%s on %s costs what Claude Code billed",
+        (model, at, bill) => {
+            const entry = priceFor(model, DEFAULT_PRICING);
+            expect(entry).not.toBeNull();
+
+            const ours = costOf(bill.tokens, resolvePrice(entry!, { at: new Date(at), contextTokens: 0 }));
+            expect(Math.abs(ours - bill.claudeCodeCostUsd) / bill.claudeCodeCostUsd).toBeLessThan(1e-6);
+        }
+    );
+});
+
 describe("what a recorded cost means", () => {
     // 1M fresh input, 1M cached, 100K output: grok-4.7 at list is $2 + $0.50 + $0.60.
     const turn = (overrides: Partial<SpendEvent> = {}): SpendEvent => ({

From dd17fb6553d69f7ba0f56a435aee0f508ac64fa8 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Wed, 14 Oct 2026 04:29:53 +0200
Subject: [PATCH 04/32] fix(codex): tools codex tail --events numbers each
 turn, counting the turns already in the log, instead of printing turn ?

(cherry picked from commit 884d8e153990a352760782cc632657d40ad121ad)
---
 src/codex/lib/tail-events.test.ts | 24 ++++++++++++-
 src/codex/lib/tail-events.ts      | 58 ++++++++++++++++++++++++++++---
 2 files changed, 77 insertions(+), 5 deletions(-)

diff --git a/src/codex/lib/tail-events.test.ts b/src/codex/lib/tail-events.test.ts
index 3b5b5f1464..6b17e91242 100644
--- a/src/codex/lib/tail-events.test.ts
+++ b/src/codex/lib/tail-events.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { SafeJSON } from "@genesiscz/utils/json";
-import { planFollowRead, takeCompleteLines } from "./tail-events";
+import { countStartedTurns, numberTurnLine, planFollowRead, takeCompleteLines } from "./tail-events";
 
 describe("takeCompleteLines", () => {
     // The regression: a size snapshot cut a record in half, the half failed to
@@ -79,3 +79,25 @@ describe("planFollowRead", () => {
         expect(planFollowRead(0, 120)).toEqual({ from: 0, rewound: true });
     });
 });
+
+describe("turn numbers", () => {
+    test("numbers a Codex turn's start and end lines, continuing after the turns already in the log", () => {
+        const turns = { n: 2 };
+
+        expect(numberTurnLine("▶ turn ? started", turns)).toBe("▶ turn 3 started");
+        expect(numberTurnLine("✔ turn ? completed ($0.0100)", turns)).toBe("✔ turn 3 completed ($0.0100)");
+        expect(numberTurnLine("🔧 command ls", turns)).toBe("🔧 command ls");
+        expect(numberTurnLine("▶ turn 7 started", turns)).toBe("▶ turn 7 started");
+    });
+
+    test("counts the turns a log already started", () => {
+        const started = SafeJSON.stringify({ source: "app-server", method: "turn/started", params: { threadId: "t" } });
+        const done = SafeJSON.stringify({
+            source: "app-server",
+            method: "turn/completed",
+            params: { threadId: "t", turn: {} },
+        });
+
+        expect(countStartedTurns(`${started}\n${done}\n${started}\n`)).toBe(2);
+    });
+});
diff --git a/src/codex/lib/tail-events.ts b/src/codex/lib/tail-events.ts
index aa938dc33c..6f4cc854f7 100644
--- a/src/codex/lib/tail-events.ts
+++ b/src/codex/lib/tail-events.ts
@@ -20,7 +20,54 @@ export function takeCompleteLines(buffer: string): { complete: string; rest: str
     return { complete: buffer.slice(0, cut + 1), rest: buffer.slice(cut + 1) };
 }
 
-export function printFollowedChunk(text: string, asEvents: boolean): void {
+/**
+ * Codex's app-server names a turn by id, not by number, so a rendered turn line read "▶ turn ? started". The
+ * follower counts the turns it renders (seeded from the log it skipped) and numbers the start and end lines.
+ */
+export interface TurnCounter {
+    n: number;
+}
+
+export function numberTurnLine(line: string, turns: TurnCounter): string {
+    if (line.startsWith("▶ turn ? ")) {
+        turns.n += 1;
+        return line.replace("turn ?", `turn ${turns.n}`);
+    }
+
+    if (line.startsWith("✔ turn ? ") && turns.n > 0) {
+        return line.replace("turn ?", `turn ${turns.n}`);
+    }
+
+    return line;
+}
+
+function renderedLines(text: string): string[] {
+    const lines: string[] = [];
+
+    for (const rawLine of text.split("\n")) {
+        if (!rawLine.trim()) {
+            continue;
+        }
+
+        try {
+            const line = formatStoredEventLine(SafeJSON.parse(rawLine, { strict: true }) as StoredCodexEvent);
+            if (line) {
+                lines.push(line);
+            }
+        } catch (err) {
+            logger.debug({ err, rawLine: rawLine.slice(0, 200) }, "[codex:tail] skipping unparseable event line");
+        }
+    }
+
+    return lines;
+}
+
+/** How many turns the skipped part of the log already started, so the first followed turn gets the next number. */
+export function countStartedTurns(text: string): number {
+    return renderedLines(text).filter((line) => line.startsWith("▶ turn")).length;
+}
+
+export function printFollowedChunk(text: string, asEvents: boolean, turns: TurnCounter = { n: 0 }): void {
     if (!asEvents) {
         out.print(text);
         return;
@@ -41,7 +88,7 @@ export function printFollowedChunk(text: string, asEvents: boolean): void {
 
         const line = formatStoredEventLine(stored);
         if (line) {
-            out.println(line);
+            out.println(numberTurnLine(line, turns));
         }
     }
 }
@@ -78,6 +125,9 @@ export async function followSessionEvents(name: string, asEvents: boolean): Prom
     const path = sessionEventsPath(name);
     let offset = existsSync(path) ? statSync(path).size : 0;
     let carry = "";
+    const turns: TurnCounter = {
+        n: asEvents && offset > 0 ? countStartedTurns(await Bun.file(path).slice(0, offset).text()) : 0,
+    };
     // A streaming decoder, not `.text()` per read: a size snapshot can cut
     // a multi-byte codepoint in half, and decoding each byte slice on its
     // own turned every such character into U+FFFD. The decoder holds the
@@ -104,7 +154,7 @@ export async function followSessionEvents(name: string, asEvents: boolean): Prom
                 const { complete, rest } = takeCompleteLines(carry + chunk);
                 carry = rest;
                 if (complete) {
-                    printFollowedChunk(complete, asEvents);
+                    printFollowedChunk(complete, asEvents, turns);
                 }
                 offset = size;
             }
@@ -117,7 +167,7 @@ export async function followSessionEvents(name: string, asEvents: boolean): Prom
             // first, in case the file ends mid-codepoint.
             const tail = carry + decoder.decode();
             if (tail) {
-                printFollowedChunk(tail, asEvents);
+                printFollowedChunk(tail, asEvents, turns);
             }
             return;
         }

From 78f9f5766cc281f9850496e45e5b4fb89a7a314e Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Wed, 14 Oct 2026 04:52:05 +0200
Subject: [PATCH 05/32] fix(ai, grok): a malformed Grok auth file is logged by
 category, never with the parser message that quotes its tokens

(cherry picked from commit 3490353dca4e38eae2813ae01a7f0a138f36ec7c)
---
 src/utils/ai/grok/auth.test.ts | 35 ++++++++++++++++++++++++++++++++--
 src/utils/ai/grok/auth.ts      | 10 ++++++++--
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/src/utils/ai/grok/auth.test.ts b/src/utils/ai/grok/auth.test.ts
index 65d6ef77e7..85854d7665 100644
--- a/src/utils/ai/grok/auth.test.ts
+++ b/src/utils/ai/grok/auth.test.ts
@@ -1,9 +1,17 @@
-import { afterEach, describe, expect, it } from "bun:test";
+import { afterEach, describe, expect, it, spyOn } from "bun:test";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { SafeJSON } from "@genesiscz/utils/json";
-import { decodeJwtClaims, getActiveAuthEntry, getTokenPrefix, isTokenExpired, readAuthFile } from "./auth";
+import { logger } from "@genesiscz/utils/logger";
+import {
+    decodeJwtClaims,
+    getActiveAuthEntry,
+    getTokenPrefix,
+    isTokenExpired,
+    readAuthFile,
+    readAuthFileAsync,
+} from "./auth";
 
 const TEST_PAYLOAD = {
     tier: 5,
@@ -49,6 +57,29 @@ describe("grok auth", () => {
         expect(entries.get("https://auth.x.ai::client-id")?.key).toBe("token-abc");
     });
 
+    it("a malformed auth file is logged without its token text, by both readers", async () => {
+        tempDir = mkdtempSync(join(tmpdir(), "grok-auth-"));
+        const authPath = join(tempDir, "auth.json");
+        writeFileSync(authPath, '{"https://auth.x.ai::client-id": {"key": "fixture-secret-token", broken}');
+        const warn = spyOn(logger, "warn").mockImplementation(() => {});
+
+        try {
+            expect(readAuthFile(authPath).size).toBe(0);
+            expect((await readAuthFileAsync(authPath)).size).toBe(0);
+            expect(warn).toHaveBeenCalledTimes(2);
+            // The day log serializes an Error's message, which JSON.stringify would drop: read it the same way.
+            const logged = warn.mock.calls
+                .flat()
+                .flatMap((arg) => (arg && typeof arg === "object" ? Object.values(arg) : [arg]))
+                .map((value) => (value instanceof Error ? value.message : String(value)))
+                .join(" ");
+            expect(logged).toContain(authPath);
+            expect(logged).not.toContain("fixture-secret-token");
+        } finally {
+            warn.mockRestore();
+        }
+    });
+
     it("selects first active auth entry", () => {
         const entries = new Map([
             [
diff --git a/src/utils/ai/grok/auth.ts b/src/utils/ai/grok/auth.ts
index 11ffe6575b..4f16a840a8 100644
--- a/src/utils/ai/grok/auth.ts
+++ b/src/utils/ai/grok/auth.ts
@@ -36,6 +36,12 @@ function parseAuthEntries(raw: unknown): Map<string, GrokAuthEntry> {
     return entries;
 }
 
+// A parser error quotes the malformed document, and this one holds access and refresh tokens: log a category only.
+function logAuthReadFailure(authPath: string, err: unknown): void {
+    const reason = err instanceof SyntaxError ? "invalid JSON" : "unreadable";
+    logger.warn({ authPath, reason }, "grok: failed to parse auth file");
+}
+
 export function readAuthFile(path?: string): Map<string, GrokAuthEntry> {
     const authPath = path ?? grokAuthPath();
 
@@ -46,7 +52,7 @@ export function readAuthFile(path?: string): Map<string, GrokAuthEntry> {
     try {
         return parseAuthEntries(SafeJSON.parse(readFileSync(authPath, "utf-8")));
     } catch (err) {
-        logger.warn({ err, authPath }, "grok: failed to parse auth file");
+        logAuthReadFailure(authPath, err);
         return new Map();
     }
 }
@@ -62,7 +68,7 @@ export async function readAuthFileAsync(path?: string): Promise<Map<string, Grok
         const text = await Bun.file(authPath).text();
         return parseAuthEntries(SafeJSON.parse(text));
     } catch (err) {
-        logger.warn({ err, authPath }, "grok: failed to parse auth file");
+        logAuthReadFailure(authPath, err);
         return new Map();
     }
 }

From 606767d01b750db8f55f600074eddfbd61c7aeba Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Wed, 14 Oct 2026 05:16:07 +0200
Subject: [PATCH 06/32] fix(Clicky): the library integration tests delete their
 per-test preferences file, which removePersistentDomain left behind (1,541 of
 them)

(cherry picked from commit ea1bd823d41f4cbd6665284acc27f29488e38449)
---
 .../Tests/GenesisKitTests/ClickyTests.swift   | 103 ++++++++++--------
 1 file changed, 57 insertions(+), 46 deletions(-)

diff --git a/src/macos/GenesisKit/Tests/GenesisKitTests/ClickyTests.swift b/src/macos/GenesisKit/Tests/GenesisKitTests/ClickyTests.swift
index 014f54ccf9..efa5e2f35e 100644
--- a/src/macos/GenesisKit/Tests/GenesisKitTests/ClickyTests.swift
+++ b/src/macos/GenesisKit/Tests/GenesisKitTests/ClickyTests.swift
@@ -426,7 +426,7 @@ final class ClickyTests: XCTestCase {
     func testUnreadablePreferencesDoNotEraseValidTypingHistory() throws {
         let suite = "dev.genesis.clicky.persistence.\(UUID().uuidString)"
         let defaults = try XCTUnwrap(UserDefaults(suiteName: suite))
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         var saved = ClickyStatistics()
         saved.record(keyCode: 0, release: false, at: date(12))
         defaults.set(Data("{invalid preferences".utf8), forKey: "clicky.preferences.v1")
@@ -450,7 +450,7 @@ final class ClickyTests: XCTestCase {
     func testUndecodablePreferencesAreKeptBeforeTheFirstSaveReplacesThem() throws {
         let suite = "dev.genesis.clicky.persistence.\(UUID().uuidString)"
         let defaults = try XCTUnwrap(UserDefaults(suiteName: suite))
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let stored = Data("{\"releaseSounds\": false, \"notifications\": tru".utf8)
         defaults.set(stored, forKey: "clicky.preferences.v1")
         let model = ClickyModel(defaults: defaults, previewOnly: true, observeSystemEvents: false)
@@ -468,7 +468,7 @@ final class ClickyTests: XCTestCase {
     func testUndecodableLibraryListIsKeptBeforeAnAddedFolderReplacesIt() throws {
         let suite = "dev.genesis.clicky.persistence.\(UUID().uuidString)"
         let defaults = try XCTUnwrap(UserDefaults(suiteName: suite))
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let stored = Data("[{\"id\": \"work\", \"displayName\": \"Work sou".utf8)
         defaults.set(stored, forKey: "clicky.libraries.v1")
         let library = ClickySoundLibrary(defaults: defaults, bundled: nil)
@@ -478,7 +478,7 @@ final class ClickyTests: XCTestCase {
         XCTAssertEqual(recovery.count, 1)
         XCTAssertEqual(defaults.data(forKey: try XCTUnwrap(recovery.first)), stored)
 
-        defaults.removePersistentDomain(forName: suite)
+        disposeIntegrationDefaults(defaults, suite: suite)
         let reopened = ClickySoundLibrary(defaults: defaults, bundled: nil)
         defer { reopened.stop() }
         XCTAssertTrue(defaults.dictionaryRepresentation().keys.allSatisfy { !$0.contains(".undecodable.") })
@@ -488,7 +488,7 @@ final class ClickyTests: XCTestCase {
     func testDecodablePreferencesLeaveNoRecoveryCopy() throws {
         let suite = "dev.genesis.clicky.persistence.\(UUID().uuidString)"
         let defaults = try XCTUnwrap(UserDefaults(suiteName: suite))
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         var saved = ClickyPreferences()
         saved.releaseSounds = false
         defaults.set(try JSONEncoder().encode(saved), forKey: "clicky.preferences.v1")
@@ -503,7 +503,7 @@ final class ClickyTests: XCTestCase {
     func testUnreadableHistoryIsNeverOverwrittenByActivationOrShutdown() throws {
         let suite = "dev.genesis.clicky.persistence.\(UUID().uuidString)"
         let defaults = try XCTUnwrap(UserDefaults(suiteName: suite))
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let original = Data("{\"presses\":12000,\"minutes\":\"unreadable\"}".utf8)
         defaults.set(original, forKey: "clicky.statistics.v1")
         let monitor = InputMonitorStub()
@@ -535,7 +535,7 @@ final class ClickyTests: XCTestCase {
     func testRepeatedResetsKeepOnlyTheNewestRecoveryCopies() throws {
         let suite = "dev.genesis.clicky.persistence.\(UUID().uuidString)"
         let defaults = try XCTUnwrap(UserDefaults(suiteName: suite))
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let prefix = "clicky.statistics.recovery."
         defaults.set(Data("from an older build".utf8), forKey: prefix + UUID().uuidString)
         for round in 1...5 {
@@ -554,7 +554,7 @@ final class ClickyTests: XCTestCase {
     func testHistoryRetryReopensRestoredDataWithoutResettingOrWritingIt() throws {
         let suite = "dev.genesis.clicky.persistence.\(UUID().uuidString)"
         let defaults = try XCTUnwrap(UserDefaults(suiteName: suite))
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let original = Data("unreadable".utf8)
         defaults.set(original, forKey: "clicky.statistics.v1")
         let model = ClickyModel(defaults: defaults, previewOnly: true, observeSystemEvents: false)
@@ -583,7 +583,7 @@ final class ClickyTests: XCTestCase {
         let (model, defaults, suite) = monitorFixture(monitor)
         defer {
             model.shutdown()
-            defaults.removePersistentDomain(forName: suite)
+            disposeIntegrationDefaults(defaults, suite: suite)
         }
         XCTAssertFalse(model.enabled)
         model.activate()
@@ -607,7 +607,7 @@ final class ClickyTests: XCTestCase {
         let (model, defaults, suite) = monitorFixture(monitor)
         defer {
             model.shutdown()
-            defaults.removePersistentDomain(forName: suite)
+            disposeIntegrationDefaults(defaults, suite: suite)
         }
         model.activate()
         XCTAssertFalse(model.enabled)
@@ -632,7 +632,7 @@ final class ClickyTests: XCTestCase {
         let (model, defaults, suite) = monitorFixture(monitor)
         defer {
             model.shutdown()
-            defaults.removePersistentDomain(forName: suite)
+            disposeIntegrationDefaults(defaults, suite: suite)
         }
         // "Allow Input Monitoring…" in the privacy note, with Clicky off.
         model.openInputSettings()
@@ -661,7 +661,7 @@ final class ClickyTests: XCTestCase {
             XCTAssertEqual(monitor.permissionDialogs, result == .permissionRequired ? 1 : 0)
             XCTAssertEqual(monitor.starts, 1)
             model.shutdown()
-            defaults.removePersistentDomain(forName: suite)
+            disposeIntegrationDefaults(defaults, suite: suite)
         }
     }
 
@@ -672,7 +672,7 @@ final class ClickyTests: XCTestCase {
         let (model, defaults, suite) = monitorFixture(monitor, snapshot: true)
         defer {
             model.shutdown()
-            defaults.removePersistentDomain(forName: suite)
+            disposeIntegrationDefaults(defaults, suite: suite)
         }
         model.activate()
         XCTAssertFalse(model.enabled)
@@ -688,7 +688,7 @@ final class ClickyTests: XCTestCase {
         let (model, defaults, suite) = monitorFixture(monitor)
         defer {
             model.shutdown()
-            defaults.removePersistentDomain(forName: suite)
+            disposeIntegrationDefaults(defaults, suite: suite)
         }
         model.activate()
         let event = try XCTUnwrap(CGEvent(source: nil))
@@ -706,7 +706,7 @@ final class ClickyTests: XCTestCase {
         let (model, defaults, suite) = monitorFixture(monitor)
         defer {
             model.shutdown()
-            defaults.removePersistentDomain(forName: suite)
+            disposeIntegrationDefaults(defaults, suite: suite)
         }
         model.activate()
         let event = try XCTUnwrap(CGEvent(source: nil))
@@ -730,7 +730,7 @@ final class ClickyTests: XCTestCase {
     func testSettingsRegistrationPreservesPendingRequestsAndPersistsSelection() {
         let suite = "dev.genesis.settings.test.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let appearance = NativeSettingsAppearance(
             defaults: defaults, notificationNamespace: suite, observeExternalChanges: false)
         let initial = settingsSection("general", pages: ["general"], order: 0)
@@ -751,7 +751,7 @@ final class ClickyTests: XCTestCase {
     func testSettingsRejectDuplicatePageIDsWithoutChangingTheCatalog() {
         let suite = "dev.genesis.settings.test.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let appearance = NativeSettingsAppearance(
             defaults: defaults, notificationNamespace: suite, observeExternalChanges: false)
         let store = NativeSettingsStore(
@@ -775,7 +775,7 @@ final class ClickyTests: XCTestCase {
     func testSettingsOrderPlacesLateRegisteredFeaturesBeforeAbout() {
         let suite = "dev.genesis.settings.test.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let appearance = NativeSettingsAppearance(
             defaults: defaults, notificationNamespace: suite, observeExternalChanges: false)
         let store = NativeSettingsStore(
@@ -793,7 +793,7 @@ final class ClickyTests: XCTestCase {
     func testSharedAppearanceIsDurableIndependentAndMigrationDoesNotOverwrite() {
         let suite = "dev.genesis.settings.test.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let first = NativeSettingsAppearance(
             defaults: defaults, notificationNamespace: suite, observeExternalChanges: false)
         first.migrateIfNeeded(reduceMotion: true, reduceTransparency: false)
@@ -819,7 +819,7 @@ final class ClickyTests: XCTestCase {
     func testThemeChoiceSurvivesIndependentTransparencyOverrides() {
         let suite = "dev.genesis.settings.test.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let appearance = NativeSettingsAppearance(
             defaults: defaults, notificationNamespace: suite, observeExternalChanges: false)
         appearance.theme = .gradient
@@ -843,7 +843,7 @@ final class ClickyTests: XCTestCase {
     func testIndependentAppearanceWritesDoNotOverwriteAnotherInstancesChanges() {
         let suite = "dev.genesis.settings.test.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let first = NativeSettingsAppearance(
             defaults: defaults, notificationNamespace: suite, observeExternalChanges: false)
         let stale = NativeSettingsAppearance(
@@ -863,7 +863,7 @@ final class ClickyTests: XCTestCase {
     func testSharedAppearanceReceivesDistributedChanges() async {
         let suite = "dev.genesis.settings.test.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let writer = NativeSettingsAppearance(defaults: defaults, notificationNamespace: suite)
         let reader = NativeSettingsAppearance(defaults: UserDefaults(suiteName: suite)!, notificationNamespace: suite)
         let changed = expectation(description: "Distributed appearance notification")
@@ -880,7 +880,7 @@ final class ClickyTests: XCTestCase {
     func testClickyLegacyAppearanceAndSharedStoreRemainConnected() async throws {
         let suite = "dev.genesis.settings.test.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         var legacy = ClickyPreferences()
         legacy.reduceMotion = true
         defaults.set(try JSONEncoder().encode(legacy), forKey: "clicky.preferences.v1")
@@ -905,7 +905,7 @@ final class ClickyTests: XCTestCase {
     func testSettingsTaxonomyRetainsOneClickyModelWithoutEnablingInput() {
         let suite = "dev.genesis.settings.test.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let model = ClickyModel(defaults: defaults, previewOnly: true)
         let sections = ClickySettingsPages.sections(model: model)
         XCTAssertEqual(sections.map(\.id), ["general", "clicky", "about"])
@@ -924,7 +924,7 @@ final class ClickyTests: XCTestCase {
     func testNotificationPermissionRoutesDeniedToSettingsAndRetainsActivationPreference() async {
         let suite = "dev.genesis.clicky.notifications.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         var authorization: UNAuthorizationStatus = .denied
         var requests = 0
         var settingsOpens = 0
@@ -961,7 +961,7 @@ final class ClickyTests: XCTestCase {
     func testStaleNotificationReadCannotOverwriteCompletedPermissionRequest() async {
         let suite = "dev.genesis.clicky.notifications.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let started = AsyncStream<Void>.makeStream()
         var pending: CheckedContinuation<UNAuthorizationStatus, Never>?
         var first = true
@@ -992,7 +992,7 @@ final class ClickyTests: XCTestCase {
     func testNotificationSettingsFailureIsActionable() async {
         let suite = "dev.genesis.clicky.notifications.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let model = ClickyModel(defaults: defaults, observeSystemEvents: false,
             notificationClient: NativeNotificationClient(status: { .denied }, request: {
                 XCTFail("Denied authorization must not be requested again")
@@ -1038,7 +1038,7 @@ final class ClickyTests: XCTestCase {
     func testPreviewCannotActivateInputAndStartsOff() {
         let suite = "dev.genesis.clicky.test.\(UUID().uuidString)"
         let defaults = UserDefaults(suiteName: suite)!
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let model = ClickyModel(defaults: defaults, previewOnly: true)
         XCTAssertFalse(model.enabled)
         model.activate()
@@ -1544,6 +1544,7 @@ extension ClickyPackTests {
         return (UserDefaults(suiteName: suite)!, suite)
     }
 
+
     @MainActor
     private func seedLibrary(_ defaults: UserDefaults, root: URL, count: Int = 1) throws -> [ClickyLibraryRecord] {
         let bookmark = try root.bookmarkData(options: [.withSecurityScope], includingResourceValuesForKeys: nil, relativeTo: nil)
@@ -1560,7 +1561,7 @@ extension ClickyPackTests {
         let fixture = try Fixture()
         defer { fixture.dispose() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let library = ClickySoundLibrary(defaults: defaults, bundled: fixture.root)
         defer { library.stop() }
         XCTAssertEqual(library.records.map(\.id), [ClickySoundLibrary.bundledID])
@@ -1597,7 +1598,7 @@ extension ClickyPackTests {
         let loader = GatedIntegrationLoader(packs: [a, b], prepareStarted: { starts[$0 - 1].fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let record = try XCTUnwrap(seedLibrary(defaults, root: fixture.root).first)
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         defer { library.stop() }
@@ -1635,7 +1636,7 @@ extension ClickyPackTests {
             let loader = GatedIntegrationLoader(packs: [base], prepareStarted: { _ in started.fulfill() })
             addTeardownBlock { await loader.cancelPending() }
             let (defaults, suite) = integrationDefaults()
-            defer { defaults.removePersistentDomain(forName: suite) }
+            defer { disposeIntegrationDefaults(defaults, suite: suite) }
             let record = try XCTUnwrap(seedLibrary(defaults, root: fixture.root).first)
             let library = ClickySoundLibrary(defaults: defaults, loader: loader)
             defer { library.stop() }
@@ -1664,7 +1665,7 @@ extension ClickyPackTests {
         let loader = GatedIntegrationLoader(packs: [a, b], prepareStarted: { starts[$0 - 1].fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let record = try XCTUnwrap(seedLibrary(defaults, root: fixture.root).first)
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         defer { library.stop() }
@@ -1718,7 +1719,7 @@ extension ClickyPackTests {
         let loader = GatedIntegrationLoader(packs: [a, b], prepareStarted: { starts[$0 - 1].fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let record = try XCTUnwrap(seedLibrary(defaults, root: fixture.root).first)
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         defer { library.stop() }
@@ -1751,7 +1752,7 @@ extension ClickyPackTests {
         let loader = GatedIntegrationLoader(packs: [pack], catalogueStarted: { _ in started.fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let record = try XCTUnwrap(seedLibrary(defaults, root: fixture.root).first)
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         defer { library.stop() }
@@ -1779,7 +1780,7 @@ extension ClickyPackTests {
         let loader = GatedIntegrationLoader(packs: [older, newer], catalogueStarted: { starts[$0 - 1].fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         _ = try seedLibrary(defaults, root: fixture.root)
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         defer { library.stop() }
@@ -1807,7 +1808,7 @@ extension ClickyPackTests {
         let loader = GatedIntegrationLoader(packs: [pack], catalogueStarted: { starts[$0 - 1].fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         _ = try seedLibrary(defaults, root: firstFixture.root)
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         defer { library.stop() }
@@ -1834,7 +1835,7 @@ extension ClickyPackTests {
         let loader = GatedIntegrationLoader(packs: [pack], catalogueStarted: { _ in started.fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         await loader.holdCatalogues()
         let importing = Task { @MainActor in await library.register(fixture.root) }
@@ -1856,7 +1857,7 @@ extension ClickyPackTests {
         let loader = GatedIntegrationLoader(packs: [pack], catalogueStarted: { starts[$0 - 1].fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         defer { library.stop() }
         await loader.holdCatalogues()
@@ -1885,7 +1886,7 @@ extension ClickyPackTests {
         let loader = GatedIntegrationLoader(packs: [pack], catalogueStarted: { starts[$0 - 1].fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         _ = try seedLibrary(defaults, root: firstFixture.root, count: 31)
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         defer { library.stop() }
@@ -1957,7 +1958,7 @@ extension ClickyPackTests {
         let loader = GatedIntegrationLoader(packs: [pack], prepareStarted: { _ in started.fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let record = try XCTUnwrap(seedLibrary(defaults, root: fixture.root).first)
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         defer { library.stop() }
@@ -2018,7 +2019,7 @@ extension ClickyTests {
         let monitor = InputMonitorStub()
         monitor.granted = true
         let (model, defaults, suite) = monitorFixture(monitor)
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         model.activate()
         XCTAssertTrue(model.enabled)
         model.shutdown()
@@ -2070,7 +2071,7 @@ extension ClickyTests {
         let (model, defaults, suite) = monitorFixture(monitor, snapshot: true)
         model.shutdown()
         defaults.set(data, forKey: "clicky.preferences.v1")
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let restored = ClickyModel(defaults: defaults, previewOnly: true, inputMonitor: monitor, observeSystemEvents: false)
         defer { restored.shutdown() }
         XCTAssertEqual(restored.preferences, original)
@@ -2098,7 +2099,7 @@ extension ClickyTests {
         let monitor = InputMonitorStub()
         let suite = "dev.genesis.clicky.missing-library.\(UUID().uuidString)"
         let defaults = try XCTUnwrap(UserDefaults(suiteName: suite))
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         var saved = ClickyPreferences()
         saved.selectedSwitch = .honey
         saved.selectedPack = ClickyPackReference(libraryID: "missing-library", packID: "fixture")
@@ -2134,7 +2135,7 @@ extension ClickyPackTests {
         let loader = GatedIntegrationLoader(packs: [pack], prepareStarted: { _ in started.fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let record = try XCTUnwrap(seedLibrary(defaults, root: fixture.root).first)
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         defer { library.stop() }
@@ -2163,7 +2164,7 @@ extension ClickyPackTests {
                                             prepareStarted: { _ in forbidden.fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         let record = try XCTUnwrap(seedLibrary(defaults, root: fixture.root).first)
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         defer { library.stop() }
@@ -2191,7 +2192,7 @@ extension ClickyPackTests {
                                             prepareStarted: { _ in forbidden.fulfill() })
         addTeardownBlock { await loader.cancelPending() }
         let (defaults, suite) = integrationDefaults()
-        defer { defaults.removePersistentDomain(forName: suite) }
+        defer { disposeIntegrationDefaults(defaults, suite: suite) }
         _ = try seedLibrary(defaults, root: fixture.root)
         let library = ClickySoundLibrary(defaults: defaults, loader: loader)
         defer { library.stop() }
@@ -2385,3 +2386,13 @@ extension ClickyTests {
         XCTAssertEqual(stats.presses, 12002)
     }
 }
+
+/// `removePersistentDomain` empties a suite but leaves its plist in ~/Library/Preferences, so every run of these
+/// tests used to leave one file per test behind (1,541 by 2026-10-14). Remove the file too.
+@MainActor
+func disposeIntegrationDefaults(_ defaults: UserDefaults, suite: String) {
+    defaults.removePersistentDomain(forName: suite)
+    let plist = FileManager.default.homeDirectoryForCurrentUser
+        .appendingPathComponent("Library/Preferences/\(suite).plist")
+    try? FileManager.default.removeItem(at: plist)
+}

From 7fff4e5272376004051b25dbf5ca917d861b4ca7 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Wed, 14 Oct 2026 05:32:14 +0200
Subject: [PATCH 07/32] fix(tools): a handoff worker commits without asking
 again when its brief or the orchestrator explicitly authorizes the commit

(cherry picked from commit dff6959b42107b58d38ef2eb5117ac7cd305f5b1)
---
 src/utils/worker/contract.test.ts | 3 +++
 src/utils/worker/contract.ts      | 4 +++-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/utils/worker/contract.test.ts b/src/utils/worker/contract.test.ts
index 724ce34ece..d96ec14394 100644
--- a/src/utils/worker/contract.test.ts
+++ b/src/utils/worker/contract.test.ts
@@ -11,6 +11,9 @@ describe("buildWorkerContract", () => {
             expect(text).toContain("Honor any `Stop and report` block in your task brief literally");
             expect(text).toContain("fails twice in a row, STOP");
             expect(text).toContain("CHARACTER FOR CHARACTER");
+            // A brief or a steer that grants "commit once" is honoured; without one the worker still asks.
+            expect(text).toContain("running any git commit/push or destructive command,");
+            expect(text).toContain("explicitly authorizes that exact action");
             for (const key of WORKER_REPORT_KEYS) {
                 expect(text).toMatch(new RegExp(`^${key}: `, "m"));
             }
diff --git a/src/utils/worker/contract.ts b/src/utils/worker/contract.ts
index 3b43b40a7e..444ddadafd 100644
--- a/src/utils/worker/contract.ts
+++ b/src/utils/worker/contract.ts
@@ -90,7 +90,9 @@ function checkpointLines(): string[] {
     return [
         "You are the receiving end of a handoff. Honor any `Stop and report` block in your task brief literally —",
         "stopping to ask is expected behavior, not a failure. Ask before creating files outside the declared scope,",
-        "adding dependencies, changing public interfaces, or running any git commit/push or destructive command.",
+        "adding dependencies, changing public interfaces, or running any git commit/push or destructive command,",
+        "unless your task brief or a later message from the orchestrator explicitly authorizes that exact action",
+        '(for example "commit once"): then do exactly what was authorized, no more, and do not ask again.',
         "Run the verification command in your brief yourself and paste its real output; never report a state you did not observe.",
         "If a verification command fails twice in a row, STOP and report both outputs instead of patching further.",
         "Copy every file path from the brief CHARACTER FOR CHARACTER; do not retype or normalize paths.",

From 29cbc2122d07ffd25bb31dcae88725f3d0e0d603 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Wed, 14 Oct 2026 06:36:46 +0200
Subject: [PATCH 08/32] fix(agents, skills, agents-talk): agents message takes
 the body as positional words too, and refuses a body given twice

(cherry picked from commit 00ade134887e4e81bdb93e68ea23ca488c390803)
---
 src/agents/commands/message.ts   | 23 ++++++++++++++++++++---
 src/agents/tests/request.test.ts | 10 ++++++++++
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/src/agents/commands/message.ts b/src/agents/commands/message.ts
index 3dc8b24e36..d05760d9aa 100644
--- a/src/agents/commands/message.ts
+++ b/src/agents/commands/message.ts
@@ -15,7 +15,7 @@ import type { AgentRecord, MessageEvent } from "../lib/types";
 
 const log = logger.child({ component: "agents:message" });
 
-interface MessageOpts {
+export interface MessageOpts {
     from?: string;
     to?: string;
     body?: string;
@@ -26,6 +26,22 @@ interface MessageOpts {
     session?: string;
 }
 
+/**
+ * The body may also come as positional words (`tools agents message --to x "text"`), the way agents and request
+ * files keep writing it; before, those words were rejected and only the help printed. Exactly one source counts.
+ */
+export function withPositionalBody(words: string[], opts: MessageOpts): MessageOpts {
+    if (words.length === 0) {
+        return opts;
+    }
+
+    if (opts.body !== undefined || opts.bodyFile !== undefined) {
+        throw new FriendlyError("the message text was given twice", "Pass it once: as words, --body or --body-file.");
+    }
+
+    return { ...opts, body: words.join(" ") };
+}
+
 function resolveBody(opts: MessageOpts): string | undefined {
     if (opts.bodyFile) {
         if (opts.body) {
@@ -180,6 +196,7 @@ export function registerMessageCommand(program: Command): void {
             "Send a bus message to agents logged into this bus session (direct, broadcast, reply, or pure ack). " +
                 "To reach a running Claude, Codex or Grok session that is not on the bus, use `tools <agent> message <session>`"
         )
+        .argument("[body...]", "Message body, the same as --body")
         .option("--from <token>", "Sender agent — name or id")
         .option("--to <csv>", "Recipient agents — comma-separated names or ids; empty = broadcast")
         .option("--body <text>", "Message body (omit + --reply for pure ack)")
@@ -191,7 +208,7 @@ export function registerMessageCommand(program: Command): void {
         .option("--meta <json>", "Optional JSON object")
         .option("--private", "Mark as private (v1: stored, not enforced)")
         .option("--session <id>", "Override session resolution")
-        .action(async (opts: MessageOpts) => {
-            await runMessage(opts);
+        .action(async (words: string[], opts: MessageOpts) => {
+            await runWithFriendlyErrors(async () => runMessageImpl(withPositionalBody(words, opts)));
         });
 }
diff --git a/src/agents/tests/request.test.ts b/src/agents/tests/request.test.ts
index 2a7529e650..f1b2956c0b 100644
--- a/src/agents/tests/request.test.ts
+++ b/src/agents/tests/request.test.ts
@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { env } from "@genesiscz/utils/env";
 import { watchFileFeed } from "@genesiscz/utils/fs/file-feed-watcher";
+import { withPositionalBody } from "../commands/message";
 import { appendFeed, appendMessage, FeedLogCursor, readFeed } from "../lib/feed";
 import { ensureSessionDir, sessionPaths } from "../lib/paths";
 import { sendRequest } from "../lib/request";
@@ -154,3 +155,12 @@ describe("agents request", () => {
         });
     });
 });
+
+describe("agents message body", () => {
+    test("positional words are the body, and a second source is refused", () => {
+        expect(withPositionalBody(["hello", "there"], { to: "worker" }).body).toBe("hello there");
+        expect(withPositionalBody([], { body: "kept" }).body).toBe("kept");
+        expect(() => withPositionalBody(["twice"], { body: "already" })).toThrow("given twice");
+        expect(() => withPositionalBody(["twice"], { bodyFile: "/tmp/x" })).toThrow("given twice");
+    });
+});

From 66b4badbd87be8fd52c84d054b72a4ad5b1871e4 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Wed, 14 Oct 2026 08:04:11 +0200
Subject: [PATCH 09/32] fix(tools): a worker takes a commit grant in its brief
 as given in advance, instead of asking once first

(cherry picked from commit f8b260579108a4d4c548ca8b88085a3776cc9c69)
---
 src/utils/worker/contract.test.ts | 4 ++++
 src/utils/worker/contract.ts      | 3 ++-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/utils/worker/contract.test.ts b/src/utils/worker/contract.test.ts
index d96ec14394..a444cb10a0 100644
--- a/src/utils/worker/contract.test.ts
+++ b/src/utils/worker/contract.test.ts
@@ -14,6 +14,10 @@ describe("buildWorkerContract", () => {
             // A brief or a steer that grants "commit once" is honoured; without one the worker still asks.
             expect(text).toContain("running any git commit/push or destructive command,");
             expect(text).toContain("explicitly authorizes that exact action");
+            // A grant in the brief is not a cue to ask once first (2026-10-14: a worker with "Commit exactly ONCE"
+            // in its brief still stopped for confirmation, reading "do not ask again" as "ask once").
+            expect(text).toContain("given in advance: do the authorized action without stopping");
+            expect(text).not.toContain("do not ask again");
             for (const key of WORKER_REPORT_KEYS) {
                 expect(text).toMatch(new RegExp(`^${key}: `, "m"));
             }
diff --git a/src/utils/worker/contract.ts b/src/utils/worker/contract.ts
index 444ddadafd..1adcbe82e5 100644
--- a/src/utils/worker/contract.ts
+++ b/src/utils/worker/contract.ts
@@ -92,7 +92,8 @@ function checkpointLines(): string[] {
         "stopping to ask is expected behavior, not a failure. Ask before creating files outside the declared scope,",
         "adding dependencies, changing public interfaces, or running any git commit/push or destructive command,",
         "unless your task brief or a later message from the orchestrator explicitly authorizes that exact action",
-        '(for example "commit once"): then do exactly what was authorized, no more, and do not ask again.',
+        '(for example "commit once"). That authorization is given in advance: do the authorized action without stopping',
+        "to ask for it first, exactly as authorized and no more.",
         "Run the verification command in your brief yourself and paste its real output; never report a state you did not observe.",
         "If a verification command fails twice in a row, STOP and report both outputs instead of patching further.",
         "Copy every file path from the brief CHARACTER FOR CHARACTER; do not retype or normalize paths.",

From 4476e7f8ada69a5f79661e81aa8be81053bd49b3 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Wed, 14 Oct 2026 08:55:16 +0200
Subject: [PATCH 10/32] fix(codex): a worker's app-server error shows its
 nested message and a dropped stream's status, not unknown codex error

(cherry picked from commit f46deb17bf8a75b76b00b95376b4c366b062eadd)
---
 src/utils/codex/worker-stream.test.ts | 25 +++++++++++++++++++++++++
 src/utils/codex/worker-stream.ts      | 15 ++++++++++++++-
 2 files changed, 39 insertions(+), 1 deletion(-)
 create mode 100644 src/utils/codex/worker-stream.test.ts

diff --git a/src/utils/codex/worker-stream.test.ts b/src/utils/codex/worker-stream.test.ts
new file mode 100644
index 0000000000..98fdce6776
--- /dev/null
+++ b/src/utils/codex/worker-stream.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { toWorkerEvent } from "./worker-stream";
+
+describe("codex worker stream", () => {
+    test("an app-server error shows its nested message and the dropped stream's status", () => {
+        const event = toWorkerEvent({
+            source: "app-server",
+            method: "error",
+            params: {
+                threadId: "thread-1",
+                error: {
+                    message: "Reconnecting... 3/5",
+                    codexErrorInfo: { responseStreamDisconnected: { httpStatusCode: 503 } },
+                },
+            },
+        });
+        expect(event).toMatchObject({ kind: "error", message: "Reconnecting... 3/5 (stream dropped, HTTP 503)" });
+        expect(toWorkerEvent({ source: "app-server", method: "error", params: { message: "flat" } })).toMatchObject({
+            message: "flat",
+        });
+        expect(toWorkerEvent({ source: "app-server", method: "error", params: {} })).toMatchObject({
+            message: "unknown codex error",
+        });
+    });
+});
diff --git a/src/utils/codex/worker-stream.ts b/src/utils/codex/worker-stream.ts
index 98f0e1f01d..feb5481f7d 100644
--- a/src/utils/codex/worker-stream.ts
+++ b/src/utils/codex/worker-stream.ts
@@ -90,6 +90,19 @@ function toolCallOf(item: CodexItem, sessionId: string, ts?: string): WorkerEven
  * echoes); unknown methods are also null but logged at debug so a protocol
  * addition never disappears silently.
  */
+/**
+ * The app-server nests its text as `params.error.message` (a 503 stream drop arrives as "Reconnecting... 3/5"), so
+ * reading `params.message` alone printed "unknown codex error" for every one, retries included (2026-10-14).
+ */
+function errorMessageOf(params: Record<string, unknown> | undefined): string {
+    const nested = params?.error as
+        | { message?: unknown; codexErrorInfo?: { responseStreamDisconnected?: { httpStatusCode?: unknown } } }
+        | undefined;
+    const message = str(params?.message) ?? str(nested?.message) ?? "unknown codex error";
+    const status = nested?.codexErrorInfo?.responseStreamDisconnected?.httpStatusCode;
+    return typeof status === "number" ? `${message} (stream dropped, HTTP ${status})` : message;
+}
+
 export function toWorkerEvent(event: StoredCodexEvent): WorkerEvent | null {
     const { method, ts } = event;
     const params = paramsOf(event);
@@ -179,7 +192,7 @@ export function toWorkerEvent(event: StoredCodexEvent): WorkerEvent | null {
             }
         }
         case "error":
-            return { kind: "error", sessionId, message: str(params?.message) ?? "unknown codex error", ts };
+            return { kind: "error", sessionId, message: errorMessageOf(params), ts };
         case "thread/status/changed": {
             const status = params?.status as { type?: string } | undefined;
             return status?.type === "closed" ? { kind: "session.closed", sessionId, ts } : null;

From ce829f8b4cd3380e7b0c1cb4bdeb89e9106a2d4c Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Wed, 14 Oct 2026 16:49:40 +0200
Subject: [PATCH 11/32] perf(GenesisKit, diff): the file tree's git marks are
 built off the main thread and walk folders by UTF-8 index, so a vault status
 refresh no longer holds the viewer about 250 ms

(cherry picked from commit 9c81fd0329c3e10a5518bdd8bf0e4c0b13d44af6)
---
 .../GenesisKit/Diff/Model/GitState.swift      | 33 +++++++++++++------
 .../GenesisKit/Diff/Source/GitRepos.swift     | 26 +++++++++++----
 .../GenesisKitTests/Diff/GitReposTests.swift  | 23 +++++++++++++
 3 files changed, 65 insertions(+), 17 deletions(-)

diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Diff/Model/GitState.swift b/src/macos/GenesisKit/Sources/GenesisKit/Diff/Model/GitState.swift
index c815568f70..b83e79d324 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Diff/Model/GitState.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Diff/Model/GitState.swift
@@ -177,31 +177,44 @@ public struct GitRepoStatus: Equatable, Sendable {
         let given = treeRoot.standardizedFileURL.path
         let givenReal = GitWorkingTreeSource.realPath(given)
         let rootReal = GitWorkingTreeSource.realPath(root.standardizedFileURL.path)
+        let inside = givenReal + "/"
+        // Lengths once, and the folder walks cut at the last "/" in UTF-8: `String.count` walks every character, and
+        // the walks asked it at every level of every entry (117 ms per call for a vault folder with 1,825 entries,
+        // debug build, 2026-10-14).
+        let realLength = givenReal.count
+        let givenBytes = given.utf8.count
         var files: [String: GitChangeKind] = [:]
         var folders = Set<String>()
         var counts: [String: GitLineCount] = [:]
         for entry in entries {
             guard let kind = entry.shown else { continue }
             let real = rootReal + "/" + entry.path
-            guard real.hasPrefix(givenReal + "/") else { continue }
-            let spelled = given + real.dropFirst(givenReal.count)
+            guard real.hasPrefix(inside) else { continue }
+            let spelled = given + real.dropFirst(realLength)
             files[spelled] = kind
-            var folder = (spelled as NSString).deletingLastPathComponent
-            while folder.count > given.count, folders.insert(folder).inserted {
-                folder = (folder as NSString).deletingLastPathComponent
+            var folder = Self.parent(of: spelled[...])
+            while let current = folder, current.utf8.count > givenBytes, folders.insert(String(current)).inserted {
+                folder = Self.parent(of: current)
             }
             guard let lines = numstat[entry.path] else { continue }
             counts[spelled] = lines
-            var parent = (spelled as NSString).deletingLastPathComponent
-            while parent.count > given.count {
-                let sum = counts[parent] ?? GitLineCount(additions: 0, deletions: 0)
-                counts[parent] = GitLineCount(additions: sum.additions + lines.additions, deletions: sum.deletions + lines.deletions)
-                parent = (parent as NSString).deletingLastPathComponent
+            var parent = Self.parent(of: spelled[...])
+            while let current = parent, current.utf8.count > givenBytes {
+                let key = String(current)
+                let sum = counts[key] ?? GitLineCount(additions: 0, deletions: 0)
+                counts[key] = GitLineCount(additions: sum.additions + lines.additions, deletions: sum.deletions + lines.deletions)
+                parent = Self.parent(of: current)
             }
         }
         return GitTreeDecorations(files: files, folders: folders, counts: counts)
     }
 
+    /// Everything before the last "/" (an absolute path's folder), nil when there is none.
+    private static func parent(of path: Substring) -> Substring? {
+        guard let slash = path.utf8.lastIndex(of: UInt8(ascii: "/")) else { return nil }
+        return path[..<slash]
+    }
+
     /// The change to show for each absolute path, and a mark for each folder that holds one: what a file tree
     /// decorates.
     public var decorations: GitTreeDecorations {
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Diff/Source/GitRepos.swift b/src/macos/GenesisKit/Sources/GenesisKit/Diff/Source/GitRepos.swift
index 65c366932c..00b775ef6b 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Diff/Source/GitRepos.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Diff/Source/GitRepos.swift
@@ -262,24 +262,36 @@ public final class GitTreeDecorationsModel: ObservableObject {
     private var counts: [String: GitLineCount] = [:]
     private var ticket = 0
 
-    /// The marks at once (with the last counts), then the line counts from one `git diff --numstat` off the main thread.
+    /// The marks with the last counts, then the line counts from one `git diff --numstat` and the marks again: all built
+    /// and compared off the main thread. Built on it, one refresh of a vault's status (1,825 entries) held the main
+    /// thread about 250 ms in a debug build, at every git change, every start and every move of the tree's root
+    /// (2026-10-14, 24% of the main thread in MarkdownTreeLagBenchTests).
     private func update() {
         guard let root, let repo = GitRepos.shared.model(for: root) else { return }
         hasRepository = true
         guard let status = repo.status else { return }
-        let marked = status.decorations(under: root, numstat: counts)
-        if marked != decorations { decorations = marked }
         ticket += 1
         let ticket = ticket
+        let counts = counts
+        let shown = decorations
         let provider = GenesisKitGT.provider
         let repoRoot = repo.root
         DispatchQueue.global(qos: .utility).async {
-            let counts = GitQueries(provider: provider).numstat(in: repoRoot)
+            let marked = status.decorations(under: root, numstat: counts)
+            let markedChanged = marked != shown
+            if markedChanged {
+                DispatchQueue.main.async { [weak self] in
+                    guard let self, self.ticket == ticket, self.root == root else { return }
+                    self.decorations = marked
+                }
+            }
+            let fresh = GitQueries(provider: provider).numstat(in: repoRoot)
+            let recounted = status.decorations(under: root, numstat: fresh)
+            let recountChanged = recounted != (markedChanged ? marked : shown)
             DispatchQueue.main.async { [weak self] in
                 guard let self, self.ticket == ticket, self.root == root else { return }
-                self.counts = counts
-                let fresh = status.decorations(under: root, numstat: counts)
-                if fresh != self.decorations { self.decorations = fresh }
+                self.counts = fresh
+                if recountChanged { self.decorations = recounted }
             }
         }
     }
diff --git a/src/macos/GenesisKit/Tests/GenesisKitTests/Diff/GitReposTests.swift b/src/macos/GenesisKit/Tests/GenesisKitTests/Diff/GitReposTests.swift
index 136f22e823..d7f429adf0 100644
--- a/src/macos/GenesisKit/Tests/GenesisKitTests/Diff/GitReposTests.swift
+++ b/src/macos/GenesisKit/Tests/GenesisKitTests/Diff/GitReposTests.swift
@@ -171,6 +171,29 @@ final class GitReposTests: XCTestCase {
         XCTAssertNil(marks.count(for: "/tmp/gk-counts-repo/notes/new.md"), "an untracked file has no numstat")
     }
 
+    /// The folder walks cut paths at "/" in UTF-8 (2026-10-14); accented names keep their marks and sums, and the
+    /// tree's own root is never marked.
+    func testTheTreeMarksWalkFoldersWithAccentedNames() {
+        let root = URL(fileURLWithPath: "/tmp/gk-accents-repo")
+        let status = GitRepoStatus(root: root, branch: "main", upstream: nil, ahead: 0, behind: 0, entries: [
+            GitStatusEntry(path: "ČEZ/úkoly/žádost/a.md", unstaged: .modified),
+            GitStatusEntry(path: "ČEZ/úkoly/b.md", unstaged: .modified),
+            GitStatusEntry(path: "ČEZ/c.md", unstaged: .untracked),
+            GitStatusEntry(path: "jinde/d.md", unstaged: .modified),
+        ])
+        let numstat = [
+            "ČEZ/úkoly/žádost/a.md": GitLineCount(additions: 2, deletions: 1),
+            "ČEZ/úkoly/b.md": GitLineCount(additions: 1, deletions: 3),
+        ]
+        let marks = status.decorations(under: root.appendingPathComponent("ČEZ"), numstat: numstat)
+        let tree = "/tmp/gk-accents-repo/ČEZ"
+        XCTAssertEqual(Set(marks.files.keys), ["\(tree)/úkoly/žádost/a.md", "\(tree)/úkoly/b.md", "\(tree)/c.md"])
+        XCTAssertEqual(marks.folders, ["\(tree)/úkoly/žádost", "\(tree)/úkoly"], "the tree's root is not marked")
+        XCTAssertEqual(marks.count(for: "\(tree)/úkoly/žádost"), GitLineCount(additions: 2, deletions: 1))
+        XCTAssertEqual(marks.count(for: "\(tree)/úkoly"), GitLineCount(additions: 3, deletions: 4))
+        XCTAssertNil(marks.count(for: tree), "the tree's root sums nothing")
+    }
+
     func testAFolderOutsideARepositoryHasNoModel() async throws {
         let folder = FileManager.default.temporaryDirectory.appendingPathComponent("norepo-\(UUID().uuidString)")
         try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)

From 34e8d9ae4ff88fe1a83b6ed38a97ec46caaa79c8 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Wed, 14 Oct 2026 22:55:51 +0200
Subject: [PATCH 12/32] fix(claude): tools claude info <name> reads account
 names only, because loading every secret for the statusline read the vault
 key from the keychain and macOS asked the user whether gt-claude may use it

(cherry picked from commit 14b1182d12537ac39c35d3987f1e55f0b480a759)
---
 src/claude/commands/info.test.ts | 46 ++++++++++++++++++++++++++++++++
 src/claude/commands/info.ts      | 45 +++++++++++++++++++++++++------
 2 files changed, 83 insertions(+), 8 deletions(-)
 create mode 100644 src/claude/commands/info.test.ts

diff --git a/src/claude/commands/info.test.ts b/src/claude/commands/info.test.ts
new file mode 100644
index 0000000000..ee6e755d36
--- /dev/null
+++ b/src/claude/commands/info.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { resolveInfoAccount } from "./info";
+
+const vaultRead = async (): Promise<never> => {
+    throw new Error("the vault was opened: the keychain would ask the user for gt-claude");
+};
+
+describe("tools claude info: which account", () => {
+    test("a named account reads names only and never opens the vault", async () => {
+        const account = await resolveInfoAccount({
+            name: "work",
+            readAccounts: async () => [{ name: "personal" }, { name: "work", label: "max 20x" }],
+            loadSecrets: vaultRead,
+            readToken: async () => "tok-work",
+        });
+
+        expect(account).toEqual({ name: "work", label: "max 20x" });
+    });
+
+    test("a token on stdin is matched against the stored tokens", async () => {
+        const account = await resolveInfoAccount({
+            name: undefined,
+            readAccounts: vaultRead,
+            loadSecrets: async () => ({
+                getAccountsByProvider: () => [
+                    { name: "personal", provider: "anthropic-sub", tokens: { longLivedToken: "tok-personal" } },
+                    { name: "work", provider: "anthropic-sub", tokens: { longLivedToken: "tok-work" } },
+                ],
+            }),
+            readToken: async () => "tok-work",
+        });
+
+        expect(account?.name).toBe("work");
+    });
+
+    test("no name and no token reads nothing", async () => {
+        const account = await resolveInfoAccount({
+            name: undefined,
+            readAccounts: vaultRead,
+            loadSecrets: vaultRead,
+            readToken: async () => null,
+        });
+
+        expect(account).toBeNull();
+    });
+});
diff --git a/src/claude/commands/info.ts b/src/claude/commands/info.ts
index b5edadb906..060b60e259 100644
--- a/src/claude/commands/info.ts
+++ b/src/claude/commands/info.ts
@@ -1,4 +1,5 @@
 import { AIConfig } from "@genesiscz/utils/ai/AIConfig";
+import { AiConfigStore } from "@genesiscz/utils/ai/config/AiConfigStore";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import type { AIAccountEntry } from "@genesiscz/utils/config/ai.types";
 import { SafeJSON } from "@genesiscz/utils/json";
@@ -34,22 +35,51 @@ async function readStdinToken(): Promise<string | null> {
     return token.length > 0 ? token : null;
 }
 
-async function resolveAccount(name: string | undefined, aiConfig: AIConfig): Promise<AIAccountEntry | null> {
-    const accounts = aiConfig.getAccountsByProvider("anthropic-sub");
+/** What the payload needs of an account: its name and label, no secret. */
+export interface InfoAccount {
+    name: string;
+    label?: string;
+}
+
+interface SecretAccounts {
+    getAccountsByProvider(provider: "anthropic-sub"): AIAccountEntry[];
+}
 
+/**
+ * The statusline runs this in every Claude session. With a name it reads the config's account list only:
+ * `AIConfig.load()` decrypts every account's secrets, which reads the vault's master key from the keychain, and
+ * macOS then asks the user whether `gt-claude` may use it. Only a token on stdin needs the stored tokens to compare.
+ */
+export async function resolveInfoAccount({
+    name,
+    readAccounts = readAnthropicAccounts,
+    loadSecrets = () => AIConfig.load(),
+    readToken = readStdinToken,
+}: {
+    name: string | undefined;
+    readAccounts?: () => Promise<InfoAccount[]>;
+    loadSecrets?: () => Promise<SecretAccounts>;
+    readToken?: () => Promise<string | null>;
+}): Promise<InfoAccount | null> {
     if (name) {
-        return accounts.find((a) => a.name === name) ?? null;
+        return (await readAccounts()).find((a) => a.name === name) ?? null;
     }
 
-    const token = await readStdinToken();
+    const token = await readToken();
     if (!token) {
         return null;
     }
 
-    return accounts.find((a) => a.tokens.longLivedToken === token) ?? null;
+    const config = await loadSecrets();
+    return config.getAccountsByProvider("anthropic-sub").find((a) => a.tokens.longLivedToken === token) ?? null;
+}
+
+async function readAnthropicAccounts(): Promise<InfoAccount[]> {
+    const store = await AiConfigStore.readOnly();
+    return store.data().accounts.filter((a) => a.provider === "anthropic-sub");
 }
 
-async function buildPayload(account: AIAccountEntry): Promise<AccountInfoPayload> {
+async function buildPayload(account: InfoAccount): Promise<AccountInfoPayload> {
     // Passive cache read only — `tools claude info` must never hit the network
     // (it is called from the statusline on every cache-miss refresh).
     const cached = await peekSharedUsage();
@@ -105,8 +135,7 @@ export function registerInfoCommand(program: Command): void {
                 process.exit(1);
             }
 
-            const aiConfig = await AIConfig.load();
-            const account = await resolveAccount(name, aiConfig);
+            const account = await resolveInfoAccount({ name });
 
             if (!account) {
                 if (name) {

From 9a61ad8f0cc69621442bcd61ca97e628ae4d0bc1 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 00:24:29 +0200
Subject: [PATCH 13/32] feat(ai, macos): with GenesisTools.app installed, a
 tool gets the vault key through the app's approval window, which shows why,
 what, who and which session from the kernel, because every gt-<tool> link
 raised its own keychain dialog with nothing to judge

(cherry picked from commit 46c36d5051a94ebed012e1e6591ff982f8739b1d)
---
 src/ai/commands/gate/index.ts                 |  27 +-
 src/ai/commands/usage/poll-daemon.ts          |   2 +
 src/claude/commands/info.ts                   |   6 +-
 src/macos/GenesisTools/Sources/Gate.swift     |   4 +-
 src/macos/GenesisTools/Sources/Notify.swift   |   9 +-
 .../GenesisTools/Sources/VaultUnlock.swift    | 450 ++++++++++++++++++
 .../GenesisTools/Tests/VaultUnlockTests.swift | 100 ++++
 src/say/lib/credential.ts                     |   7 +-
 src/utils/ai/gate/grants.ts                   |  52 +-
 src/utils/ai/gate/index.ts                    |   3 +
 src/utils/ai/gate/types.ts                    |  15 +
 src/utils/macos/genesis-app-rpc.ts            |  50 ++
 src/utils/security/MasterKey.ts               |  11 +-
 src/utils/security/SecretStore.ts             |   4 +
 src/utils/security/keyring/app-gate.test.ts   | 148 ++++++
 src/utils/security/keyring/app-gate.ts        | 148 ++++++
 src/utils/security/keyring/types.ts           |   2 +-
 src/utils/security/vault-purpose.ts           |  69 +++
 18 files changed, 1093 insertions(+), 14 deletions(-)
 create mode 100644 src/macos/GenesisTools/Sources/VaultUnlock.swift
 create mode 100644 src/macos/GenesisTools/Tests/VaultUnlockTests.swift
 create mode 100644 src/utils/security/keyring/app-gate.test.ts
 create mode 100644 src/utils/security/keyring/app-gate.ts
 create mode 100644 src/utils/security/vault-purpose.ts

diff --git a/src/ai/commands/gate/index.ts b/src/ai/commands/gate/index.ts
index 8234db2acb..5fbe3481fd 100644
--- a/src/ai/commands/gate/index.ts
+++ b/src/ai/commands/gate/index.ts
@@ -8,9 +8,12 @@ import {
     grantsPath,
     isGateProvider,
     listGrants,
+    listVaultGrants,
     readAuditTail,
     requestAccountAccess,
     revokeGrants,
+    revokeVaultGrants,
+    vaultGrantsPath,
 } from "@genesiscz/utils/ai/gate";
 import { suggestCommand, suggestEnumFlag } from "@genesiscz/utils/cli";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
@@ -135,9 +138,10 @@ export function registerGateCommands(program: Command): void {
         .option("--json", "Machine-readable output")
         .action((opts: { json?: boolean }) => {
             const grants = listGrants();
+            const vault = listVaultGrants();
 
             if (opts.json) {
-                out.result(grants);
+                out.result({ grants, vault });
                 return;
             }
 
@@ -156,8 +160,24 @@ export function registerGateCommands(program: Command): void {
             }
 
             out.println(table.toString());
+
+            renderCliHeader("Vault key", `${vault.length} remembered by GenesisTools.app`);
+            const vaultTable = createBoxTable(["TOOL", "EXECUTABLE", "SCRIPT", "UNTIL", "BY"]);
+
+            for (const grant of vault) {
+                vaultTable.push([
+                    truncateDisplay(grant.tool, 16),
+                    truncateDisplay(grant.executable, 32),
+                    truncateDisplay(grant.script ?? "", 40),
+                    grant.until === null ? "always" : new Date(grant.until).toLocaleString("sv-SE").slice(0, 16),
+                    grant.method,
+                ]);
+            }
+
+            out.println(vaultTable.toString());
             renderCliSection("Files");
             out.println(`  ${pc.dim(grantsPath())}`);
+            out.println(`  ${pc.dim(vaultGrantsPath())}`);
         });
 
     gate.command("revoke [client]")
@@ -174,7 +194,10 @@ export function registerGateCommands(program: Command): void {
             }
 
             const removed = await revokeGrants(selector);
-            out.log.info(`Revoked ${removed} grant${removed === 1 ? "" : "s"}.`);
+            const vault = await revokeVaultGrants(selector);
+            out.log.info(
+                `Revoked ${removed} grant${removed === 1 ? "" : "s"} and ${vault} vault-key approval${vault === 1 ? "" : "s"}.`
+            );
         });
 
     gate.command("audit")
diff --git a/src/ai/commands/usage/poll-daemon.ts b/src/ai/commands/usage/poll-daemon.ts
index a871174a2a..eb171c7d49 100644
--- a/src/ai/commands/usage/poll-daemon.ts
+++ b/src/ai/commands/usage/poll-daemon.ts
@@ -17,6 +17,7 @@ import { SafeJSON } from "@genesiscz/utils/json";
 import { logger, out } from "@genesiscz/utils/logger";
 import { isObject } from "@genesiscz/utils/object";
 import { cpuMeta, profiler } from "@genesiscz/utils/profile";
+import { setVaultPurpose } from "@genesiscz/utils/security/vault-purpose";
 
 const ANTHROPIC_SUB = "anthropic-sub";
 /** The daemon runner kills this task at 60 s (`timeoutMs` in the task log); the tick keeps 10 s of headroom. */
@@ -161,6 +162,7 @@ async function main(): Promise<void> {
         beforeMain: `${Math.round((beforeMain.user + beforeMain.system) / 1000)}ms`,
     }));
     logger.info("[ai-usage] daemon poll starting");
+    setVaultPurpose("refresh the usage of every AI account (the usage daemon, once a minute in the background)");
 
     const dashConfig = await loadDashboardConfig();
     const db = new UsageLimitsDb();
diff --git a/src/claude/commands/info.ts b/src/claude/commands/info.ts
index 060b60e259..3c4bd991d4 100644
--- a/src/claude/commands/info.ts
+++ b/src/claude/commands/info.ts
@@ -4,6 +4,7 @@ import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import type { AIAccountEntry } from "@genesiscz/utils/config/ai.types";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { out } from "@genesiscz/utils/logger";
+import { withVaultPurpose } from "@genesiscz/utils/security/vault-purpose";
 import type { Command } from "commander";
 import pc from "picocolors";
 import { normalizeLimits } from "../lib/usage/limits";
@@ -70,7 +71,10 @@ export async function resolveInfoAccount({
         return null;
     }
 
-    const config = await loadSecrets();
+    const config = await withVaultPurpose(
+        "match this Claude session's token to a configured account, for the statusline",
+        () => loadSecrets()
+    );
     return config.getAccountsByProvider("anthropic-sub").find((a) => a.tokens.longLivedToken === token) ?? null;
 }
 
diff --git a/src/macos/GenesisTools/Sources/Gate.swift b/src/macos/GenesisTools/Sources/Gate.swift
index 100b3a6ddf..be5acc383b 100644
--- a/src/macos/GenesisTools/Sources/Gate.swift
+++ b/src/macos/GenesisTools/Sources/Gate.swift
@@ -145,8 +145,8 @@ private func gateEmit(decision: String, rememberSeconds: Int, method: String, re
 }
 
 /// Touch ID first, then the account password when biometrics are unavailable or the user picks
-/// the fallback. A cancel at either step is a deny.
-private func authenticate(reason: String, completion: @escaping (_ method: String?, _ failure: String) -> Void) {
+/// the fallback. A cancel at either step is a deny. The vault window (VaultUnlock.swift) confirms with it too.
+func authenticate(reason: String, completion: @escaping (_ method: String?, _ failure: String) -> Void) {
     let biometric = LAContext()
     biometric.localizedFallbackTitle = "Use Password"
     var unavailable: NSError?
diff --git a/src/macos/GenesisTools/Sources/Notify.swift b/src/macos/GenesisTools/Sources/Notify.swift
index 70df81205e..a2f2a9a22f 100644
--- a/src/macos/GenesisTools/Sources/Notify.swift
+++ b/src/macos/GenesisTools/Sources/Notify.swift
@@ -815,7 +815,7 @@ private func list() {
 /// bump it: a client discovers those from `rpc.hello`'s method list instead.
 let rpcProtocolVersion = 1
 
-let rpcMethods = ["rpc.hello", "notify.post", "notify.remove", "notify.list", "notify.status", "notify.authorize", "notify.settings", "notify.reply", "gate.approve"]
+let rpcMethods = ["rpc.hello", "notify.post", "notify.remove", "notify.list", "notify.status", "notify.authorize", "notify.settings", "notify.reply", "gate.approve", "vault.unlock"]
 
 /// `GenesisTools --rpc '<json>'`, or `--rpc -` to read the request from stdin: run one method and
 /// exit with one JSON line on stdout.
@@ -905,6 +905,13 @@ func runRpc(_ arguments: [String]) -> Never {
 
         approveGate(request.params)
 
+    case "vault.unlock":
+        guard let request = try? decoder.decode(ParamsEnvelope<VaultUnlockParams>.self, from: data) else {
+            emitError(code: "params_invalid", message: "vault.unlock needs params.tool and params.purpose", exitCode: 64)
+        }
+
+        unlockVault(request.params)
+
     default:
         emitError(code: "method_unknown", message: "unknown method \(envelope.method)", exitCode: 69)
     }
diff --git a/src/macos/GenesisTools/Sources/VaultUnlock.swift b/src/macos/GenesisTools/Sources/VaultUnlock.swift
new file mode 100644
index 0000000000..c2c447f03e
--- /dev/null
+++ b/src/macos/GenesisTools/Sources/VaultUnlock.swift
@@ -0,0 +1,450 @@
+// The vault key's approval window (`--rpc {"method":"vault.unlock"}`), Martin's DECISION 131 b (2026-10-15):
+// "App approval window, but it probably should have enough context so i know exactly what / who / which session /
+// triggered that and why (each caller should give that context possibly)".
+//
+// A `gt-<tool>` process needs the GenesisTools vault master key. Before this, each tool's own bun link read the
+// keychain item and macOS asked "gt-claude wants to use your confidential information" with nothing to judge. Now the
+// tool starts this process and the app reads the item as itself (macOS asks once, naming GenesisTools).
+//
+// WHO comes from the kernel, never from the request: this process is the caller's child, so `getppid()` is the caller,
+// and its executable, arguments, environment (the session ids), working folder and parent chain are read from there.
+// WHY and WHAT come from the request, because only the caller knows them. A remembered approval for the same tool,
+// executable and script skips the window; otherwise Touch ID confirms an allow. Every outcome goes to the gate's audit
+// log. A deny, a cancel, a failed authentication and a timeout all reply "deny" with a reason.
+
+import AppKit
+import Darwin
+import Foundation
+import Security
+
+struct VaultUnlockParams: Decodable {
+    var tool: String
+    var purpose: String
+    var secret: String?
+    var command: String?
+}
+
+/// `KERN_PROCARGS2` of a process: the executable path, then `argc` arguments, then the environment.
+struct ProcArgs: Equatable {
+    var executable: String
+    var arguments: [String]
+    var environment: [String]
+
+    func environmentValue(_ name: String) -> String? {
+        let prefix = "\(name)="
+        return environment.first { $0.hasPrefix(prefix) }.map { String($0.dropFirst(prefix.count)) }
+    }
+}
+
+/// What the kernel says about one process.
+struct VaultCaller {
+    var pid: pid_t
+    var executable: String?
+    var args: ProcArgs?
+    var cwd: String?
+    var ancestors: [(pid: pid_t, command: String)]
+
+    /// The script an interpreter runs (`bun …/src/claude/index.ts`), part of the identity a grant is remembered for.
+    var script: String? {
+        guard let arguments = args?.arguments, arguments.count > 1 else { return nil }
+        let candidate = arguments.dropFirst().first { !$0.hasPrefix("-") }
+        guard let candidate, [".ts", ".tsx", ".js", ".mjs", ".cjs"].contains(where: candidate.hasSuffix) else { return nil }
+        return candidate
+    }
+
+    /// Flags and environment that load code the script path does not name. Any of them: no remembered approval.
+    var injected: [String] {
+        var found: [String] = []
+        let environment = args?.environmentValue
+        if let value = environment?("DYLD_INSERT_LIBRARIES"), !value.isEmpty {
+            found.append("DYLD_INSERT_LIBRARIES")
+        }
+
+        for name in ["NODE_OPTIONS", "BUN_OPTIONS"] {
+            if let value = environment?(name), ["--require", "-r ", "--import", "--loader", "--preload"].contains(where: value.contains) {
+                found.append(name)
+            }
+        }
+
+        let flags = (args?.arguments.dropFirst() ?? []).prefix { $0.hasPrefix("-") }
+        if flags.contains(where: { ["--preload", "-r", "--require", "--import", "--loader"].contains($0) }) {
+            found.append("interpreter flags \(flags.joined(separator: " "))")
+        }
+
+        return found
+    }
+}
+
+enum VaultProcess {
+    /// Little-endian `argc`, the executable path, NUL padding, `argc` arguments, the environment up to an empty entry.
+    static func parseProcArgs(_ bytes: [UInt8]) -> ProcArgs? {
+        guard bytes.count > 4 else { return nil }
+        let argc = Int(bytes[0]) | Int(bytes[1]) << 8 | Int(bytes[2]) << 16 | Int(bytes[3]) << 24
+        var index = 4
+
+        func next() -> String? {
+            guard index < bytes.count else { return nil }
+            let start = index
+            while index < bytes.count, bytes[index] != 0 {
+                index += 1
+            }
+
+            let value = String(decoding: bytes[start..<index], as: UTF8.self)
+            index += 1
+            return value
+        }
+
+        guard let executable = next() else { return nil }
+        while index < bytes.count, bytes[index] == 0 {
+            index += 1
+        }
+
+        var arguments: [String] = []
+        for _ in 0..<max(0, argc) {
+            guard let argument = next() else { break }
+            arguments.append(argument)
+        }
+
+        var environment: [String] = []
+        while let entry = next(), !entry.isEmpty {
+            environment.append(entry)
+        }
+
+        return ProcArgs(executable: executable, arguments: arguments, environment: environment)
+    }
+
+    static func procArgs(_ pid: pid_t) -> ProcArgs? {
+        var mib: [Int32] = [CTL_KERN, KERN_PROCARGS2, pid]
+        var size = 0
+        guard sysctl(&mib, 3, nil, &size, nil, 0) == 0, size > 0 else { return nil }
+        var buffer = [UInt8](repeating: 0, count: size)
+        guard sysctl(&mib, 3, &buffer, &size, nil, 0) == 0 else { return nil }
+        return parseProcArgs(Array(buffer.prefix(size)))
+    }
+
+    static func path(_ pid: pid_t) -> String? {
+        var buffer = [CChar](repeating: 0, count: 4 * Int(MAXPATHLEN))
+        guard proc_pidpath(pid, &buffer, UInt32(buffer.count)) > 0 else { return nil }
+        return String(cString: buffer)
+    }
+
+    static func cwd(_ pid: pid_t) -> String? {
+        var info = proc_vnodepathinfo()
+        let size = proc_pidinfo(pid, PROC_PIDVNODEPATHINFO, 0, &info, Int32(MemoryLayout<proc_vnodepathinfo>.size))
+        guard size > 0 else { return nil }
+        return withUnsafePointer(to: info.pvi_cdir.vip_path) {
+            String(cString: UnsafeRawPointer($0).assumingMemoryBound(to: CChar.self))
+        }
+    }
+
+    static func parent(_ pid: pid_t) -> pid_t? {
+        var info = proc_bsdinfo()
+        let size = proc_pidinfo(pid, PROC_PIDTBSDINFO, 0, &info, Int32(MemoryLayout<proc_bsdinfo>.size))
+        guard size > 0, info.pbi_ppid > 0 else { return nil }
+        return pid_t(info.pbi_ppid)
+    }
+
+    /// `name first-argument` of a process, short enough for one link of the chain.
+    static func label(_ pid: pid_t) -> String {
+        let name = path(pid).map { ($0 as NSString).lastPathComponent } ?? "pid \(pid)"
+        let first = procArgs(pid)?.arguments.dropFirst().first { !$0.hasPrefix("-") }.map { ($0 as NSString).lastPathComponent }
+        let text = [name, first].compactMap { $0 }.joined(separator: " ")
+        return text.count > 60 ? String(text.prefix(59)) + "…" : text
+    }
+
+    static func caller(_ pid: pid_t) -> VaultCaller {
+        var ancestors: [(pid: pid_t, command: String)] = []
+        var current = parent(pid)
+        while let ancestor = current, ancestor > 1, ancestors.count < 8 {
+            ancestors.append((ancestor, label(ancestor)))
+            current = parent(ancestor)
+        }
+
+        return VaultCaller(pid: pid, executable: path(pid), args: procArgs(pid), cwd: cwd(pid), ancestors: ancestors)
+    }
+}
+
+/// The session the caller belongs to, from its own environment and its parent chain.
+enum VaultSession {
+    static func describe(_ caller: VaultCaller) -> String? {
+        var parts: [String] = []
+        if let id = caller.args?.environmentValue("CLAUDE_CODE_SESSION_ID"), !id.isEmpty {
+            parts.append("Claude Code session \(id)")
+        } else if let agent = caller.ancestors.first(where: { ["claude", "codex", "grok"].contains($0.command.split(separator: " ").first.map(String.init) ?? "") }) {
+            parts.append("\(agent.command) (pid \(agent.pid))")
+        }
+
+        if let tab = caller.args?.environmentValue("CMUX_SURFACE_ID"), !tab.isEmpty {
+            parts.append("cmux tab \(tab)")
+        }
+
+        return parts.isEmpty ? nil : parts.joined(separator: ", ")
+    }
+}
+
+/// One remembered approval: this tool, this executable, this script.
+struct VaultGrant: Codable, Equatable {
+    var key: String
+    var tool: String
+    var executable: String
+    var script: String?
+    var grantedAt: Int64
+    /// Epoch milliseconds; nil means "always", until revoked with `tools ai gate revoke`.
+    var until: Int64?
+    var method: String
+
+    func isLive(at now: Int64) -> Bool {
+        until.map { $0 > now } ?? true
+    }
+}
+
+struct VaultGrantsFile: Codable {
+    var version: Int
+    var grants: [VaultGrant]
+}
+
+enum VaultGrants {
+    static func key(tool: String, executable: String, script: String?) -> String {
+        "vault|\(tool)|\(executable)|\(script ?? "")"
+    }
+
+    static var directory: String {
+        (genesisHome() as NSString).appendingPathComponent(".genesis-tools/ai/gate")
+    }
+
+    static var path: String {
+        (directory as NSString).appendingPathComponent("vault-grants.json")
+    }
+
+    static func load(from path: String = path) -> VaultGrantsFile {
+        guard let data = FileManager.default.contents(atPath: path),
+              let file = try? JSONDecoder().decode(VaultGrantsFile.self, from: data) else {
+            return VaultGrantsFile(version: 1, grants: [])
+        }
+
+        return file
+    }
+
+    static func live(_ key: String, now: Int64, in file: VaultGrantsFile) -> VaultGrant? {
+        file.grants.last { $0.key == key && $0.isLive(at: now) }
+    }
+
+    /// Replaces any grant for the same key and drops expired ones.
+    static func remember(_ grant: VaultGrant, now: Int64, in file: VaultGrantsFile) -> VaultGrantsFile {
+        var next = file
+        next.grants = file.grants.filter { $0.key != grant.key && $0.isLive(at: now) } + [grant]
+        return next
+    }
+
+    static func save(_ file: VaultGrantsFile, to path: String = path) {
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        guard let data = try? encoder.encode(file) else { return }
+        try? FileManager.default.createDirectory(atPath: (path as NSString).deletingLastPathComponent, withIntermediateDirectories: true)
+        let temporary = path + ".tmp-\(getpid())"
+        guard FileManager.default.createFile(atPath: temporary, contents: data, attributes: [.posixPermissions: 0o600]) else { return }
+        _ = rename(temporary, path)
+    }
+}
+
+/// One open window per tool: the usage daemon starts a process every minute, and without this each one would open its
+/// own window while the first waits for an answer. The lock lives as long as this process (one request, one window).
+enum VaultWindowLock {
+    static func path(for key: String) -> String {
+        let hash = key.utf8.reduce(UInt64(14_695_981_039_346_656_037)) { ($0 ^ UInt64($1)) &* 1_099_511_628_211 }
+        return (VaultGrants.directory as NSString).appendingPathComponent("vault-window-\(String(hash, radix: 16)).lock")
+    }
+
+    /// The descriptor holding the lock, or nil when another process holds it. Never closed: the process exits with it.
+    static func acquire(_ path: String) -> Int32? {
+        try? FileManager.default.createDirectory(atPath: (path as NSString).deletingLastPathComponent, withIntermediateDirectories: true)
+        let fd = open(path, O_CREAT | O_RDWR, 0o600)
+        guard fd >= 0 else { return nil }
+        guard flock(fd, LOCK_EX | LOCK_NB) == 0 else {
+            close(fd)
+            return nil
+        }
+
+        return fd
+    }
+}
+
+enum VaultWindow {
+    static func title(_ params: VaultUnlockParams) -> String {
+        "“\(params.tool)” asks for the GenesisTools vault key"
+    }
+
+    static func body(_ params: VaultUnlockParams, caller: VaultCaller, session: String?) -> String {
+        var lines: [String] = ["Why: \(params.purpose)"]
+        if let secret = params.secret, !secret.isEmpty {
+            lines.append("It was reading: \(secret)")
+        }
+
+        lines.append("")
+        lines.append("Who (read from the system, not from the request):")
+        lines.append("Process: pid \(caller.pid)")
+        lines.append("Executable: \(caller.executable ?? "unknown")")
+        if let script = caller.script {
+            lines.append("Script: \(script)")
+        }
+
+        if let arguments = caller.args?.arguments, !arguments.isEmpty {
+            let command = arguments.joined(separator: " ")
+            lines.append("Command: \(command.count > 300 ? String(command.prefix(299)) + "…" : command)")
+        }
+
+        if let cwd = caller.cwd {
+            lines.append("Working dir: \(cwd)")
+        }
+
+        if !caller.ancestors.isEmpty {
+            lines.append("Started by: " + caller.ancestors.map { "\($0.command) (\($0.pid))" }.joined(separator: " ← "))
+        }
+
+        lines.append("Session: \(session ?? "none found (not started from an agent session)")")
+        if !caller.injected.isEmpty {
+            lines.append("⚠️ Extra code may be loaded: \(caller.injected.joined(separator: ", ")). Allow once at most.")
+        }
+
+        lines.append("")
+        lines.append("The vault key decrypts every secret GenesisTools stores (AI account tokens and API keys): an allowed tool can read all of them. Touch ID confirms an allow.")
+        return lines.joined(separator: "\n")
+    }
+
+    static func choices(rememberable: Bool) -> [Int?] {
+        rememberable ? [0, 8 * 3_600, 7 * 86_400, nil] : [0]
+    }
+
+    static func label(_ seconds: Int?) -> String {
+        guard let seconds else { return "Always allow this tool" }
+        if seconds == 0 { return "Allow once" }
+        if seconds % 86_400 == 0 { return "Allow for \(seconds / 86_400) days" }
+        return "Allow for \(seconds / 3_600) hours"
+    }
+}
+
+private func vaultAudit(_ event: String, params: VaultUnlockParams, caller: VaultCaller, session: String?, detail: String = "") {
+    var parts = ["purpose: \(params.purpose)"]
+    if let secret = params.secret { parts.append("secret: \(secret)") }
+    if let session { parts.append("session: \(session)") }
+    if !detail.isEmpty { parts.append(detail) }
+
+    let entry: [String: Any] = [
+        "at": ISO8601DateFormatter().string(from: Date()),
+        "event": event,
+        "client": ["name": params.tool, "pid": Int(caller.pid), "executable": caller.executable ?? NSNull(), "cwd": caller.cwd ?? NSNull()],
+        "account": "vault",
+        "detail": parts.joined(separator: "; "),
+    ]
+    guard let data = try? JSONSerialization.data(withJSONObject: entry, options: [.sortedKeys]) else { return }
+    let path = (VaultGrants.directory as NSString).appendingPathComponent("audit.jsonl")
+    try? FileManager.default.createDirectory(atPath: VaultGrants.directory, withIntermediateDirectories: true)
+    if !FileManager.default.fileExists(atPath: path) {
+        FileManager.default.createFile(atPath: path, contents: nil, attributes: [.posixPermissions: 0o600])
+    }
+
+    guard let handle = FileHandle(forWritingAtPath: path) else { return }
+    defer { try? handle.close() }
+    _ = try? handle.seekToEnd()
+    try? handle.write(contentsOf: data + Data("\n".utf8))
+}
+
+/// The keychain item the bun rung writes (`genesis-tools` / `master-key`, base64), read as this app.
+private func emitVaultKey(remembered: Bool) -> Never {
+    let query: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: "genesis-tools",
+        kSecAttrAccount as String: "master-key",
+        kSecReturnData as String: true,
+        kSecMatchLimit as String: kSecMatchLimitOne,
+    ]
+    var item: CFTypeRef?
+    let status = SecItemCopyMatching(query as CFDictionary, &item)
+
+    guard status == errSecSuccess, let data = item as? Data, let key = String(data: data, encoding: .utf8) else {
+        if status == errSecItemNotFound {
+            emitError(code: "no_key", message: "the keychain holds no genesis-tools master key", exitCode: 66)
+        }
+
+        let reason = SecCopyErrorMessageString(status, nil) as String? ?? "status \(status)"
+        emitError(code: "keychain", message: "GenesisTools could not read the vault key: \(reason)", exitCode: 74)
+    }
+
+    emitResult(["decision": "allow", "key": key, "remembered": remembered])
+}
+
+private func vaultDeny(_ reason: String) -> Never {
+    logClick("vault.unlock decision=deny reason=\(reason)")
+    emitResult(["decision": "deny", "reason": reason])
+}
+
+func unlockVault(_ params: VaultUnlockParams) {
+    let caller = VaultProcess.caller(getppid())
+    let session = VaultSession.describe(caller)
+    guard let executable = caller.executable else {
+        vaultAudit("denied", params: params, caller: caller, session: session, detail: "the caller's executable could not be read")
+        vaultDeny("the caller's executable could not be read")
+    }
+
+    let rememberable = caller.injected.isEmpty
+    let key = VaultGrants.key(tool: params.tool, executable: executable, script: caller.script)
+    let now = Int64(Date().timeIntervalSince1970 * 1_000)
+
+    if rememberable, VaultGrants.live(key, now: now, in: VaultGrants.load()) != nil {
+        vaultAudit("remembered", params: params, caller: caller, session: session)
+        emitVaultKey(remembered: true)
+    }
+
+    guard VaultWindowLock.acquire(VaultWindowLock.path(for: key)) != nil else {
+        vaultAudit("denied", params: params, caller: caller, session: session, detail: "an approval window for this tool is already open")
+        vaultDeny("an approval window for “\(params.tool)” is already open; answer that one first")
+    }
+
+    DispatchQueue.main.asyncAfter(deadline: .now() + 170) {
+        vaultAudit("denied", params: params, caller: caller, session: session, detail: "no answer within 170 s")
+        vaultDeny("no answer within 170 s")
+    }
+
+    DispatchQueue.main.async {
+        NSApplication.shared.activate(ignoringOtherApps: true)
+        vaultAudit("prompted", params: params, caller: caller, session: session)
+
+        let choices = VaultWindow.choices(rememberable: rememberable)
+        let alert = NSAlert()
+        alert.alertStyle = .warning
+        alert.messageText = VaultWindow.title(params)
+        alert.informativeText = VaultWindow.body(params, caller: caller, session: session)
+        for seconds in choices {
+            alert.addButton(withTitle: VaultWindow.label(seconds))
+        }
+
+        let deny = alert.addButton(withTitle: "Deny")
+        deny.keyEquivalent = "\u{1b}"
+
+        let index = alert.runModal().rawValue - NSApplication.ModalResponse.alertFirstButtonReturn.rawValue
+        guard index >= 0, index < choices.count else {
+            vaultAudit("denied", params: params, caller: caller, session: session, detail: "denied in the window")
+            vaultDeny("denied in the approval window")
+        }
+
+        let remember = choices[index]
+        authenticate(reason: "give “\(params.tool)” the GenesisTools vault key") { method, failure in
+            guard let method else {
+                vaultAudit("denied", params: params, caller: caller, session: session, detail: failure)
+                vaultDeny(failure)
+            }
+
+            if remember != 0 {
+                let until = remember.map { now + Int64($0) * 1_000 }
+                let grant = VaultGrant(key: key, tool: params.tool, executable: executable, script: caller.script,
+                                       grantedAt: now, until: until, method: method)
+                VaultGrants.save(VaultGrants.remember(grant, now: now, in: VaultGrants.load()))
+            }
+
+            vaultAudit("allowed", params: params, caller: caller, session: session,
+                       detail: "method: \(method); remembered: \(remember.map { $0 == 0 ? "once" : "\($0 / 3_600) h" } ?? "always")")
+            logClick("vault.unlock decision=allow tool=\(params.tool) method=\(method)")
+            emitVaultKey(remembered: false)
+        }
+    }
+}
diff --git a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
new file mode 100644
index 0000000000..7dbb5af2e5
--- /dev/null
+++ b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
@@ -0,0 +1,100 @@
+import XCTest
+@testable import GenesisTools
+
+/// The vault approval window's pure parts (Sources/VaultUnlock.swift): reading a process from the kernel's bytes,
+/// what counts as the same tool for a remembered approval, and what the window tells the user.
+final class VaultUnlockTests: XCTestCase {
+    private func procArgsBytes(argc: Int32, executable: String, arguments: [String], environment: [String]) -> [UInt8] {
+        var bytes = withUnsafeBytes(of: argc.littleEndian) { Array($0) }
+        bytes += Array(executable.utf8) + [0, 0, 0, 0]
+        for argument in arguments {
+            bytes += Array(argument.utf8) + [0]
+        }
+
+        for entry in environment {
+            bytes += Array(entry.utf8) + [0]
+        }
+
+        // The environment ends at an empty entry; the "apple" strings after it are not environment.
+        bytes += [0] + Array("executable_path=/x".utf8) + [0]
+        return bytes
+    }
+
+    private func caller(arguments: [String], environment: [String] = [], ancestors: [(pid_t, String)] = []) -> VaultCaller {
+        VaultCaller(pid: 4242, executable: "/Users/alice/.genesis-tools/bin/gt-claude",
+                    args: ProcArgs(executable: "/Users/alice/.genesis-tools/bin/gt-claude", arguments: arguments, environment: environment),
+                    cwd: "/Users/alice/project", ancestors: ancestors.map { (pid: $0.0, command: $0.1) })
+    }
+
+    func testTheKernelBytesSplitIntoExecutableArgumentsAndEnvironment() throws {
+        let bytes = procArgsBytes(argc: 3, executable: "/Users/alice/.genesis-tools/bin/gt-claude",
+                                  arguments: ["gt-claude", "/repo/src/claude/index.ts", "info"],
+                                  environment: ["CLAUDE_CODE_SESSION_ID=0f3a", "HOME=/Users/alice"])
+        let parsed = try XCTUnwrap(VaultProcess.parseProcArgs(bytes))
+
+        XCTAssertEqual(parsed.executable, "/Users/alice/.genesis-tools/bin/gt-claude")
+        XCTAssertEqual(parsed.arguments, ["gt-claude", "/repo/src/claude/index.ts", "info"])
+        XCTAssertEqual(parsed.environment, ["CLAUDE_CODE_SESSION_ID=0f3a", "HOME=/Users/alice"])
+        XCTAssertEqual(parsed.environmentValue("CLAUDE_CODE_SESSION_ID"), "0f3a")
+    }
+
+    func testTheScriptIsPartOfTheIdentityAndLoadersBlockRemembering() {
+        XCTAssertEqual(caller(arguments: ["gt-claude", "/repo/src/claude/index.ts", "info"]).script, "/repo/src/claude/index.ts")
+        XCTAssertEqual(caller(arguments: ["gt-claude", "/repo/src/claude/index.ts"]).injected, [])
+        XCTAssertFalse(caller(arguments: ["gt-claude", "--preload", "/tmp/x.ts", "/repo/src/claude/index.ts"]).injected.isEmpty)
+        XCTAssertFalse(caller(arguments: ["gt-claude", "/repo/src/claude/index.ts"], environment: ["DYLD_INSERT_LIBRARIES=/tmp/x.dylib"]).injected.isEmpty)
+        XCTAssertEqual(VaultWindow.choices(rememberable: false), [0], "with extra code loaded, only allow once")
+    }
+
+    func testARememberedApprovalCoversOnlyTheSameToolExecutableAndScriptUntilItEnds() {
+        let key = VaultGrants.key(tool: "claude", executable: "/bin/gt-claude", script: "/repo/src/claude/index.ts")
+        let grant = VaultGrant(key: key, tool: "claude", executable: "/bin/gt-claude", script: "/repo/src/claude/index.ts",
+                               grantedAt: 1_000, until: 2_000, method: "touch-id")
+        let file = VaultGrants.remember(grant, now: 1_000, in: VaultGrantsFile(version: 1, grants: []))
+
+        XCTAssertNotNil(VaultGrants.live(key, now: 1_500, in: file))
+        XCTAssertNil(VaultGrants.live(key, now: 2_000, in: file), "a timed approval ends")
+        XCTAssertNil(VaultGrants.live(VaultGrants.key(tool: "claude", executable: "/bin/gt-claude", script: "/tmp/other.ts"), now: 1_500, in: file))
+        XCTAssertNil(VaultGrants.live(VaultGrants.key(tool: "say", executable: "/bin/gt-claude", script: "/repo/src/claude/index.ts"), now: 1_500, in: file))
+
+        var always = grant
+        always.until = nil
+        XCTAssertNotNil(VaultGrants.live(key, now: Int64.max, in: VaultGrants.remember(always, now: 1_000, in: file)), "always lasts until revoked")
+    }
+
+    func testTheWindowSaysWhyWhatWhoAndWhichSession() {
+        let params = VaultUnlockParams(tool: "claude", purpose: "match the session's token to an account for the statusline",
+                                       secret: "ai/acc_work/longLivedToken", command: "tools claude info")
+        let who = caller(arguments: ["gt-claude", "/repo/src/claude/index.ts", "info"],
+                         environment: ["CLAUDE_CODE_SESSION_ID=0f3a-session", "CMUX_SURFACE_ID=surface-9"],
+                         ancestors: [(100, "GenesisTools gt-claude"), (90, "zsh"), (80, "claude")])
+        let session = VaultSession.describe(who)
+        let body = VaultWindow.body(params, caller: who, session: session)
+
+        XCTAssertEqual(session, "Claude Code session 0f3a-session, cmux tab surface-9")
+        XCTAssertTrue(body.contains("Why: match the session's token to an account for the statusline"))
+        XCTAssertTrue(body.contains("It was reading: ai/acc_work/longLivedToken"))
+        XCTAssertTrue(body.contains("Executable: /Users/alice/.genesis-tools/bin/gt-claude"))
+        XCTAssertTrue(body.contains("Script: /repo/src/claude/index.ts"))
+        XCTAssertTrue(body.contains("Started by: GenesisTools gt-claude (100) ← zsh (90) ← claude (80)"))
+        XCTAssertTrue(body.contains("Session: Claude Code session 0f3a-session"))
+        XCTAssertFalse(body.contains("Extra code"))
+    }
+
+    func testASecondRequestFromTheSameToolGetsNoSecondWindow() throws {
+        let path = (NSTemporaryDirectory() as NSString).appendingPathComponent("vault-window-test-\(UUID().uuidString).lock")
+        defer { try? FileManager.default.removeItem(atPath: path) }
+        let first = try XCTUnwrap(VaultWindowLock.acquire(path))
+
+        XCTAssertNil(VaultWindowLock.acquire(path), "the first window holds the lock")
+        close(first)
+        XCTAssertNotNil(VaultWindowLock.acquire(path), "a closed window frees it")
+        XCTAssertNotEqual(VaultWindowLock.path(for: "vault|claude|/a|"), VaultWindowLock.path(for: "vault|say|/a|"))
+    }
+
+    func testWithoutASessionIdTheAgentInTheParentChainNamesIt() {
+        let who = caller(arguments: ["gt-say", "/repo/src/say/index.ts"], ancestors: [(90, "zsh"), (80, "codex exec")])
+
+        XCTAssertEqual(VaultSession.describe(who), "codex exec (pid 80)")
+    }
+}
diff --git a/src/say/lib/credential.ts b/src/say/lib/credential.ts
index b9b21ad22a..7e169067fa 100644
--- a/src/say/lib/credential.ts
+++ b/src/say/lib/credential.ts
@@ -4,6 +4,7 @@ import { resolveProviderApiKey } from "@genesiscz/utils/ai/providers/resolve";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { logger } from "@genesiscz/utils/logger";
 import type { SayProvider } from "@genesiscz/utils/macos/SayConfigManager";
+import { withVaultPurpose } from "@genesiscz/utils/security/vault-purpose";
 
 export type SayCredentialCheck =
     | { kind: "ok"; apiKey?: string }
@@ -173,9 +174,9 @@ export async function sayAccountKey(account: SayAccount, deps: SayAccountDeps =
     logger.debug({ account: account.entry.name, provider: account.provider, gated }, "[say] resolving the account key");
 
     try {
-        return gated
-            ? await (deps.requestGate ?? gateKey)(account.entry)
-            : await (deps.resolveKey ?? accountKey)(account.entry);
+        return await withVaultPurpose(`speak through ${account.provider} with the account ${account.entry.name}`, () =>
+            gated ? (deps.requestGate ?? gateKey)(account.entry) : (deps.resolveKey ?? accountKey)(account.entry)
+        );
     } catch (err) {
         if (err instanceof SayAccountError) {
             throw err;
diff --git a/src/utils/ai/gate/grants.ts b/src/utils/ai/gate/grants.ts
index c86bb3ac4d..df2cb67f38 100644
--- a/src/utils/ai/gate/grants.ts
+++ b/src/utils/ai/gate/grants.ts
@@ -8,7 +8,7 @@ import { logger } from "@genesiscz/utils/logger";
 import { isJsonObject, readJsonFileForUpdateSync } from "@genesiscz/utils/storage/atomic-file";
 import { withFileLock } from "@genesiscz/utils/storage/file-lock";
 import { atomicWriteFileSync } from "@genesiscz/utils/storage/storage";
-import type { ClientIdentity, GateGrant, GateProvider, TokenKind } from "./types";
+import type { ClientIdentity, GateGrant, GateProvider, TokenKind, VaultGrant } from "./types";
 
 const { log } = logger.scoped("ai-gate");
 
@@ -123,6 +123,56 @@ export async function rememberGrant(grant: GateGrant): Promise<void> {
     ]);
 }
 
+export function vaultGrantsPath(): string {
+    return join(gateDir(), "vault-grants.json");
+}
+
+function isVaultGrant(value: unknown): value is VaultGrant {
+    return isJsonObject(value) && typeof value.key === "string" && typeof value.tool === "string";
+}
+
+function readVaultGrants(): VaultGrant[] {
+    const path = vaultGrantsPath();
+    if (!existsSync(path)) {
+        return [];
+    }
+
+    const parsed = parseJSON<{ grants?: unknown[] }>(readFileSync(path, "utf8"));
+    return (parsed?.grants ?? []).filter(isVaultGrant);
+}
+
+/** Vault-key approvals GenesisTools.app remembers that have not ended. */
+export function listVaultGrants(now = Date.now()): VaultGrant[] {
+    return readVaultGrants().filter((grant) => grant.until === null || grant.until > now);
+}
+
+/** Drop vault-key approvals by tool name or key; `"*"` drops every one. The app writes this file by atomic rename. */
+export async function revokeVaultGrants(selector: string): Promise<number> {
+    const path = vaultGrantsPath();
+    let removed = 0;
+
+    if (!existsSync(path)) {
+        return 0;
+    }
+
+    await withFileLock(
+        `${path}.lock`,
+        async () => {
+            const grants = readVaultGrants();
+            const kept = grants.filter(
+                (grant) => selector !== "*" && grant.key !== selector && grant.tool !== selector
+            );
+            removed = grants.length - kept.length;
+            atomicWriteFileSync(path, `${SafeJSON.stringify({ version: 1, grants: kept }, null, 2)}\n`, {
+                mode: 0o600,
+            });
+        },
+        10_000
+    );
+
+    return removed;
+}
+
 /** Drop grants by client key or client name; `"*"` drops every grant. Returns how many went. */
 export async function revokeGrants(selector: string): Promise<number> {
     let removed = 0;
diff --git a/src/utils/ai/gate/index.ts b/src/utils/ai/gate/index.ts
index cbe0906a62..da812e873a 100644
--- a/src/utils/ai/gate/index.ts
+++ b/src/utils/ai/gate/index.ts
@@ -13,9 +13,12 @@ export {
     gateDir,
     grantsPath,
     listGrants,
+    listVaultGrants,
     readAuditTail,
     rememberGrant,
     revokeGrants,
+    revokeVaultGrants,
+    vaultGrantsPath,
 } from "./grants";
 export { type GateDeps, providerTokenResolver, requestAccountAccess, type TokenResolver } from "./request";
 export * from "./types";
diff --git a/src/utils/ai/gate/types.ts b/src/utils/ai/gate/types.ts
index 8a8fd84826..92d153222d 100644
--- a/src/utils/ai/gate/types.ts
+++ b/src/utils/ai/gate/types.ts
@@ -91,6 +91,21 @@ export type ApprovalDecision =
     | { decision: "deny"; reason: string };
 
 /** A remembered approval. Matched on client key, provider, account id and the token kind approved. */
+/**
+ * A remembered vault-key approval, written by GenesisTools.app's vault window (src/macos/GenesisTools/Sources/
+ * VaultUnlock.swift) into `vault-grants.json`. One tool, one executable, one script; `until` null means "always",
+ * until `tools ai gate revoke` drops it.
+ */
+export interface VaultGrant {
+    key: string;
+    tool: string;
+    executable: string;
+    script?: string | null;
+    grantedAt: number;
+    until: number | null;
+    method: string;
+}
+
 export interface GateGrant {
     key: string;
     clientName: string;
diff --git a/src/utils/macos/genesis-app-rpc.ts b/src/utils/macos/genesis-app-rpc.ts
index fa164fceb0..2974d16a3a 100644
--- a/src/utils/macos/genesis-app-rpc.ts
+++ b/src/utils/macos/genesis-app-rpc.ts
@@ -115,6 +115,56 @@ export async function genesisAppRpc<T>(
 }
 
 /** Exported for tests: this is where a reply from something other than the app has to be caught. */
+/**
+ * `genesisAppRpc` for a caller that cannot await: the synchronous vault-key read behind `resolveSecretSync`. It blocks
+ * the event loop until the app answers, which for an approval window is up to `timeoutMs`; use it only where a sync
+ * signature leaves no choice.
+ */
+export function genesisAppRpcSync<T>(
+    method: string,
+    params?: Record<string, unknown>,
+    opts: GenesisAppRpcOptions<T> = {}
+): GenesisAppRpcOutcome<T> {
+    const launcher = installedGenesisAppLauncher();
+
+    if (!launcher) {
+        return {
+            ok: false,
+            error: { code: "unavailable", message: "GenesisTools.app is not installed, or routing is switched off" },
+        };
+    }
+
+    const request = SafeJSON.stringify(params ? { method, params: stripUndefined(params) } : { method });
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const proc = Bun.spawnSync([launcher, "--rpc", request], {
+        stdout: "pipe",
+        stderr: "pipe",
+        stdin: "ignore",
+        timeout: timeoutMs,
+    });
+    const stderr = proc.stderr.toString();
+
+    if (proc.exitedDueToTimeout) {
+        logger.debug({ method, timeoutMs }, "GenesisTools.app RPC timed out");
+        return { ok: false, error: { code: "timeout", message: `${method} timed out after ${timeoutMs}ms` } };
+    }
+
+    const line = proc.stdout.toString().trim().split("\n").filter(Boolean).at(-1);
+
+    if (!line) {
+        logger.debug({ method, exitCode: proc.exitCode, stderr }, "GenesisTools.app RPC returned no reply line");
+        return {
+            ok: false,
+            error: {
+                code: "handshake",
+                message: `${method} produced no reply (exit ${proc.exitCode})${stderr.trim() ? `: ${stderr.trim()}` : ""}`,
+            },
+        };
+    }
+
+    return parseReply<T>(method, line, proc.exitCode ?? -1, stderr, opts.isResult);
+}
+
 export function parseReply<T>(
     method: string,
     line: string,
diff --git a/src/utils/security/MasterKey.ts b/src/utils/security/MasterKey.ts
index 21e294b024..e7aaed70d5 100644
--- a/src/utils/security/MasterKey.ts
+++ b/src/utils/security/MasterKey.ts
@@ -6,6 +6,7 @@ import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { env } from "@genesiscz/utils/env";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { logger } from "@genesiscz/utils/logger";
+import { appGateKey } from "./keyring/app-gate";
 import { envKeyProvider, fileKeyProvider, masterKeyFilePath, securityStorage } from "./keyring/headless";
 import { osKeyring } from "./keyring/os-keyring";
 import { MASTER_KEY_BYTES, type MasterKeyProvider, type MasterKeySource } from "./keyring/types";
@@ -30,10 +31,13 @@ interface KeyState {
 }
 
 let cached: KeyState | null = null;
-let providers: MasterKeyProvider[] = [envKeyProvider, osKeyring, fileKeyProvider];
+// The app rung sits before the keychain: with GenesisTools.app installed, the app's approval window replaces the
+// keychain's per-executable dialog. It answers nothing when the app cannot (then the keychain does), and throws on a
+// deny, so a refused key never falls through to the dialog it replaces.
+let providers: MasterKeyProvider[] = [envKeyProvider, appGateKey, osKeyring, fileKeyProvider];
 
 /**
- * Ladder, first hit wins: in-process cache, env, OS keychain, opt-in key file.
+ * Ladder, first hit wins: in-process cache, env, GenesisTools.app's approval window, OS keychain, opt-in key file.
  * Interactive processes generate and store a key when every rung misses;
  * headless ones fail loudly rather than minting a key nobody can find later.
  *
@@ -238,7 +242,8 @@ export async function writeMasterKey(key: Buffer): Promise<MasterKeySource> {
     }
 
     for (const provider of providers) {
-        if (provider.id === "env") {
+        // The env rung is the caller's own override and the app rung only reads, so neither stores a new key.
+        if (provider.id === "env" || provider.id === "app") {
             continue;
         }
 
diff --git a/src/utils/security/SecretStore.ts b/src/utils/security/SecretStore.ts
index f7ed06b57b..0504d6813b 100644
--- a/src/utils/security/SecretStore.ts
+++ b/src/utils/security/SecretStore.ts
@@ -15,6 +15,7 @@ import {
 } from "./MasterKey";
 import { isSecretPath, isSecureRef, type MaybeSecret, type SecureRef, secureRef } from "./SecureRef";
 import { emptyVault, VAULT_HKDF_SALT, VAULT_VERSION, type VaultEntry, type VaultFile } from "./vault-format";
+import { noteVaultSecret } from "./vault-purpose";
 
 const KEY_BYTES = 32;
 const IV_BYTES = 12;
@@ -192,6 +193,7 @@ class FileSecretStore implements SecretStore {
             return undefined;
         }
 
+        noteVaultSecret(path);
         try {
             return decryptEntry(await masterKeyForId(vault.keyId), path, entry);
         } catch (err) {
@@ -214,6 +216,7 @@ class FileSecretStore implements SecretStore {
                     return undefined;
                 }
 
+                noteVaultSecret(path);
                 key ??= masterKeyForId(vault.keyId);
                 try {
                     return decryptEntry(await key, path, entry);
@@ -240,6 +243,7 @@ class FileSecretStore implements SecretStore {
                 return undefined;
             }
 
+            noteVaultSecret(path);
             const key = masterKeyForIdSync(snapshot.keyId);
             if (!key) {
                 projectionMissedKey = true;
diff --git a/src/utils/security/keyring/app-gate.test.ts b/src/utils/security/keyring/app-gate.test.ts
new file mode 100644
index 0000000000..3680ef6a0a
--- /dev/null
+++ b/src/utils/security/keyring/app-gate.test.ts
@@ -0,0 +1,148 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { _setMasterKeyProvidersForTest, masterKey, masterKeySync, writeMasterKey } from "../MasterKey";
+import {
+    _resetVaultContextForTest,
+    currentCommandLine,
+    currentToolName,
+    noteVaultSecret,
+    setVaultPurpose,
+} from "../vault-purpose";
+import { appGateKey, createAppGateKeyProvider, VaultKeyDeniedError, type VaultUnlockRequest } from "./app-gate";
+import type { MasterKeyProvider } from "./types";
+
+const KEY = Buffer.alloc(32, 7);
+const allow = { ok: true as const, result: { decision: "allow" as const, key: KEY.toString("base64") } };
+const deny = { ok: true as const, result: { decision: "deny" as const, reason: "denied in the approval window" } };
+const failure = (code: string) => ({ ok: false as const, error: { code, message: `${code} from the fake app` } });
+
+/** A keychain stand-in that records reads and writes; `throwOnRead` proves a path never reached it. */
+function fakeKeychain(stored: Buffer | undefined, throwOnRead = false) {
+    const calls = { reads: 0, writes: [] as Buffer[] };
+    const rung: MasterKeyProvider = {
+        id: "keychain",
+        available: async () => true,
+        get: async () => rung.getSync?.(),
+        getSync: () => {
+            calls.reads++;
+            if (throwOnRead) {
+                throw new Error("the keychain was read after the app denied the key");
+            }
+
+            return stored;
+        },
+        set: async (key) => {
+            calls.writes.push(key);
+        },
+    };
+    return { rung, calls };
+}
+
+afterEach(() => {
+    _resetVaultContextForTest();
+    _setMasterKeyProvidersForTest([]);
+});
+
+describe("the app rung", () => {
+    test("an allow returns the key the app read", async () => {
+        const rung = createAppGateKeyProvider({ available: () => true, rpc: async () => allow, rpcSync: () => allow });
+
+        expect(await rung.get()).toEqual(KEY);
+        expect(rung.getSync?.()).toEqual(KEY);
+    });
+
+    test("a deny throws with the window's reason and never reaches the keychain", () => {
+        const keychain = fakeKeychain(KEY, true);
+        _setMasterKeyProvidersForTest([
+            createAppGateKeyProvider({ available: () => true, rpcSync: () => deny }),
+            keychain.rung,
+        ]);
+
+        expect(() => masterKeySync()).toThrow(VaultKeyDeniedError);
+        expect(() => masterKeySync()).toThrow("denied in the approval window");
+        expect(keychain.calls.reads).toBe(0);
+    });
+
+    test("an app that cannot answer lets the keychain answer, as before the app existed", async () => {
+        for (const code of ["unavailable", "method_unknown", "handshake", "no_key"]) {
+            const keychain = fakeKeychain(KEY);
+            const app = createAppGateKeyProvider({
+                available: () => true,
+                rpc: async () => failure(code),
+                rpcSync: () => failure(code),
+            });
+            _setMasterKeyProvidersForTest([app, keychain.rung]);
+
+            expect(masterKeySync()).toEqual(KEY);
+            expect(keychain.calls.reads).toBe(1);
+        }
+    });
+
+    test("no answer within the window's time is a deny, not a fall-through to the keychain dialog", () => {
+        const app = createAppGateKeyProvider({ available: () => true, rpcSync: () => failure("timeout") });
+
+        expect(() => app.getSync?.()).toThrow("timeout");
+    });
+
+    test("without the app the rung asks nothing and the keychain answers", async () => {
+        let asked = 0;
+        const keychain = fakeKeychain(KEY);
+        const app = createAppGateKeyProvider({
+            available: () => false,
+            rpc: async () => {
+                asked++;
+                return allow;
+            },
+        });
+        _setMasterKeyProvidersForTest([app, keychain.rung]);
+
+        expect(await masterKey()).toEqual(KEY);
+        expect(asked).toBe(0);
+    });
+
+    test("the request carries why, what and the command", async () => {
+        const seen: VaultUnlockRequest[] = [];
+        setVaultPurpose("refresh the usage figures of 3 accounts for the statusline");
+        noteVaultSecret("ai/acc_work/accessToken");
+        noteVaultSecret("ai/acc_side/accessToken");
+        const app = createAppGateKeyProvider({
+            available: () => true,
+            rpc: async (request) => {
+                seen.push(request);
+                return allow;
+            },
+        });
+
+        await app.get();
+        expect(seen[0]?.purpose).toBe("refresh the usage figures of 3 accounts for the statusline");
+        expect(seen[0]?.secret).toBe("ai/acc_work/accessToken");
+        expect(seen[0]?.command.startsWith("tools ")).toBe(true);
+    });
+
+    test("a new key is stored by the keychain, never by the app rung", async () => {
+        const keychain = fakeKeychain(undefined);
+        _setMasterKeyProvidersForTest([
+            createAppGateKeyProvider({ available: () => true, rpc: async () => allow }),
+            keychain.rung,
+        ]);
+
+        expect(await writeMasterKey(KEY)).toBe("keychain");
+        expect(keychain.calls.writes).toEqual([KEY]);
+    });
+
+    test("a test process never reaches the real app", async () => {
+        expect(await appGateKey.available()).toBe(false);
+        expect(appGateKey.getSync?.()).toBeUndefined();
+    });
+});
+
+describe("the caller's name and command", () => {
+    test("from the tool's entry script, else from its gt- launcher", () => {
+        expect(currentToolName(["/Users/x/.genesis-tools/bin/gt-claude", "/repo/src/claude/index.ts", "info"])).toBe(
+            "claude"
+        );
+        expect(currentToolName(["/Users/x/.genesis-tools/bin/gt-say", "/somewhere/else.ts"])).toBe("say");
+        expect(currentCommandLine(["gt-say", "/repo/src/say/index.ts", "hello there", "--app", "claude"])).toBe(
+            'tools say "hello there" --app claude'
+        );
+    });
+});
diff --git a/src/utils/security/keyring/app-gate.ts b/src/utils/security/keyring/app-gate.ts
new file mode 100644
index 0000000000..c9f1ac8ef5
--- /dev/null
+++ b/src/utils/security/keyring/app-gate.ts
@@ -0,0 +1,148 @@
+import { logger } from "@genesiscz/utils/logger";
+import {
+    type GenesisAppRpcOutcome,
+    genesisAppRpc,
+    genesisAppRpcSync,
+    isGenesisAppRpcAvailable,
+} from "@genesiscz/utils/macos/genesis-app-rpc";
+import { currentCommandLine, currentToolName, vaultPurpose, vaultSecretAsked } from "../vault-purpose";
+import { decodeMasterKey, isTestProcess, type MasterKeyProvider } from "./types";
+
+/**
+ * The vault master key through GenesisTools.app's approval window (Martin's DECISION 131 b, 2026-10-15).
+ *
+ * Every tool runs as its own `gt-<tool>` link of bun, and macOS keys a keychain item's access list on the executable
+ * path, so each tool used to raise its own "gt-claude wants to use your confidential information" dialog with nothing
+ * in it to judge. Here the app reads the item as itself (one macOS prompt, ever, naming GenesisTools) and hands the key
+ * on only after its own window: WHO from the kernel (the app is this process's child), WHICH SESSION from this
+ * process's environment, WHY and WHAT from the request below. A remembered approval skips the window.
+ *
+ * A deny throws: falling through to the keychain rung would bring back the dialog this rung exists to replace. An app
+ * that cannot answer (not installed, switched off, an older build without `vault.unlock`) returns undefined, and the
+ * keychain rung answers as before.
+ */
+
+/** A person reads the window and touches the sensor; the app gives up at 170 s and says so. */
+export const VAULT_UNLOCK_TIMEOUT_MS = 180_000;
+
+export interface VaultUnlockRequest {
+    /** The tool as GenesisTools names it (`claude`, `say`); the app shows it beside the executable it verified. */
+    tool: string;
+    /** Why, in one sentence: the caller's own, else the command line. */
+    purpose: string;
+    /** The secret this process was reading when it needed the key (`ai/<account>/<field>`). */
+    secret?: string;
+    command: string;
+}
+
+export interface VaultUnlockReply {
+    decision: "allow" | "deny";
+    /** The keychain item as stored: base64 of the 32-byte key. Present only with "allow". */
+    key?: string;
+    reason?: string;
+    /** True when a remembered approval answered and no window opened. */
+    remembered?: boolean;
+}
+
+export class VaultKeyDeniedError extends Error {
+    constructor(tool: string, reason: string) {
+        super(
+            `GenesisTools.app did not give the vault key to “${tool}”: ${reason}. ` +
+                "Allow it in the approval window, or set GENESIS_TOOLS_NO_APP=1 to read the keychain directly."
+        );
+        this.name = "VaultKeyDeniedError";
+    }
+}
+
+/** App errors that mean "nobody here can decide": the keychain rung answers instead. */
+const FALL_THROUGH = new Set(["unavailable", "method_unknown", "handshake", "no_key"]);
+
+export function vaultUnlockRequest(): VaultUnlockRequest {
+    const command = currentCommandLine();
+
+    return {
+        tool: currentToolName(),
+        purpose: vaultPurpose() ?? `run ${command}`,
+        secret: vaultSecretAsked(),
+        command,
+    };
+}
+
+function isReply(value: unknown): value is VaultUnlockReply {
+    return typeof value === "object" && value !== null && "decision" in value;
+}
+
+/** The app's answer as a key, undefined (let the next rung answer), or a thrown deny. */
+export function keyFromReply(outcome: GenesisAppRpcOutcome<VaultUnlockReply>, tool: string): Buffer | undefined {
+    if (!outcome.ok) {
+        if (FALL_THROUGH.has(outcome.error.code)) {
+            logger.debug(
+                { code: outcome.error.code, message: outcome.error.message },
+                "vault key: the app cannot answer"
+            );
+            return undefined;
+        }
+
+        throw new VaultKeyDeniedError(tool, `${outcome.error.code}: ${outcome.error.message}`);
+    }
+
+    if (outcome.result.decision !== "allow") {
+        throw new VaultKeyDeniedError(tool, outcome.result.reason ?? "denied in the approval window");
+    }
+
+    const key = decodeMasterKey(outcome.result.key, "app");
+    if (!key) {
+        throw new VaultKeyDeniedError(tool, "the app allowed it but returned no readable key");
+    }
+
+    logger.debug({ tool, remembered: outcome.result.remembered === true }, "vault key handed down by GenesisTools.app");
+    return key;
+}
+
+export interface AppGateDeps {
+    available?: () => boolean;
+    rpc?: (request: VaultUnlockRequest) => Promise<GenesisAppRpcOutcome<VaultUnlockReply>>;
+    rpcSync?: (request: VaultUnlockRequest) => GenesisAppRpcOutcome<VaultUnlockReply>;
+}
+
+/** Tests build the rung with fakes; production uses `appGateKey`. A test process never reaches the real app. */
+export function createAppGateKeyProvider(deps: AppGateDeps = {}): MasterKeyProvider {
+    const available = deps.available ?? (() => !isTestProcess() && isGenesisAppRpcAvailable());
+    const options = { timeoutMs: VAULT_UNLOCK_TIMEOUT_MS, isResult: isReply };
+    const params = (request: VaultUnlockRequest): Record<string, unknown> => ({ ...request });
+    const rpc =
+        deps.rpc ??
+        ((request: VaultUnlockRequest) => genesisAppRpc<VaultUnlockReply>("vault.unlock", params(request), options));
+    const rpcSync =
+        deps.rpcSync ??
+        ((request: VaultUnlockRequest) =>
+            genesisAppRpcSync<VaultUnlockReply>("vault.unlock", params(request), options));
+
+    return {
+        id: "app",
+        async available() {
+            return available();
+        },
+        async get() {
+            if (!available()) {
+                return undefined;
+            }
+
+            const request = vaultUnlockRequest();
+            return keyFromReply(await rpc(request), request.tool);
+        },
+        getSync() {
+            if (!available()) {
+                return undefined;
+            }
+
+            const request = vaultUnlockRequest();
+            return keyFromReply(rpcSync(request), request.tool);
+        },
+        async set() {
+            throw new Error("GenesisTools.app only reads the vault key; a new key is stored by the keychain rung");
+        },
+    };
+}
+
+export const appGateKey: MasterKeyProvider = createAppGateKeyProvider();
diff --git a/src/utils/security/keyring/types.ts b/src/utils/security/keyring/types.ts
index 204cc3c651..3045f9dead 100644
--- a/src/utils/security/keyring/types.ts
+++ b/src/utils/security/keyring/types.ts
@@ -1,6 +1,6 @@
 import { isTestProcess } from "@genesiscz/utils/test-process";
 
-export type MasterKeySource = "keychain" | "env" | "file";
+export type MasterKeySource = "keychain" | "env" | "file" | "app";
 
 export interface MasterKeyProvider {
     readonly id: MasterKeySource;
diff --git a/src/utils/security/vault-purpose.ts b/src/utils/security/vault-purpose.ts
new file mode 100644
index 0000000000..585deef703
--- /dev/null
+++ b/src/utils/security/vault-purpose.ts
@@ -0,0 +1,69 @@
+import { basename } from "node:path";
+
+/**
+ * Why this process reads the vault, for the approval window GenesisTools.app shows before it hands the master key to a
+ * tool. Martin, 2026-10-15: "enough context so i know exactly what / who / which session / triggered that and why
+ * (each caller should give that context possibly)". WHO and WHICH SESSION the app reads from the kernel; WHY and WHAT
+ * only the caller knows, so they live here.
+ */
+let purpose: string | undefined;
+let firstSecret: string | undefined;
+
+/** One sentence a person can judge: "refresh the usage figures of 11 accounts for the statusline". */
+export function setVaultPurpose(text: string | undefined): void {
+    purpose = text?.trim() || undefined;
+}
+
+/** The purpose for the duration of `fn`, then the one before it again. */
+export async function withVaultPurpose<T>(text: string, fn: () => Promise<T>): Promise<T> {
+    const previous = purpose;
+    purpose = text.trim() || previous;
+
+    try {
+        return await fn();
+    } finally {
+        purpose = previous;
+    }
+}
+
+export function vaultPurpose(): string | undefined {
+    return purpose;
+}
+
+/** The first secret this process read: what it was after when it needed the master key. */
+export function noteVaultSecret(path: string): void {
+    firstSecret ??= path;
+}
+
+export function vaultSecretAsked(): string | undefined {
+    return firstSecret;
+}
+
+/** Test seam. */
+export function _resetVaultContextForTest(): void {
+    purpose = undefined;
+    firstSecret = undefined;
+}
+
+/** The tool this process runs: `src/<tool>/index.ts` from the script path, else the `gt-<tool>` launcher name. */
+export function currentToolName(argv: string[] = process.argv): string {
+    const script = argv[1] ?? "";
+    const fromScript = script.match(/[/\\]src[/\\]([^/\\]+)[/\\]index\.tsx?$/)?.[1];
+
+    if (fromScript) {
+        return fromScript;
+    }
+
+    const launcher = basename(argv[0] ?? "");
+    return launcher.startsWith("gt-") ? launcher.slice(3) : launcher || "unknown";
+}
+
+/** `tools <tool> <args>`, cut to a length a window can show. Tokens never travel in argv (they go through stdin). */
+export function currentCommandLine(argv: string[] = process.argv, max = 300): string {
+    const words = ["tools", currentToolName(argv), ...argv.slice(2)].map((word) =>
+        word.includes(" ") ? `"${word}"` : word
+    );
+    const line = words.join(" ");
+
+    return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+}

From 1da3a69bb2fff65b2e6dfb5fbb55ee41d986b4fa Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 00:43:56 +0200
Subject: [PATCH 14/32] fix(ai, macos): the vault and account approval windows
 are one SwiftUI panel that leads with why and folds the details, time out for
 real, remember a program by its script and ask the keychain password once,
 because the first window was a wall of text, kept reopening and asked for the
 password twice on every allow

(cherry picked from commit d5b318467e522e585599c1d32a8b1ef656240fa8)
---
 .../Permissions/ApprovalDialog.swift          | 297 +++++++++++
 src/macos/GenesisTools/Sources/Gate.swift     | 200 ++++----
 .../GenesisTools/Sources/VaultUnlock.swift    | 469 +++++++++++++-----
 .../GenesisTools/Tests/VaultUnlockTests.swift | 157 ++++--
 src/utils/security/keyring/app-gate.test.ts   |  28 ++
 src/utils/security/keyring/app-gate.ts        |  32 +-
 src/utils/security/vault-purpose.ts           |  19 +-
 7 files changed, 938 insertions(+), 264 deletions(-)
 create mode 100644 src/macos/GenesisKit/Sources/GenesisKit/Permissions/ApprovalDialog.swift

diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Permissions/ApprovalDialog.swift b/src/macos/GenesisKit/Sources/GenesisKit/Permissions/ApprovalDialog.swift
new file mode 100644
index 0000000000..7857aa43d7
--- /dev/null
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Permissions/ApprovalDialog.swift
@@ -0,0 +1,297 @@
+import AppKit
+import SwiftUI
+
+/// One line of an approval request: a short label and its value. `help` holds the full text when the value is cut.
+public struct ApprovalFact: Identifiable, Equatable {
+    public let label: String
+    public let value: String
+    public let help: String?
+    public let monospaced: Bool
+
+    public var id: String { label }
+
+    public init(_ label: String, _ value: String, help: String? = nil, monospaced: Bool = false) {
+        self.label = label
+        self.value = value
+        self.help = help
+        self.monospaced = monospaced
+    }
+}
+
+/// How long an allow is remembered; `seconds` 0 is "just this once", nil is "always" (until revoked).
+public struct ApprovalRemember: Identifiable, Hashable {
+    public let seconds: Int?
+    public let title: String
+
+    public var id: String { title }
+
+    public init(seconds: Int?, title: String) {
+        self.seconds = seconds
+        self.title = title
+    }
+}
+
+/// A request only the user may allow (a secret handed to another program): why first, then who, then the details
+/// behind a disclosure. The answer arrives once, through `onAllow` or `onDeny`.
+@MainActor
+public final class ApprovalDialogModel: ObservableObject {
+    public let title: String
+    public let purpose: String
+    public let symbol: String
+    public let facts: [ApprovalFact]
+    public let details: [ApprovalFact]
+    public let warning: String?
+    public let footnote: String
+    public let rememberChoices: [ApprovalRemember]
+    public let rememberNote: String?
+    public let allowTitle: String
+    public let deadline: Date?
+    public let identifier: String
+
+    @Published public var rememberIndex = 0
+    @Published public var showsDetails = false
+    @Published public private(set) var answered = false
+
+    public var onAllow: @MainActor (ApprovalRemember?) -> Void = { _ in }
+    public var onDeny: @MainActor () -> Void = {}
+
+    public init(title: String, purpose: String, symbol: String, facts: [ApprovalFact], details: [ApprovalFact],
+                warning: String?, footnote: String, rememberChoices: [ApprovalRemember], rememberNote: String?,
+                allowTitle: String, deadline: Date?, identifier: String) {
+        self.title = title
+        self.purpose = purpose
+        self.symbol = symbol
+        self.facts = facts
+        self.details = details
+        self.warning = warning
+        self.footnote = footnote
+        self.rememberChoices = rememberChoices
+        self.rememberNote = rememberNote
+        self.allowTitle = allowTitle
+        self.deadline = deadline
+        self.identifier = identifier
+    }
+
+    public func allow() {
+        guard !answered else { return }
+        answered = true
+        onAllow(rememberChoices.indices.contains(rememberIndex) ? rememberChoices[rememberIndex] : nil)
+    }
+
+    public func deny() {
+        guard !answered else { return }
+        answered = true
+        onDeny()
+    }
+}
+
+/// Laid out like a macOS alert: the app icon with the request's symbol, a short title, the reason as the first line a
+/// reader sees, a column of facts, the rest folded, and the buttons on the trailing edge with the default last.
+public struct ApprovalDialogView: View {
+    @ObservedObject var model: ApprovalDialogModel
+
+    public init(model: ApprovalDialogModel) {
+        self.model = model
+    }
+
+    public var body: some View {
+        VStack(alignment: .leading, spacing: 14) {
+            HStack(alignment: .top, spacing: 14) {
+                icon
+                VStack(alignment: .leading, spacing: 4) {
+                    Text(model.title)
+                        .font(.system(size: 13, weight: .semibold))
+                        .accessibilityAddTraits(.isHeader)
+                    Text(model.purpose)
+                        .font(.system(size: 12))
+                        .fixedSize(horizontal: false, vertical: true)
+                        .textSelection(.enabled)
+                }
+                .frame(maxWidth: .infinity, alignment: .leading)
+            }
+
+            facts(model.facts)
+                .padding(.leading, 66)
+
+            GenDisclosure(isExpanded: $model.showsDetails, minHeight: 22, identifier: "\(model.identifier)-details") {
+                facts(model.details)
+                    .padding(.leading, 18)
+                    .padding(.top, 2)
+            } label: {
+                Text("Details")
+                    .font(.system(size: 12))
+                    .foregroundStyle(.secondary)
+            }
+            .padding(.leading, 66)
+
+            if let warning = model.warning {
+                Label(warning, systemImage: "exclamationmark.triangle.fill")
+                    .font(.system(size: 11))
+                    .foregroundStyle(.orange)
+                    .fixedSize(horizontal: false, vertical: true)
+                    .padding(.leading, 66)
+                    .accessibilityIdentifier("\(model.identifier)-warning")
+            }
+
+            Text(model.footnote)
+                .font(.system(size: 11))
+                .foregroundStyle(.secondary)
+                .fixedSize(horizontal: false, vertical: true)
+                .padding(.leading, 66)
+
+            buttons
+        }
+        .padding(20)
+        .frame(width: 480)
+        .accessibilityElement(children: .contain)
+        .accessibilityIdentifier(model.identifier)
+    }
+
+    private var icon: some View {
+        ZStack(alignment: .bottomTrailing) {
+            Image(nsImage: NSApp?.applicationIconImage ?? NSImage())
+                .resizable()
+                .frame(width: 52, height: 52)
+            Image(systemName: model.symbol)
+                .font(.system(size: 11, weight: .semibold))
+                .foregroundStyle(.white)
+                .frame(width: 22, height: 22)
+                .background(Circle().fill(Color.orange))
+                .overlay(Circle().stroke(Color(nsColor: .windowBackgroundColor), lineWidth: 2))
+                .offset(x: 4, y: 4)
+        }
+        .frame(width: 56, height: 56, alignment: .topLeading)
+        .accessibilityHidden(true)
+    }
+
+    private func facts(_ rows: [ApprovalFact]) -> some View {
+        Grid(alignment: .leadingFirstTextBaseline, horizontalSpacing: 10, verticalSpacing: 5) {
+            ForEach(rows) { fact in
+                GridRow {
+                    Text(fact.label)
+                        .font(.system(size: 11))
+                        .foregroundStyle(.secondary)
+                        .gridColumnAlignment(.trailing)
+                    Text(verbatim: fact.value)
+                        .font(fact.monospaced ? .system(size: 11, design: .monospaced) : .system(size: 12))
+                        .lineLimit(3)
+                        .truncationMode(.middle)
+                        .textSelection(.enabled)
+                        .help(fact.help ?? fact.value)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+                }
+            }
+        }
+    }
+
+    private var buttons: some View {
+        HStack(spacing: 8) {
+            Button("Deny", action: model.deny)
+                .keyboardShortcut(.cancelAction)
+                .accessibilityIdentifier("\(model.identifier)-deny")
+            if let deadline = model.deadline {
+                (Text("Denies itself in ") + Text(timerInterval: Date()...max(Date(), deadline), countsDown: true))
+                    .font(.system(size: 11).monospacedDigit())
+                    .foregroundStyle(.tertiary)
+            }
+            Spacer(minLength: 8)
+            if model.rememberChoices.count > 1 {
+                Picker("Remember", selection: $model.rememberIndex) {
+                    ForEach(model.rememberChoices.indices, id: \.self) { index in
+                        Text(model.rememberChoices[index].title).tag(index)
+                    }
+                }
+                .labelsHidden()
+                .pickerStyle(.menu)
+                .fixedSize()
+                .accessibilityIdentifier("\(model.identifier)-remember")
+            } else if let note = model.rememberNote {
+                Text(note)
+                    .font(.system(size: 11))
+                    .foregroundStyle(.secondary)
+                    .lineLimit(2)
+                    .frame(maxWidth: 170, alignment: .trailing)
+                    .multilineTextAlignment(.trailing)
+            }
+            Button(model.allowTitle, action: model.allow)
+                .keyboardShortcut(.defaultAction)
+                .buttonStyle(.borderedProminent)
+                .accessibilityIdentifier("\(model.identifier)-allow")
+        }
+        .controlSize(.regular)
+        .disabled(model.answered)
+        // The panel is non-activating, so its app is never active while it shows; AppKit then greys the prominent
+        // button and the main action looks like the others (the permission dialog's live check, 2026-10-10).
+        .environment(\.controlActiveState, .key)
+    }
+}
+
+/// One floating panel for one request. It never runs a modal session (a modal loop on the main queue stops every
+/// timer queued there, so a deadline never fired), never activates its app, and takes the keyboard only after the
+/// user clicks into it: a request that pops up while someone types must not catch a stray Return.
+@MainActor
+public final class ApprovalPanelPresenter: NSObject, NSWindowDelegate {
+    private var panel: NSPanel?
+    private var model: ApprovalDialogModel?
+
+    public override init() {}
+
+    public func present(_ model: ApprovalDialogModel) {
+        if NSApp == nil { _ = NSApplication.shared }
+        let controller = NSHostingController(rootView: ApprovalDialogView(model: model).titlebarZone())
+        // The panel follows the view's size, so opening Details grows it and closing shrinks it back.
+        controller.sizingOptions = [.preferredContentSize]
+        let size = controller.view.fittingSize
+        let panel = ApprovalPanel(
+            contentRect: CGRect(origin: .zero, size: size),
+            styleMask: [.titled, .closable, .fullSizeContentView, .nonactivatingPanel],
+            backing: .buffered, defer: false)
+        panel.titleVisibility = .hidden
+        panel.titlebarAppearsTransparent = true
+        for button in [NSWindow.ButtonType.closeButton, .miniaturizeButton, .zoomButton] {
+            panel.standardWindowButton(button)?.isHidden = true
+        }
+        panel.title = model.title
+        panel.hidesOnDeactivate = false
+        panel.isReleasedWhenClosed = false
+        panel.isFloatingPanel = true
+        // After isFloatingPanel, whose setter resets the level: above the widget's panels, as the permission dialog.
+        panel.level = NSWindow.Level(rawValue: NSWindow.Level.statusBar.rawValue + 1)
+        panel.collectionBehavior = [.moveToActiveSpace, .fullScreenAuxiliary]
+        panel.animationBehavior = .alertPanel
+        panel.contentViewController = controller
+        panel.delegate = self
+        panel.setAccessibilityIdentifier(model.identifier)
+        panel.setFrameOrigin(Self.origin(for: size))
+        self.panel = panel
+        self.model = model
+        panel.orderFrontRegardless()
+    }
+
+    public func close() {
+        panel?.delegate = nil
+        panel?.orderOut(nil)
+        panel = nil
+    }
+
+    /// ⌘W answers the way Deny does.
+    public func windowShouldClose(_ sender: NSWindow) -> Bool {
+        model?.deny()
+        return false
+    }
+
+    /// Horizontally centred in the upper fifth of the screen under the pointer, where macOS puts an alert.
+    private static func origin(for size: CGSize) -> CGPoint {
+        let mouse = NSEvent.mouseLocation
+        let screen = NSScreen.screens.first { NSMouseInRect(mouse, $0.frame, false) } ?? NSScreen.main
+        let visible = screen?.visibleFrame ?? CGRect(x: 0, y: 0, width: 1440, height: 900)
+        let top = visible.maxY - visible.height * 0.2
+        return CGPoint(x: (visible.midX - size.width / 2).rounded(), y: (top - size.height).rounded())
+    }
+}
+
+/// A titled panel that can take the keyboard without activating its app.
+private final class ApprovalPanel: NSPanel {
+    override var canBecomeKey: Bool { true }
+    override var canBecomeMain: Bool { false }
+}
diff --git a/src/macos/GenesisTools/Sources/Gate.swift b/src/macos/GenesisTools/Sources/Gate.swift
index be5acc383b..4d86ad21ca 100644
--- a/src/macos/GenesisTools/Sources/Gate.swift
+++ b/src/macos/GenesisTools/Sources/Gate.swift
@@ -68,72 +68,6 @@ private func describeToken(_ kind: String?, provider: String) -> String {
 /// a little earlier and says why.
 private let gateDeadlineSeconds: Double = 170
 
-private func rememberLabel(_ seconds: Int) -> String {
-    if seconds <= 0 {
-        return "Allow once"
-    }
-
-    if seconds % 86_400 == 0 {
-        let days = seconds / 86_400
-        return "Allow for \(days) day\(days == 1 ? "" : "s")"
-    }
-
-    if seconds % 3_600 == 0 {
-        let hours = seconds / 3_600
-        return "Allow for \(hours) hour\(hours == 1 ? "" : "s")"
-    }
-
-    return "Allow for \(seconds / 60) min"
-}
-
-private func describeClient(_ client: GateClientInfo) -> String {
-    var lines: [String] = []
-
-    if let pid = client.pid {
-        lines.append("Process: pid \(pid)")
-    } else {
-        lines.append("Process: not identified (no pid)")
-    }
-
-    if let executable = client.executable, !executable.isEmpty {
-        lines.append("Executable: \(executable)")
-    } else if client.pid != nil {
-        lines.append("Executable: not running under that pid")
-    }
-
-    if let script = client.script, !script.isEmpty {
-        lines.append("Script: \(script)")
-    }
-
-    if let command = client.command, !command.isEmpty, command != client.executable {
-        lines.append("Command: \(command)")
-    }
-
-    if let cwd = client.cwd, !cwd.isEmpty {
-        lines.append("Working dir: \(cwd)")
-    }
-
-    if let ancestors = client.ancestors, !ancestors.isEmpty {
-        let chain = ancestors.map { "\($0.command) (\($0.pid))" }.joined(separator: " ← ")
-        lines.append("Started by: \(chain)")
-    }
-
-    if let injected = client.injected, !injected.isEmpty {
-        lines.append("⚠️ Extra code may be loaded: \(injected.joined(separator: ", "))")
-    }
-
-    // A running pid that did not start the request is refused before this window opens, so an
-    // unverified client here is either a real ancestor whose identity is incomplete, or no pid.
-    if client.verified != true {
-        let why = client.isAncestor == true
-            ? "its binary or script could not be established"
-            : "no running pid was given"
-        lines.append("⚠️ Unverified: \(why). Allow once at most; it will not be remembered.")
-    }
-
-    return lines.joined(separator: "\n")
-}
-
 private func gateEmit(decision: String, rememberSeconds: Int, method: String, reason: String) -> Never {
     logClick("gate.approve decision=\(decision) remember=\(rememberSeconds) method=\(method) reason=\(reason)")
     emitResult([
@@ -187,51 +121,119 @@ func authenticate(reason: String, completion: @escaping (_ method: String?, _ fa
     }
 }
 
-func approveGate(_ params: GateApproveParams) {
-    let choices = (params.rememberChoicesSeconds?.isEmpty == false ? params.rememberChoicesSeconds : nil) ?? [0, 8 * 3_600, 7 * 86_400]
-    let accountLabel = params.account.label.map { "\(params.account.name) (\($0))" } ?? params.account.name
+/// What the gate window shows, built from the CLI's request. Pure, so tests read it.
+struct GateWindowContent {
+    var title: String
+    var purpose: String
+    var facts: [ApprovalFact]
+    var details: [ApprovalFact]
+    var warning: String?
+    var rememberChoices: [ApprovalRemember]
+
+    static func rememberTitle(_ seconds: Int) -> String {
+        if seconds <= 0 { return "Just this once" }
+        if seconds % 86_400 == 0 { return "For \(Plural.count(seconds / 86_400, "day"))" }
+        if seconds % 3_600 == 0 { return "For \(Plural.count(seconds / 3_600, "hour"))" }
+        return "For \(seconds / 60) min"
+    }
+
+    static func build(_ params: GateApproveParams, home: String = NSHomeDirectory()) -> GateWindowContent {
+        let client = params.client
+        let accountLabel = params.account.label.map { "\(params.account.name) (\($0))" } ?? params.account.name
+        let choices = (params.rememberChoicesSeconds?.isEmpty == false ? params.rememberChoicesSeconds : nil) ?? [0, 8 * 3_600, 7 * 86_400]
+        let program = client.script ?? client.executable
+
+        var facts = [ApprovalFact("Account", "\(accountLabel) · \(params.provider)")]
+        facts.append(ApprovalFact("Program", program.map { "\(client.name) · \(VaultWindowContent.shortPath($0, home: home))" } ?? client.name,
+                                  help: [client.executable, client.script].compactMap { $0 }.joined(separator: " ")))
+        if let cwd = client.cwd, !cwd.isEmpty {
+            facts.append(ApprovalFact("Folder", VaultWindowContent.shortPath(cwd, home: home), help: cwd))
+        }
 
-    DispatchQueue.main.asyncAfter(deadline: .now() + gateDeadlineSeconds) {
-        gateEmit(decision: "deny", rememberSeconds: 0, method: "none", reason: "no answer within \(Int(gateDeadlineSeconds))s")
-    }
+        var details = [ApprovalFact("Process", client.pid.map { "pid \($0)" } ?? "not identified (no pid)")]
+        if let executable = client.executable, !executable.isEmpty {
+            details.append(ApprovalFact("Executable", executable, monospaced: true))
+        }
 
-    DispatchQueue.main.async {
-        NSApplication.shared.activate(ignoringOtherApps: true)
+        if let command = client.command, !command.isEmpty, command != client.executable {
+            details.append(ApprovalFact("Command", command, monospaced: true))
+        }
 
-        let isApiKey = params.tokenKind == "api-key"
-        let alert = NSAlert()
-        alert.alertStyle = .warning
-        alert.messageText = isApiKey
-            ? "“\(params.client.name)” asks for the API KEY of the \(params.provider) account \(accountLabel)"
-            : "“\(params.client.name)” asks for the \(params.provider) token of \(accountLabel)"
-        alert.informativeText = describeClient(params.client)
-            + "\n\n" + describeToken(params.tokenKind, provider: params.provider) + " Touch ID confirms an allow."
-
-        for seconds in choices {
-            alert.addButton(withTitle: rememberLabel(seconds))
+        if let ancestors = client.ancestors, !ancestors.isEmpty {
+            details.append(ApprovalFact("Started by", ancestors.map { "\($0.command) (\($0.pid))" }.joined(separator: " ← ")))
+        }
+
+        var warnings: [String] = []
+        if let injected = client.injected, !injected.isEmpty {
+            warnings.append("Extra code may be loaded (\(injected.joined(separator: ", "))).")
+        }
+
+        // A running pid that did not start the request is refused before this window opens, so an unverified client
+        // here is either a real ancestor whose identity is incomplete, or no pid.
+        if client.verified != true {
+            warnings.append(client.isAncestor == true
+                ? "Unverified: its binary or script could not be established. It will not be remembered."
+                : "Unverified: no running pid was given. It will not be remembered.")
         }
 
-        let deny = alert.addButton(withTitle: "Deny")
-        deny.keyEquivalent = "\u{1b}"
+        let isApiKey = params.tokenKind == "api-key"
+        return GateWindowContent(
+            title: isApiKey
+                ? "“\(client.name)” wants the \(params.provider) API key of \(params.account.name)"
+                : "“\(client.name)” wants the \(params.provider) token of \(params.account.name)",
+            purpose: describeToken(params.tokenKind, provider: params.provider),
+            facts: facts,
+            details: details,
+            warning: warnings.isEmpty ? nil : warnings.joined(separator: " "),
+            rememberChoices: choices.map { ApprovalRemember(seconds: $0, title: rememberTitle($0)) })
+    }
+}
+
+@MainActor private let gatePresenter = ApprovalPanelPresenter()
+
+func approveGate(_ params: GateApproveParams) {
+    let content = GateWindowContent.build(params)
+    let biometric = LAContext().canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil)
 
-        let response = alert.runModal()
-        let index = response.rawValue - NSApplication.ModalResponse.alertFirstButtonReturn.rawValue
+    DispatchQueue.main.async {
+        let model = ApprovalDialogModel(
+            title: content.title, purpose: content.purpose, symbol: "person.badge.key.fill", facts: content.facts,
+            details: content.details, warning: content.warning,
+            footnote: "Every decision is written to the gate audit log (tools ai gate audit).",
+            rememberChoices: content.rememberChoices.count > 1 ? content.rememberChoices : [],
+            rememberNote: content.rememberChoices.count > 1 ? nil : "Only once",
+            allowTitle: biometric ? "Allow with Touch ID" : "Allow…",
+            deadline: Date().addingTimeInterval(gateDeadlineSeconds), identifier: "gate-approve")
+
+        // The NSAlert this replaces ran a modal loop on the main queue, so this timer never fired there.
+        let deadline = DispatchWorkItem {
+            gateEmit(decision: "deny", rememberSeconds: 0, method: "none", reason: "no answer within \(Int(gateDeadlineSeconds))s")
+        }
+        DispatchQueue.main.asyncAfter(deadline: .now() + gateDeadlineSeconds, execute: deadline)
 
-        guard index >= 0, index < choices.count else {
+        model.onDeny = {
+            deadline.cancel()
+            gatePresenter.close()
             gateEmit(decision: "deny", rememberSeconds: 0, method: "none", reason: "denied in the approval window")
         }
 
-        let remember = choices[index]
-        let reason = isApiKey
-            ? "give “\(params.client.name)” the API key of the \(params.provider) account \(params.account.name)"
-            : "allow “\(params.client.name)” to use the \(params.provider) account \(params.account.name)"
+        model.onAllow = { choice in
+            deadline.cancel()
+            gatePresenter.close()
+            let remember = choice?.seconds ?? 0
+            let reason = params.tokenKind == "api-key"
+                ? "give “\(params.client.name)” the API key of the \(params.provider) account \(params.account.name)"
+                : "allow “\(params.client.name)” to use the \(params.provider) account \(params.account.name)"
+
+            authenticate(reason: reason) { method, failure in
+                guard let method else {
+                    gateEmit(decision: "deny", rememberSeconds: 0, method: "none", reason: failure)
+                }
 
-        authenticate(reason: reason) { method, failure in
-            guard let method else {
-                gateEmit(decision: "deny", rememberSeconds: 0, method: "none", reason: failure)
+                gateEmit(decision: "allow", rememberSeconds: remember, method: method, reason: "")
             }
-
-            gateEmit(decision: "allow", rememberSeconds: remember, method: method, reason: "")
         }
+
+        gatePresenter.present(model)
     }
 }
diff --git a/src/macos/GenesisTools/Sources/VaultUnlock.swift b/src/macos/GenesisTools/Sources/VaultUnlock.swift
index c2c447f03e..fcde0c49d6 100644
--- a/src/macos/GenesisTools/Sources/VaultUnlock.swift
+++ b/src/macos/GenesisTools/Sources/VaultUnlock.swift
@@ -4,17 +4,23 @@
 //
 // A `gt-<tool>` process needs the GenesisTools vault master key. Before this, each tool's own bun link read the
 // keychain item and macOS asked "gt-claude wants to use your confidential information" with nothing to judge. Now the
-// tool starts this process and the app reads the item as itself (macOS asks once, naming GenesisTools).
+// tool starts this process, and the app hands the key on after its own window.
 //
 // WHO comes from the kernel, never from the request: this process is the caller's child, so `getppid()` is the caller,
-// and its executable, arguments, environment (the session ids), working folder and parent chain are read from there.
-// WHY and WHAT come from the request, because only the caller knows them. A remembered approval for the same tool,
+// and its executable, script, arguments, environment (the session ids), working folder and parent chain are read from
+// there. WHY and WHAT come from the request, because only the caller knows them. A remembered approval for the same
 // executable and script skips the window; otherwise Touch ID confirms an allow. Every outcome goes to the gate's audit
 // log. A deny, a cancel, a failed authentication and a timeout all reply "deny" with a reason.
+//
+// Second version, after Martin's first look (2026-10-15 00:28, "this can be probably nicer", and "it wanted touchid
+// and when i gave it it wanted password 2 times always"): a SwiftUI panel instead of an NSAlert (whose modal loop
+// also kept the 170 s deadline from ever firing), `bun run <script>` read as the script it runs, and the app's own
+// copy of the key, so the login-keychain password is asked once per key rather than on every allow.
 
 import AppKit
 import Darwin
 import Foundation
+import LocalAuthentication
 import Security
 
 struct VaultUnlockParams: Decodable {
@@ -44,12 +50,40 @@ struct VaultCaller {
     var cwd: String?
     var ancestors: [(pid: pid_t, command: String)]
 
-    /// The script an interpreter runs (`bun …/src/claude/index.ts`), part of the identity a grant is remembered for.
-    var script: String? {
+    private static let scriptExtensions = [".ts", ".tsx", ".js", ".mjs", ".cjs"]
+
+    /// Where the script sits in the arguments: after the interpreter's flags and the `run` of `bun run <script>`.
+    private var scriptIndex: Int? {
         guard let arguments = args?.arguments, arguments.count > 1 else { return nil }
-        let candidate = arguments.dropFirst().first { !$0.hasPrefix("-") }
-        guard let candidate, [".ts", ".tsx", ".js", ".mjs", ".cjs"].contains(where: candidate.hasSuffix) else { return nil }
-        return candidate
+        var index = 1
+        while index < arguments.count, arguments[index].hasPrefix("-") || arguments[index] == "run" {
+            index += 1
+        }
+
+        guard index < arguments.count, Self.scriptExtensions.contains(where: arguments[index].hasSuffix) else { return nil }
+        return index
+    }
+
+    /// The script an interpreter runs (`bun run …/src/ai/commands/usage/poll-daemon.ts`): with the executable, the
+    /// identity a remembered approval is for.
+    var script: String? {
+        scriptIndex.flatMap { args?.arguments[$0] }
+    }
+
+    /// bun, node, deno, or a `gt-<tool>` link of bun: the program is the script, not the executable.
+    var isInterpreter: Bool {
+        let name = executable.map { ($0 as NSString).lastPathComponent } ?? ""
+        return ["bun", "node", "deno"].contains(name) || name.hasPrefix("gt-")
+    }
+
+    /// The tool as GenesisTools names it, from the kernel's view: `src/<tool>/` in the script, else the `gt-<tool>` link.
+    var toolName: String? {
+        if let script, let range = script.range(of: #"/src/([^/]+)/"#, options: .regularExpression) {
+            return String(script[range].dropFirst(5).dropLast())
+        }
+
+        let name = executable.map { ($0 as NSString).lastPathComponent } ?? ""
+        return name.hasPrefix("gt-") ? String(name.dropFirst(3)) : nil
     }
 
     /// Flags and environment that load code the script path does not name. Any of them: no remembered approval.
@@ -66,13 +100,22 @@ struct VaultCaller {
             }
         }
 
-        let flags = (args?.arguments.dropFirst() ?? []).prefix { $0.hasPrefix("-") }
+        let arguments = args?.arguments ?? []
+        let end = scriptIndex ?? arguments.count
+        let flags = arguments.count > 1 ? arguments[1..<max(1, end)].filter { $0.hasPrefix("-") } : []
         if flags.contains(where: { ["--preload", "-r", "--require", "--import", "--loader"].contains($0) }) {
             found.append("interpreter flags \(flags.joined(separator: " "))")
         }
 
         return found
     }
+
+    /// Why this request can only be allowed once, or nil when an allow may be remembered.
+    var onceOnlyReason: String? {
+        if !injected.isEmpty { return "extra code may be loaded" }
+        if isInterpreter, script == nil { return "the script it runs is not known" }
+        return nil
+    }
 }
 
 enum VaultProcess {
@@ -164,25 +207,77 @@ enum VaultProcess {
     }
 }
 
-/// The session the caller belongs to, from its own environment and its parent chain.
+/// The agent session the caller belongs to, from its own environment, its parent chain and the session's transcript.
+struct VaultSessionInfo: Equatable {
+    var sessionId: String?
+    var title: String?
+    var agent: String?
+    var cmuxTab: String?
+
+    /// "genesis-tools-native (Claude Code)", "Claude Code session 1b4001ba", "codex exec (pid 80)", or nil.
+    var summary: String? {
+        if let sessionId {
+            return title.map { "\($0) (Claude Code)" } ?? "Claude Code session \(sessionId.prefix(8))"
+        }
+
+        return agent
+    }
+}
+
 enum VaultSession {
-    static func describe(_ caller: VaultCaller) -> String? {
-        var parts: [String] = []
+    static func info(_ caller: VaultCaller, claudeHome: String) -> VaultSessionInfo {
+        var info = VaultSessionInfo()
         if let id = caller.args?.environmentValue("CLAUDE_CODE_SESSION_ID"), !id.isEmpty {
-            parts.append("Claude Code session \(id)")
+            info.sessionId = id
+            info.title = claudeTitle(sessionId: id, claudeHome: caller.args?.environmentValue("CLAUDE_CONFIG_DIR") ?? claudeHome)
         } else if let agent = caller.ancestors.first(where: { ["claude", "codex", "grok"].contains($0.command.split(separator: " ").first.map(String.init) ?? "") }) {
-            parts.append("\(agent.command) (pid \(agent.pid))")
+            info.agent = "\(agent.command) (pid \(agent.pid))"
         }
 
         if let tab = caller.args?.environmentValue("CMUX_SURFACE_ID"), !tab.isEmpty {
-            parts.append("cmux tab \(tab)")
+            info.cmuxTab = tab
+        }
+
+        return info
+    }
+
+    /// The session's name as Claude Code shows it, from the last 512 KB of its transcript (the title rows repeat).
+    static func claudeTitle(sessionId: String, claudeHome: String) -> String? {
+        let projects = (claudeHome as NSString).appendingPathComponent("projects")
+        guard sessionId.range(of: #"^[A-Za-z0-9-]+$"#, options: .regularExpression) != nil,
+              let folders = try? FileManager.default.contentsOfDirectory(atPath: projects) else { return nil }
+
+        for folder in folders {
+            let path = (projects as NSString).appendingPathComponent("\(folder)/\(sessionId).jsonl")
+            guard let handle = FileHandle(forReadingAtPath: path) else { continue }
+            defer { try? handle.close() }
+            let size = (try? handle.seekToEnd()) ?? 0
+            try? handle.seek(toOffset: size > 524_288 ? size - 524_288 : 0)
+            guard let data = try? handle.readToEnd() else { return nil }
+            return title(fromTranscriptTail: String(decoding: data, as: UTF8.self))
         }
 
-        return parts.isEmpty ? nil : parts.joined(separator: ", ")
+        return nil
+    }
+
+    /// A name the user gave (`/rename`) beats the agent name, which beats the generated title; the last of each wins.
+    static func title(fromTranscriptTail text: String) -> String? {
+        for field in ["customTitle", "agentName", "aiTitle"] {
+            let pattern = "\"\(field)\":\"((?:[^\"\\\\]|\\\\.)*)\""
+            guard let regex = try? NSRegularExpression(pattern: pattern) else { continue }
+            let range = NSRange(text.startIndex..., in: text)
+            guard let match = regex.matches(in: text, range: range).last,
+                  let raw = Range(match.range(at: 1), in: text),
+                  let value = try? JSONDecoder().decode(String.self, from: Data("\"\(text[raw])\"".utf8)),
+                  !value.trimmingCharacters(in: .whitespaces).isEmpty else { continue }
+            return value
+        }
+
+        return nil
     }
 }
 
-/// One remembered approval: this tool, this executable, this script.
+/// One remembered approval: this executable, this script. `tool` is for display and `revoke <tool>` only.
 struct VaultGrant: Codable, Equatable {
     var key: String
     var tool: String
@@ -196,6 +291,14 @@ struct VaultGrant: Codable, Equatable {
     func isLive(at now: Int64) -> Bool {
         until.map { $0 > now } ?? true
     }
+
+    /// A grant without a script, for an interpreter, would cover every program it runs; the first version stored such
+    /// grants for `bun run <script>` callers. They match nothing and go on the next write.
+    var isTooBroad: Bool {
+        guard script == nil else { return false }
+        let name = (executable as NSString).lastPathComponent
+        return ["bun", "node", "deno"].contains(name) || name.hasPrefix("gt-")
+    }
 }
 
 struct VaultGrantsFile: Codable {
@@ -225,14 +328,16 @@ enum VaultGrants {
         return file
     }
 
-    static func live(_ key: String, now: Int64, in file: VaultGrantsFile) -> VaultGrant? {
-        file.grants.last { $0.key == key && $0.isLive(at: now) }
+    static func live(executable: String, script: String?, now: Int64, in file: VaultGrantsFile) -> VaultGrant? {
+        file.grants.last { $0.executable == executable && $0.script == script && !$0.isTooBroad && $0.isLive(at: now) }
     }
 
-    /// Replaces any grant for the same key and drops expired ones.
+    /// Replaces any grant for the same program and drops expired and too-broad ones.
     static func remember(_ grant: VaultGrant, now: Int64, in file: VaultGrantsFile) -> VaultGrantsFile {
         var next = file
-        next.grants = file.grants.filter { $0.key != grant.key && $0.isLive(at: now) } + [grant]
+        next.grants = file.grants.filter {
+            !($0.executable == grant.executable && $0.script == grant.script) && !$0.isTooBroad && $0.isLive(at: now)
+        } + [grant]
         return next
     }
 
@@ -247,8 +352,8 @@ enum VaultGrants {
     }
 }
 
-/// One open window per tool: the usage daemon starts a process every minute, and without this each one would open its
-/// own window while the first waits for an answer. The lock lives as long as this process (one request, one window).
+/// One open window per program: the usage daemon starts a process every minute, and without this each one would open
+/// its own window while the first waits for an answer. The lock lives as long as this process (one request, one window).
 enum VaultWindowLock {
     static func path(for key: String) -> String {
         let hash = key.utf8.reduce(UInt64(14_695_981_039_346_656_037)) { ($0 ^ UInt64($1)) &* 1_099_511_628_211 }
@@ -269,70 +374,194 @@ enum VaultWindowLock {
     }
 }
 
-enum VaultWindow {
-    static func title(_ params: VaultUnlockParams) -> String {
-        "“\(params.tool)” asks for the GenesisTools vault key"
+/// What the window shows, built from the request, the kernel's caller and its session. Pure, so tests read it.
+struct VaultWindowContent {
+    var title: String
+    var purpose: String
+    var facts: [ApprovalFact]
+    var details: [ApprovalFact]
+    var warning: String?
+    var onceOnlyReason: String?
+
+    static let rememberChoices = [
+        ApprovalRemember(seconds: 0, title: "Just this once"),
+        ApprovalRemember(seconds: 8 * 3_600, title: "For 8 hours"),
+        ApprovalRemember(seconds: 7 * 86_400, title: "For 7 days"),
+        ApprovalRemember(seconds: nil, title: "Always for this program"),
+    ]
+
+    static let footnote = "The vault key unlocks every secret GenesisTools stores (AI account tokens and API keys), so an allowed program can read all of them."
+
+    static func shortPath(_ path: String, home: String = NSHomeDirectory()) -> String {
+        path == home ? "~" : path.hasPrefix(home + "/") ? "~" + path.dropFirst(home.count) : path
     }
 
-    static func body(_ params: VaultUnlockParams, caller: VaultCaller, session: String?) -> String {
-        var lines: [String] = ["Why: \(params.purpose)"]
-        if let secret = params.secret, !secret.isEmpty {
-            lines.append("It was reading: \(secret)")
-        }
+    /// `ai/acc_work/apiKey` reads as `acc_work › apiKey`.
+    static func secretLabel(_ secret: String) -> String {
+        let parts = secret.split(separator: "/").map(String.init)
+        return (parts.first == "ai" ? Array(parts.dropFirst()) : parts).joined(separator: " › ")
+    }
+
+    /// The caller's phrase as a sentence: capital first letter, a full stop at the end.
+    static func sentence(_ text: String) -> String {
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let first = trimmed.first else { return trimmed }
+        let capitalised = first.uppercased() + trimmed.dropFirst()
+        return [".", "!", "?", ")"].contains(where: capitalised.hasSuffix) ? capitalised : capitalised + "."
+    }
+
+    static func build(_ params: VaultUnlockParams, caller: VaultCaller, session: VaultSessionInfo,
+                      home: String = NSHomeDirectory()) -> VaultWindowContent {
+        let tool = caller.toolName ?? params.tool
+        var facts = [ApprovalFact("Session", session.summary ?? "None found (not started from an agent session)")]
 
-        lines.append("")
-        lines.append("Who (read from the system, not from the request):")
-        lines.append("Process: pid \(caller.pid)")
-        lines.append("Executable: \(caller.executable ?? "unknown")")
         if let script = caller.script {
-            lines.append("Script: \(script)")
+            facts.append(ApprovalFact("Program", "\(tool) · \(shortPath(script, home: home))",
+                                      help: "\(caller.executable ?? "unknown") \(script)"))
+        } else {
+            facts.append(ApprovalFact("Program", "\(tool) · \(shortPath(caller.executable ?? "unknown", home: home))",
+                                      help: caller.executable))
+        }
+
+        if let cwd = caller.cwd {
+            facts.append(ApprovalFact("Folder", shortPath(cwd, home: home), help: cwd))
+        }
+
+        if let secret = params.secret, !secret.isEmpty {
+            facts.append(ApprovalFact("Reading", secretLabel(secret), help: secret))
         }
 
+        var details = [ApprovalFact("Process", "pid \(caller.pid)"),
+                       ApprovalFact("Executable", caller.executable ?? "unknown", monospaced: true)]
         if let arguments = caller.args?.arguments, !arguments.isEmpty {
             let command = arguments.joined(separator: " ")
-            lines.append("Command: \(command.count > 300 ? String(command.prefix(299)) + "…" : command)")
+            details.append(ApprovalFact("Command", command.count > 400 ? String(command.prefix(399)) + "…" : command,
+                                        help: command, monospaced: true))
         }
 
-        if let cwd = caller.cwd {
-            lines.append("Working dir: \(cwd)")
+        if !caller.ancestors.isEmpty {
+            details.append(ApprovalFact("Started by", caller.ancestors.map { "\($0.command) (\($0.pid))" }.joined(separator: " ← ")))
         }
 
-        if !caller.ancestors.isEmpty {
-            lines.append("Started by: " + caller.ancestors.map { "\($0.command) (\($0.pid))" }.joined(separator: " ← "))
+        if let id = session.sessionId {
+            details.append(ApprovalFact("Session ID", id, monospaced: true))
         }
 
-        lines.append("Session: \(session ?? "none found (not started from an agent session)")")
-        if !caller.injected.isEmpty {
-            lines.append("⚠️ Extra code may be loaded: \(caller.injected.joined(separator: ", ")). Allow once at most.")
+        if let tab = session.cmuxTab {
+            details.append(ApprovalFact("cmux tab", tab, monospaced: true))
         }
 
-        lines.append("")
-        lines.append("The vault key decrypts every secret GenesisTools stores (AI account tokens and API keys): an allowed tool can read all of them. Touch ID confirms an allow.")
-        return lines.joined(separator: "\n")
+        let injected = caller.injected
+        return VaultWindowContent(
+            title: "“\(tool)” wants the vault key",
+            purpose: sentence(params.purpose),
+            facts: facts,
+            details: details,
+            warning: injected.isEmpty ? nil : "Extra code may be loaded (\(injected.joined(separator: ", "))). It can only be allowed once.",
+            onceOnlyReason: caller.onceOnlyReason)
     }
+}
 
-    static func choices(rememberable: Bool) -> [Int?] {
-        rememberable ? [0, 8 * 3_600, 7 * 86_400, nil] : [0]
+/// The app's own copy of the key. The bun keychain rung created the `genesis-tools` item, so macOS asks for the login
+/// password whenever another program (this app) reads it; Martin got that twice per allow. The app reads it once, keeps
+/// a copy in an item it creates itself (its creator reads it without a prompt), and stamps the copy with the source
+/// item's modification date, so a rotated key is read again. Reading attributes alone never prompts.
+enum VaultKeychain {
+    static let service = "genesis-tools"
+    static let copyService = "genesis-tools-app-copy"
+    static let account = "master-key"
+
+    enum Outcome: Equatable {
+        case key(String, fromCopy: Bool)
+        case missing
+        case failed(String)
+    }
+
+    /// The copy may answer only for the exact source it was taken from.
+    static func copyIsCurrent(copyStamp: String?, sourceStamp: String?) -> Bool {
+        guard let copyStamp, let sourceStamp else { return false }
+        return copyStamp == sourceStamp
+    }
+
+    private static func query(_ service: String) -> [String: Any] {
+        [kSecClass as String: kSecClassGenericPassword,
+         kSecAttrService as String: service,
+         kSecAttrAccount as String: account,
+         kSecMatchLimit as String: kSecMatchLimitOne]
+    }
+
+    private static func stamp(of service: String) -> (status: OSStatus, stamp: String?) {
+        var request = query(service)
+        request[kSecReturnAttributes as String] = true
+        var item: CFTypeRef?
+        let status = SecItemCopyMatching(request as CFDictionary, &item)
+        let attributes = item as? [String: Any]
+        let date = attributes?[kSecAttrModificationDate as String] as? Date
+        return (status, date.map { ISO8601DateFormatter().string(from: $0) })
+    }
+
+    private static func read(_ service: String) -> (status: OSStatus, value: String?, generic: String?) {
+        var request = query(service)
+        request[kSecReturnAttributes as String] = true
+        request[kSecReturnData as String] = true
+        var item: CFTypeRef?
+        let status = SecItemCopyMatching(request as CFDictionary, &item)
+        let attributes = item as? [String: Any]
+        let value = (attributes?[kSecValueData as String] as? Data).flatMap { String(data: $0, encoding: .utf8) }
+        let generic = (attributes?[kSecAttrGeneric as String] as? Data).flatMap { String(data: $0, encoding: .utf8) }
+        return (status, value, generic)
+    }
+
+    private static func writeCopy(_ value: String, stamp: String) {
+        let fields: [String: Any] = [kSecValueData as String: Data(value.utf8),
+                                     kSecAttrGeneric as String: Data(stamp.utf8),
+                                     kSecAttrLabel as String: "GenesisTools vault key (app copy)"]
+        var lookup = query(copyService)
+        lookup.removeValue(forKey: kSecMatchLimit as String)
+        if SecItemUpdate(lookup as CFDictionary, fields as CFDictionary) == errSecItemNotFound {
+            _ = SecItemAdd(lookup.merging(fields) { $1 } as CFDictionary, nil)
+        }
     }
 
-    static func label(_ seconds: Int?) -> String {
-        guard let seconds else { return "Always allow this tool" }
-        if seconds == 0 { return "Allow once" }
-        if seconds % 86_400 == 0 { return "Allow for \(seconds / 86_400) days" }
-        return "Allow for \(seconds / 3_600) hours"
+    static func key() -> Outcome {
+        let source = stamp(of: service)
+        if source.status == errSecItemNotFound { return .missing }
+
+        let copy = read(copyService)
+        if copy.status == errSecSuccess, let value = copy.value, copyIsCurrent(copyStamp: copy.generic, sourceStamp: source.stamp) {
+            return .key(value, fromCopy: true)
+        }
+
+        let original = read(service)
+        guard original.status == errSecSuccess, let value = original.value else {
+            if original.status == errSecItemNotFound { return .missing }
+            return .failed(SecCopyErrorMessageString(original.status, nil) as String? ?? "status \(original.status)")
+        }
+
+        if let stamp = source.stamp {
+            writeCopy(value, stamp: stamp)
+        }
+
+        return .key(value, fromCopy: false)
     }
 }
 
-private func vaultAudit(_ event: String, params: VaultUnlockParams, caller: VaultCaller, session: String?, detail: String = "") {
+private func vaultAudit(_ event: String, params: VaultUnlockParams, caller: VaultCaller, session: VaultSessionInfo, detail: String = "") {
     var parts = ["purpose: \(params.purpose)"]
     if let secret = params.secret { parts.append("secret: \(secret)") }
-    if let session { parts.append("session: \(session)") }
+    if let summary = session.summary { parts.append("session: \(summary)") }
+    if let id = session.sessionId { parts.append("session id: \(id)") }
     if !detail.isEmpty { parts.append(detail) }
 
+    var client: [String: Any] = ["name": caller.toolName ?? params.tool, "pid": Int(caller.pid)]
+    client["executable"] = caller.executable
+    client["script"] = caller.script
+    client["cwd"] = caller.cwd
+
     let entry: [String: Any] = [
         "at": ISO8601DateFormatter().string(from: Date()),
         "event": event,
-        "client": ["name": params.tool, "pid": Int(caller.pid), "executable": caller.executable ?? NSNull(), "cwd": caller.cwd ?? NSNull()],
+        "client": client,
         "account": "vault",
         "detail": parts.joined(separator: "; "),
     ]
@@ -349,28 +578,16 @@ private func vaultAudit(_ event: String, params: VaultUnlockParams, caller: Vaul
     try? handle.write(contentsOf: data + Data("\n".utf8))
 }
 
-/// The keychain item the bun rung writes (`genesis-tools` / `master-key`, base64), read as this app.
 private func emitVaultKey(remembered: Bool) -> Never {
-    let query: [String: Any] = [
-        kSecClass as String: kSecClassGenericPassword,
-        kSecAttrService as String: "genesis-tools",
-        kSecAttrAccount as String: "master-key",
-        kSecReturnData as String: true,
-        kSecMatchLimit as String: kSecMatchLimitOne,
-    ]
-    var item: CFTypeRef?
-    let status = SecItemCopyMatching(query as CFDictionary, &item)
-
-    guard status == errSecSuccess, let data = item as? Data, let key = String(data: data, encoding: .utf8) else {
-        if status == errSecItemNotFound {
-            emitError(code: "no_key", message: "the keychain holds no genesis-tools master key", exitCode: 66)
-        }
-
-        let reason = SecCopyErrorMessageString(status, nil) as String? ?? "status \(status)"
+    switch VaultKeychain.key() {
+    case let .key(key, fromCopy):
+        logClick("vault.unlock key from=\(fromCopy ? "app copy" : "keychain item")")
+        emitResult(["decision": "allow", "key": key, "remembered": remembered])
+    case .missing:
+        emitError(code: "no_key", message: "the keychain holds no genesis-tools master key", exitCode: 66)
+    case let .failed(reason):
         emitError(code: "keychain", message: "GenesisTools could not read the vault key: \(reason)", exitCode: 74)
     }
-
-    emitResult(["decision": "allow", "key": key, "remembered": remembered])
 }
 
 private func vaultDeny(_ reason: String) -> Never {
@@ -378,73 +595,87 @@ private func vaultDeny(_ reason: String) -> Never {
     emitResult(["decision": "deny", "reason": reason])
 }
 
+@MainActor private let vaultPresenter = ApprovalPanelPresenter()
+
 func unlockVault(_ params: VaultUnlockParams) {
     let caller = VaultProcess.caller(getppid())
-    let session = VaultSession.describe(caller)
+    let session = VaultSession.info(caller, claudeHome: (NSHomeDirectory() as NSString).appendingPathComponent(".claude"))
     guard let executable = caller.executable else {
         vaultAudit("denied", params: params, caller: caller, session: session, detail: "the caller's executable could not be read")
         vaultDeny("the caller's executable could not be read")
     }
 
-    let rememberable = caller.injected.isEmpty
-    let key = VaultGrants.key(tool: params.tool, executable: executable, script: caller.script)
+    let tool = caller.toolName ?? params.tool
+    let rememberable = caller.onceOnlyReason == nil
+    let key = VaultGrants.key(tool: tool, executable: executable, script: caller.script)
     let now = Int64(Date().timeIntervalSince1970 * 1_000)
 
-    if rememberable, VaultGrants.live(key, now: now, in: VaultGrants.load()) != nil {
+    if rememberable, VaultGrants.live(executable: executable, script: caller.script, now: now, in: VaultGrants.load()) != nil {
         vaultAudit("remembered", params: params, caller: caller, session: session)
         emitVaultKey(remembered: true)
     }
 
-    guard VaultWindowLock.acquire(VaultWindowLock.path(for: key)) != nil else {
-        vaultAudit("denied", params: params, caller: caller, session: session, detail: "an approval window for this tool is already open")
-        vaultDeny("an approval window for “\(params.tool)” is already open; answer that one first")
+    guard VaultWindowLock.acquire(VaultWindowLock.path(for: "vault|\(executable)|\(caller.script ?? "")")) != nil else {
+        vaultAudit("denied", params: params, caller: caller, session: session, detail: "an approval window for this program is already open")
+        vaultDeny("an approval window for “\(tool)” is already open; answer that one first")
     }
 
-    DispatchQueue.main.asyncAfter(deadline: .now() + 170) {
-        vaultAudit("denied", params: params, caller: caller, session: session, detail: "no answer within 170 s")
-        vaultDeny("no answer within 170 s")
-    }
+    let deadlineSeconds = 170.0
+    let content = VaultWindowContent.build(params, caller: caller, session: session)
+    let biometric = LAContext().canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil)
 
     DispatchQueue.main.async {
-        NSApplication.shared.activate(ignoringOtherApps: true)
-        vaultAudit("prompted", params: params, caller: caller, session: session)
-
-        let choices = VaultWindow.choices(rememberable: rememberable)
-        let alert = NSAlert()
-        alert.alertStyle = .warning
-        alert.messageText = VaultWindow.title(params)
-        alert.informativeText = VaultWindow.body(params, caller: caller, session: session)
-        for seconds in choices {
-            alert.addButton(withTitle: VaultWindow.label(seconds))
+        let model = ApprovalDialogModel(
+            title: content.title, purpose: content.purpose, symbol: "key.fill", facts: content.facts, details: content.details,
+            warning: content.warning, footnote: VaultWindowContent.footnote,
+            rememberChoices: rememberable ? VaultWindowContent.rememberChoices : [],
+            rememberNote: content.onceOnlyReason.map { "Only once: \($0)" },
+            allowTitle: biometric ? "Allow with Touch ID" : "Allow…",
+            deadline: Date().addingTimeInterval(deadlineSeconds), identifier: "vault-unlock")
+
+        // A modal loop would hold the main queue and this timer with it; the panel leaves the run loop free.
+        let deadline = DispatchWorkItem {
+            vaultAudit("denied", params: params, caller: caller, session: session, detail: "no answer within \(Int(deadlineSeconds)) s")
+            vaultDeny("no answer within \(Int(deadlineSeconds)) s")
         }
+        DispatchQueue.main.asyncAfter(deadline: .now() + deadlineSeconds, execute: deadline)
 
-        let deny = alert.addButton(withTitle: "Deny")
-        deny.keyEquivalent = "\u{1b}"
-
-        let index = alert.runModal().rawValue - NSApplication.ModalResponse.alertFirstButtonReturn.rawValue
-        guard index >= 0, index < choices.count else {
+        model.onDeny = {
+            deadline.cancel()
+            vaultPresenter.close()
             vaultAudit("denied", params: params, caller: caller, session: session, detail: "denied in the window")
             vaultDeny("denied in the approval window")
         }
 
-        let remember = choices[index]
-        authenticate(reason: "give “\(params.tool)” the GenesisTools vault key") { method, failure in
-            guard let method else {
-                vaultAudit("denied", params: params, caller: caller, session: session, detail: failure)
-                vaultDeny(failure)
+        model.onAllow = { choice in
+            // From the click on, Touch ID has the time the caller allows (180 s), not the window's deadline.
+            deadline.cancel()
+            vaultPresenter.close()
+            let remember = choice?.seconds ?? 0
+            authenticate(reason: "give “\(tool)” the GenesisTools vault key") { method, failure in
+                DispatchQueue.main.async {
+                    guard let method else {
+                        vaultAudit("denied", params: params, caller: caller, session: session, detail: failure)
+                        vaultDeny(failure)
+                    }
+
+                    let forever = rememberable && choice != nil && choice?.seconds == nil
+                    if rememberable, remember != 0 || forever {
+                        let until = forever ? nil : Optional(now + Int64(remember) * 1_000)
+                        let grant = VaultGrant(key: key, tool: tool, executable: executable, script: caller.script,
+                                               grantedAt: now, until: until, method: method)
+                        VaultGrants.save(VaultGrants.remember(grant, now: now, in: VaultGrants.load()))
+                    }
+
+                    vaultAudit("allowed", params: params, caller: caller, session: session,
+                               detail: "method: \(method); remembered: \(forever ? "always" : remember == 0 ? "once" : "\(remember / 3_600) h")")
+                    logClick("vault.unlock decision=allow tool=\(tool) method=\(method)")
+                    emitVaultKey(remembered: false)
+                }
             }
-
-            if remember != 0 {
-                let until = remember.map { now + Int64($0) * 1_000 }
-                let grant = VaultGrant(key: key, tool: params.tool, executable: executable, script: caller.script,
-                                       grantedAt: now, until: until, method: method)
-                VaultGrants.save(VaultGrants.remember(grant, now: now, in: VaultGrants.load()))
-            }
-
-            vaultAudit("allowed", params: params, caller: caller, session: session,
-                       detail: "method: \(method); remembered: \(remember.map { $0 == 0 ? "once" : "\($0 / 3_600) h" } ?? "always")")
-            logClick("vault.unlock decision=allow tool=\(params.tool) method=\(method)")
-            emitVaultKey(remembered: false)
         }
+
+        vaultAudit("prompted", params: params, caller: caller, session: session)
+        vaultPresenter.present(model)
     }
 }
diff --git a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
index 7dbb5af2e5..2ab6899d3e 100644
--- a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
+++ b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
@@ -1,8 +1,9 @@
+import GenesisKit
 import XCTest
 @testable import GenesisTools
 
 /// The vault approval window's pure parts (Sources/VaultUnlock.swift): reading a process from the kernel's bytes,
-/// what counts as the same tool for a remembered approval, and what the window tells the user.
+/// what counts as the same program for a remembered approval, the session's name, and what the window tells the user.
 final class VaultUnlockTests: XCTestCase {
     private func procArgsBytes(argc: Int32, executable: String, arguments: [String], environment: [String]) -> [UInt8] {
         var bytes = withUnsafeBytes(of: argc.littleEndian) { Array($0) }
@@ -20,9 +21,10 @@ final class VaultUnlockTests: XCTestCase {
         return bytes
     }
 
-    private func caller(arguments: [String], environment: [String] = [], ancestors: [(pid_t, String)] = []) -> VaultCaller {
-        VaultCaller(pid: 4242, executable: "/Users/alice/.genesis-tools/bin/gt-claude",
-                    args: ProcArgs(executable: "/Users/alice/.genesis-tools/bin/gt-claude", arguments: arguments, environment: environment),
+    private func caller(_ executable: String = "/Users/alice/.genesis-tools/bin/gt-claude", arguments: [String],
+                        environment: [String] = [], ancestors: [(pid_t, String)] = []) -> VaultCaller {
+        VaultCaller(pid: 4242, executable: executable,
+                    args: ProcArgs(executable: executable, arguments: arguments, environment: environment),
                     cwd: "/Users/alice/project", ancestors: ancestors.map { (pid: $0.0, command: $0.1) })
     }
 
@@ -38,50 +40,135 @@ final class VaultUnlockTests: XCTestCase {
         XCTAssertEqual(parsed.environmentValue("CLAUDE_CODE_SESSION_ID"), "0f3a")
     }
 
-    func testTheScriptIsPartOfTheIdentityAndLoadersBlockRemembering() {
-        XCTAssertEqual(caller(arguments: ["gt-claude", "/repo/src/claude/index.ts", "info"]).script, "/repo/src/claude/index.ts")
+    func testTheProgramIsTheScriptAnInterpreterRunsEvenThroughBunRun() {
+        let daemon = caller("/Users/alice/.bun/bin/bun", arguments: ["/Users/alice/.bun/bin/bun", "run", "/repo/src/ai/commands/usage/poll-daemon.ts"])
+
+        XCTAssertEqual(daemon.script, "/repo/src/ai/commands/usage/poll-daemon.ts", "the first version saw no script here")
+        XCTAssertEqual(daemon.toolName, "ai")
+        XCTAssertNil(daemon.onceOnlyReason)
+
+        let hook = caller(arguments: ["gt-claude", "/repo/hooks/statusline.ts"])
+        XCTAssertEqual(hook.toolName, "claude", "no src/<tool>/ in the script: the gt- link names the tool")
+
+        let bare = caller("/Users/alice/.bun/bin/bun", arguments: ["/Users/alice/.bun/bin/bun", "repl"])
+        XCTAssertNil(bare.script)
+        XCTAssertEqual(bare.onceOnlyReason, "the script it runs is not known")
+    }
+
+    func testLoadedExtraCodeAllowsOnlyOnce() {
         XCTAssertEqual(caller(arguments: ["gt-claude", "/repo/src/claude/index.ts"]).injected, [])
         XCTAssertFalse(caller(arguments: ["gt-claude", "--preload", "/tmp/x.ts", "/repo/src/claude/index.ts"]).injected.isEmpty)
-        XCTAssertFalse(caller(arguments: ["gt-claude", "/repo/src/claude/index.ts"], environment: ["DYLD_INSERT_LIBRARIES=/tmp/x.dylib"]).injected.isEmpty)
-        XCTAssertEqual(VaultWindow.choices(rememberable: false), [0], "with extra code loaded, only allow once")
+        XCTAssertFalse(caller(arguments: ["gt-claude", "run", "--preload", "/tmp/x.ts"]).injected.isEmpty)
+        let injected = caller(arguments: ["gt-claude", "/repo/src/claude/index.ts"], environment: ["DYLD_INSERT_LIBRARIES=/tmp/x.dylib"])
+        XCTAssertEqual(injected.onceOnlyReason, "extra code may be loaded")
     }
 
-    func testARememberedApprovalCoversOnlyTheSameToolExecutableAndScriptUntilItEnds() {
-        let key = VaultGrants.key(tool: "claude", executable: "/bin/gt-claude", script: "/repo/src/claude/index.ts")
-        let grant = VaultGrant(key: key, tool: "claude", executable: "/bin/gt-claude", script: "/repo/src/claude/index.ts",
+    func testARememberedApprovalCoversOnlyTheSameExecutableAndScriptUntilItEnds() {
+        let grant = VaultGrant(key: "k", tool: "claude", executable: "/bin/gt-claude", script: "/repo/src/claude/index.ts",
                                grantedAt: 1_000, until: 2_000, method: "touch-id")
         let file = VaultGrants.remember(grant, now: 1_000, in: VaultGrantsFile(version: 1, grants: []))
 
-        XCTAssertNotNil(VaultGrants.live(key, now: 1_500, in: file))
-        XCTAssertNil(VaultGrants.live(key, now: 2_000, in: file), "a timed approval ends")
-        XCTAssertNil(VaultGrants.live(VaultGrants.key(tool: "claude", executable: "/bin/gt-claude", script: "/tmp/other.ts"), now: 1_500, in: file))
-        XCTAssertNil(VaultGrants.live(VaultGrants.key(tool: "say", executable: "/bin/gt-claude", script: "/repo/src/claude/index.ts"), now: 1_500, in: file))
+        XCTAssertNotNil(VaultGrants.live(executable: "/bin/gt-claude", script: "/repo/src/claude/index.ts", now: 1_500, in: file))
+        XCTAssertNil(VaultGrants.live(executable: "/bin/gt-claude", script: "/repo/src/claude/index.ts", now: 2_000, in: file), "a timed approval ends")
+        XCTAssertNil(VaultGrants.live(executable: "/bin/gt-claude", script: "/tmp/other.ts", now: 1_500, in: file))
+        XCTAssertNil(VaultGrants.live(executable: "/bin/gt-say", script: "/repo/src/claude/index.ts", now: 1_500, in: file))
 
         var always = grant
         always.until = nil
-        XCTAssertNotNil(VaultGrants.live(key, now: Int64.max, in: VaultGrants.remember(always, now: 1_000, in: file)), "always lasts until revoked")
+        XCTAssertNotNil(VaultGrants.live(executable: "/bin/gt-claude", script: "/repo/src/claude/index.ts", now: Int64.max,
+                                         in: VaultGrants.remember(always, now: 1_000, in: file)), "always lasts until revoked")
     }
 
-    func testTheWindowSaysWhyWhatWhoAndWhichSession() {
-        let params = VaultUnlockParams(tool: "claude", purpose: "match the session's token to an account for the statusline",
+    func testAGrantWithoutAScriptForAnInterpreterMatchesNothingAndGoesOnTheNextWrite() {
+        let broad = VaultGrant(key: "vault|bun|/Users/alice/.bun/bin/bun|", tool: "bun", executable: "/Users/alice/.bun/bin/bun",
+                               script: nil, grantedAt: 1_000, until: nil, method: "touch-id")
+        let file = VaultGrantsFile(version: 1, grants: [broad])
+
+        XCTAssertNil(VaultGrants.live(executable: "/Users/alice/.bun/bin/bun", script: nil, now: 1_500, in: file))
+
+        let next = VaultGrant(key: "k", tool: "say", executable: "/Users/alice/.bun/bin/bun", script: "/repo/src/say/index.ts",
+                              grantedAt: 1_500, until: nil, method: "touch-id")
+        XCTAssertEqual(VaultGrants.remember(next, now: 1_500, in: file).grants, [next])
+    }
+
+    func testTheWindowLeadsWithWhyThenSessionProgramFolderAndSecret() {
+        let params = VaultUnlockParams(tool: "bun", purpose: "match this Claude session's token to a configured account, for the statusline",
                                        secret: "ai/acc_work/longLivedToken", command: "tools claude info")
-        let who = caller(arguments: ["gt-claude", "/repo/src/claude/index.ts", "info"],
+        let who = caller(arguments: ["gt-claude", "/Users/alice/repo/src/claude/index.ts", "info"],
                          environment: ["CLAUDE_CODE_SESSION_ID=0f3a-session", "CMUX_SURFACE_ID=surface-9"],
                          ancestors: [(100, "GenesisTools gt-claude"), (90, "zsh"), (80, "claude")])
-        let session = VaultSession.describe(who)
-        let body = VaultWindow.body(params, caller: who, session: session)
-
-        XCTAssertEqual(session, "Claude Code session 0f3a-session, cmux tab surface-9")
-        XCTAssertTrue(body.contains("Why: match the session's token to an account for the statusline"))
-        XCTAssertTrue(body.contains("It was reading: ai/acc_work/longLivedToken"))
-        XCTAssertTrue(body.contains("Executable: /Users/alice/.genesis-tools/bin/gt-claude"))
-        XCTAssertTrue(body.contains("Script: /repo/src/claude/index.ts"))
-        XCTAssertTrue(body.contains("Started by: GenesisTools gt-claude (100) ← zsh (90) ← claude (80)"))
-        XCTAssertTrue(body.contains("Session: Claude Code session 0f3a-session"))
-        XCTAssertFalse(body.contains("Extra code"))
+        let session = VaultSessionInfo(sessionId: "0f3a-session", title: "review-loop", agent: nil, cmuxTab: "surface-9")
+        let content = VaultWindowContent.build(params, caller: who, session: session, home: "/Users/alice")
+        let facts = Dictionary(uniqueKeysWithValues: content.facts.map { ($0.label, $0.value) })
+        let details = Dictionary(uniqueKeysWithValues: content.details.map { ($0.label, $0.value) })
+
+        XCTAssertEqual(content.title, "“claude” wants the vault key", "the kernel's tool, not the request's")
+        XCTAssertEqual(content.purpose, "Match this Claude session's token to a configured account, for the statusline.")
+        XCTAssertEqual(content.facts.map(\.label), ["Session", "Program", "Folder", "Reading"])
+        XCTAssertEqual(facts["Session"], "review-loop (Claude Code)")
+        XCTAssertEqual(facts["Program"], "claude · ~/repo/src/claude/index.ts")
+        XCTAssertEqual(facts["Folder"], "~/project")
+        XCTAssertEqual(facts["Reading"], "acc_work › longLivedToken")
+        XCTAssertEqual(details["Started by"], "GenesisTools gt-claude (100) ← zsh (90) ← claude (80)")
+        XCTAssertEqual(details["Session ID"], "0f3a-session")
+        XCTAssertEqual(details["cmux tab"], "surface-9")
+        XCTAssertNil(content.warning)
+        XCTAssertNil(content.onceOnlyReason)
+    }
+
+    func testTheSessionIsNamedFromItsTranscript() throws {
+        let tail = """
+        {"type":"ai-title","aiTitle":"Generated title","sessionId":"s"}
+        {"type":"agent-name","agentName":"old-name","sessionId":"s"}
+        {"type":"custom-title","customTitle":"first","sessionId":"s"}
+        {"type":"custom-title","customTitle":"review \\"loop\\"","sessionId":"s"}
+        """
+        XCTAssertEqual(VaultSession.title(fromTranscriptTail: tail), "review \"loop\"", "a /rename wins, the last one")
+        XCTAssertEqual(VaultSession.title(fromTranscriptTail: #"{"agentName":"bot"}{"aiTitle":"x"}"#), "bot")
+        XCTAssertNil(VaultSession.title(fromTranscriptTail: "{}"))
+
+        let home = (NSTemporaryDirectory() as NSString).appendingPathComponent("vault-claude-\(UUID().uuidString)")
+        defer { try? FileManager.default.removeItem(atPath: home) }
+        let folder = (home as NSString).appendingPathComponent("projects/-Users-alice-repo")
+        try FileManager.default.createDirectory(atPath: folder, withIntermediateDirectories: true)
+        try Data(tail.utf8).write(to: URL(fileURLWithPath: (folder as NSString).appendingPathComponent("0f3a-session.jsonl")))
+
+        XCTAssertEqual(VaultSession.claudeTitle(sessionId: "0f3a-session", claudeHome: home), "review \"loop\"")
+        XCTAssertNil(VaultSession.claudeTitle(sessionId: "../escape", claudeHome: home))
     }
 
-    func testASecondRequestFromTheSameToolGetsNoSecondWindow() throws {
+    func testWithoutASessionIdTheAgentInTheParentChainNamesIt() {
+        let who = caller(arguments: ["gt-say", "/repo/src/say/index.ts"], ancestors: [(90, "zsh"), (80, "codex exec")])
+
+        XCTAssertEqual(VaultSession.info(who, claudeHome: "/nonexistent").summary, "codex exec (pid 80)")
+    }
+
+    func testTheAppCopyOfTheKeyAnswersOnlyForTheSourceItWasTakenFrom() {
+        XCTAssertTrue(VaultKeychain.copyIsCurrent(copyStamp: "2026-07-29T02:41:12Z", sourceStamp: "2026-07-29T02:41:12Z"))
+        XCTAssertFalse(VaultKeychain.copyIsCurrent(copyStamp: "2026-07-29T02:41:12Z", sourceStamp: "2026-10-15T00:00:00Z"), "a rotated key is read again")
+        XCTAssertFalse(VaultKeychain.copyIsCurrent(copyStamp: nil, sourceStamp: "2026-07-29T02:41:12Z"))
+        XCTAssertFalse(VaultKeychain.copyIsCurrent(copyStamp: "2026-07-29T02:41:12Z", sourceStamp: nil))
+    }
+
+    func testTheAccountGateWindowUsesTheSameLayout() throws {
+        let json = """
+        {"client":{"name":"Genesis","pid":11574,"executable":"/Applications/Genesis.app/Contents/MacOS/Genesis","cwd":"/",
+          "ancestors":[{"pid":1,"command":"launchd"}],"isAncestor":true,"verified":false},
+         "provider":"xai","account":{"id":"acc_1","name":"work","label":"alice@example.com"},"tokenKind":"api-key",
+         "rememberChoicesSeconds":[0,28800,604800]}
+        """
+        let params = try JSONDecoder().decode(GateApproveParams.self, from: Data(json.utf8))
+        let content = GateWindowContent.build(params, home: "/Users/alice")
+
+        XCTAssertEqual(content.title, "“Genesis” wants the xai API key of work")
+        XCTAssertTrue(content.purpose.hasPrefix("The API KEY itself is shared"))
+        XCTAssertEqual(content.facts.map(\.label), ["Account", "Program", "Folder"])
+        XCTAssertEqual(content.facts.first?.value, "work (alice@example.com) · xai")
+        XCTAssertEqual(content.rememberChoices.map(\.title), ["Just this once", "For 8 hours", "For 7 days"])
+        XCTAssertEqual(content.warning, "Unverified: its binary or script could not be established. It will not be remembered.")
+    }
+
+    func testASecondRequestFromTheSameProgramGetsNoSecondWindow() throws {
         let path = (NSTemporaryDirectory() as NSString).appendingPathComponent("vault-window-test-\(UUID().uuidString).lock")
         defer { try? FileManager.default.removeItem(atPath: path) }
         let first = try XCTUnwrap(VaultWindowLock.acquire(path))
@@ -89,12 +176,6 @@ final class VaultUnlockTests: XCTestCase {
         XCTAssertNil(VaultWindowLock.acquire(path), "the first window holds the lock")
         close(first)
         XCTAssertNotNil(VaultWindowLock.acquire(path), "a closed window frees it")
-        XCTAssertNotEqual(VaultWindowLock.path(for: "vault|claude|/a|"), VaultWindowLock.path(for: "vault|say|/a|"))
-    }
-
-    func testWithoutASessionIdTheAgentInTheParentChainNamesIt() {
-        let who = caller(arguments: ["gt-say", "/repo/src/say/index.ts"], ancestors: [(90, "zsh"), (80, "codex exec")])
-
-        XCTAssertEqual(VaultSession.describe(who), "codex exec (pid 80)")
+        XCTAssertNotEqual(VaultWindowLock.path(for: "vault|/a|x.ts"), VaultWindowLock.path(for: "vault|/a|y.ts"))
     }
 }
diff --git a/src/utils/security/keyring/app-gate.test.ts b/src/utils/security/keyring/app-gate.test.ts
index 3680ef6a0a..69a682c29a 100644
--- a/src/utils/security/keyring/app-gate.test.ts
+++ b/src/utils/security/keyring/app-gate.test.ts
@@ -77,6 +77,26 @@ describe("the app rung", () => {
         }
     });
 
+    test("a refusal is final for the process: the next read throws without asking the app again", async () => {
+        let asked = 0;
+        const app = createAppGateKeyProvider({
+            available: () => true,
+            rpc: async () => {
+                asked++;
+                return deny;
+            },
+            rpcSync: () => {
+                asked++;
+                return failure("timeout");
+            },
+        });
+
+        await expect(app.get()).rejects.toThrow("denied in the approval window");
+        await expect(app.get()).rejects.toThrow("denied in the approval window");
+        expect(() => app.getSync?.()).toThrow("denied in the approval window");
+        expect(asked).toBe(1);
+    });
+
     test("no answer within the window's time is a deny, not a fall-through to the keychain dialog", () => {
         const app = createAppGateKeyProvider({ available: () => true, rpcSync: () => failure("timeout") });
 
@@ -141,6 +161,14 @@ describe("the caller's name and command", () => {
             "claude"
         );
         expect(currentToolName(["/Users/x/.genesis-tools/bin/gt-say", "/somewhere/else.ts"])).toBe("say");
+        expect(currentToolName(["/Users/x/.bun/bin/bun", "/repo/src/ai/commands/usage/poll-daemon.ts"])).toBe("ai");
+        expect(
+            currentToolName(
+                ["/Users/x/.bun/bin/bun", "/repo/hooks/statusline.ts"],
+                "/Users/x/.genesis-tools/bin/gt-claude"
+            )
+        ).toBe("claude");
+        expect(currentToolName(["/Users/x/.bun/bin/bun", "/tmp/probe.ts"], "/Users/x/.bun/bin/bun")).toBe("probe");
         expect(currentCommandLine(["gt-say", "/repo/src/say/index.ts", "hello there", "--app", "claude"])).toBe(
             'tools say "hello there" --app claude'
         );
diff --git a/src/utils/security/keyring/app-gate.ts b/src/utils/security/keyring/app-gate.ts
index c9f1ac8ef5..268fca81a1 100644
--- a/src/utils/security/keyring/app-gate.ts
+++ b/src/utils/security/keyring/app-gate.ts
@@ -105,7 +105,12 @@ export interface AppGateDeps {
     rpcSync?: (request: VaultUnlockRequest) => GenesisAppRpcOutcome<VaultUnlockReply>;
 }
 
-/** Tests build the rung with fakes; production uses `appGateKey`. A test process never reaches the real app. */
+/**
+ * Tests build the rung with fakes; production uses `appGateKey`. A test process never reaches the real app.
+ *
+ * A refusal is final for the process: the first version asked again on the next secret read, so one `tools say`
+ * opened a new window every three minutes (2026-10-15 00:30).
+ */
 export function createAppGateKeyProvider(deps: AppGateDeps = {}): MasterKeyProvider {
     const available = deps.available ?? (() => !isTestProcess() && isGenesisAppRpcAvailable());
     const options = { timeoutMs: VAULT_UNLOCK_TIMEOUT_MS, isResult: isReply };
@@ -118,6 +123,19 @@ export function createAppGateKeyProvider(deps: AppGateDeps = {}): MasterKeyProvi
         ((request: VaultUnlockRequest) =>
             genesisAppRpcSync<VaultUnlockReply>("vault.unlock", params(request), options));
 
+    let refusal: VaultKeyDeniedError | undefined;
+    const answer = (outcome: GenesisAppRpcOutcome<VaultUnlockReply>, tool: string): Buffer | undefined => {
+        try {
+            return keyFromReply(outcome, tool);
+        } catch (error) {
+            if (error instanceof VaultKeyDeniedError) {
+                refusal = error;
+            }
+
+            throw error;
+        }
+    };
+
     return {
         id: "app",
         async available() {
@@ -128,16 +146,24 @@ export function createAppGateKeyProvider(deps: AppGateDeps = {}): MasterKeyProvi
                 return undefined;
             }
 
+            if (refusal) {
+                throw refusal;
+            }
+
             const request = vaultUnlockRequest();
-            return keyFromReply(await rpc(request), request.tool);
+            return answer(await rpc(request), request.tool);
         },
         getSync() {
             if (!available()) {
                 return undefined;
             }
 
+            if (refusal) {
+                throw refusal;
+            }
+
             const request = vaultUnlockRequest();
-            return keyFromReply(rpcSync(request), request.tool);
+            return answer(rpcSync(request), request.tool);
         },
         async set() {
             throw new Error("GenesisTools.app only reads the vault key; a new key is stored by the keychain rung");
diff --git a/src/utils/security/vault-purpose.ts b/src/utils/security/vault-purpose.ts
index 585deef703..7e316a2ad2 100644
--- a/src/utils/security/vault-purpose.ts
+++ b/src/utils/security/vault-purpose.ts
@@ -45,17 +45,26 @@ export function _resetVaultContextForTest(): void {
     firstSecret = undefined;
 }
 
-/** The tool this process runs: `src/<tool>/index.ts` from the script path, else the `gt-<tool>` launcher name. */
-export function currentToolName(argv: string[] = process.argv): string {
+/**
+ * The tool this process runs: `src/<tool>/` in the script path (`src/ai/commands/usage/poll-daemon.ts` is `ai`), else
+ * the `gt-<tool>` launcher, else the script's own name. The first version read only `src/<tool>/index.ts` and called
+ * the usage daemon "bun".
+ */
+export function currentToolName(argv: string[] = process.argv, executable: string = process.execPath): string {
     const script = argv[1] ?? "";
-    const fromScript = script.match(/[/\\]src[/\\]([^/\\]+)[/\\]index\.tsx?$/)?.[1];
+    const fromScript = script.match(/[/\\]src[/\\]([^/\\]+)[/\\]/)?.[1];
 
     if (fromScript) {
         return fromScript;
     }
 
-    const launcher = basename(argv[0] ?? "");
-    return launcher.startsWith("gt-") ? launcher.slice(3) : launcher || "unknown";
+    for (const launcher of [basename(executable), basename(argv[0] ?? "")]) {
+        if (launcher.startsWith("gt-")) {
+            return launcher.slice(3);
+        }
+    }
+
+    return basename(script).replace(/\.[cm]?[jt]sx?$/, "") || basename(argv[0] ?? "") || "unknown";
 }
 
 /** `tools <tool> <args>`, cut to a length a window can show. Tokens never travel in argv (they go through stdin). */

From 0a926a16421a98c993e75e8466064f132f726360 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 00:48:28 +0200
Subject: [PATCH 15/32] fix(ai, macos): the approval window keeps whole
 buttons, wraps paths from the project folder and uses the full height,
 because the first SwiftUI version cut 'Allow with Touch ID', wrapped the
 countdown and left an empty band on top

(cherry picked from commit d21897c8ba1601ffbd1ce7aee275b2b88ca9704c)
---
 .../Permissions/ApprovalDialog.swift          | 58 +++++++++++++------
 src/macos/GenesisTools/Sources/Gate.swift     |  2 +-
 .../GenesisTools/Sources/VaultUnlock.swift    | 13 ++++-
 .../GenesisTools/Tests/VaultUnlockTests.swift | 49 +++++++++++++++-
 4 files changed, 99 insertions(+), 23 deletions(-)

diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Permissions/ApprovalDialog.swift b/src/macos/GenesisKit/Sources/GenesisKit/Permissions/ApprovalDialog.swift
index 7857aa43d7..7446e9b050 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Permissions/ApprovalDialog.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Permissions/ApprovalDialog.swift
@@ -139,10 +139,14 @@ public struct ApprovalDialogView: View {
                 .fixedSize(horizontal: false, vertical: true)
                 .padding(.leading, 66)
 
+            remember
             buttons
         }
         .padding(20)
         .frame(width: 480)
+        // The hosting controller insets its content by the hidden title bar; the strip stays draggable through
+        // `.titlebarZone()`, so the dialog uses the full height (Martin's screenshot showed an empty band on top).
+        .ignoresSafeArea()
         .accessibilityElement(children: .contain)
         .accessibilityIdentifier(model.identifier)
     }
@@ -176,6 +180,8 @@ public struct ApprovalDialogView: View {
                         .font(fact.monospaced ? .system(size: 11, design: .monospaced) : .system(size: 12))
                         .lineLimit(3)
                         .truncationMode(.middle)
+                        // Without it the grid measured one line and cut a path in the middle while the window had room.
+                        .fixedSize(horizontal: false, vertical: true)
                         .textSelection(.enabled)
                         .help(fact.help ?? fact.value)
                         .frame(maxWidth: .infinity, alignment: .leading)
@@ -184,18 +190,14 @@ public struct ApprovalDialogView: View {
         }
     }
 
-    private var buttons: some View {
-        HStack(spacing: 8) {
-            Button("Deny", action: model.deny)
-                .keyboardShortcut(.cancelAction)
-                .accessibilityIdentifier("\(model.identifier)-deny")
-            if let deadline = model.deadline {
-                (Text("Denies itself in ") + Text(timerInterval: Date()...max(Date(), deadline), countsDown: true))
-                    .font(.system(size: 11).monospacedDigit())
-                    .foregroundStyle(.tertiary)
-            }
-            Spacer(minLength: 8)
-            if model.rememberChoices.count > 1 {
+    /// Its own row, so the buttons keep their full titles (the first layout cut "Allow with Touch ID" short).
+    @ViewBuilder
+    private var remember: some View {
+        if model.rememberChoices.count > 1 {
+            HStack(spacing: 8) {
+                Text("Remember")
+                    .font(.system(size: 12))
+                    .foregroundStyle(.secondary)
                 Picker("Remember", selection: $model.rememberIndex) {
                     ForEach(model.rememberChoices.indices, id: \.self) { index in
                         Text(model.rememberChoices[index].title).tag(index)
@@ -205,17 +207,35 @@ public struct ApprovalDialogView: View {
                 .pickerStyle(.menu)
                 .fixedSize()
                 .accessibilityIdentifier("\(model.identifier)-remember")
-            } else if let note = model.rememberNote {
-                Text(note)
-                    .font(.system(size: 11))
-                    .foregroundStyle(.secondary)
-                    .lineLimit(2)
-                    .frame(maxWidth: 170, alignment: .trailing)
-                    .multilineTextAlignment(.trailing)
             }
+            .padding(.leading, 66)
+            .disabled(model.answered)
+            .environment(\.controlActiveState, .key)
+        } else if let note = model.rememberNote {
+            Label(note, systemImage: "clock.badge.xmark")
+                .font(.system(size: 11))
+                .foregroundStyle(.secondary)
+                .padding(.leading, 66)
+        }
+    }
+
+    private var buttons: some View {
+        HStack(spacing: 8) {
+            if let deadline = model.deadline {
+                (Text("Denies itself in ") + Text(timerInterval: Date()...max(Date(), deadline), countsDown: true))
+                    .font(.system(size: 11).monospacedDigit())
+                    .foregroundStyle(.tertiary)
+                    .lineLimit(1)
+                    .fixedSize()
+            }
+            Spacer(minLength: 8)
+            Button("Deny", action: model.deny)
+                .keyboardShortcut(.cancelAction)
+                .accessibilityIdentifier("\(model.identifier)-deny")
             Button(model.allowTitle, action: model.allow)
                 .keyboardShortcut(.defaultAction)
                 .buttonStyle(.borderedProminent)
+                .fixedSize()
                 .accessibilityIdentifier("\(model.identifier)-allow")
         }
         .controlSize(.regular)
diff --git a/src/macos/GenesisTools/Sources/Gate.swift b/src/macos/GenesisTools/Sources/Gate.swift
index 4d86ad21ca..239fa13afa 100644
--- a/src/macos/GenesisTools/Sources/Gate.swift
+++ b/src/macos/GenesisTools/Sources/Gate.swift
@@ -144,7 +144,7 @@ struct GateWindowContent {
         let program = client.script ?? client.executable
 
         var facts = [ApprovalFact("Account", "\(accountLabel) · \(params.provider)")]
-        facts.append(ApprovalFact("Program", program.map { "\(client.name) · \(VaultWindowContent.shortPath($0, home: home))" } ?? client.name,
+        facts.append(ApprovalFact("Program", program.map { "\(client.name) · \(VaultWindowContent.programPath($0, home: home))" } ?? client.name,
                                   help: [client.executable, client.script].compactMap { $0 }.joined(separator: " ")))
         if let cwd = client.cwd, !cwd.isEmpty {
             facts.append(ApprovalFact("Folder", VaultWindowContent.shortPath(cwd, home: home), help: cwd))
diff --git a/src/macos/GenesisTools/Sources/VaultUnlock.swift b/src/macos/GenesisTools/Sources/VaultUnlock.swift
index fcde0c49d6..6fcd4aa704 100644
--- a/src/macos/GenesisTools/Sources/VaultUnlock.swift
+++ b/src/macos/GenesisTools/Sources/VaultUnlock.swift
@@ -396,6 +396,14 @@ struct VaultWindowContent {
         path == home ? "~" : path.hasPrefix(home + "/") ? "~" + path.dropFirst(home.count) : path
     }
 
+    /// A script inside a project reads from the project's folder: `GenesisTools/src/ai/commands/usage/poll-daemon.ts`,
+    /// not a home path cut in the middle (Martin's screenshot, 2026-10-15 00:46).
+    static func programPath(_ path: String, home: String = NSHomeDirectory()) -> String {
+        guard let range = path.range(of: "/src/") else { return shortPath(path, home: home) }
+        let project = (String(path[..<range.lowerBound]) as NSString).lastPathComponent
+        return project.isEmpty ? shortPath(path, home: home) : project + path[range.lowerBound...]
+    }
+
     /// `ai/acc_work/apiKey` reads as `acc_work › apiKey`.
     static func secretLabel(_ secret: String) -> String {
         let parts = secret.split(separator: "/").map(String.init)
@@ -413,10 +421,11 @@ struct VaultWindowContent {
     static func build(_ params: VaultUnlockParams, caller: VaultCaller, session: VaultSessionInfo,
                       home: String = NSHomeDirectory()) -> VaultWindowContent {
         let tool = caller.toolName ?? params.tool
-        var facts = [ApprovalFact("Session", session.summary ?? "None found (not started from an agent session)")]
+        let starter = caller.ancestors.last.map { "None: started by \($0.command)" } ?? "None: started by launchd"
+        var facts = [ApprovalFact("Session", session.summary ?? starter)]
 
         if let script = caller.script {
-            facts.append(ApprovalFact("Program", "\(tool) · \(shortPath(script, home: home))",
+            facts.append(ApprovalFact("Program", "\(tool) · \(programPath(script, home: home))",
                                       help: "\(caller.executable ?? "unknown") \(script)"))
         } else {
             facts.append(ApprovalFact("Program", "\(tool) · \(shortPath(caller.executable ?? "unknown", home: home))",
diff --git a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
index 2ab6899d3e..a243689a84 100644
--- a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
+++ b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
@@ -1,4 +1,5 @@
 import GenesisKit
+import SwiftUI
 import XCTest
 @testable import GenesisTools
 
@@ -106,7 +107,8 @@ final class VaultUnlockTests: XCTestCase {
         XCTAssertEqual(content.purpose, "Match this Claude session's token to a configured account, for the statusline.")
         XCTAssertEqual(content.facts.map(\.label), ["Session", "Program", "Folder", "Reading"])
         XCTAssertEqual(facts["Session"], "review-loop (Claude Code)")
-        XCTAssertEqual(facts["Program"], "claude · ~/repo/src/claude/index.ts")
+        XCTAssertEqual(facts["Program"], "claude · repo/src/claude/index.ts")
+        XCTAssertEqual(VaultWindowContent.programPath("/Users/alice/tools/run.ts", home: "/Users/alice"), "~/tools/run.ts")
         XCTAssertEqual(facts["Folder"], "~/project")
         XCTAssertEqual(facts["Reading"], "acc_work › longLivedToken")
         XCTAssertEqual(details["Started by"], "GenesisTools gt-claude (100) ← zsh (90) ← claude (80)")
@@ -141,6 +143,12 @@ final class VaultUnlockTests: XCTestCase {
         let who = caller(arguments: ["gt-say", "/repo/src/say/index.ts"], ancestors: [(90, "zsh"), (80, "codex exec")])
 
         XCTAssertEqual(VaultSession.info(who, claudeHome: "/nonexistent").summary, "codex exec (pid 80)")
+
+        let daemon = caller("/Users/alice/.bun/bin/bun", arguments: ["/Users/alice/.bun/bin/bun", "run", "/repo/src/ai/commands/usage/poll-daemon.ts"],
+                            ancestors: [(4904, "bun usage-supervisor.ts")])
+        let content = VaultWindowContent.build(VaultUnlockParams(tool: "ai", purpose: "refresh", secret: nil, command: nil), caller: daemon,
+                                               session: VaultSessionInfo(), home: "/Users/alice")
+        XCTAssertEqual(content.facts.first?.value, "None: started by bun usage-supervisor.ts")
     }
 
     func testTheAppCopyOfTheKeyAnswersOnlyForTheSourceItWasTakenFrom() {
@@ -168,6 +176,45 @@ final class VaultUnlockTests: XCTestCase {
         XCTAssertEqual(content.warning, "Unverified: its binary or script could not be established. It will not be remembered.")
     }
 
+    /// Draws the real window into a window that is never shown, for review: `APPROVAL_SNAPSHOT_DIR=<dir>` writes
+    /// `vault-window.png` and `vault-window-details.png`. Skipped otherwise.
+    @MainActor
+    func testRenderTheVaultWindowWhenAsked() throws {
+        guard let dir = ProcessInfo.processInfo.environment["APPROVAL_SNAPSHOT_DIR"] else {
+            throw XCTSkip("set APPROVAL_SNAPSHOT_DIR to render the window")
+        }
+
+        let daemon = caller("/Users/alice/.bun/bin/bun",
+                            arguments: ["/Users/alice/.bun/bin/bun", "run", "/Users/alice/Projects/GenesisTools/src/ai/commands/usage/poll-daemon.ts"],
+                            environment: ["CLAUDE_CODE_SESSION_ID=0f3a9c1e-5b7d-4e2a-9f10-2c4b6d8e0a13", "CMUX_SURFACE_ID=D5A60715-1C64-4556-ADB6-2D0B14E12FEB"],
+                            ancestors: [(4904, "bun usage-supervisor.ts"), (812, "zsh"), (640, "claude")])
+        let params = VaultUnlockParams(tool: "ai", purpose: "refresh the usage of every AI account (the usage daemon, once a minute in the background)",
+                                       secret: "ai/acc_work/accessToken", command: nil)
+        let session = VaultSessionInfo(sessionId: "0f3a9c1e-5b7d-4e2a-9f10-2c4b6d8e0a13", title: "review-loop", agent: nil,
+                                       cmuxTab: "D5A60715-1C64-4556-ADB6-2D0B14E12FEB")
+        let content = VaultWindowContent.build(params, caller: daemon, session: session, home: "/Users/alice")
+
+        for (name, open) in [("vault-window", false), ("vault-window-details", true)] {
+            let model = ApprovalDialogModel(
+                title: content.title, purpose: content.purpose, symbol: "key.fill", facts: content.facts, details: content.details,
+                warning: content.warning, footnote: VaultWindowContent.footnote, rememberChoices: VaultWindowContent.rememberChoices,
+                rememberNote: nil, allowTitle: "Allow with Touch ID", deadline: Date().addingTimeInterval(170), identifier: "vault-unlock")
+            model.showsDetails = open
+            let host = NSHostingView(rootView: ApprovalDialogView(model: model)
+                .background(Color(nsColor: .windowBackgroundColor))
+                .environment(\.colorScheme, .dark))
+            host.frame = CGRect(origin: .zero, size: host.fittingSize)
+            let window = NSWindow(contentRect: host.frame, styleMask: [.borderless], backing: .buffered, defer: false)
+            window.appearance = NSAppearance(named: .darkAqua)
+            window.contentView = host
+            host.layoutSubtreeIfNeeded()
+            let rep = try XCTUnwrap(host.bitmapImageRepForCachingDisplay(in: host.bounds))
+            host.cacheDisplay(in: host.bounds, to: rep)
+            let png = try XCTUnwrap(rep.representation(using: .png, properties: [:]))
+            try png.write(to: URL(fileURLWithPath: (dir as NSString).appendingPathComponent("\(name).png")))
+        }
+    }
+
     func testASecondRequestFromTheSameProgramGetsNoSecondWindow() throws {
         let path = (NSTemporaryDirectory() as NSString).appendingPathComponent("vault-window-test-\(UUID().uuidString).lock")
         defer { try? FileManager.default.removeItem(atPath: path) }

From 5ed9013b0d6709b26e71f11aab1b316e1d079796 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 00:50:10 +0200
Subject: [PATCH 16/32] fix(ai, macos): a vault approval remembers a relative
 script by its path in the caller's folder, because bun scratch/x.ts matched
 the same approval from any folder

(cherry picked from commit f08a346c62f2b3c2f6927e0e6c24ae16a37fcf35)
---
 src/macos/GenesisTools/Sources/VaultUnlock.swift    | 7 ++++++-
 src/macos/GenesisTools/Tests/VaultUnlockTests.swift | 3 +++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/macos/GenesisTools/Sources/VaultUnlock.swift b/src/macos/GenesisTools/Sources/VaultUnlock.swift
index 6fcd4aa704..23bc99f082 100644
--- a/src/macos/GenesisTools/Sources/VaultUnlock.swift
+++ b/src/macos/GenesisTools/Sources/VaultUnlock.swift
@@ -67,7 +67,12 @@ struct VaultCaller {
     /// The script an interpreter runs (`bun run …/src/ai/commands/usage/poll-daemon.ts`): with the executable, the
     /// identity a remembered approval is for.
     var script: String? {
-        scriptIndex.flatMap { args?.arguments[$0] }
+        guard let raw = scriptIndex.flatMap({ args?.arguments[$0] }) else { return nil }
+        if raw.hasPrefix("/") { return (raw as NSString).standardizingPath }
+        // `bun scratch/x.ts` names a different program in every folder: remembered as typed, an approval matched
+        // the same relative path anywhere (live check, 2026-10-15 00:49). Without the working folder it is unknown.
+        guard let cwd else { return nil }
+        return ((cwd as NSString).appendingPathComponent(raw) as NSString).standardizingPath
     }
 
     /// bun, node, deno, or a `gt-<tool>` link of bun: the program is the script, not the executable.
diff --git a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
index a243689a84..910703e7c2 100644
--- a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
+++ b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
@@ -51,6 +51,9 @@ final class VaultUnlockTests: XCTestCase {
         let hook = caller(arguments: ["gt-claude", "/repo/hooks/statusline.ts"])
         XCTAssertEqual(hook.toolName, "claude", "no src/<tool>/ in the script: the gt- link names the tool")
 
+        let relative = caller("/Users/alice/.bun/bin/bun", arguments: ["/Users/alice/.bun/bin/bun", "scratch/../scratch/x.ts"])
+        XCTAssertEqual(relative.script, "/Users/alice/project/scratch/x.ts", "a relative script is the one in the caller's folder")
+
         let bare = caller("/Users/alice/.bun/bin/bun", arguments: ["/Users/alice/.bun/bin/bun", "repl"])
         XCTAssertNil(bare.script)
         XCTAssertEqual(bare.onceOnlyReason, "the script it runs is not known")

From aceee4f7d411b491bf695082e143feae98392056 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 05:20:24 +0200
Subject: [PATCH 17/32] fix(ai, macos): a vault approval for a bun script holds
 under every GenesisTools launcher, because the usage daemon starts as bun,
 gt-services, gt-claude or gt-codex (hard links of one bun) and asked again
 under each after Always

(cherry picked from commit 8fcda6f4dff429178771e8f2ad9b73e8081928e1)
---
 .../GenesisTools/Sources/VaultUnlock.swift    | 31 ++++++++++++++++---
 .../GenesisTools/Tests/VaultUnlockTests.swift | 23 ++++++++++++++
 2 files changed, 49 insertions(+), 5 deletions(-)

diff --git a/src/macos/GenesisTools/Sources/VaultUnlock.swift b/src/macos/GenesisTools/Sources/VaultUnlock.swift
index 23bc99f082..5f16790030 100644
--- a/src/macos/GenesisTools/Sources/VaultUnlock.swift
+++ b/src/macos/GenesisTools/Sources/VaultUnlock.swift
@@ -333,15 +333,36 @@ enum VaultGrants {
         return file
     }
 
-    static func live(executable: String, script: String?, now: Int64, in file: VaultGrantsFile) -> VaultGrant? {
-        file.grants.last { $0.executable == executable && $0.script == script && !$0.isTooBroad && $0.isLive(at: now) }
+    /// The runtime a grant is keyed by. Bun and GenesisTools' `gt-<tool>` launchers are one program: every launcher is
+    /// a hard link of `~/.bun/bin/bun`, and which one starts a script depends on the tool that spawned it. The usage
+    /// daemon ran as bun, gt-services, gt-claude and gt-codex on one morning (2026-10-15), and each asked again for the
+    /// same script after "Always". Only these paths count, so a binary elsewhere that calls itself bun still asks.
+    static func runtime(of executable: String, home: String = genesisHome()) -> String {
+        let bun = ["\(home)/.bun/bin/bun", "/opt/homebrew/bin/bun", "/usr/local/bin/bun"]
+        let launchers = "\(home)/.genesis-tools/bin/"
+        let isLauncher = executable.hasPrefix(launchers) && (executable as NSString).lastPathComponent.hasPrefix("gt-")
+            && !executable.dropFirst(launchers.count).contains("/")
+        return bun.contains(executable) || isLauncher ? "bun" : executable
+    }
+
+    static func sameProgram(_ grant: VaultGrant, executable: String, script: String?, home: String = genesisHome()) -> Bool {
+        grant.script == script && runtime(of: grant.executable, home: home) == runtime(of: executable, home: home)
+    }
+
+    static func live(executable: String, script: String?, now: Int64, in file: VaultGrantsFile,
+                     home: String = genesisHome()) -> VaultGrant? {
+        file.grants.last {
+            sameProgram($0, executable: executable, script: script, home: home) && !$0.isTooBroad && $0.isLive(at: now)
+        }
     }
 
     /// Replaces any grant for the same program and drops expired and too-broad ones.
-    static func remember(_ grant: VaultGrant, now: Int64, in file: VaultGrantsFile) -> VaultGrantsFile {
+    static func remember(_ grant: VaultGrant, now: Int64, in file: VaultGrantsFile,
+                         home: String = genesisHome()) -> VaultGrantsFile {
         var next = file
         next.grants = file.grants.filter {
-            !($0.executable == grant.executable && $0.script == grant.script) && !$0.isTooBroad && $0.isLive(at: now)
+            !sameProgram($0, executable: grant.executable, script: grant.script, home: home) && !$0.isTooBroad
+                && $0.isLive(at: now)
         } + [grant]
         return next
     }
@@ -629,7 +650,7 @@ func unlockVault(_ params: VaultUnlockParams) {
         emitVaultKey(remembered: true)
     }
 
-    guard VaultWindowLock.acquire(VaultWindowLock.path(for: "vault|\(executable)|\(caller.script ?? "")")) != nil else {
+    guard VaultWindowLock.acquire(VaultWindowLock.path(for: "vault|\(VaultGrants.runtime(of: executable))|\(caller.script ?? "")")) != nil else {
         vaultAudit("denied", params: params, caller: caller, session: session, detail: "an approval window for this program is already open")
         vaultDeny("an approval window for “\(tool)” is already open; answer that one first")
     }
diff --git a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
index 910703e7c2..02e5f69507 100644
--- a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
+++ b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
@@ -83,6 +83,29 @@ final class VaultUnlockTests: XCTestCase {
                                          in: VaultGrants.remember(always, now: 1_000, in: file)), "always lasts until revoked")
     }
 
+    func testBunAndEveryGtLauncherAreOneProgramForTheSameScript() {
+        let home = "/Users/alice"
+        let daemon = "/repo/src/ai/commands/usage/poll-daemon.ts"
+        let grant = VaultGrant(key: "k", tool: "ai", executable: "\(home)/.bun/bin/bun", script: daemon,
+                               grantedAt: 1_000, until: nil, method: "touch-id")
+        let file = VaultGrants.remember(grant, now: 1_000, in: VaultGrantsFile(version: 1, grants: []), home: home)
+
+        for launcher in ["\(home)/.genesis-tools/bin/gt-codex", "\(home)/.genesis-tools/bin/gt-services", "\(home)/.bun/bin/bun"] {
+            XCTAssertNotNil(VaultGrants.live(executable: launcher, script: daemon, now: 2_000, in: file, home: home), launcher)
+        }
+
+        XCTAssertNil(VaultGrants.live(executable: "/tmp/evil/bun", script: daemon, now: 2_000, in: file, home: home),
+                     "a binary elsewhere that calls itself bun is not the runtime")
+        XCTAssertNil(VaultGrants.live(executable: "\(home)/.genesis-tools/bin/sub/gt-x", script: daemon, now: 2_000, in: file, home: home))
+        XCTAssertNil(VaultGrants.live(executable: "\(home)/.genesis-tools/bin/gt-codex", script: "/repo/src/other.ts",
+                                      now: 2_000, in: file, home: home), "the script still decides")
+
+        let again = VaultGrant(key: "k2", tool: "ai", executable: "\(home)/.genesis-tools/bin/gt-claude", script: daemon,
+                               grantedAt: 3_000, until: nil, method: "touch-id")
+        XCTAssertEqual(VaultGrants.remember(again, now: 3_000, in: file, home: home).grants, [again],
+                       "one grant per runtime and script, not one per launcher")
+    }
+
     func testAGrantWithoutAScriptForAnInterpreterMatchesNothingAndGoesOnTheNextWrite() {
         let broad = VaultGrant(key: "vault|bun|/Users/alice/.bun/bin/bun|", tool: "bun", executable: "/Users/alice/.bun/bin/bun",
                                script: nil, grantedAt: 1_000, until: nil, method: "touch-id")

From 95816a79140f19248bdd3d3d5a51927c8b1f6236 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 06:17:37 +0200
Subject: [PATCH 18/32] fix(grok): a writable worker turn runs with
 --always-approve, because headless grok 1.0.52 resolved some shell commands
 (nested sh -c, ; chains) as a cancelled permission prompt and ended the whole
 turn before the command ran

(cherry picked from commit 95ac7894f220e497f26f0c73c67b48b554a27eaf)
---
 .../skills/handoff-to/references/grok.md      |  4 +-
 src/grok/README.md                            |  7 ++--
 src/grok/lib/worker.isolation.test.ts         | 29 +++++++++++++++
 src/grok/lib/worker.ts                        | 37 ++++++++++++-------
 4 files changed, 59 insertions(+), 18 deletions(-)

diff --git a/plugins/genesis-tools/skills/handoff-to/references/grok.md b/plugins/genesis-tools/skills/handoff-to/references/grok.md
index 8fd6a6d4ab..7e1804d9fb 100644
--- a/plugins/genesis-tools/skills/handoff-to/references/grok.md
+++ b/plugins/genesis-tools/skills/handoff-to/references/grok.md
@@ -60,8 +60,8 @@ tools grok sessions [--json]
 | Intent | How | Verified behavior |
 |---|---|---|
 | read-only (review, second opinion) | `--readonly` | Worker gets only `read_file,list_dir,grep` — it physically lacks edit and terminal tools; edit attempts are denied and files stay untouched |
-| implementation (default) | no flag | Headless default is **Auto mode — a project jail**: edits and commands inside `--cwd` run without approval; any write outside the project is blocked with a denial message the worker sees and reports |
-| full trust | not exposed | On purpose. For risky work, give the worker a disposable worktree and keep the default jail |
+| implementation (default) | no flag | The harness passes `--always-approve` on every writable turn: edits and commands run without approval. There is no project jail any more: on grok 1.0.52 a write to a path under $HOME was allowed in 0 ms with or without the flag (2026-10-15). Without the flag, a nested `sh -c` or a `;` chain could resolve as `cancelled` and end the whole turn |
+| full trust | same as the default | For risky work, give the worker a disposable worktree: nothing else bounds its writes |
 
 🛑 Never reach past the harness for safety flags — two raw-grok flags LOOK like safety dials and are not (both verified): `--permission-mode plan` does not restrict a headless run (the worker edited a file under it), and `--disallowed-tools` silently refuses to remove `run_terminal_command` (the worker appended via the shell instead).
 
diff --git a/src/grok/README.md b/src/grok/README.md
index 871e5f1b1d..2a0e567b68 100644
--- a/src/grok/README.md
+++ b/src/grok/README.md
@@ -68,13 +68,14 @@ worker isolation remains controlled by the worker launcher below.
 - **Two session stores.** `tools grok history` / `run --resume` list TUI dirs under `~/.grok/sessions` (and the worker-home copy of that layout). `tools grok sessions` lists headless workers under `~/.genesis-tools/grok/sessions/<name>.meta.json`. Those are not the same inventory.
 - **TUI resume is not the worker.** Bare `--resume` on `run` launches native `grok --resume` in your normal environment. A query selects an indexed session and launches `grok -r <id>` with that session's `GROK_HOME`, so a worker-home result is not looked up in a different personal home. Neither calls `runSession` or mutates the parent environment. Worker mode still needs `--name` and `--cwd` with `--resume` absent.
 - **Session bookkeeping.** The worker uuid and cwd are stored in `~/.genesis-tools/grok/sessions/<name>.meta.json`; `steer` resumes with the identical `--cwd` automatically (grok keys sessions by cwd).
-- **Sticky read-only.** The grok CLI forgets `--tools` on every `--resume`; the harness re-arms the read-only allowlist on each steer of a `--readonly` session. `steer --writable` switches the session back to the project jail deliberately.
+- **Sticky permission flags.** The grok CLI forgets `--tools` and `--always-approve` on every `--resume`; the harness re-arms the read-only allowlist on each steer of a `--readonly` session, and `--always-approve` on each writable turn. `steer --writable` switches the session back to writable mode deliberately.
 - **Honest exit codes.** The grok CLI exits 0 even when a turn dies. `tools grok` parses the stream and exits 1 when no terminal `end` event is present.
 - **One claim per name, one transcript per turn.** `run` reserves the session name with `O_EXCL`, and each turn reserves its own log file the same way, so two concurrent invocations cannot both start turn 1 or truncate each other's transcript.
 
-## Safety model (verified against grok CLI 1.0.3, 2026-08-26)
+## Safety model (re-verified against grok CLI 1.0.52, 2026-10-15)
 
-- Default headless mode is a **project jail**: edits and commands inside `--cwd` run without approval; writes outside are blocked with a denial the worker sees.
+- A writable turn runs with `--always-approve`. Nobody can answer a permission prompt in a headless turn: without the flag, grok sent a nested `sh -c` or a `;` chain through a 1-6 s gate, and a verdict other than "allow" came back as `cancelled` and ended the whole turn before the command ran. `--allow Bash` does not stop that gate.
+- There is **no project jail**. The jail verified on 1.0.3 is gone: on 1.0.52 a write to a path under $HOME was allowed in 0 ms with and without `--always-approve`. Give a writable worker a disposable worktree.
 - `--readonly` maps to the `--tools read_file,list_dir,grep` allowlist — the worker physically lacks edit and terminal tools.
 - Do not hand-roll bare `grok` flags for safety: `--permission-mode plan` does not restrict headless runs, and `--disallowed-tools` silently keeps `run_terminal_command`.
 
diff --git a/src/grok/lib/worker.isolation.test.ts b/src/grok/lib/worker.isolation.test.ts
index 53e44cf93b..eaf3272901 100644
--- a/src/grok/lib/worker.isolation.test.ts
+++ b/src/grok/lib/worker.isolation.test.ts
@@ -170,6 +170,35 @@ describe("read-only tool restriction", () => {
     });
 });
 
+/**
+ * Regression test: 2026-10-15, grok 1.0.52. Without a permission mode a headless
+ * worker sends some shell commands (a nested `sh -c`, a `;` chain) through a
+ * gate that takes 1-6 s. Nobody can answer it, and a verdict that is not
+ * "allow" came back as `permission_resolved: cancelled`, which ended the whole
+ * turn (`stopReason: cancelled`) before the command ran. `--always-approve`
+ * resolves the same calls in 0 ms; `--allow Bash` does not (the nested-shell
+ * floor still applies). The CLI forgets flags on `--resume`, so every writable
+ * turn must carry it.
+ */
+describe("headless permission mode", () => {
+    test("a writable run approves tool calls, because no one can answer a headless prompt", () => {
+        expect(buildRunArgs({ sessionId: "s-1", model: undefined, readOnly: false }, ["-p", "hi"])).toContain(
+            "--always-approve"
+        );
+    });
+
+    test("a resumed writable session is re-armed, because the CLI forgets the flag", () => {
+        expect(buildSteerArgs({ sessionId: "s-1" }, false, ["-p", "again"])).toContain("--always-approve");
+    });
+
+    test("a read-only session never gets always-approve", () => {
+        expect(buildRunArgs({ sessionId: "s-1", model: undefined, readOnly: true }, ["-p", "hi"])).not.toContain(
+            "--always-approve"
+        );
+        expect(buildSteerArgs({ sessionId: "s-1" }, true, ["-p", "again"])).not.toContain("--always-approve");
+    });
+});
+
 describe("interrupted initial launch", () => {
     test("retries session creation before using resume", () => {
         const meta = {
diff --git a/src/grok/lib/worker.ts b/src/grok/lib/worker.ts
index f992a870f0..ec8bf31d68 100644
--- a/src/grok/lib/worker.ts
+++ b/src/grok/lib/worker.ts
@@ -42,6 +42,24 @@ const SIDE_EFFECT_ENV: Record<string, string> = {
 
 const READ_ONLY_TOOLS = "read_file,list_dir,grep";
 
+/**
+ * The tool and permission flags of one turn, re-armed on EVERY turn because the
+ * grok CLI forgets them on `--resume`.
+ *
+ * Read-only: the `--tools` allowlist, so the worker has no edit or terminal tool.
+ * Writable: `--always-approve`. A headless turn has nobody to answer a permission
+ * prompt. Without a mode, grok 1.0.52 sends some shell commands (a nested `sh -c`,
+ * a `;` chain) through a 1-6 s gate, and a verdict other than "allow" resolves as
+ * `cancelled`, which ends the whole turn before the command runs (2026-10-15,
+ * bs-521 and bs-94). `--allow Bash` does not help: the nested-shell floor still
+ * applies. Deny rules still apply under always-approve, and the default mode no
+ * longer jails edits to `--cwd` anyway (a write to a path under $HOME was allowed
+ * in 0 ms in both modes).
+ */
+function permissionArgs(readOnly: boolean): string[] {
+    return readOnly ? ["--tools", READ_ONLY_TOOLS] : ["--always-approve"];
+}
+
 export type GrokAuthMode = "subscription" | "api-key";
 
 /**
@@ -174,18 +192,15 @@ export function buildRunArgs(
         args.push("-m", session.model);
     }
 
-    if (session.readOnly) {
-        args.push("--tools", READ_ONLY_TOOLS);
-    }
-
-    args.push(...contractArgs(session.readOnly, session.surfaces));
+    args.push(...permissionArgs(session.readOnly), ...contractArgs(session.readOnly, session.surfaces));
     return args;
 }
 
 /**
- * Arguments for a resumed turn. `--tools` is re-armed every time because the
- * grok CLI drops safety flags on `--resume`; without this a session started
- * read-only silently gains write tools from turn 2 onward.
+ * Arguments for a resumed turn. `permissionArgs` is re-armed every time because
+ * the grok CLI drops safety flags on `--resume`; without this a session started
+ * read-only silently gains write tools from turn 2 onward, and a writable one
+ * loses always-approve.
  */
 export function buildSteerArgs(
     session: { sessionId: string; surfaces?: WorkerSurfaces },
@@ -193,11 +208,7 @@ export function buildSteerArgs(
     promptArguments: string[]
 ): string[] {
     const args = [...promptArguments, "--resume", session.sessionId];
-    if (readOnly) {
-        args.push("--tools", READ_ONLY_TOOLS);
-    }
-
-    args.push(...contractArgs(readOnly, session.surfaces));
+    args.push(...permissionArgs(readOnly), ...contractArgs(readOnly, session.surfaces));
     return args;
 }
 

From 2f5c83323cdb64f0e69d627d5b5c9440a4ca0c51 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 06:39:15 +0200
Subject: [PATCH 19/32] fix(agents, hooks): #520 followup - diff log keeps
 reading for a background task's flusher after the task's own command, because
 a subagent's call can print it from another transcript

(cherry picked from commit 0e42014d6c2b69f43e12f7111c77e832fef074b5)
---
 src/agents/lib/hooks/diff-log.ts       | 64 +++++++++++++++++---------
 src/agents/lib/hooks/diff/diff.test.ts | 44 ++++++++++++++++++
 2 files changed, 86 insertions(+), 22 deletions(-)

diff --git a/src/agents/lib/hooks/diff-log.ts b/src/agents/lib/hooks/diff-log.ts
index 6235cd779c..f4a5cba50e 100644
--- a/src/agents/lib/hooks/diff-log.ts
+++ b/src/agents/lib/hooks/diff-log.ts
@@ -369,33 +369,43 @@ function readChunk(
 }
 
 /**
- * Reads `file` from the end until every selected call has its command, a line is older than
- * `floor`, or the start of the file. Each read is one fixed chunk. Only lines that name a
- * still-wanted call are parsed.
+ * The calls whose message holds a selected background task's blocks and has not been read yet.
+ * Only a task that printed something: its flusher's message is then not empty.
+ */
+function pendingFlushers(calls: Map<string, DiffLogEntry>): Set<string> {
+    return new Set(
+        [...calls.values()].flatMap((entry) =>
+            entry.flushedBy && entry.task && entry.decision === "emitted" && !entry.blocks ? [entry.flushedBy] : []
+        )
+    );
+}
+
+/**
+ * Reads `file` from the end until every selected call has its command and every pending flusher
+ * its message, a line is older than `floor`, or the start of the file. Each read is one fixed
+ * chunk. Only lines that name a still-wanted call or flusher are parsed. Both sets are shared
+ * across the session's files, because a subagent's call can flush a task the main transcript ran.
  */
 function hydrateTail({
     file,
     calls,
     agent,
     wanted,
+    flushers,
     floor,
 }: {
     file: string;
     calls: Map<string, DiffLogEntry>;
     agent: string | undefined;
     wanted: Set<string>;
+    flushers: Set<string>;
     floor: number;
 }): { parsed: number; linesSeen: number; widestRead: number } {
     let parsed = 0;
     let linesSeen = 0;
     let widestRead = 0;
     let fd: number;
-    // A background task's blocks are in the message of the later call that printed them.
-    const flushers = new Set(
-        [...calls.values()].flatMap((entry) =>
-            entry.flushedBy && wanted.has(entry.toolUseId) ? [entry.flushedBy] : []
-        )
-    );
+    const searching = () => wanted.size > 0 || flushers.size > 0;
 
     try {
         fd = openSync(file, "r");
@@ -407,7 +417,7 @@ function hydrateTail({
         let end = fstatSync(fd).size;
         let held: Buffer = Buffer.alloc(0);
 
-        while (wanted.size > 0 && end > 0) {
+        while (searching() && end > 0) {
             const chunk = readChunk(fd, end, held);
             held = chunk.held;
             widestRead = Math.max(widestRead, chunk.read);
@@ -435,7 +445,11 @@ function hydrateTail({
                 parsed += 1;
 
                 try {
-                    readRow({ row: SafeJSON.parse(line, { strict: true }), calls, agent });
+                    const printed = readRow({ row: SafeJSON.parse(line, { strict: true }), calls, agent });
+
+                    if (printed) {
+                        flushers.delete(printed);
+                    }
                 } catch {
                     // The line names a selected call and is not one JSON value.
                 }
@@ -444,12 +458,12 @@ function hydrateTail({
                     wanted.delete(id);
                 }
 
-                if (wanted.size === 0) {
+                if (!searching()) {
                     break;
                 }
             }
 
-            if (aged || chunk.done || wanted.size === 0) {
+            if (aged || chunk.done || !searching()) {
                 break;
             }
 
@@ -511,8 +525,9 @@ function field(value: unknown, key: string): unknown {
 
 /**
  * Fills the transcript fields of Claude entries in place. The main transcript is read from the
- * end, and a subagent file is opened only when a selected call still has no command and the file
- * was modified inside the horizon. Returns how much was opened, so a bound can be tested.
+ * end, and a subagent file is opened only when a selected call still has no command, or a selected
+ * background task's flusher no message, and the file was modified inside the horizon. Returns how
+ * much was opened, so a bound can be tested.
  */
 export function extendFromTranscripts(entries: DiffLogEntry[]): {
     files: number;
@@ -546,25 +561,26 @@ export function extendFromTranscripts(entries: DiffLogEntry[]): {
         }
 
         const wanted = new Set(calls.keys());
+        const flushers = pendingFlushers(calls);
         const floor = oldestAt(calls) - TRANSCRIPT_HORIZON_MS;
-        const mainCounts = hydrateTail({ file: main, calls, agent: undefined, wanted, floor });
+        const mainCounts = hydrateTail({ file: main, calls, agent: undefined, wanted, flushers, floor });
         files += 1;
         parsed += mainCounts.parsed;
         linesSeen += mainCounts.linesSeen;
         widestRead = Math.max(widestRead, mainCounts.widestRead);
 
-        if (wanted.size === 0) {
+        if (wanted.size === 0 && flushers.size === 0) {
             continue;
         }
 
         for (const file of recentSubagents(main, floor)) {
-            const counts = hydrateTail({ file, calls, agent: basename(file, ".jsonl"), wanted, floor });
+            const counts = hydrateTail({ file, calls, agent: basename(file, ".jsonl"), wanted, flushers, floor });
             files += 1;
             parsed += counts.parsed;
             linesSeen += counts.linesSeen;
             widestRead = Math.max(widestRead, counts.widestRead);
 
-            if (wanted.size === 0) {
+            if (wanted.size === 0 && flushers.size === 0) {
                 break;
             }
         }
@@ -581,7 +597,7 @@ function readRow({
     row: unknown;
     calls: Map<string, DiffLogEntry>;
     agent: string | undefined;
-}): void {
+}): string | undefined {
     const content = field(field(row, "message"), "content");
 
     for (const item of Array.isArray(content) ? content : []) {
@@ -629,14 +645,14 @@ function readRow({
         const flushed = [...calls.values()].filter((item) => item.flushedBy === id && item.task && !item.blocks);
 
         if (stdout.length === 0 || ((!entry || entry.blocks) && flushed.length === 0)) {
-            return;
+            return undefined;
         }
 
         try {
             const message = text(field(SafeJSON.parse(stdout, { strict: true }), "systemMessage"));
 
             if (message.length === 0) {
-                return;
+                return undefined;
             }
 
             const read = readMessage(message);
@@ -655,10 +671,14 @@ function readRow({
                     item.notes = part.notes;
                 }
             }
+
+            return id;
         } catch {
             // Another hook's output on the same event.
         }
     }
+
+    return undefined;
 }
 
 function localTime(at: string): string {
diff --git a/src/agents/lib/hooks/diff/diff.test.ts b/src/agents/lib/hooks/diff/diff.test.ts
index 3c549234f5..2f13dc6483 100644
--- a/src/agents/lib/hooks/diff/diff.test.ts
+++ b/src/agents/lib/hooks/diff/diff.test.ts
@@ -3971,6 +3971,50 @@ describe("tools agents hooks diff log", () => {
                 expect(early.command).toContain("EARLY-COMMAND");
                 // Each read stays one 64 KiB chunk. Growing the window made the next read 256 KiB.
                 expect(earlyStats.widestRead).toBeLessThanOrEqual(64 * 1024);
+
+                // A background task run in the main transcript and printed by a subagent's later call:
+                // its blocks are in that subagent's transcript, read after the task's command is found.
+                const flushedSession = "gt-bound-flushed";
+                const now = new Date().toISOString();
+
+                writeFileSync(
+                    join(project, `${flushedSession}.jsonl`),
+                    `${toolLine("toolu_task", "bun /x/long.ts", now)}\n`
+                );
+                mkdirSync(join(project, flushedSession, "subagents"), { recursive: true });
+
+                const message = [
+                    "background task bgflush ended (bun /x/long.ts):",
+                    "Added src/flushed.ts (+1 -0)",
+                    "     1 +flushed",
+                ].join("\n");
+
+                writeFileSync(
+                    join(project, flushedSession, "subagents", "agent-flusher.jsonl"),
+                    `${SafeJSON.stringify({
+                        type: "attachment",
+                        timestamp: now,
+                        attachment: {
+                            type: "hook_success",
+                            hookEvent: "PostToolUse",
+                            toolUseID: "toolu_flusher",
+                            stdout: SafeJSON.stringify({ systemMessage: message }),
+                        },
+                    })}\n`
+                );
+
+                const flushed: DiffLogEntry = {
+                    ...entry,
+                    session: flushedSession,
+                    toolUseId: "toolu_task",
+                    task: "bgflush",
+                    flushedBy: "toolu_flusher",
+                };
+
+                extendFromTranscripts([flushed]);
+
+                expect(flushed.command).toContain("bun /x/long.ts");
+                expect(flushed.blocks?.map((block) => block.path)).toEqual(["src/flushed.ts"]);
             });
         } finally {
             rmSync(home, { recursive: true, force: true });

From 24d272da01915929cf080c47f4783ea7b25d246e Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Tue, 13 Oct 2026 20:29:29 +0200
Subject: [PATCH 20/32] fix(mcp-manager): a global Claude disable removes the
 server from mcpServers again, because no project can lift a deny

(cherry picked from commit da023889de4faf4925255db2c194378b21f49d49)
---
 src/mcp-manager/README.md                     | 119 ++---
 .../__tests__/claude-global-disable.test.ts   | 179 ++-----
 .../__tests__/claude-project-override.test.ts |  54 +--
 src/mcp-manager/commands/rename.ts            |   9 +-
 src/mcp-manager/utils/providers/claude.ts     | 444 +++++++-----------
 src/mcp-manager/utils/providers/grok.ts       |  46 --
 6 files changed, 240 insertions(+), 611 deletions(-)

diff --git a/src/mcp-manager/README.md b/src/mcp-manager/README.md
index abab3eda1a..eddc16a0e9 100644
--- a/src/mcp-manager/README.md
+++ b/src/mcp-manager/README.md
@@ -157,30 +157,20 @@ The tool uses a unified configuration file at `~/.genesis-tools/mcp-manager/conf
 
 -   Supports global and project-specific server configurations
 -   Supports stdio, SSE, and HTTP transports
--   **Global disable = a `deniedMcpServers` entry in `~/.claude/settings.json`**
-    (see below); the config stays in `mcpServers`
+-   **Global disable = removal from `mcpServers`** (see below)
 
 #### Claude enable/disable semantics
 
-Verified on Claude Code 2.1.296 (research note
-`2026-10-13-ClaudeCodeGlobalMcpSwitch.md`): the only
-global switch for one server is a `deniedMcpServers: [{ "serverName": "<name>" }]`
-entry in `~/.claude/settings.json`. It covers every project, also one registered
-later, and the config stays in `mcpServers`. Claude Code reads
-`disabledMcpServers` **only** from the current project entry
-(`.projects[<cwd>].disabledMcpServers`); the **top-level `disabledMcpServers` key
-in `~/.claude.json` is never read**. mcp-manager no longer writes it, and `sync`
-removes it.
-
-What a denied server looks like in Claude Code:
-
--   It is ABSENT from `claude mcp list` and `/mcp`, not shown as "disabled";
-    `claude mcp get <name>` says `No MCP server named "<name>"`.
--   `/mcp` cannot turn it back on: the error blames "enterprise managed policy",
-    although the entry is in your user settings. Use `tools mcp-manager enable`.
--   The deny matches the name in every scope, so a project-scope entry or a
-    `.mcp.json` server of the same name is blocked too. A per-project enable
-    therefore cannot override a global disable; the command warns about this.
+Verified against the Claude Code binary (2.1.296, research note
+`2026-10-13-ClaudeCodeGlobalMcpSwitch.md`): Claude Code reads `disabledMcpServers`
+**only** from per-project entries (`.projects[<cwd>].disabledMcpServers`). The
+**top-level `disabledMcpServers` key is never read by Claude Code** — it is an
+mcp-manager-only marker. The only mechanism Claude Code honors globally
+(including future projects) that one project can still override is the server
+**not existing in `mcpServers` at all**. A `deniedMcpServers` entry in
+`~/.claude/settings.json` is global and costs no tokens, but no project setting
+can lift it (it also blocks a project-scope or `.mcp.json` server of the same
+name), so mcp-manager does not use it for a global disable.
 
 **Global means the global switch only.** A global disable, a global enable,
 an install and a `sync` never write the per-project `disabledMcpServers` lists
@@ -189,22 +179,21 @@ exception is `enable --clear-project-overrides` (below). A dry run of
 `sync` once wanted to add one disabled server to the lists of all 98 projects
 (about 640 diff lines). That is why the old sweep was removed on 2026-10-13.
 
+mcp-manager therefore implements a TRUE global disable for Claude:
+
 -   **Global disable** (`tools mcp-manager disable <server> --provider claude`):
-    1. Adds `{ "serverName": "<server>" }` to `deniedMcpServers` in
-       `~/.claude/settings.json` (once; other keys and entries stay). This write
-       comes first: if you reject it, nothing else is written.
-    2. Records `_meta.enabled.claude = false` in the unified config (imports the
-       config there first if it is missing).
-    3. Keeps the entry in `mcpServers`. An entry that an older delete-based
-       disable removed is put back from the unified config, with one exception
-       for Grok (below).
-    4. Drops the name from the top-level marker.
--   **Global enable** puts the entry back into `mcpServers` when it is missing,
-    then removes exactly the `serverName` deny entry (a `serverUrl` pattern is
-    never touched; the key goes when the list is empty). It does not change
-    project lists. When some projects still list the server (old entries from
-    the removed sweep, or a per-project disable), the server stays off in those
-    projects, and one warning gives the count and the two commands below.
+    1. Preserves the server's full config in the unified config with
+       `_meta.enabled.claude = false` (imports it there first if missing —
+       the entry is never removed unless it is safely preserved). If the
+       config cannot be preserved, the entry stays and Claude Code still loads
+       the server everywhere; a warning says so.
+    2. Keeps the top-level marker.
+    3. **Removes the entry from `mcpServers`** in `~/.claude.json`.
+-   **Global enable** restores the entry into `mcpServers` from the unified
+    config and drops the top-level marker. It does not change project lists.
+    When some projects still list the server (old entries from the removed
+    sweep, or a per-project disable), the server stays off in those projects,
+    and one warning gives the count and the two commands below.
 -   **Global enable with `--clear-project-overrides`**
     (`tools mcp-manager enable <server> -p claude --clear-project-overrides`)
     also takes the name off every `.projects[<path>].disabledMcpServers` list
@@ -217,52 +206,42 @@ exception is `enable --clear-project-overrides` (below). A dry run of
 -   **Per-project disable or enable** (`--project <path>`) is the only command
     that writes a project's `disabledMcpServers` list, and only for the named
     projects. The global entry stays in `mcpServers`.
--   **`list` and `show`** read the global state from `deniedMcpServers`. A server
-    that is still absent from `~/.claude.json` with `_meta.enabled.claude = false`
-    shows as `disabled`, sourced from the unified config.
--   **`sync`**: `_meta.enabled.claude === false` puts the config into
-    `mcpServers` and denies the name; `true` removes its `serverName` deny entry;
-    an unset state or a per-project map leaves the denylist as it is. The first
-    sync after this change therefore migrates every server the old
-    delete-based disable removed: config back, deny added, no change in what
-    Claude Code loads. The denylist is written first; if you reject that write,
-    `~/.claude.json` is not written either. For `true`, `false` or an unset
-    state, `sync` writes no project list. For a per-project map
-    (`{ "/abs/path": false }`), it writes only the lists of the projects the map
-    names, and creates no project entry.
--   **Grok.** Grok loads `~/.claude.json` top-level `mcpServers` too, and
-    Claude's deny does not reach Grok. So an entry for a server that stays off in
-    Claude is put back only when Grok would not start it: Grok has its own
-    `config.toml` table for the name, lists it in `disabled_mcp_servers`, has
-    `[compat.claude] mcps = false`, or the unified config enables it for Grok.
-    Otherwise the entry stays out of `mcpServers` with a warning, and the deny
-    still keeps it off in Claude. A global ENABLE restores the entry
-    regardless: the server is meant to run, and Grok sees it as it always did.
--   **`sync-from-providers`** keeps `_meta.enabled.claude = false` for a denied
-    server, and does not interpret a missing entry as "user deleted it".
--   **`remove`** also removes the server's `serverName` deny entry, so a later
-    server of the same name is not blocked. **`rename`** moves the deny to the
-    new name.
+-   **`list`** shows globally-disabled servers (absent from `~/.claude.json`)
+    as `disabled` for claude — sourced from the unified config — instead of
+    "not installed".
+-   **`sync`** treats `_meta.enabled.claude === false` as disabled-by-absence:
+    such servers are never (re)installed into `mcpServers`, and drifted
+    entries are removed. For `true`, `false` or an unset state, `sync` writes
+    no project list. For a per-project map (`{ "/abs/path": false }`), it writes
+    only the lists of the projects the map names, and creates no project entry.
+-   **`sync-from-providers`** does not interpret the absence of a
+    globally-disabled server as "user deleted it" — the unified config entry
+    and its `_meta.enabled.claude = false` flag are preserved.
 
 #### Per-project enable override (claude)
 
+A global disable can be overridden for individual projects:
+
 ```bash
 tools mcp-manager enable <server> -p claude --project /abs/path [--project /other] [-y]
 ```
 
 -   Installs the server's claude-format config into
-    `.projects[<path>].mcpServers.<name>` in `~/.claude.json` when the global
-    entry is missing, and removes the name from that project's
+    `.projects[<path>].mcpServers.<name>` in `~/.claude.json` — Claude Code
+    DOES honor project-scope entries there (it's the same storage
+    `claude mcp add -s local` uses) — and removes the name from that project's
     `disabledMcpServers` list.
--   ⚠️ Against a global disable this no longer helps: the deny blocks the name in
-    every scope, project-scope entries included, and the command warns. To run a
-    server in some projects only, enable it globally and disable it with
-    `--project` where you do not want it.
--   The override is tracked solely by the presence of the project-scope entry —
-    no extra metadata. A global disable and `sync` never delete the
+-   The global state stays disabled: the server remains absent from the global
+    `mcpServers` and `_meta.enabled.claude` stays `false`. The override is
+    tracked solely by the presence of the project-scope entry — no extra
+    metadata.
+-   **Override-awareness:** a global disable and `sync` never delete the
     project-scope entry, and never put the name back on that project's
     `disabledMcpServers` list (a per-project map in `sync` skips that project
     too). `sync` refreshes the entry's config from the unified config.
+    `sync-from-providers` keeps `_meta.enabled.claude === false` even though
+    the override projects report the server as enabled.
+-   `list` shows such servers as `disabled globally, enabled in N project(s)`.
 -   Undo with `tools mcp-manager disable <server> -p claude --project <path>` —
     removes the project-scope entry and puts the name back on that project's
     disabled list.
diff --git a/src/mcp-manager/commands/__tests__/claude-global-disable.test.ts b/src/mcp-manager/commands/__tests__/claude-global-disable.test.ts
index aa125aa3b7..64572e1fd9 100644
--- a/src/mcp-manager/commands/__tests__/claude-global-disable.test.ts
+++ b/src/mcp-manager/commands/__tests__/claude-global-disable.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, mock, spyOn } from "bun:test";
-import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { atomicWriteIo } from "@genesiscz/utils/storage/atomic-file";
@@ -75,22 +75,6 @@ describe("claude provider TRUE global disable", () => {
         return SafeJSON.parse(readFileSync(claudeJsonPath(), "utf-8")) as ClaudeGenericConfig & Record<string, unknown>;
     };
 
-    const userSettingsPath = () => join(homeDir, ".claude", "settings.json");
-
-    const writeUserSettings = (settings: Record<string, unknown>) => {
-        mkdirSync(join(homeDir, ".claude"), { recursive: true });
-        writeFileSync(userSettingsPath(), `${SafeJSON.stringify(settings, null, 2)}\n`);
-    };
-
-    /** `deniedMcpServers` of the user settings: the real global switch of Claude Code. */
-    const readDenied = (): unknown => {
-        if (!existsSync(userSettingsPath())) {
-            return undefined;
-        }
-
-        return (SafeJSON.parse(readFileSync(userSettingsPath(), "utf-8")) as Record<string, unknown>).deniedMcpServers;
-    };
-
     const writeUnified = async (config: UnifiedMCPConfig) => {
         const storage = new Storage("mcp-manager");
         await storage.ensureDirs();
@@ -129,28 +113,20 @@ describe("claude provider TRUE global disable", () => {
     });
 
     describe("disableServer(name, null) — global", () => {
-        // Intended change 2026-10-13 (V-2): the global switch Claude Code honours is the
-        // user-settings deniedMcpServers list. The entry stays in mcpServers, and the top-level
-        // disabledMcpServers marker (which Claude Code never reads) is dropped.
-        it("denies the server in settings.json, keeps its entry, drops the marker, leaves every project alone", async () => {
+        // Intended change 2026-10-13: a global disable no longer sweeps the name into every
+        // project's disabledMcpServers list. Global means the global switch only.
+        it("removes the entry from mcpServers, keeps the top-level marker, leaves every project alone", async () => {
             writeClaudeJson(claudeFixture());
             await writeUnified(unifiedFixture());
-            writeUserSettings({ theme: "dark" });
 
             const provider = new ClaudeProvider();
             await provider.disableServer("serena", null);
 
             const claude = readClaudeJson();
-            expect(claude.mcpServers?.serena).toEqual(SERENA); // config kept
-            expect(readDenied()).toEqual([{ serverName: "serena" }]); // the global switch
-            expect((SafeJSON.parse(readFileSync(userSettingsPath(), "utf-8")) as Record<string, unknown>).theme).toBe(
-                "dark"
-            );
+            expect(claude.mcpServers?.serena).toBeUndefined(); // TRUE global disable
             expect(claude.mcpServers?.github).toBeDefined(); // untouched sibling
-            expect(claude.disabledMcpServers).toBeUndefined(); // the empty marker list is gone
+            expect(claude.disabledMcpServers).toContain("serena"); // mcp-manager marker
             expect(claude.projects).toEqual(claudeFixture().projects as ClaudeGenericConfig["projects"]); // no sweep
-            expect((await provider.listServers()).find((row) => row.name === "serena")?.enabled).toBe(false);
-            expect(await provider.isServerEnabled("serena")).toBe(false);
             // Unrelated state preserved (read-modify-write)
             expect(claude.numStartups).toBe(5);
             expect((claude.projects?.["/proj/a"] as Record<string, unknown> | undefined)?.history).toEqual([
@@ -176,11 +152,10 @@ describe("claude provider TRUE global disable", () => {
             expect(unified.mcpServers.serena.args).toEqual(["serena"]);
             expect(unified.mcpServers.serena._meta?.enabled?.claude).toBe(false);
 
-            expect(readClaudeJson().mcpServers?.serena).toBeDefined(); // kept: the deny is the switch
-            expect(readDenied()).toEqual([{ serverName: "serena" }]);
+            expect(readClaudeJson().mcpServers?.serena).toBeUndefined();
         });
 
-        it("still denies the server when the unified config write is rejected; nothing is removed", async () => {
+        it("does NOT remove the entry when it cannot be preserved in the unified config", async () => {
             writeClaudeJson(claudeFixture());
             await writeUnified({ mcpServers: {} });
 
@@ -191,59 +166,11 @@ describe("claude provider TRUE global disable", () => {
             await provider.disableServer("serena", null);
 
             const claude = readClaudeJson();
-            expect(claude.mcpServers?.serena).toBeDefined(); // the config never leaves ~/.claude.json
-            expect(readDenied()).toEqual([{ serverName: "serena" }]);
+            expect(claude.mcpServers?.serena).toBeDefined(); // kept — no data loss
+            expect(claude.disabledMcpServers).toContain("serena"); // marker still applied
             expect(claude.projects).toEqual(claudeFixture().projects as ClaudeGenericConfig["projects"]);
-        });
-
-        it("puts back an entry an older delete-based disable removed, unless Grok would start it", async () => {
-            const claude = claudeFixture();
-            delete (claude.mcpServers as Record<string, unknown>).serena;
-            delete (claude.mcpServers as Record<string, unknown>).github;
-            writeClaudeJson(claude);
-            await writeUnified(unifiedFixture());
-            // Grok reads ~/.claude.json mcpServers: github has a Grok table (Grok runs that one),
-            // serena has none, so a serena entry in ~/.claude.json would start serena in Grok.
-            mkdirSync(join(homeDir, ".grok"), { recursive: true });
-            writeFileSync(
-                join(homeDir, ".grok", "config.toml"),
-                TOML.stringify({ mcp_servers: { github: { command: "bunx", enabled: false } } })
-            );
-
-            await new ClaudeProvider().disableServers(["serena", "github"], null);
-
-            expect(readClaudeJson().mcpServers?.github).toEqual(GITHUB); // put back
-            expect(readClaudeJson().mcpServers?.serena).toBeUndefined(); // kept out because of Grok
-            expect(readDenied()).toEqual([{ serverName: "serena" }, { serverName: "github" }]);
-            expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("'serena' stays out of mcpServers"));
-        });
-
-        it("a sync puts the entry back despite Grok when the unified config enables it for Grok", async () => {
-            const claude = claudeFixture();
-            delete (claude.mcpServers as Record<string, unknown>).serena;
-            writeClaudeJson(claude);
-            const unified = unifiedFixture();
-            unified.mcpServers.serena._meta = { enabled: { claude: false, grok: true } };
-            await writeUnified(unified);
-            mkdirSync(join(homeDir, ".grok"), { recursive: true });
-            writeFileSync(join(homeDir, ".grok", "config.toml"), TOML.stringify({ disabled_mcp_servers: ["other"] }));
-
-            await new ClaudeProvider().syncServers({ serena: unified.mcpServers.serena });
-
-            expect(readClaudeJson().mcpServers?.serena).toEqual(SERENA); // Grok is meant to run it
-            expect(readDenied()).toEqual([{ serverName: "serena" }]); // Claude keeps it off
-        });
-
-        it("writes nothing to ~/.claude.json when the deny write is rejected", async () => {
-            const claude = claudeFixture();
-            delete (claude.mcpServers as Record<string, unknown>).serena;
-            writeClaudeJson(claude);
-            await writeUnified(unifiedFixture());
-            const before = readFileSync(claudeJsonPath(), "utf-8");
-            setGlobalOptions({}); // no --yes: every confirmation is answered "no" in a non-TTY
-
-            expect(await new ClaudeProvider().disableServers(["serena"], null)).toBe(WriteResult.Rejected);
-            expect(readFileSync(claudeJsonPath(), "utf-8")).toBe(before); // no restore without its deny
+            expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("NOT removed"));
+            expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("still loads it in every project"));
         });
     });
 
@@ -293,8 +220,6 @@ describe("claude provider TRUE global disable", () => {
         it("restores the entry, drops the top-level marker, leaves project lists and warns with the count", async () => {
             const projects = await listedEverywhere();
 
-            writeUserSettings({ deniedMcpServers: [{ serverName: "serena" }, { serverUrl: "https://other.test/*" }] });
-
             const provider = new ClaudeProvider();
             await provider.enableServer("serena", null);
 
@@ -302,8 +227,7 @@ describe("claude provider TRUE global disable", () => {
             expect(result.mcpServers?.serena).toBeDefined(); // restored
             expect(result.mcpServers?.serena.command).toBe("uvx");
             expect((result.mcpServers?.serena as Record<string, unknown> | undefined)?._meta).toBeUndefined(); // no _meta leak
-            expect(result.disabledMcpServers).toBeUndefined(); // the marker is gone
-            expect(readDenied()).toEqual([{ serverUrl: "https://other.test/*" }]); // only its own entry lifted
+            expect(result.disabledMcpServers).not.toContain("serena");
             expect(result.projects).toEqual(projects as ClaudeGenericConfig["projects"]); // lists untouched
             expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("3 project(s)"));
             expect(logger.warn).toHaveBeenCalledWith(
@@ -363,31 +287,7 @@ describe("claude provider TRUE global disable", () => {
         });
     });
 
-    describe("remove command", () => {
-        it("removeServers lifts the deny entry too, so a later server of that name is not blocked", async () => {
-            writeClaudeJson(claudeFixture());
-            writeUserSettings({ deniedMcpServers: [{ serverName: "serena" }, { serverName: "other" }] });
-
-            await new ClaudeProvider().removeServers(["serena"]);
-
-            expect(readClaudeJson().mcpServers?.serena).toBeUndefined();
-            expect(readDenied()).toEqual([{ serverName: "other" }]);
-        });
-    });
-
     describe("listServers", () => {
-        it("reads the global state from deniedMcpServers, not from the top-level marker", async () => {
-            const claude = claudeFixture();
-            claude.disabledMcpServers = ["github"]; // ignored by Claude Code, and now by mcp-manager
-            writeClaudeJson(claude);
-            writeUserSettings({ deniedMcpServers: [{ serverName: "serena" }] });
-
-            const rows = await new ClaudeProvider().listServers();
-
-            expect(rows.find((row) => row.name === "serena")?.enabled).toBe(false);
-            expect(rows.find((row) => row.name === "github")?.enabled).toBe(true);
-        });
-
         it("reports a globally-disabled (absent) server as disabled, not missing", async () => {
             const claude = claudeFixture();
             delete (claude.mcpServers as Record<string, unknown>).serena;
@@ -409,12 +309,8 @@ describe("claude provider TRUE global disable", () => {
     });
 
     describe("syncServers (provider)", () => {
-        // Intended change 2026-10-13 (V-2): false = in mcpServers AND denied; true lifts the deny.
-        it("denies a disabled server and keeps its entry, lifts the deny of an enabled one, drops the marker", async () => {
-            const claude = claudeFixture();
-            claude.disabledMcpServers = ["serena", "github", "old-name"];
-            writeClaudeJson(claude);
-            writeUserSettings({ deniedMcpServers: [{ serverName: "github" }] }); // stale deny of an enabled server
+        it("removes globally-disabled servers from mcpServers and keeps enabled ones", async () => {
+            writeClaudeJson(claudeFixture()); // serena still installed (drift)
             const unified = unifiedFixture();
             unified.mcpServers.serena._meta = { enabled: { claude: false } };
             await writeUnified(unified);
@@ -422,24 +318,11 @@ describe("claude provider TRUE global disable", () => {
             const provider = new ClaudeProvider();
             await provider.syncServers(unified.mcpServers);
 
-            const result = readClaudeJson();
-            expect(result.mcpServers?.serena).toEqual(SERENA);
-            expect(result.mcpServers?.github).toBeDefined();
-            expect(readDenied()).toEqual([{ serverName: "serena" }]);
-            expect(result.disabledMcpServers).toBeUndefined(); // Claude Code never read it
-        });
-
-        it("leaves the deny of a server with no claude decision as it is", async () => {
-            writeClaudeJson(claudeFixture());
-            writeUserSettings({ deniedMcpServers: [{ serverName: "unset" }] });
-            const unified = unifiedFixture();
-            unified.mcpServers.unset = { type: "stdio", command: "unset-mcp" };
-            await writeUnified(unified);
-
-            await new ClaudeProvider().syncServers({ unset: unified.mcpServers.unset });
-
-            expect(readDenied()).toEqual([{ serverName: "unset" }]);
-            expect(readClaudeJson().mcpServers?.unset).toBeDefined();
+            const claude = readClaudeJson();
+            expect(claude.mcpServers?.serena).toBeUndefined(); // drift corrected
+            expect(claude.mcpServers?.github).toBeDefined();
+            expect(claude.disabledMcpServers).toContain("serena");
+            expect(claude.disabledMcpServers).not.toContain("github");
         });
     });
 
@@ -465,9 +348,7 @@ describe("claude provider TRUE global disable", () => {
             const claude = readClaudeJson();
             expect(claude.mcpServers?.github).toBeDefined(); // the sync really ran
             expect(claude.mcpServers?.unset).toBeDefined();
-            // /proj/o runs serena through a project-scope entry, so serena keeps the older switch.
             expect(claude.mcpServers?.serena).toBeUndefined();
-            expect(readDenied()).toBeUndefined();
             // The only project change: the override entry is refreshed from the unified config.
             const expected = {
                 ...projectsFixture(),
@@ -499,7 +380,7 @@ describe("claude provider TRUE global disable", () => {
     });
 
     describe("sync command", () => {
-        it("puts a disabled server back into mcpServers and denies it", async () => {
+        it("does not (re)install globally-disabled servers", async () => {
             writeClaudeJson({
                 numStartups: 5,
                 mcpServers: {},
@@ -515,9 +396,7 @@ describe("claude provider TRUE global disable", () => {
 
             const claude = readClaudeJson();
             expect(claude.mcpServers?.github).toBeDefined(); // enabled → installed
-            expect(claude.mcpServers?.serena).toEqual(SERENA); // disabled → kept, denied
-            expect(readDenied()).toEqual([{ serverName: "serena" }]);
-            expect(claude.disabledMcpServers).toBeUndefined();
+            expect(claude.mcpServers?.serena).toBeUndefined(); // disabled → stays absent
         });
     });
 
@@ -542,7 +421,7 @@ describe("claude provider TRUE global disable", () => {
     });
 
     describe("rename command", () => {
-        it("renames a globally-disabled server: the new name is kept and denied, the old deny goes", async () => {
+        it("renames a globally-disabled server in the unified config without installing it in claude", async () => {
             writeClaudeJson({
                 mcpServers: {},
                 disabledMcpServers: ["serena"],
@@ -552,7 +431,6 @@ describe("claude provider TRUE global disable", () => {
             await writeUnified({
                 mcpServers: { serena: { ...SERENA, _meta: { enabled: { claude: false } } } },
             });
-            writeUserSettings({ deniedMcpServers: [{ serverName: "serena" }] });
 
             const provider = new ClaudeProvider();
             await renameServer("serena", "serena-x", [provider]);
@@ -563,22 +441,20 @@ describe("claude provider TRUE global disable", () => {
             expect(unified.mcpServers.serena).toBeUndefined();
 
             const claude = readClaudeJson();
-            expect(claude.mcpServers?.["serena-x"]).toEqual(SERENA); // kept under its new name
+            expect(claude.mcpServers?.["serena-x"]).toBeUndefined(); // still globally disabled = absent
             expect(claude.mcpServers?.serena).toBeUndefined();
-            expect(readDenied()).toEqual([{ serverName: "serena-x" }]); // still off; no stale deny
         });
     });
 
     describe("disable/enable commands end-to-end (toggle flow)", () => {
-        it("disable --provider claude denies the server, keeps the entry and flips _meta to false", async () => {
+        it("disable --provider claude removes the entry and flips _meta to false", async () => {
             writeClaudeJson(claudeFixture());
             await writeUnified(unifiedFixture());
 
             const provider = new ClaudeProvider();
             await disableCommand("serena", [provider], { provider: "claude" });
 
-            expect(readClaudeJson().mcpServers?.serena).toEqual(SERENA);
-            expect(readDenied()).toEqual([{ serverName: "serena" }]);
+            expect(readClaudeJson().mcpServers?.serena).toBeUndefined();
             const unified = await readUnified();
             expect(unified.mcpServers.serena._meta?.enabled?.claude).toBe(false);
             expect(unified.mcpServers.serena.command).toBe("uvx");
@@ -599,8 +475,7 @@ describe("claude provider TRUE global disable", () => {
 
             const result = readClaudeJson();
             expect(result.mcpServers?.serena).toBeDefined();
-            expect(result.disabledMcpServers).toBeUndefined();
-            expect(readDenied()).toBeUndefined(); // nothing was denied, nothing is written
+            expect(result.disabledMcpServers).not.toContain("serena");
 
             const unifiedAfter = await readUnified();
             expect(unifiedAfter.mcpServers.serena._meta?.enabled?.claude).toBe(true);
diff --git a/src/mcp-manager/commands/__tests__/claude-project-override.test.ts b/src/mcp-manager/commands/__tests__/claude-project-override.test.ts
index 5febda3668..c8b86c871d 100644
--- a/src/mcp-manager/commands/__tests__/claude-project-override.test.ts
+++ b/src/mcp-manager/commands/__tests__/claude-project-override.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, mock, spyOn } from "bun:test";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { setupStorageSandbox } from "@genesiscz/utils/storage/test-sandbox";
@@ -50,13 +50,6 @@ describe("claude per-project enable override for globally-disabled servers", ()
         return SafeJSON.parse(readFileSync(claudeJsonPath(), "utf-8")) as ClaudeGenericConfig & Record<string, unknown>;
     };
 
-    const readDenied = (): unknown => {
-        const settingsPath = join(homeDir, ".claude", "settings.json");
-        return existsSync(settingsPath)
-            ? (SafeJSON.parse(readFileSync(settingsPath, "utf-8")) as Record<string, unknown>).deniedMcpServers
-            : undefined;
-    };
-
     const writeUnified = async (config: UnifiedMCPConfig) => {
         const storage = new Storage("mcp-manager");
         await storage.ensureDirs();
@@ -154,27 +147,6 @@ describe("claude per-project enable override for globally-disabled servers", ()
     });
 
     // Intended change 2026-10-13: a global disable no longer sweeps project lists at all.
-    it("a later global disable keeps the older switch for an overridden server: no deny, entry absent", async () => {
-        writeClaudeJson({
-            mcpServers: { serena: { ...SERENA }, github: { ...GITHUB } },
-            projects: {
-                "/proj/a": { mcpServers: { serena: { ...SERENA } }, disabledMcpServers: [] },
-                "/proj/b": { mcpServers: {}, disabledMcpServers: [] },
-            },
-        });
-        await writeUnified(unifiedFixture());
-
-        await new ClaudeProvider().disableServers(["serena", "github"], null);
-
-        const claude = readClaudeJson();
-        expect(claude.mcpServers?.serena).toBeUndefined(); // overridden: absence is the switch
-        expect(claude.projects?.["/proj/a"].mcpServers?.serena).toBeDefined(); // the override keeps working
-        expect(claude.mcpServers?.github).toBeDefined(); // not overridden: kept and denied
-        expect(readDenied()).toEqual([{ serverName: "github" }]);
-        expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("'serena' keeps the older global switch"));
-        expect((await readUnified()).mcpServers.serena.command).toBe("uvx"); // config preserved
-    });
-
     it("a later global disable leaves every project entry alone, the override included", async () => {
         writeClaudeJson(globallyDisabledFixture());
         await writeUnified(unifiedFixture());
@@ -205,10 +177,8 @@ describe("claude per-project enable override for globally-disabled servers", ()
         expect(claude.projects?.["/proj/a"].mcpServers?.serena.command).toBe("uvx");
         // Name NOT re-added to the override project's disabled list
         expect(claude.projects?.["/proj/a"].disabledMcpServers).not.toContain("serena");
-        // Global disable still enforced by absence: a deny (V-2) would match the project-scope
-        // entry too and switch /proj/a off, so an overridden server keeps the older switch.
+        // Global disable still enforced (absent from mcpServers); other project lists untouched
         expect(claude.mcpServers?.serena).toBeUndefined();
-        expect(readDenied()).toBeUndefined();
         expect(claude.projects?.["/proj/b"].disabledMcpServers).toEqual(["serena"]);
         // Enabled sibling unaffected
         expect(claude.mcpServers?.github).toBeDefined();
@@ -248,23 +218,6 @@ describe("claude per-project enable override for globally-disabled servers", ()
         expect(unified.mcpServers.serena._meta?.enabled?.claude).toBe(false); // global state untouched
     });
 
-    it("a per-project enable of a DENIED server warns that the deny wins in every project", async () => {
-        writeClaudeJson({
-            mcpServers: { serena: { ...SERENA }, github: { ...GITHUB } },
-            projects: { "/proj/a": { mcpServers: {}, disabledMcpServers: [] } },
-        });
-        await writeUnified(unifiedFixture());
-        mkdirSync(join(homeDir, ".claude"), { recursive: true });
-        writeFileSync(
-            join(homeDir, ".claude", "settings.json"),
-            SafeJSON.stringify({ deniedMcpServers: [{ serverName: "serena" }] })
-        );
-
-        await enableCommand("serena", [new ClaudeProvider()], { provider: "claude", project: ["/proj/a"] });
-
-        expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("a per-project enable cannot turn it on"));
-    });
-
     it("listServers reports the global disable AND the per-project override", async () => {
         writeClaudeJson(globallyDisabledFixture());
         await writeUnified(unifiedFixture());
@@ -301,8 +254,7 @@ describe("claude per-project enable override for globally-disabled servers", ()
         await disableCommand("github", [provider, cursorProvider], { provider: "all" });
 
         const claude = readClaudeJson();
-        expect(claude.mcpServers?.github).toBeDefined(); // globally disabled = denied, config kept
-        expect(readDenied()).toEqual([{ serverName: "github" }]);
+        expect(claude.mcpServers?.github).toBeUndefined(); // globally disabled = removed
 
         const cursor = SafeJSON.parse(readFileSync(join(homeDir, ".cursor", "mcp.json"), "utf-8")) as {
             mcpServers?: Record<string, unknown>;
diff --git a/src/mcp-manager/commands/rename.ts b/src/mcp-manager/commands/rename.ts
index 2a5c66f361..2e452cf3a3 100644
--- a/src/mcp-manager/commands/rename.ts
+++ b/src/mcp-manager/commands/rename.ts
@@ -284,10 +284,8 @@ async function renameServerInProvider(
     }
 
     // IMPORTANT: syncServers only adds/updates servers, it doesn't remove servers not in the map
-    // We need to explicitly remove the old server name from the provider config after syncing.
-    // Claude can hold the old name only as a deny entry in ~/.claude/settings.json (an older
-    // delete-based disable left no config), so Claude always gets the removal.
-    if (oldName !== newName && (hasOldServer || provider.getName() === "claude")) {
+    // We need to explicitly remove the old server name from the provider config after syncing
+    if (hasOldServer && oldName !== newName) {
         await removeServerFromProvider(provider, oldName);
     }
 
@@ -329,9 +327,6 @@ async function removeServerFromProvider(provider: MCPProvider, serverName: strin
                 }
             }
             await provider.writeConfig(claudeConfig);
-            // The old name's deny entry in ~/.claude/settings.json would block a later server of
-            // that name; removeServers lifts it (the entries above are already gone).
-            await provider.removeServers([serverName]);
             break;
         }
         case "codex": {
diff --git a/src/mcp-manager/utils/providers/claude.ts b/src/mcp-manager/utils/providers/claude.ts
index e3ef3754d3..f128dbc987 100644
--- a/src/mcp-manager/utils/providers/claude.ts
+++ b/src/mcp-manager/utils/providers/claude.ts
@@ -12,7 +12,6 @@ import { atomicWriteFileSync } from "@genesiscz/utils/storage/atomic-file";
 import { matchGlob } from "@genesiscz/utils/string";
 import chalk from "chalk";
 import type { ClaudeGenericConfig, ClaudeMCPServerConfig } from "./claude.types.js";
-import { namesGrokWouldStartFromClaudeJson } from "./grok.js";
 import { claudeEnabledPluginServers, readClaudeSettings } from "./plugins.js";
 import type { EnableServersOptions, MCPServerInfo, UnifiedMCPServerConfig } from "./types.js";
 import { MCPProvider, WriteResult } from "./types.js";
@@ -47,55 +46,21 @@ function isDeniedByClaude(denied: unknown[], registeredName: string, url: string
     });
 }
 
-/** Applied when either write applied; otherwise the two writes changed nothing. */
-function combineWrites(first: WriteResult, second: WriteResult): WriteResult {
-    if (second === WriteResult.Rejected) {
-        return second;
-    }
-
-    return first === WriteResult.Applied || second === WriteResult.Applied
-        ? WriteResult.Applied
-        : WriteResult.NoChanges;
-}
-
-/** How many projects run `name` through their own project-scope entry (an `enable --project` override). */
-function projectsOverriding(config: ClaudeGenericConfig, name: string): number {
-    return Object.values(config.projects ?? {}).filter((project) => project.mcpServers?.[name]).length;
-}
-
-/** Drop names from the top-level `disabledMcpServers` marker, and the key once it is empty. */
-function dropTopLevelMarker(config: ClaudeGenericConfig, names: string[]): void {
-    if (!config.disabledMcpServers) {
-        return;
-    }
-
-    config.disabledMcpServers = config.disabledMcpServers.filter((name) => !names.includes(name));
-
-    if (config.disabledMcpServers.length === 0) {
-        delete config.disabledMcpServers;
-    }
-}
-
 /**
  * Claude Desktop MCP provider.
  * Manages MCP servers in ~/.claude.json
  *
- * The global switch (verified on Claude Code 2.1.296, research note
- * 2026-10-13-ClaudeCodeGlobalMcpSwitch.md): a
- * `deniedMcpServers: [{ "serverName": "<name>" }]` entry in
- * `~/.claude/settings.json`. It covers every project, also one registered later,
- * and the config stays in `mcpServers`. A denied server is ABSENT from
- * `claude mcp list` and `/mcp` (not shown as disabled), and `/mcp` cannot turn
- * it back on ("blocked by enterprise managed policy"). The deny matches the
- * name in every scope, so a project-scope entry of the same name is blocked too.
- * The top-level `disabledMcpServers` key in `~/.claude.json` does nothing;
- * mcp-manager no longer writes it and removes it on sync. Claude Code reads
- * `disabledMcpServers` only from the current project entry.
- *
- * Grok reads `~/.claude.json` top-level `mcpServers` too, and Claude's deny does
- * not reach Grok. So a server that stays off in Claude is put back into
- * `mcpServers` only when Grok would not start it from there (see
- * `namesGrokWouldStartFromClaudeJson`) or the unified config enables it for Grok.
+ * IMPORTANT (verified against the Claude Code binary 2.1.296, research note
+ * 2026-10-13-ClaudeCodeGlobalMcpSwitch.md): Claude Code reads
+ * `disabledMcpServers` ONLY from per-project entries
+ * (`.projects[<cwd>].disabledMcpServers`). The TOP-LEVEL `disabledMcpServers`
+ * key is NEVER read by Claude Code — it is an mcp-manager-only marker. The only
+ * mechanism Claude Code honors globally (including future projects) that one
+ * project can still override is the server NOT existing in `mcpServers` — so a
+ * TRUE global disable removes the entry (after preserving its full config in the
+ * unified config with `_meta.enabled.claude = false`), and a global enable
+ * restores it. A `deniedMcpServers` entry is global and costs no tokens, but no
+ * project setting can lift it, so it is not used for a global disable.
  *
  * Global means the global switch only. A global disable, a global enable, an
  * install and a sync of a boolean or unset `_meta.enabled.claude` never write a
@@ -121,9 +86,10 @@ export class ClaudeProvider extends MCPProvider {
     }
 
     shouldBeInstalled(serverConfig: UnifiedMCPServerConfig): boolean {
-        // A server with `_meta.enabled.claude === false` is put back into
-        // mcpServers by syncServers itself, which first checks that Grok would
-        // not start it from ~/.claude.json. Everything else installs up front.
+        // A globally-disabled server (_meta.enabled.claude === false) must be
+        // ABSENT from ~/.claude.json — absence is the only global disable
+        // Claude Code honors. Everything else (enabled, per-project, unset)
+        // stays installed.
         return serverConfig._meta?.enabled?.claude !== false;
     }
 
@@ -163,18 +129,18 @@ export class ClaudeProvider extends MCPProvider {
 
     async listServers(): Promise<MCPServerInfo[]> {
         const config = await this.readConfig();
-        const denied = await this.readDeniedEntries();
         const servers: MCPServerInfo[] = [];
         const globalNames = new Set<string>();
 
-        // Global servers: off when the user-settings denylist names them.
+        // Global servers
         if (config.mcpServers) {
+            const disabledServers = new Set(config.disabledMcpServers || []);
             for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
                 globalNames.add(name);
                 servers.push({
                     name,
                     config: this.claudeToUnified(serverConfig),
-                    enabled: !isDeniedByClaude(denied, name, serverConfig.url),
+                    enabled: !disabledServers.has(name),
                     provider: this.providerName,
                 });
             }
@@ -193,8 +159,7 @@ export class ClaudeProvider extends MCPProvider {
                             servers.push({
                                 name,
                                 config: this.claudeToUnified(serverConfig),
-                                enabled:
-                                    !projectDisabled.has(name) && !isDeniedByClaude(denied, name, serverConfig.url),
+                                enabled: !projectDisabled.has(name),
                                 provider: `${this.providerName}:${projectPath}`,
                             });
                         }
@@ -203,9 +168,9 @@ export class ClaudeProvider extends MCPProvider {
             }
         }
 
-        // A server an older delete-based disable removed from ~/.claude.json (or one
-        // kept out because Grok would start it): surface it from the unified config
-        // as disabled so it does not look "not installed".
+        // Globally-disabled servers are absent from ~/.claude.json entirely
+        // (absence is the only global disable Claude Code honors). Surface them
+        // from the unified config as disabled so they don't look "not installed".
         const unified = await readUnifiedConfig();
         for (const [name, entry] of Object.entries(unified.mcpServers)) {
             if (entry._meta?.enabled?.claude !== false) {
@@ -263,59 +228,6 @@ export class ClaudeProvider extends MCPProvider {
         }
     }
 
-    /** The `deniedMcpServers` entries of the user settings; an unreadable file counts as none, with a warning. */
-    private async readDeniedEntries(): Promise<unknown[]> {
-        try {
-            return deniedEntries(await this.readSettings());
-        } catch (error) {
-            logger.warn({ error, path: this.getSettingsPath() }, "mcp-manager: could not read Claude user settings");
-            return [];
-        }
-    }
-
-    /**
-     * Edit the user-settings denylist in memory: add `{ serverName }` for each name in `deny` that no
-     * entry names yet, and remove exactly the `serverName` entries for the names in `allow` (a
-     * `serverUrl` pattern is never touched). The key goes when the list ends up empty. Returns
-     * whether anything changed.
-     */
-    private applyDenyChanges(settings: Record<string, unknown>, change: { deny: string[]; allow: string[] }): boolean {
-        const current = deniedEntries(settings);
-        const named = (entry: unknown): string | undefined =>
-            isObject(entry) && typeof entry.serverName === "string" ? entry.serverName : undefined;
-        const kept = current.filter((entry) => {
-            const name = named(entry);
-            return name === undefined || !change.allow.includes(name);
-        });
-        const present = new Set(kept.map(named));
-        const added = [...new Set(change.deny)].filter((name) => !present.has(name));
-
-        if (kept.length === current.length && added.length === 0) {
-            return false;
-        }
-
-        const next = [...kept, ...added.map((serverName) => ({ serverName }))];
-
-        if (next.length === 0) {
-            delete settings.deniedMcpServers;
-        } else {
-            settings.deniedMcpServers = next;
-        }
-
-        return true;
-    }
-
-    /** Deny (`denied`) or allow the given registered server names in `~/.claude/settings.json`. */
-    private async setDeniedServerNames(names: string[], denied: boolean): Promise<WriteResult> {
-        const settings = await this.readSettings();
-        const changed = this.applyDenyChanges(
-            settings,
-            denied ? { deny: names, allow: [] } : { deny: [], allow: names }
-        );
-
-        return changed ? this.writeSettings(settings) : WriteResult.NoChanges;
-    }
-
     /**
      * Claude Code's global switch for one plugin server is the user-settings denylist:
      * `deniedMcpServers: [{ "serverName": "plugin:<plugin>:<server>" }]`. The plugin stays enabled
@@ -324,24 +236,48 @@ export class ClaudeProvider extends MCPProvider {
      */
     async setPluginServersEnabled(serverNames: string[], enabled: boolean): Promise<WriteResult> {
         const settings = await this.readSettings();
-        const registered = [
-            ...new Set(
-                (await this.discoverPluginServers(settings))
-                    .filter((server) => serverNames.includes(server.info.name))
-                    .map((server) => server.registeredName)
-            ),
-        ];
-
-        if (registered.length === 0) {
+        const registered = new Set(
+            (await this.discoverPluginServers(settings))
+                .filter((server) => serverNames.includes(server.info.name))
+                .map((server) => server.registeredName)
+        );
+
+        if (registered.size === 0) {
             return WriteResult.NoChanges;
         }
 
-        const changed = this.applyDenyChanges(
-            settings,
-            enabled ? { deny: [], allow: registered } : { deny: registered, allow: [] }
-        );
+        const current = deniedEntries(settings);
+        const namedIn = (entry: unknown): boolean =>
+            isObject(entry) && typeof entry.serverName === "string" && registered.has(entry.serverName);
+
+        if (enabled) {
+            const kept = current.filter((entry) => !namedIn(entry));
+
+            if (kept.length === current.length) {
+                return WriteResult.NoChanges;
+            }
+
+            if (kept.length === 0) {
+                delete settings.deniedMcpServers;
+            } else {
+                settings.deniedMcpServers = kept;
+            }
+        } else {
+            const present = new Set(
+                current
+                    .filter(isObject)
+                    .flatMap((entry) => (typeof entry.serverName === "string" ? [entry.serverName] : []))
+            );
+            const missing = [...registered].filter((name) => !present.has(name));
+
+            if (missing.length === 0) {
+                return WriteResult.NoChanges;
+            }
 
-        return changed ? this.writeSettings(settings) : WriteResult.NoChanges;
+            settings.deniedMcpServers = [...current, ...missing.map((serverName) => ({ serverName }))];
+        }
+
+        return this.writeSettings(settings);
     }
 
     /** Same flow as every harness write (diff, confirm or --yes, backup), aimed at settings.json. */
@@ -363,7 +299,6 @@ export class ClaudeProvider extends MCPProvider {
         }
 
         await this.backupManager.createBackup(settingsPath, this.providerName);
-        // Atomic like every harness write: a crash or a full disk leaves the old settings.json, never a short one.
         await mkdir(path.dirname(settingsPath), { recursive: true });
         atomicWriteFileSync(settingsPath, newContent, { mode: 0o600 });
         logger.info(chalk.green(`✓ Configuration written to ${settingsPath}`));
@@ -444,11 +379,29 @@ export class ClaudeProvider extends MCPProvider {
     }
 
     async enableServer(serverName: string, projectPath?: string | null): Promise<void> {
-        await this.enableServers([serverName], projectPath);
+        const config = await this.readConfig();
+
+        if (projectPath === null || projectPath === undefined) {
+            // Global enable (no project specified = global)
+            await this.applyGlobalEnable([serverName], config);
+        } else {
+            await this.applyProjectEnable([serverName], projectPath, config);
+        }
+
+        await this.writeConfig(config);
     }
 
     async disableServer(serverName: string, projectPath?: string | null): Promise<void> {
-        await this.disableServers([serverName], projectPath);
+        const config = await this.readConfig();
+
+        if (projectPath === null || projectPath === undefined) {
+            // Global disable (no project specified = global)
+            await this.applyGlobalDisable([serverName], config);
+        } else {
+            this.applyProjectDisable([serverName], projectPath, config);
+        }
+
+        await this.writeConfig(config);
     }
 
     async enableServerForAllProjects(serverName: string): Promise<void> {
@@ -459,10 +412,6 @@ export class ClaudeProvider extends MCPProvider {
         await this.disableServer(serverName, null);
     }
 
-    /**
-     * A global enable writes ~/.claude.json first (restore the entry), then lifts the deny in
-     * settings.json. A rejected second write leaves the server denied, so it stays off.
-     */
     async enableServers(
         serverNames: string[],
         projectPath?: string | null,
@@ -470,45 +419,25 @@ export class ClaudeProvider extends MCPProvider {
     ): Promise<WriteResult> {
         const config = await this.readConfig();
 
-        if (projectPath !== null && projectPath !== undefined) {
+        if (projectPath === null || projectPath === undefined) {
+            await this.applyGlobalEnable(serverNames, config, options);
+        } else {
             await this.applyProjectEnable(serverNames, projectPath, config);
-            return this.writeConfig(config);
-        }
-
-        await this.applyGlobalEnable(serverNames, config, options);
-        const written = await this.writeConfig(config);
-
-        if (written === WriteResult.Rejected) {
-            return written;
         }
 
-        return combineWrites(written, await this.setDeniedServerNames(serverNames, false));
+        return this.writeConfig(config);
     }
 
-    /**
-     * A global disable denies the server in settings.json FIRST, then fixes ~/.claude.json (entry
-     * kept or put back, top-level marker dropped). A rejected deny writes nothing, so a disable
-     * can never restore an entry without its deny and turn the server on. A server that some
-     * project runs through its own project-scope entry is not denied (see `applyGlobalDisable`).
-     */
     async disableServers(serverNames: string[], projectPath?: string | null): Promise<WriteResult> {
         const config = await this.readConfig();
 
-        if (projectPath !== null && projectPath !== undefined) {
+        if (projectPath === null || projectPath === undefined) {
+            await this.applyGlobalDisable(serverNames, config);
+        } else {
             this.applyProjectDisable(serverNames, projectPath, config);
-            return this.writeConfig(config);
-        }
-
-        const overridden = serverNames.filter((name) => projectsOverriding(config, name) > 0);
-        const deniable = serverNames.filter((name) => !overridden.includes(name));
-        const denied = deniable.length > 0 ? await this.setDeniedServerNames(deniable, true) : WriteResult.NoChanges;
-
-        if (denied === WriteResult.Rejected) {
-            return denied;
         }
 
-        await this.applyGlobalDisable(serverNames, config, overridden);
-        return combineWrites(denied, await this.writeConfig(config));
+        return this.writeConfig(config);
     }
 
     /**
@@ -528,15 +457,6 @@ export class ClaudeProvider extends MCPProvider {
         config: ClaudeGenericConfig
     ): Promise<void> {
         const existingProject = config.projects?.[projectPath];
-        const denied = await this.readDeniedEntries();
-
-        for (const name of serverNames.filter((server) => isDeniedByClaude(denied, server, undefined))) {
-            logger.warn(
-                chalk.yellow(
-                    `⚠ '${name}' is denied globally (deniedMcpServers), and Claude Code applies that in every project, project-scope entries included, so a per-project enable cannot turn it on. Enable it globally, then disable it in the projects where you do not want it: ${toolCommand("mcp-manager disable", name, "-p", "claude", "--project", "<path>")}`
-                )
-            );
-        }
 
         // Remove from the project's disabled list (Claude Code reads this list,
         // so an override entry only works when the name is NOT in it)
@@ -603,66 +523,62 @@ export class ClaudeProvider extends MCPProvider {
     }
 
     /**
-     * The ~/.claude.json half of a global disable (the deny itself is in settings.json):
-     * 1. Record `_meta.enabled.claude = false` in the unified config (import the config there if
-     *    it is missing).
-     * 2. Keep the entry in `mcpServers`; put it back from the unified config when an older
-     *    delete-based disable removed it, unless Grok would then start it (`restoreMissing`).
-     * 3. Drop the names from the top-level `disabledMcpServers` marker, which Claude Code ignores.
-     * No project's `disabledMcpServers` list is written.
-     *
-     * Exception, `overridden`: a server that some project runs through its own project-scope entry.
-     * The deny matches the name in every scope and would switch those projects off too, so such a
-     * server keeps the older switch instead: absent from the global `mcpServers` (its config stays in
-     * the unified config and in the project entries), not denied.
+     * Apply a TRUE global disable to the in-memory Claude config:
+     * 1. Preserve each server's full config in the unified config with
+     *    `_meta.enabled.claude = false` (import it there if missing).
+     * 2. Keep the top-level marker (Claude Code ignores it; mcp-manager reads it).
+     * 3. Remove the entry from `mcpServers` — the only mechanism Claude Code
+     *    honors globally, including projects registered in the future.
+     * No project's `disabledMcpServers` list is written. Entries that could not
+     * be preserved are NOT removed (no data loss).
      */
-    private async applyGlobalDisable(
-        serverNames: string[],
-        config: ClaudeGenericConfig,
-        overridden: string[] = []
-    ): Promise<void> {
-        const preserved = await this.preserveServersInUnifiedConfig(serverNames, config);
-        await this.restoreMissing(
-            serverNames.filter((name) => !overridden.includes(name)),
-            config,
-            { staysOffInClaude: true }
-        );
-        dropTopLevelMarker(config, serverNames);
+    private async applyGlobalDisable(serverNames: string[], config: ClaudeGenericConfig): Promise<void> {
+        if (!config.disabledMcpServers) {
+            config.disabledMcpServers = [];
+        }
 
-        for (const name of overridden) {
-            if (config.mcpServers?.[name] && preserved.has(name)) {
-                delete config.mcpServers[name];
+        const safeToRemove = await this.preserveServersInUnifiedConfig(serverNames, config);
+
+        for (const serverName of serverNames) {
+            // Top-level marker (ignored by Claude Code, kept for back-compat)
+            if (!config.disabledMcpServers.includes(serverName)) {
+                config.disabledMcpServers.push(serverName);
             }
 
-            this.reportOverridden(name, config);
+            // TRUE global disable: remove the entry from mcpServers
+            if (config.mcpServers?.[serverName]) {
+                if (safeToRemove.has(serverName)) {
+                    delete config.mcpServers[serverName];
+                } else {
+                    logger.warn(
+                        chalk.yellow(
+                            `⚠ '${serverName}' was NOT removed from mcpServers in ${this.configPath} because its config could not be preserved in the unified config, so Claude Code still loads it in every project.`
+                        )
+                    );
+                }
+            }
         }
     }
 
-    private reportOverridden(name: string, config: ClaudeGenericConfig): void {
-        logger.warn(
-            chalk.yellow(
-                `⚠ '${name}' keeps the older global switch (absent from mcpServers, not denied): ${projectsOverriding(config, name)} project(s) run it through a project-scope entry, and a deny would switch those projects off too.`
-            )
-        );
-    }
-
     /**
-     * The ~/.claude.json half of a global enable (the caller then lifts the deny): put the entry
-     * back into `mcpServers` when an older delete-based disable removed it, and drop the top-level
-     * marker. Grok sees a restored entry as well; that matches the old behaviour of a global
-     * enable, and the server is meant to run. Project lists stay as they are unless
-     * `clearProjectOverrides` asks to take the name off every list that still names it; without
-     * it, one warning gives the count and the flag.
+     * Apply a global enable to the in-memory Claude config: restore the entry
+     * into `mcpServers` from the unified config (a TRUE global disable removed
+     * it) and drop the top-level marker. Project lists stay as they are unless
+     * `clearProjectOverrides` asks to take the name off every list that still
+     * names it; without it, one warning gives the count and the flag.
      */
     private async applyGlobalEnable(
         serverNames: string[],
         config: ClaudeGenericConfig,
         options: EnableServersOptions = {}
     ): Promise<void> {
-        await this.restoreMissing(serverNames, config, { staysOffInClaude: false });
-        dropTopLevelMarker(config, serverNames);
+        await this.restoreServersFromUnifiedConfig(serverNames, config);
 
         for (const serverName of serverNames) {
+            if (config.disabledMcpServers) {
+                config.disabledMcpServers = config.disabledMcpServers.filter((name) => name !== serverName);
+            }
+
             const listing = Object.values(config.projects ?? {}).filter((project) =>
                 project.disabledMcpServers?.includes(serverName)
             );
@@ -691,8 +607,11 @@ export class ClaudeProvider extends MCPProvider {
     }
 
     /**
-     * Record `_meta.enabled.claude = false` in the unified config, importing a server's config
-     * there when it is missing. Returns the names whose config the unified config now holds.
+     * Ensure full server configs are preserved in the unified config with
+     * `_meta.enabled.claude = false` BEFORE they are removed from
+     * ~/.claude.json. Returns the set of server names whose config body is
+     * safely stored in the unified config (pre-existing or successfully
+     * imported) — only those may be removed without data loss.
      */
     private async preserveServersInUnifiedConfig(
         serverNames: string[],
@@ -733,42 +652,21 @@ export class ClaudeProvider extends MCPProvider {
     }
 
     /**
-     * Put entries an older delete-based disable removed back into `mcpServers`, from the unified
-     * config (or from `source` when the caller has the projected config). For a server that stays
-     * off in Claude (`staysOffInClaude`), Grok decides: it reads `mcpServers` too and Claude's deny
-     * does not reach it, so the entry is put back only when Grok would not start it or the unified
-     * config enables it for Grok. Otherwise it stays out, and Claude's deny still covers it.
+     * Restore entries removed by a TRUE global disable: copy the server config
+     * back into `mcpServers` from the unified config (where it was preserved).
      */
-    private async restoreMissing(
-        serverNames: string[],
-        config: ClaudeGenericConfig,
-        opts: { staysOffInClaude: boolean; source?: Record<string, UnifiedMCPServerConfig> }
-    ): Promise<void> {
+    private async restoreServersFromUnifiedConfig(serverNames: string[], config: ClaudeGenericConfig): Promise<void> {
         const missing = serverNames.filter((name) => !config.mcpServers?.[name]);
         if (missing.length === 0) {
             return;
         }
 
         const unified = await readUnifiedConfig();
-        const grokWouldStart = opts.staysOffInClaude
-            ? await namesGrokWouldStartFromClaudeJson(missing, unified)
-            : new Set<string>();
-
         for (const name of missing) {
-            const entry = opts.source?.[name] ?? unified.mcpServers[name];
+            const entry = unified.mcpServers[name];
             if (!entry) {
                 continue; // Not in unified config — nothing to restore
             }
-
-            if (grokWouldStart.has(name) && unified.mcpServers[name]?._meta?.enabled?.grok !== true) {
-                logger.warn(
-                    chalk.yellow(
-                        `⚠ '${name}' stays out of mcpServers in ${this.configPath}: Grok loads that list, has no table for it and would start it, and Claude's deny does not reach Grok. Claude's deny still keeps it off in Claude.`
-                    )
-                );
-                continue;
-            }
-
             if (!config.mcpServers) {
                 config.mcpServers = {};
             }
@@ -821,66 +719,41 @@ export class ClaudeProvider extends MCPProvider {
             }
         }
 
-        const written = await this.writeConfig(config);
-
-        if (written === WriteResult.Rejected) {
-            return written;
-        }
-
-        // A deny entry left behind would block a later server of the same name.
-        return combineWrites(written, await this.setDeniedServerNames(serverNames, false));
+        return this.writeConfig(config);
     }
 
-    /**
-     * `_meta.enabled.claude === false`: denied in settings.json, and the config kept in (or put back
-     * into) `mcpServers`, Grok permitting (`restoreMissing`). `true`: in `mcpServers`, and its
-     * `serverName` deny entry removed. Unset or a per-project map: in `mcpServers`, deny left as it
-     * is. The top-level `disabledMcpServers` marker is removed: Claude Code never reads it. The
-     * denylist is written first; when that write is rejected, ~/.claude.json is not written either,
-     * so a sync never puts an entry back without its deny.
-     */
     async syncServers(servers: Record<string, UnifiedMCPServerConfig>): Promise<WriteResult> {
-        const settings = await this.readSettings();
-        const current = await this.readConfig();
-        const disabled = Object.keys(servers).filter((name) => servers[name]._meta?.enabled?.claude === false);
-        // Same exception as a global disable: a server some project overrides keeps the older switch.
-        const overridden = disabled.filter((name) => projectsOverriding(current, name) > 0);
-        const deny = disabled.filter((name) => !overridden.includes(name));
-        const allow = Object.keys(servers).filter((name) => servers[name]._meta?.enabled?.claude === true);
-        let denyResult = WriteResult.NoChanges;
-
-        if (this.applyDenyChanges(settings, { deny, allow })) {
-            denyResult = await this.writeSettings(settings);
-
-            if (denyResult === WriteResult.Rejected) {
-                return denyResult;
-            }
-        }
-
         const config = await this.readConfig();
 
         if (!config.mcpServers) {
             config.mcpServers = {};
         }
-
-        delete config.disabledMcpServers;
-        await this.restoreMissing(deny, config, { staysOffInClaude: true, source: servers });
-
-        for (const name of overridden) {
-            delete config.mcpServers[name];
-            this.reportOverridden(name, config);
+        if (!config.disabledMcpServers) {
+            config.disabledMcpServers = [];
         }
 
         for (const [name, serverConfig] of Object.entries(servers)) {
             const cleanConfig = stripMeta(serverConfig);
+
             const enabledState = serverConfig._meta?.enabled?.claude;
+            const isGloballyEnabled = enabledState === true;
+            const isGloballyDisabled = enabledState === false;
 
-            // A disabled server keeps its config in mcpServers (the deny is the switch); one that
-            // restoreMissing kept out because of Grok, or an overridden one, stays out.
-            if (enabledState !== false || (config.mcpServers[name] && !overridden.includes(name))) {
+            if (isGloballyDisabled) {
+                // TRUE global disable = absent from mcpServers (Claude Code
+                // never reads the top-level disabledMcpServers key, and the
+                // per-project sweep misses projects registered later).
+                delete config.mcpServers[name];
+            } else {
                 config.mcpServers[name] = this.unifiedToClaude(cleanConfig);
             }
 
+            if (isGloballyEnabled) {
+                config.disabledMcpServers = config.disabledMcpServers.filter((n) => n !== name);
+            } else if (!config.disabledMcpServers.includes(name)) {
+                config.disabledMcpServers.push(name);
+            }
+
             // Per-project override entry (.projects[<path>].mcpServers.<name>):
             // refresh its config from the unified config, NEVER delete it.
             for (const projectConfig of Object.values(config.projects ?? {})) {
@@ -896,7 +769,7 @@ export class ClaudeProvider extends MCPProvider {
             }
         }
 
-        return combineWrites(denyResult, await this.writeConfig(config));
+        return this.writeConfig(config);
     }
 
     /**
@@ -949,8 +822,9 @@ export class ClaudeProvider extends MCPProvider {
      * Check if a server is enabled in this provider's config
      */
     async isServerEnabled(serverName: string): Promise<boolean> {
-        const url = (await this.readConfig()).mcpServers?.[serverName]?.url;
-        return !isDeniedByClaude(await this.readDeniedEntries(), serverName, url);
+        const config = await this.readConfig();
+        const disabledServers = new Set(config.disabledMcpServers || []);
+        return !disabledServers.has(serverName);
     }
 
     fromUnifiedConfig(servers: Record<string, UnifiedMCPServerConfig>): unknown {
diff --git a/src/mcp-manager/utils/providers/grok.ts b/src/mcp-manager/utils/providers/grok.ts
index 7e43e3aab3..01c8b3410e 100644
--- a/src/mcp-manager/utils/providers/grok.ts
+++ b/src/mcp-manager/utils/providers/grok.ts
@@ -75,52 +75,6 @@ function grokConfigPathForHome(home: string): string {
     return path.join(expanded, "config.toml");
 }
 
-/**
- * Of `names`, the ones Grok would START if they appeared in `~/.claude.json` top-level `mcpServers`:
- * Grok reads that list (unless `[compat.claude] mcps = false`), Claude's `deniedMcpServers` does not
- * reach Grok, a config.toml table shadows the Claude copy, and `disabled_mcp_servers` stops it.
- * Checked in every Grok home the unified config names; a home without a config.toml has no Grok.
- * A config.toml that does not parse counts as "would start", the safe answer for the caller.
- */
-export async function namesGrokWouldStartFromClaudeJson(
-    names: string[],
-    unified: UnifiedMCPConfig
-): Promise<Set<string>> {
-    const result = new Set<string>();
-
-    for (const home of resolveHarnessHomes(unified, "grok", "syncTo")) {
-        const configPath = grokConfigPathForHome(home);
-        if (!existsSync(configPath)) {
-            continue;
-        }
-
-        let config: GrokGenericConfig;
-        try {
-            config = TOML.parse(await readFile(configPath, "utf-8")) as GrokGenericConfig;
-        } catch (error) {
-            logger.warn({ error, configPath }, "mcp-manager: could not read a Grok config; assuming Grok would start");
-            for (const name of names) {
-                result.add(name);
-            }
-
-            continue;
-        }
-
-        if (!compatMcpsOn(config, "claude")) {
-            continue;
-        }
-
-        const disabled = stringList(config.disabled_mcp_servers);
-        for (const name of names) {
-            if (!config.mcp_servers?.[name] && !disabled.includes(name)) {
-                result.add(name);
-            }
-        }
-    }
-
-    return result;
-}
-
 export class GrokProvider extends MCPProvider {
     constructor() {
         const home = path.join(env.paths.getHome() || env.paths.getUserProfile() || "~", ".grok");

From 5e4a50b0567ba488c8900bac459aad25e4319a16 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 12:18:24 +0200
Subject: [PATCH 21/32] fix(ai, macos): the vault window treats the tools
 wrapper's own preloads as part of the program, so a tools login can be
 remembered and names its real script

(cherry picked from commit 16ca45ec05e0da845f85da4a30b362c34d7d642b)
---
 .../GenesisTools/Sources/VaultUnlock.swift    | 57 ++++++++++++---
 .../GenesisTools/Tests/VaultUnlockTests.swift | 20 ++++++
 src/utils/ai/gate/client-identity.test.ts     | 18 +++++
 src/utils/ai/gate/client-identity.ts          | 69 +++++++++++++++++--
 4 files changed, 149 insertions(+), 15 deletions(-)

diff --git a/src/macos/GenesisTools/Sources/VaultUnlock.swift b/src/macos/GenesisTools/Sources/VaultUnlock.swift
index 5f16790030..a774a4ab9a 100644
--- a/src/macos/GenesisTools/Sources/VaultUnlock.swift
+++ b/src/macos/GenesisTools/Sources/VaultUnlock.swift
@@ -52,12 +52,49 @@ struct VaultCaller {
 
     private static let scriptExtensions = [".ts", ".tsx", ".js", ".mjs", ".cjs"]
 
-    /// Where the script sits in the arguments: after the interpreter's flags and the `run` of `bun run <script>`.
+    /// Interpreter flags whose value is the next argument (`--preload <file>`): that value is not the script.
+    private static let valueFlags: Set<String> = [
+        "--preload", "-r", "--require", "--import", "--loader", "--config", "--cwd", "--env-file",
+    ]
+
+    /// The preloads the `tools` wrapper passes to every tool, relative to the checkout the script is in. They are
+    /// GenesisTools' own code, so they load no extra code (2026-10-15: every `tools claude login` could only be
+    /// allowed once, and the window named the preload as the program).
+    static let ownPreloads = ["src/utils/bun/preload-solid-scoped.ts", "src/utils/search/stores/sqlite-vec-preload.ts"]
+
+    /// The interpreter's flags before the script, each with its value (`--preload=x` or `--preload x`).
+    private var leadingFlags: [(flag: String, value: String?)] {
+        guard let arguments = args?.arguments, arguments.count > 1 else { return [] }
+        var flags: [(flag: String, value: String?)] = []
+        var index = 1
+        while index < arguments.count {
+            let argument = arguments[index]
+            if argument == "run" { index += 1; continue }
+            guard argument.hasPrefix("-") else { break }
+            if let equals = argument.firstIndex(of: "=") {
+                flags.append((String(argument[..<equals]), String(argument[argument.index(after: equals)...])))
+                index += 1
+            } else if Self.valueFlags.contains(argument) {
+                flags.append((argument, index + 1 < arguments.count ? arguments[index + 1] : nil))
+                index += 2
+            } else {
+                flags.append((argument, nil))
+                index += 1
+            }
+        }
+        return flags
+    }
+
+    /// Where the script sits in the arguments: after the interpreter's flags (and their values) and the `run` of
+    /// `bun run <script>`.
     private var scriptIndex: Int? {
         guard let arguments = args?.arguments, arguments.count > 1 else { return nil }
         var index = 1
-        while index < arguments.count, arguments[index].hasPrefix("-") || arguments[index] == "run" {
-            index += 1
+        while index < arguments.count {
+            let argument = arguments[index]
+            if argument == "run" { index += 1; continue }
+            guard argument.hasPrefix("-") else { break }
+            index += !argument.contains("=") && Self.valueFlags.contains(argument) ? 2 : 1
         }
 
         guard index < arguments.count, Self.scriptExtensions.contains(where: arguments[index].hasSuffix) else { return nil }
@@ -105,11 +142,15 @@ struct VaultCaller {
             }
         }
 
-        let arguments = args?.arguments ?? []
-        let end = scriptIndex ?? arguments.count
-        let flags = arguments.count > 1 ? arguments[1..<max(1, end)].filter { $0.hasPrefix("-") } : []
-        if flags.contains(where: { ["--preload", "-r", "--require", "--import", "--loader"].contains($0) }) {
-            found.append("interpreter flags \(flags.joined(separator: " "))")
+        // A checkout's own preloads are part of the program; any other preload, or any other loading flag, is not.
+        let checkout = script.flatMap { path in path.range(of: "/src/").map { String(path[..<$0.lowerBound]) } }
+        let own = Set(Self.ownPreloads.compactMap { relative in checkout.map { root in "\(root)/\(relative)" } })
+        let foreign = leadingFlags.filter { flag in
+            !(flag.flag == "--preload" && flag.value.map { value in own.contains((value as NSString).standardizingPath) } == true)
+        }
+        if foreign.contains(where: { ["--preload", "-r", "--require", "--import", "--loader"].contains($0.flag) }) {
+            let shown = foreign.map { flag in flag.value.map { value in "\(flag.flag) \(value)" } ?? flag.flag }
+            found.append("interpreter flags \(shown.joined(separator: " "))")
         }
 
         return found
diff --git a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
index 02e5f69507..4048bfbd12 100644
--- a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
+++ b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
@@ -67,6 +67,26 @@ final class VaultUnlockTests: XCTestCase {
         XCTAssertEqual(injected.onceOnlyReason, "extra code may be loaded")
     }
 
+    func testGenesisToolsOwnPreloadsAreNotExtraCodeAndDoNotHideTheScript() {
+        // `tools claude login-long admin` as the tools wrapper starts it (2026-10-15: the window named the preload as
+        // the program and allowed it only once).
+        let login = caller(arguments: ["gt-claude", "--preload", "/repo/src/utils/bun/preload-solid-scoped.ts",
+                                       "--preload", "/repo/src/utils/search/stores/sqlite-vec-preload.ts",
+                                       "/repo/src/claude/index.ts", "login-long", "admin"])
+        XCTAssertEqual(login.script, "/repo/src/claude/index.ts")
+        XCTAssertEqual(login.toolName, "claude")
+        XCTAssertEqual(login.injected, [])
+        XCTAssertNil(login.onceOnlyReason)
+
+        // The same file from another checkout, or another file in this one, is still extra code.
+        let foreign = caller(arguments: ["gt-claude", "--preload", "/other/src/utils/bun/preload-solid-scoped.ts",
+                                         "/repo/src/claude/index.ts"])
+        XCTAssertEqual(foreign.script, "/repo/src/claude/index.ts")
+        XCTAssertFalse(foreign.injected.isEmpty)
+        let other = caller(arguments: ["gt-claude", "--preload=/repo/src/utils/bun/other.ts", "/repo/src/claude/index.ts"])
+        XCTAssertFalse(other.injected.isEmpty)
+    }
+
     func testARememberedApprovalCoversOnlyTheSameExecutableAndScriptUntilItEnds() {
         let grant = VaultGrant(key: "k", tool: "claude", executable: "/bin/gt-claude", script: "/repo/src/claude/index.ts",
                                grantedAt: 1_000, until: 2_000, method: "touch-id")
diff --git a/src/utils/ai/gate/client-identity.test.ts b/src/utils/ai/gate/client-identity.test.ts
index b711c1bbdc..8c685400fc 100644
--- a/src/utils/ai/gate/client-identity.test.ts
+++ b/src/utils/ai/gate/client-identity.test.ts
@@ -226,6 +226,24 @@ describe("describeClient", () => {
         expect(isInterpreter("/Applications/Pi.app/Contents/MacOS/pi")).toBe(false);
     });
 
+    test("GenesisTools' own preloads neither hide the script nor count as extra code", () => {
+        // `tools claude login-long admin` as the tools wrapper starts it (2026-10-15: every login could be allowed
+        // only once, and the preload was taken for the script).
+        const bun = "/opt/bun/bin/bun";
+        const login =
+            "gt-claude --preload /repo/src/utils/bun/preload-solid-scoped.ts" +
+            " --preload /repo/src/utils/search/stores/sqlite-vec-preload.ts /repo/src/claude/index.ts login-long admin";
+        expect(scriptOf(login, null, bun)).toBe("/repo/src/claude/index.ts");
+        expect(codeInjectionSignals(login, null, bun)).toEqual([]);
+
+        const foreign = "gt-claude --preload /other/src/utils/bun/preload-solid-scoped.ts /repo/src/claude/index.ts";
+        expect(scriptOf(foreign, null, bun)).toBe("/repo/src/claude/index.ts");
+        expect(codeInjectionSignals(foreign, null, bun)).toEqual(["flag --preload"]);
+        expect(codeInjectionSignals("bun --preload=/repo/src/utils/bun/x.ts /repo/src/a/index.ts", null, bun)).toEqual([
+            "flag --preload",
+        ]);
+    });
+
     test("framework Python and other interpreters are matched without regard to case", () => {
         for (const path of [
             "/Library/Frameworks/Python.framework/Versions/3.12/Resources/Python.app/Contents/MacOS/Python",
diff --git a/src/utils/ai/gate/client-identity.ts b/src/utils/ai/gate/client-identity.ts
index bfd6fc4512..4626641ca9 100644
--- a/src/utils/ai/gate/client-identity.ts
+++ b/src/utils/ai/gate/client-identity.ts
@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { statSync } from "node:fs";
-import { basename, isAbsolute, resolve } from "node:path";
+import { basename, isAbsolute, join, resolve } from "node:path";
 import { logger } from "@genesiscz/utils/logger";
 import {
     batchCommandWithEnvironment,
@@ -28,6 +28,54 @@ const COMMAND_DISPLAY_MAX = 200;
 const INTERPRETERS =
     /^(node|nodejs|bun|deno|python[0-9.]*|pypy[0-9.]*|ruby[0-9.]*|perl[0-9.]*|php[0-9.]*|lua[0-9.]*|luajit|tclsh[0-9.]*|wish|osascript|java|pwsh|sh|bash|zsh|fish|dash|ksh|mksh|tcsh|csh)$/i;
 
+/** bun and node flags whose value is the next argument (`--preload <file>`): that value is not the script. */
+const VALUE_FLAGS = new Set([
+    "--preload",
+    "-r",
+    "--require",
+    "--import",
+    "--loader",
+    "--config",
+    "--cwd",
+    "--env-file",
+]);
+const VALUE_FLAG_RUNNERS = /^(node|nodejs|bun)$/i;
+
+/**
+ * The preloads the `tools` wrapper passes to every tool, relative to the checkout the script is in. They are
+ * GenesisTools' own code, so they load no extra code (2026-10-15: every `tools claude login` could be allowed only
+ * once, and the preload was taken for the script). The Swift vault window keeps the same list (`ownPreloads`).
+ */
+export const OWN_PRELOADS = ["src/utils/bun/preload-solid-scoped.ts", "src/utils/search/stores/sqlite-vec-preload.ts"];
+
+/** The interpreter's flags before the script, each with its value, and the arguments from the script on. */
+function splitLeadingFlags(
+    args: string[],
+    executable: string
+): { flags: Array<{ flag: string; value: string | null }>; rest: string[] } {
+    const takesValues = VALUE_FLAG_RUNNERS.test(basename(executable));
+    const flags: Array<{ flag: string; value: string | null }> = [];
+    let index = 0;
+
+    while (index < args.length && args[index].startsWith("-")) {
+        const arg = args[index];
+        const equals = arg.indexOf("=");
+
+        if (equals !== -1) {
+            flags.push({ flag: arg.slice(0, equals), value: arg.slice(equals + 1) });
+            index += 1;
+        } else if (takesValues && VALUE_FLAGS.has(arg)) {
+            flags.push({ flag: arg, value: args[index + 1] ?? null });
+            index += 2;
+        } else {
+            flags.push({ flag: arg, value: null });
+            index += 1;
+        }
+    }
+
+    return { flags, rest: args.slice(index) };
+}
+
 /** Runners that take a subcommand before the script: `bun run pi.ts`, `deno run -A pi.ts`. */
 const SUBCOMMAND_RUNNERS = /^(bun|deno)$/i;
 
@@ -192,7 +240,8 @@ export function scriptOf(
     cwd: string | null,
     executable: string = executableOf(command)
 ): string | null {
-    const script = scriptArgs(command, executable)?.find((arg) => !arg.startsWith("-"));
+    const args = scriptArgs(command, executable);
+    const script = args ? splitLeadingFlags(args, executable).rest[0] : undefined;
 
     if (!script) {
         return null;
@@ -217,13 +266,19 @@ export function codeInjectionSignals(
     executable: string = executableOf(command)
 ): string[] {
     const signals: string[] = [];
-
-    for (const arg of scriptArgs(command, executable) ?? []) {
-        if (!arg.startsWith("-")) {
-            break;
+    const { flags, rest } = splitLeadingFlags(scriptArgs(command, executable) ?? [], executable);
+    const script = rest[0];
+    const checkout =
+        script && isAbsolute(script) && script.includes("/src/") ? script.slice(0, script.indexOf("/src/")) : null;
+    const own = new Set(checkout ? OWN_PRELOADS.map((relative) => join(checkout, relative)) : []);
+
+    for (const { flag, value } of flags) {
+        // A checkout's own preloads are part of the program; any other preload, or any other flag, is not.
+        if (flag === "--preload" && value && own.has(resolve(value))) {
+            continue;
         }
 
-        signals.push(`flag ${arg.split("=")[0]}`);
+        signals.push(`flag ${flag}`);
     }
 
     signals.push(...environmentSignals(environmentLine, CODE_LOADING_ENV));

From b653703cc28c904593b537e6ec06fde2cb662e72 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 14:41:52 +0200
Subject: [PATCH 22/32] fix(agents, hooks): a block fill stops at diff.fillMax
 (72) columns, because one long changed line padded every row to the pane and
 a narrower pane then wrapped each row into an empty band row

(cherry picked from commit 6abf17709b44ec4f4f2b30b4edf76e21fa09e3df)
---
 src/agents/README.md                   |  4 +++-
 src/agents/lib/hooks/config.ts         | 10 ++++++++++
 src/agents/lib/hooks/diff/diff.test.ts | 22 ++++++++++++++++++++++
 src/agents/lib/hooks/diff/render.ts    | 20 ++++++++++++--------
 src/agents/lib/hooks/set-config.ts     |  6 ++++++
 5 files changed, 53 insertions(+), 9 deletions(-)

diff --git a/src/agents/README.md b/src/agents/README.md
index dd483a793f..c8dd02dcf5 100644
--- a/src/agents/README.md
+++ b/src/agents/README.md
@@ -198,7 +198,9 @@ only while the browser router routes Markdown on this Mac; otherwise the message
 `tools agents hooks diff show <call>` prints it too.
 
 `diff.fill` sets how far a changed row's band reaches. `block` (default) fills to the widest row of
-the file. `terminal` fills to the pane's width, like Claude Code's own diff; but a hook message is fixed
+the file, but never past `diff.fillMax` columns (72; 0 lifts the limit): without that, one long line made
+every row as wide as the pane, and every row wrapped into an empty band row when the pane got narrower.
+A row longer than the limit is not padded. `terminal` fills to the pane's width, like Claude Code's own diff; but a hook message is fixed
 text, so when the pane later gets narrower, every row wraps into an empty band row. `none` ends the band
 with the text.
 
diff --git a/src/agents/lib/hooks/config.ts b/src/agents/lib/hooks/config.ts
index 90dbde7448..97fdb5285c 100644
--- a/src/agents/lib/hooks/config.ts
+++ b/src/agents/lib/hooks/config.ts
@@ -65,6 +65,14 @@ export interface DiffConfig {
      * narrower every row wraps into an empty band row. `none`: the band ends with the text.
      */
     fill: FillMode;
+    /**
+     * The most columns a `block` fill pads a row to, the gutter included; 0 lifts the limit. Without it
+     * one long changed line widened every row of the file to the pane, and a hook message is fixed text:
+     * once the pane was narrower than when the message was drawn, every padded row wrapped into an empty
+     * band row (2026-10-15 11:54: rows of 106 columns, shown in a pane of 76). A row longer than this is
+     * not padded and its band ends with the text.
+     */
+    fillMax: number;
     /**
      * How a block looks; see `diff/theme.ts`. `claude` copies Claude Code's own Bash diff in the
      * theme Claude Code is set to, so the hook can replace that diff (`bashEditDiffEnabled: false`)
@@ -346,6 +354,7 @@ export const DEFAULT_HOOKS_CONFIG: HooksConfig = {
         maxCaptureFileMB: 0.256,
         highlight: "256",
         fill: "block",
+        fillMax: 72,
         theme: "claude",
         columns: "auto",
         fullDiff: "genesis",
@@ -560,6 +569,7 @@ function mergeDiff(stored: StoredHooksConfig["diff"]): DiffConfig {
         }),
         highlight: highlightOr(stored?.highlight, base.highlight),
         fill: FILL_MODES.find((mode) => mode === stored?.fill) ?? base.fill,
+        fillMax: countOr({ field: "diff.fillMax", value: stored?.fillMax, fallback: base.fillMax, min: 0 }),
         theme: themeOr(stored?.theme, base.theme),
         columns: columnsOr(stored?.columns, base.columns),
         fullDiff: FULL_DIFF_MODES.find((mode) => mode === stored?.fullDiff) ?? base.fullDiff,
diff --git a/src/agents/lib/hooks/diff/diff.test.ts b/src/agents/lib/hooks/diff/diff.test.ts
index 2f13dc6483..36e7edbe98 100644
--- a/src/agents/lib/hooks/diff/diff.test.ts
+++ b/src/agents/lib/hooks/diff/diff.test.ts
@@ -3565,6 +3565,28 @@ describe("the claude theme: Claude Code's own Bash diff, drawn by the hook", ()
         expect(widths[0]).toBeLessThan(40);
     });
 
+    it("stops a block fill at fillMax, so one long changed row cannot widen every row to the pane", () => {
+        const long = `-old ${"x".repeat(95)}`;
+        const patch = ["@@ -1,3 +1,3 @@", long, "-short one", "+short two", " same"].join("\n");
+        const rendered = renderPatch(patch, palette);
+        const block: DiffBlock = {
+            head: "head",
+            body: rendered.body,
+            dress: themedDress({ palette, path: "x.ts", width: 120 }),
+        };
+        const shown = (fillMax: number) =>
+            assembleMessage([block], { ...quiet, fillMax, maxMessageChars: 100_000 })
+                .split("\n")
+                .map((line) => stripAnsi(line))
+                .filter((line) => /short (one|two)/.test(line))
+                .map((line) => Bun.stringWidth(line));
+
+        expect(DEFAULT_HOOKS_CONFIG.diff.fillMax).toBe(72);
+        expect(shown(72)).toEqual([72, 72]);
+        // 0 lifts the limit: the short rows reach the long row's width, as before.
+        expect(shown(0).every((width) => width > 100)).toBe(true);
+    });
+
     it("wraps a long row under its own content, band and colour carried onto every part", () => {
         const long = `const message = "${"x".repeat(50)}";`;
         const patch = ["@@ -1,1 +1,1 @@", "-const message = 1;", `+${long}`].join("\n");
diff --git a/src/agents/lib/hooks/diff/render.ts b/src/agents/lib/hooks/diff/render.ts
index 61b84240d7..5d632f5aa2 100644
--- a/src/agents/lib/hooks/diff/render.ts
+++ b/src/agents/lib/hooks/diff/render.ts
@@ -832,12 +832,14 @@ function textLength(text: string): number {
 
 /**
  * The right edge of a `block` fill: the widest kept CHANGED row of the file plus two columns (a context
- * row carries no band, and one long wrapped comment made the block as wide as the pane). A hook message
- * is fixed text, so a band padded to the terminal's width wrapped into an empty band row under every
- * row once the pane got narrower (2026-10-15 01:17: rows of 163 columns, padded for a 170-column pane
- * that was 167 columns by then). A block-wide band wraps only where the text itself would.
+ * row carries no band), and never past `fillMax` columns in all (the gutter is `INDENT` of them). A hook
+ * message is fixed text, so a band padded to the terminal's width wrapped into an empty band row under
+ * every row once the pane got narrower (2026-10-15 01:17: rows of 163 columns, padded for a 170-column
+ * pane that was 167 by then). One long changed line made the block as wide as the pane all the same
+ * (11:54: 30 rows padded to 106 columns for one 98-column comment, shown in a pane of 76), hence the cap.
+ * A row past the cap is not padded; its band ends with the text.
  */
-function blockWidth(body: PatchLine[], held: Set<number> | undefined): number {
+function blockWidth(body: PatchLine[], held: Set<number> | undefined, fillMax: number): number {
     let widest = 0;
 
     for (const at of held ?? []) {
@@ -848,7 +850,7 @@ function blockWidth(body: PatchLine[], held: Set<number> | undefined): number {
         }
     }
 
-    return widest + 2;
+    return fillMax > 0 ? Math.min(widest + 2, Math.max(0, fillMax - INDENT)) : widest + 2;
 }
 
 /**
@@ -862,12 +864,14 @@ function dressBlocks({
     tinted,
     budget,
     fill,
+    fillMax,
 }: {
     blocks: DiffBlock[];
     kept: Set<number>[];
     tinted: Map<number, string>[];
     budget: number;
     fill: FillMode;
+    fillMax: number;
 }): number {
     let left = budget;
 
@@ -882,7 +886,7 @@ function dressBlocks({
             return;
         }
 
-        const fillTo = fill === "block" ? blockWidth(block.body, kept[index]) : undefined;
+        const fillTo = fill === "block" ? blockWidth(block.body, kept[index], fillMax) : undefined;
 
         for (const at of [...(kept[index] ?? [])].sort((first, second) => first - second)) {
             const line = block.body[at];
@@ -984,7 +988,7 @@ export function fitMessage(blocks: DiffBlock[], config: DiffConfig): { message:
         }
     }
 
-    left = dressBlocks({ blocks, kept, tinted, budget: left, fill: config.fill });
+    left = dressBlocks({ blocks, kept, tinted, budget: left, fill: config.fill, fillMax: config.fillMax });
 
     blocks.forEach((block, index) => {
         const held = kept[index];
diff --git a/src/agents/lib/hooks/set-config.ts b/src/agents/lib/hooks/set-config.ts
index 215d4cbf59..9174aa285a 100644
--- a/src/agents/lib/hooks/set-config.ts
+++ b/src/agents/lib/hooks/set-config.ts
@@ -44,6 +44,7 @@ export const SETTABLE_KEYS = [
     "diff.theme",
     "diff.highlight",
     "diff.fill",
+    "diff.fillMax",
     "diff.columns",
     "diff.fullDiff",
     "diff.replaceNative",
@@ -346,6 +347,11 @@ export function applySetting(
         return next;
     }
 
+    if (key === "diff.fillMax") {
+        next.diff.fillMax = asCount(key, value, 0);
+        return next;
+    }
+
     if (key === "diff.fullDiff") {
         const mode = FULL_DIFF_MODES.find((candidate) => candidate === value);
 

From a0500ae2144d222bbe638fde5b6d072308df15ec Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 15:17:41 +0200
Subject: [PATCH 23/32] fix(agents, hooks): a folder moved with one mv is one
 "old/ -> new/ (N files)" line, because its new copy was a collapsed untracked
 entry, over the expansion cap and the scan limit, and the files were drawn as
 whole-file deletions

(cherry picked from commit 00c7a6bd024b7568d9298010d1c4136ee37cf60b)
---
 src/agents/README.md                   |   4 +-
 src/agents/lib/hooks/diff/diff.test.ts |  73 ++++++++++++
 src/agents/lib/hooks/diff/run.ts       | 155 +++++++++++++++++++++----
 3 files changed, 208 insertions(+), 24 deletions(-)

diff --git a/src/agents/README.md b/src/agents/README.md
index c8dd02dcf5..263aedc0d8 100644
--- a/src/agents/README.md
+++ b/src/agents/README.md
@@ -195,7 +195,9 @@ Every mode drops escape codes that change nothing (a reset before a new colour,
 colour on blanks); that loses no colour, so there is no raw mode. A message that cuts lines links
 the call's full diff (`diff.fullDiff`: `genesis`, `path` or `off`). The `genesis` link is printed
 only while the browser router routes Markdown on this Mac; otherwise the message names the path.
-`tools agents hooks diff show <call>` prints it too.
+`tools agents hooks diff show <call>` prints it too. A file or a whole folder moved with `mv` or
+`git mv` is one line, `old/ → new/ (284 files)`, when the new copies match the old ones byte for byte
+(up to 4,000 files; a file over 4 MiB is not compared).
 
 `diff.fill` sets how far a changed row's band reaches. `block` (default) fills to the widest row of
 the file, but never past `diff.fillMax` columns (72; 0 lifts the limit): without that, one long line made
diff --git a/src/agents/lib/hooks/diff/diff.test.ts b/src/agents/lib/hooks/diff/diff.test.ts
index 36e7edbe98..c4d7806134 100644
--- a/src/agents/lib/hooks/diff/diff.test.ts
+++ b/src/agents/lib/hooks/diff/diff.test.ts
@@ -4,8 +4,10 @@ import {
     existsSync,
     mkdirSync,
     mkdtempSync,
+    readdirSync,
     readFileSync,
     realpathSync,
+    renameSync,
     rmSync,
     statSync,
     symlinkSync,
@@ -4335,6 +4337,77 @@ describe("the misfires of 2026-10-14", () => {
         git(["commit", "-qm", "owned done"]);
     });
 
+    it("pairs a whole folder moved with one mv, past the expansion cap and the old scan limit", () => {
+        const names = Array.from({ length: 450 }, (_, index) => `note-${String(index).padStart(3, "0")}.md`);
+
+        mkdirSync(join(repo, "moved-src", "inner"), { recursive: true });
+
+        for (const [index, name] of names.entries()) {
+            writeFileSync(join(repo, "moved-src", index % 2 === 0 ? name : `inner/${name}`), `body of ${name}\n`);
+        }
+
+        git(["add", "moved-src"]);
+        git(["commit", "-qm", "folder to move"]);
+
+        const past = new Date(Date.now() - 3_600_000);
+
+        for (const dir of ["moved-src", "moved-src/inner"]) {
+            for (const entry of readdirSync(join(repo, dir), { withFileTypes: true })) {
+                if (entry.isFile()) {
+                    utimesSync(join(repo, dir, entry.name), past, past);
+                }
+            }
+        }
+
+        const current = begin({ command: "mv moved-src moved-dst" });
+
+        renameSync(join(repo, "moved-src"), join(repo, "moved-dst"));
+
+        const decision = runDiffPost({ payload: current, config: plain });
+        const message = decision.message ?? "";
+
+        try {
+            expect(message).toContain("450 file(s) moved unchanged");
+            expect(message).toContain("moved-src/ → moved-dst/ (450 files)");
+            expect(message).not.toContain("Deleted");
+            expect(decision.files).toEqual([]);
+        } finally {
+            git(["add", "-A", "moved-src", "moved-dst"]);
+            git(["commit", "-qm", "folder moved"]);
+        }
+    });
+
+    it("shows a single moved file with both paths, and a renamed one too", () => {
+        const text = "single\n";
+
+        writeFileSync(join(repo, "single-a.ts"), text);
+        writeFileSync(join(repo, "single-b.ts"), `${text}two\n`);
+        git(["add", "single-a.ts", "single-b.ts"]);
+        git(["commit", "-qm", "singles"]);
+        mkdirSync(join(repo, "single-dir"), { recursive: true });
+
+        const past = new Date(Date.now() - 3_600_000);
+
+        utimesSync(join(repo, "single-a.ts"), past, past);
+        utimesSync(join(repo, "single-b.ts"), past, past);
+
+        const current = begin({ command: "mv single-a.ts single-dir/single-a.ts && mv single-b.ts single-c.ts" });
+
+        renameSync(join(repo, "single-a.ts"), join(repo, "single-dir", "single-a.ts"));
+        renameSync(join(repo, "single-b.ts"), join(repo, "single-c.ts"));
+
+        const message = runDiffPost({ payload: current, config: plain }).message ?? "";
+
+        try {
+            expect(message).toContain("2 file(s) moved unchanged");
+            expect(message).toContain("single-a.ts → single-dir/single-a.ts");
+            expect(message).toContain("single-b.ts → single-c.ts");
+        } finally {
+            git(["add", "-A", "single-dir", "single-c.ts", "single-a.ts", "single-b.ts"]);
+            git(["commit", "-qm", "singles moved"]);
+        }
+    });
+
     it("does not announce a rename another actor owns", () => {
         writeFileSync(join(repo, "foreign-src.ts"), "moved\nbody\n");
         git(["add", "foreign-src.ts"]);
diff --git a/src/agents/lib/hooks/diff/run.ts b/src/agents/lib/hooks/diff/run.ts
index 76ee9c1abd..681f9019b2 100644
--- a/src/agents/lib/hooks/diff/run.ts
+++ b/src/agents/lib/hooks/diff/run.ts
@@ -28,7 +28,7 @@ import {
 } from "../../changes/log";
 import { gitObjectSink } from "../../changes/objects";
 import { type DiffConfig, diffFor, type HooksConfig } from "../config";
-import { committedPaths, gitOut, lastHistoryMove, objectId, statusOf } from "../git";
+import { committedPaths, gitOut, lastHistoryMove, objectId, statusOf, untrackedFilesIn } from "../git";
 import { hookDiag } from "../log";
 import { callDir, safeSegment } from "../paths";
 import { type HookPayload, normalizeEvent } from "../payload";
@@ -193,8 +193,41 @@ function siblingNamed({ ownDir, since, actor }: { ownDir: string; since: number;
     return found;
 }
 
-/** More files than this in one root, and renames are not looked for: two git spawns cover them all. */
-const RENAME_SCAN_LIMIT = 400;
+/**
+ * More files than this in one root, and renames are not looked for. The git work is a few spawns of
+ * at most `RENAME_ARGS` paths each, whatever the count; the limit bounds the files hashed (a vault
+ * folder of 284 notes moved with one `mv` is 568 candidates).
+ */
+const RENAME_SCAN_LIMIT = 4_000;
+const RENAME_ARGS = 400;
+/** A file this large is not hashed for pairing: reading it costs more than a moved copy is worth. */
+const RENAME_MAX_BYTES = 4 * 1024 * 1024;
+
+function inChunks<T>(items: T[], size: number): T[][] {
+    const chunks: T[][] = [];
+
+    for (let at = 0; at < items.length; at += size) {
+        chunks.push(items.slice(at, at + size));
+    }
+
+    return chunks;
+}
+
+function commonSuffix(first: string, second: string): number {
+    const left = first.split("/");
+    const right = second.split("/");
+    let shared = 0;
+
+    while (
+        shared < left.length &&
+        shared < right.length &&
+        left[left.length - 1 - shared] === right[right.length - 1 - shared]
+    ) {
+        shared += 1;
+    }
+
+    return shared;
+}
 /**
  * Files past `maxFiles` whose patch still goes into the full diff, as a multiple of `maxFiles`
  * (45 at the default 15). Each costs one `git diff` process in the post hook (7.2 ms p50, 11.3 ms
@@ -224,32 +257,54 @@ function renamesIn({
     to: string;
 }> {
     const gone = files.filter((file) => file.deleted);
+
+    if (gone.length === 0) {
+        return [];
+    }
+
     // From `git status`, not from `files`: `git mv` and `mv` keep the file's old mtime, so the moved
     // copy is older than the call and the mtime filter behind `files` drops it (2026-10-15: the test
-    // passed only when the write and the move fell in one second).
+    // passed only when the write and the move fell in one second). A folder moved whole is one
+    // collapsed `? new-folder/` entry; it is expanded here, past `untrackedExpansionCap`, because the
+    // cap bounds what is shown and a rename costs no row.
+    const collapsed = entries
+        .filter((entry) => entry.kind === "untracked" && entry.path.endsWith("/"))
+        .flatMap((entry) =>
+            (untrackedFilesIn(root, entry.path, RENAME_SCAN_LIMIT) ?? []).map((name) => join(root, name))
+        );
     const fresh = [
         ...new Set([
             ...files.filter((file) => !file.deleted).map((file) => file.path),
             ...entries
                 .filter((entry) => (entry.kind === "untracked" && !entry.path.endsWith("/")) || entry.index === "A")
                 .map((entry) => join(root, entry.path)),
+            ...collapsed,
         ]),
-    ];
+    ].filter((path) => {
+        try {
+            return statSync(path).size <= RENAME_MAX_BYTES;
+        } catch {
+            return false;
+        }
+    });
 
-    if (gone.length === 0 || fresh.length === 0 || fresh.length + gone.length > RENAME_SCAN_LIMIT) {
+    if (fresh.length === 0 || fresh.length + gone.length > RENAME_SCAN_LIMIT) {
         return [];
     }
 
-    const blobs = new Map<string, string>();
-    const listing = gitOut(root, ["ls-tree", "-z", base, "--", ...gone.map((file) => relative(root, file.path))], {
-        quiet: true,
-    });
+    const blobs = new Map<string, string[]>();
+
+    for (const chunk of inChunks(gone, RENAME_ARGS)) {
+        const listing = gitOut(root, ["ls-tree", "-z", base, "--", ...chunk.map((file) => relative(root, file.path))], {
+            quiet: true,
+        });
 
-    for (const entry of listing.split("\0")) {
-        const match = /^\d+ blob ([0-9a-f]+)\t(.+)$/.exec(entry);
+        for (const entry of listing.split("\0")) {
+            const match = /^\d+ blob ([0-9a-f]+)\t(.+)$/.exec(entry);
 
-        if (match?.[1] && match[2]) {
-            blobs.set(match[1], join(root, match[2]));
+            if (match?.[1] && match[2]) {
+                blobs.set(match[1], [...(blobs.get(match[1]) ?? []), join(root, match[2])]);
+            }
         }
     }
 
@@ -257,17 +312,31 @@ function renamesIn({
         return [];
     }
 
-    const hashes = gitOut(root, ["hash-object", "--", ...fresh], { quiet: true }).split("\n");
+    const hashes: string[] = [];
+
+    for (const chunk of inChunks(fresh, RENAME_ARGS)) {
+        const out = gitOut(root, ["hash-object", "--", ...chunk], { quiet: true }).split("\n");
+
+        hashes.push(...chunk.map((_, index) => out[index]?.trim() ?? ""));
+    }
+
     const pairs: Array<{ from: string; to: string }> = [];
 
     fresh.forEach((path, index) => {
-        const hash = hashes[index]?.trim() ?? "";
-        const from = blobs.get(hash);
+        const candidates = blobs.get(hashes[index] ?? "");
 
-        if (from) {
-            pairs.push({ from, to: path });
-            blobs.delete(hash);
+        if (!candidates || candidates.length === 0) {
+            return;
         }
+
+        // Files with the same content (empty placeholders, copies) pair with the deletion that shares
+        // the most trailing path with the new name, so a folder move keeps each file in its own place.
+        const best = candidates.reduce((chosen, candidate) =>
+            commonSuffix(candidate, path) > commonSuffix(chosen, path) ? candidate : chosen
+        );
+
+        pairs.push({ from: best, to: path });
+        candidates.splice(candidates.indexOf(best), 1);
     });
 
     return pairs;
@@ -292,11 +361,51 @@ function ownedRename(
     return fromKind !== "others" && fromKind !== "ambiguous" && toKind !== "others" && toKind !== "ambiguous";
 }
 
+/**
+ * The note for files that moved unchanged. Two or more files that moved from one folder to one
+ * other with their names kept are one entry, `old/ → new/ (284 files)`; a lone file shows both paths.
+ */
 function renameLine(root: string, pairs: Array<{ from: string; to: string }>): string {
-    const shown = pairs.slice(0, 3).map((pair) => `${relative(root, pair.from)} → ${relative(root, pair.to)}`);
-    const more = pairs.length > 3 ? ` and ${pairs.length - 3} more` : "";
+    const prefix = (path: string, shared: number): string => {
+        const parts = path.split("/");
+
+        return parts.slice(0, parts.length - shared).join("/") || ".";
+    };
+    const moves = pairs.map((pair) => {
+        const from = relative(root, pair.from);
+        const to = relative(root, pair.to);
+        const shared = commonSuffix(from, to);
+
+        // A renamed file shares no trailing segment; a moved one shares at least its name.
+        return { from, to, key: shared >= 1 ? `${prefix(from, shared)}/ → ${prefix(to, shared)}/` : null };
+    });
+    const folders = new Map<string, number>();
+
+    for (const move of moves) {
+        if (move.key) {
+            folders.set(move.key, (folders.get(move.key) ?? 0) + 1);
+        }
+    }
+
+    const entries: string[] = [];
+    const named = new Set<string>();
+
+    for (const move of moves) {
+        const count = move.key ? (folders.get(move.key) ?? 0) : 0;
+
+        if (move.key && count >= 2) {
+            if (!named.has(move.key)) {
+                named.add(move.key);
+                entries.push(`${move.key} (${count} files)`);
+            }
+        } else {
+            entries.push(`${move.from} → ${move.to}`);
+        }
+    }
+
+    const more = entries.length > 3 ? ` and ${entries.length - 3} more` : "";
 
-    return `${pairs.length} file(s) moved unchanged in ${basename(root)}: ${shown.join(", ")}${more}`;
+    return `${pairs.length} file(s) moved unchanged in ${basename(root)}: ${entries.slice(0, 3).join(", ")}${more}`;
 }
 
 /**

From 23b521b81c2ecb5d2ef9b9ee324bcbd5bb2fa43c Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 15:22:31 +0200
Subject: [PATCH 24/32] feat(agents, hooks): themed diff rows are coloured by
 highlight.js in Claude Code's own palette instead of a bat process, with bat
 kept for light themes and unknown file types (diff.highlighter)

(cherry picked from commit 0c1f0489091459fe26761c904312dd43ec1a41ea)
---
 src/agents/README.md                   |   9 +-
 src/agents/lib/hooks/config.ts         |  12 ++
 src/agents/lib/hooks/diff/diff.test.ts |  76 +++++++
 src/agents/lib/hooks/diff/render.ts    |  38 +++-
 src/agents/lib/hooks/diff/syntax.ts    | 269 +++++++++++++++++++++++++
 src/agents/lib/hooks/set-config.ts     |  13 ++
 6 files changed, 406 insertions(+), 11 deletions(-)
 create mode 100644 src/agents/lib/hooks/diff/syntax.ts

diff --git a/src/agents/README.md b/src/agents/README.md
index 263aedc0d8..9fb457b327 100644
--- a/src/agents/README.md
+++ b/src/agents/README.md
@@ -183,7 +183,14 @@ Every row carries its syntax colour and is wrapped at the terminal width before
 rows are bought first, together with the context row right above and below each change, then the
 other context, nearest first. The full-width fill is bought last, from what is left.
 
-`diff.highlight` sets the syntax colour, through `bat` (one run per syntax in a message):
+`diff.highlighter` picks what paints the syntax colour. `hljs` (default) is highlight.js in process,
+in Claude Code's own dark palette (Monokai Extended, 24 scopes): it loads in about 7 ms once, then 0.3 ms a
+call, and on three samples of this repository wrote about half the characters of `bat` (5,539 against
+10,934 for 90 lines of TypeScript; 146 colour switches against 387). `bat` is one process per syntax in a
+message (25 ms median) in `bat`'s own theme. A file type the painter does not know (`.txt`, `.env`), a text
+none of whose scopes has a colour in that palette (Markdown), and every light theme go to `bat`.
+
+`diff.highlight` sets how much colour is written, for either painter (`bat` is spawned once per syntax in a message):
 
 | Mode | Characters | Risk |
 |---|---|---|
diff --git a/src/agents/lib/hooks/config.ts b/src/agents/lib/hooks/config.ts
index 97fdb5285c..419e051a47 100644
--- a/src/agents/lib/hooks/config.ts
+++ b/src/agents/lib/hooks/config.ts
@@ -58,6 +58,13 @@ export interface DiffConfig {
      * loses no colour, so there is no raw mode.
      */
     highlight: HighlightMode;
+    /**
+     * What paints the syntax colour. `hljs` (default): highlight.js in process, in Claude Code's own dark
+     * palette (`diff/syntax.ts`): 7.4 ms to load once, then 0.3 ms a call. `bat`: one `bat` process per
+     * syntax in a message (24.8 ms median) in `bat`'s own theme. A file type `syntax.ts` does not know, and
+     * every light theme, fall back to `bat`.
+     */
+    highlighter: Highlighter;
     /**
      * How far a changed row's band reaches. `block` (default): the widest row of the file, so a pane
      * made narrower after the message was printed wraps only the rows that are long anyway. `terminal`:
@@ -353,6 +360,7 @@ export const DEFAULT_HOOKS_CONFIG: HooksConfig = {
         maxCaptureMB: 8,
         maxCaptureFileMB: 0.256,
         highlight: "256",
+        highlighter: "hljs",
         fill: "block",
         fillMax: 72,
         theme: "claude",
@@ -568,6 +576,7 @@ function mergeDiff(stored: StoredHooksConfig["diff"]): DiffConfig {
             fallback: base.maxCaptureFileMB,
         }),
         highlight: highlightOr(stored?.highlight, base.highlight),
+        highlighter: HIGHLIGHTERS.find((name) => name === stored?.highlighter) ?? base.highlighter,
         fill: FILL_MODES.find((mode) => mode === stored?.fill) ?? base.fill,
         fillMax: countOr({ field: "diff.fillMax", value: stored?.fillMax, fallback: base.fillMax, min: 0 }),
         theme: themeOr(stored?.theme, base.theme),
@@ -610,6 +619,9 @@ function mergeDiff(stored: StoredHooksConfig["diff"]): DiffConfig {
     };
 }
 
+export const HIGHLIGHTERS = ["hljs", "bat"] as const;
+export type Highlighter = (typeof HIGHLIGHTERS)[number];
+
 export const FILL_MODES = ["block", "terminal", "none"] as const;
 export type FillMode = (typeof FILL_MODES)[number];
 
diff --git a/src/agents/lib/hooks/diff/diff.test.ts b/src/agents/lib/hooks/diff/diff.test.ts
index c4d7806134..2f14aeeb62 100644
--- a/src/agents/lib/hooks/diff/diff.test.ts
+++ b/src/agents/lib/hooks/diff/diff.test.ts
@@ -65,6 +65,7 @@ import {
     runDiffPost,
     silentReason,
 } from "./run";
+import { languageOf, syntaxRows } from "./syntax";
 import { resolvePalette } from "./theme";
 import { writerChanges } from "./writers";
 
@@ -3804,6 +3805,81 @@ describe("files the harness writes during every call", () => {
     });
 });
 
+describe("syntax colour from highlight.js", () => {
+    const palette = resolvePalette("claude-dark");
+
+    if (!palette) {
+        throw new Error("claude-dark has a palette");
+    }
+
+    it("colours a TypeScript row in Claude Code's own palette", () => {
+        const rows = syntaxRows({
+            text: 'const label = "a"; // note\nreturn 42;',
+            path: "x.ts",
+            mode: "truecolor",
+        });
+
+        expect(rows).toHaveLength(2);
+        // const is a storage word, a string and a comment have their own colours.
+        expect(rows?.[0]).toContain("\u001b[38;2;102;217;239mconst");
+        expect(rows?.[0]).toContain('\u001b[38;2;230;219;116m"a"');
+        expect(rows?.[0]).toContain("\u001b[38;2;117;113;94m// note");
+        // return is a control keyword, 42 a number.
+        expect(rows?.[1]).toContain("\u001b[38;2;249;38;114mreturn");
+        expect(rows?.[1]).toContain("\u001b[38;2;190;132;255m42");
+    });
+
+    it("writes 256-colour codes in the 256 mode, and no truecolor code", () => {
+        const rows = syntaxRows({ text: "let n = 1;", path: "x.ts", mode: "256" });
+
+        expect(rows?.[0]).toContain("\u001b[38;5;");
+        expect(rows?.[0]).not.toContain("\u001b[38;2;");
+    });
+
+    it("closes a token that spans lines at each line end and opens it again on the next", () => {
+        const rows = syntaxRows({ text: "/* one\n two */\nlet a = 1;", path: "x.ts", mode: "256" });
+
+        expect(rows).toHaveLength(3);
+        expect(stripAnsi(rows?.[1] ?? "")).toBe(" two */");
+        // The comment colour (117,113,94) is index 102 in the 256 palette, on both of its lines.
+        expect(rows?.[0]).toContain("\u001b[38;5;102m");
+        expect(rows?.[1]).toContain("\u001b[38;5;102m");
+        expect(rows?.[2]).not.toContain("\u001b[38;5;102m");
+    });
+
+    it("keeps the text exactly, markup characters included", () => {
+        const text = 'if (a < b && c > "d\'s") { return `x${1}`; }';
+        const rows = syntaxRows({ text, path: "x.ts", mode: "256" });
+
+        expect(stripAnsi(rows?.join("\n") ?? "")).toBe(text);
+    });
+
+    it("leaves a text to bat when none of its scopes has a colour in the palette", () => {
+        expect(syntaxRows({ text: "# Title\n\n- a bullet", path: "note.md", mode: "256" })).toBeNull();
+    });
+
+    it("knows its languages by extension or name, and nothing else", () => {
+        expect(languageOf("a/b.TSX")).toBe("typescript");
+        expect(languageOf("Makefile")).toBe("makefile");
+        expect(languageOf("notes.txt")).toBeNull();
+        expect(syntaxRows({ text: "x", path: "notes.txt", mode: "256" })).toBeNull();
+    });
+
+    it("hands a file type it does not know to bat, and the whole themed block still carries colour", () => {
+        const rendered = renderPatch(["@@ -1,1 +1,1 @@", "-alpha", "+beta"].join("\n"), palette);
+        const block: DiffBlock = {
+            head: "head",
+            body: rendered.body,
+            dress: themedDress({ palette, path: "notes.unknownext", width: 0 }),
+        };
+        const message = assembleMessage([block], { ...DEFAULT_HOOKS_CONFIG.diff, maxMessageChars: 100_000 });
+
+        expect(DEFAULT_HOOKS_CONFIG.diff.highlighter).toBe("hljs");
+        expect(stripAnsi(message)).toContain("-alpha");
+        expect(stripAnsi(message)).toContain("+beta");
+    });
+});
+
 describe("tools agents hooks diff log", () => {
     it("reads back what a message showed: each file, its changed lines shown, and the notes", () => {
         const message = [
diff --git a/src/agents/lib/hooks/diff/render.ts b/src/agents/lib/hooks/diff/render.ts
index 5d632f5aa2..018191d97e 100644
--- a/src/agents/lib/hooks/diff/render.ts
+++ b/src/agents/lib/hooks/diff/render.ts
@@ -4,6 +4,7 @@ import { env } from "@genesiscz/utils/env";
 import type { DiffConfig, FillMode } from "../config";
 import type { DiffCategory } from "./classify";
 import type { ChangedFile } from "./collect";
+import { syntaxRows } from "./syntax";
 import type { Palette } from "./theme";
 
 const DIM = "\u001b[2m";
@@ -597,6 +598,19 @@ function paintThemed(blocks: DiffBlock[], config: DiffConfig): void {
         // theme, or the default Monokai foregrounds would sit on near-white bands.
         const theme = first.palette.light ? ["--theme=GitHub"] : [];
         const input = group.flatMap((block) => block.body.map((line) => line.content ?? ""));
+
+        // highlight.js paints a dark theme in Claude Code's own colours, in process. A language it does
+        // not have, or a light theme, goes to `bat` below.
+        const own =
+            config.highlighter === "hljs" && !first.palette.light
+                ? syntaxRows({ text: input.join("\n"), path: first.path, mode: config.highlight })
+                : null;
+
+        if (own && own.length === input.length) {
+            assignPainted(group, own);
+            continue;
+        }
+
         const run = spawnSync(
             "bat",
             [
@@ -620,19 +634,23 @@ function paintThemed(blocks: DiffBlock[], config: DiffConfig): void {
             continue;
         }
 
-        const rows = run.stdout.split("\n");
-        let at = 0;
+        assignPainted(group, run.stdout.split("\n"));
+    }
+}
 
-        for (const block of group) {
-            if (block.dress) {
-                block.dress.painted = block.body.map((line, index) => {
-                    const row = rows[at + index];
-                    return line.kind && row !== undefined ? compactColour(row) : undefined;
-                });
-            }
+/** Gives each block of a group its rows of the one painted listing, compacted (`dress.painted`). */
+function assignPainted(group: DiffBlock[], rows: string[]): void {
+    let at = 0;
 
-            at += block.body.length;
+    for (const block of group) {
+        if (block.dress) {
+            block.dress.painted = block.body.map((line, index) => {
+                const row = rows[at + index];
+                return line.kind && row !== undefined ? compactColour(row) : undefined;
+            });
         }
+
+        at += block.body.length;
     }
 }
 
diff --git a/src/agents/lib/hooks/diff/syntax.ts b/src/agents/lib/hooks/diff/syntax.ts
new file mode 100644
index 0000000000..72352858d3
--- /dev/null
+++ b/src/agents/lib/hooks/diff/syntax.ts
@@ -0,0 +1,269 @@
+import { basename } from "node:path";
+import { hookDiag } from "../log";
+
+type Rgb = readonly [number, number, number];
+
+/**
+ * Claude Code's dark syntax palette ("Monokai Extended"), read from the diff module of the 2.1.296
+ * binary on 2026-10-15: highlight.js scope names, truecolor. A scope that is not here takes the nearest
+ * ancestor that is, by its dotted prefix (`title.function` falls back to `title`), and one with no
+ * ancestor keeps the text's default colour.
+ */
+const PALETTE: Record<string, Rgb> = {
+    keyword: [249, 38, 114],
+    operator: [249, 38, 114],
+    built_in: [166, 226, 46],
+    type: [166, 226, 46],
+    title: [166, 226, 46],
+    "title.function": [166, 226, 46],
+    "title.class": [166, 226, 46],
+    attr: [166, 226, 46],
+    attribute: [166, 226, 46],
+    literal: [190, 132, 255],
+    number: [190, 132, 255],
+    symbol: [190, 132, 255],
+    string: [230, 219, 116],
+    regexp: [230, 219, 116],
+    params: [253, 151, 31],
+    comment: [117, 113, 94],
+    meta: [117, 113, 94],
+    variable: [255, 255, 255],
+    property: [255, 255, 255],
+    punctuation: [248, 248, 242],
+    subst: [248, 248, 242],
+};
+
+/** A `keyword` token with one of these words is a storage word, not a control keyword. */
+const STORAGE_WORDS = new Set([
+    "const",
+    "let",
+    "var",
+    "function",
+    "class",
+    "type",
+    "interface",
+    "enum",
+    "namespace",
+    "module",
+    "def",
+    "fn",
+    "func",
+    "struct",
+    "trait",
+    "impl",
+]);
+const STORAGE: Rgb = [102, 217, 239];
+
+/** The highlight.js language module for a file extension. Every module named here exists in highlight.js 11. */
+const BY_EXTENSION: Record<string, string> = {
+    ts: "typescript",
+    tsx: "typescript",
+    mts: "typescript",
+    cts: "typescript",
+    js: "javascript",
+    jsx: "javascript",
+    mjs: "javascript",
+    cjs: "javascript",
+    json: "json",
+    jsonc: "json",
+    md: "markdown",
+    markdown: "markdown",
+    swift: "swift",
+    py: "python",
+    sh: "bash",
+    bash: "bash",
+    zsh: "bash",
+    css: "css",
+    scss: "scss",
+    less: "less",
+    html: "xml",
+    xml: "xml",
+    svg: "xml",
+    plist: "xml",
+    yml: "yaml",
+    yaml: "yaml",
+    rs: "rust",
+    go: "go",
+    java: "java",
+    kt: "kotlin",
+    kts: "kotlin",
+    rb: "ruby",
+    php: "php",
+    sql: "sql",
+    c: "c",
+    h: "c",
+    cpp: "cpp",
+    cc: "cpp",
+    hpp: "cpp",
+    cs: "csharp",
+    m: "objectivec",
+    mm: "objectivec",
+    lua: "lua",
+    graphql: "graphql",
+    gql: "graphql",
+    toml: "ini",
+    ini: "ini",
+    diff: "diff",
+    patch: "diff",
+};
+const BY_NAME: Record<string, string> = { Dockerfile: "dockerfile", Makefile: "makefile" };
+
+/** The highlight.js language of a path, or `null` when this painter does not know it (`bat` then paints). */
+export function languageOf(path: string): string | null {
+    const name = basename(path);
+    const named = BY_NAME[name];
+
+    if (named) {
+        return named;
+    }
+
+    const dot = name.lastIndexOf(".");
+
+    return dot > 0 ? (BY_EXTENSION[name.slice(dot + 1).toLowerCase()] ?? null) : null;
+}
+
+interface Engine {
+    highlight(code: string, options: { language: string; ignoreIllegals: boolean }): { value: string };
+    registerLanguage(name: string, language: unknown): void;
+    getLanguage(name: string): unknown;
+}
+
+let engine: Engine | undefined;
+
+function engineFor(language: string): Engine {
+    // lazy: saves 7.4 ms of cold import (highlight.js core plus one language) on every hook call that
+    // paints nothing, and a language is loaded only when a diff holds it (measured 2026-10-15)
+    engine ??= require("highlight.js/lib/core");
+
+    if (!engine) {
+        throw new Error("highlight.js did not load");
+    }
+
+    if (!engine.getLanguage(language)) {
+        engine.registerLanguage(language, require(`highlight.js/lib/languages/${language}`));
+    }
+
+    return engine;
+}
+
+/** The xterm 256-colour index nearest to a colour: the grey ramp for greys, else the 6x6x6 cube. */
+function nearest256([red, green, blue]: Rgb): number {
+    if (red === green && green === blue) {
+        if (red < 8) {
+            return 16;
+        }
+
+        return red > 248 ? 231 : Math.round(((red - 8) / 247) * 24) + 232;
+    }
+
+    const level = (value: number) => Math.round((value / 255) * 5);
+
+    return 16 + 36 * level(red) + 6 * level(green) + level(blue);
+}
+
+function colourCode(colour: Rgb, mode: "256" | "truecolor"): string {
+    return mode === "truecolor"
+        ? `\u001b[38;2;${colour[0]};${colour[1]};${colour[2]}m`
+        : `\u001b[38;5;${nearest256(colour)}m`;
+}
+
+const ENTITIES: Record<string, string> = {
+    "&amp;": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&#x27;": "'",
+};
+
+function decode(text: string): string {
+    return text.replace(/&(?:amp|lt|gt|quot|#x27);/g, (entity) => ENTITIES[entity] ?? entity);
+}
+
+/**
+ * `hljs-title function_` is the scope `title.function`; `hljs-keyword` is `keyword`. The first class names
+ * the scope and a later one ending in an underscore is its sub-scope.
+ */
+function scopeOf(classes: string): string {
+    const [first = "", ...rest] = classes.split(" ");
+    const base = first.startsWith("hljs-") ? first.slice(5) : first;
+    const sub = rest.find((name) => name.endsWith("_"));
+
+    return sub ? `${base}.${sub.slice(0, -1)}` : base;
+}
+
+function paletteColour(scope: string): Rgb | undefined {
+    return PALETTE[scope] ?? PALETTE[scope.split(".")[0] ?? ""];
+}
+
+const TOKENS = /<span class="([^"]*)">|<\/span>|[^<]+/g;
+
+/**
+ * One syntax-coloured string per line of `text`, in the colours of Claude Code's own diff, or `null` when
+ * the language is not one this painter has, highlight.js fails, or none of its scopes has a colour in this
+ * palette (Markdown headings and bullets are not among the 24: `bat` colours them, so `bat` paints). Colours
+ * are foreground only, each run
+ * closed with `ESC[0m`; the caller runs the row through `compactColour`. A token that spans lines (a block
+ * comment) is closed at the line end and opened again on the next line.
+ */
+export function syntaxRows({
+    text,
+    path,
+    mode,
+}: {
+    text: string;
+    path: string;
+    mode: "256" | "truecolor";
+}): string[] | null {
+    const language = languageOf(path);
+
+    if (!language) {
+        return null;
+    }
+
+    try {
+        const html = engineFor(language).highlight(text, { language, ignoreIllegals: true }).value;
+        const stack: Array<{ scope: string; colour: Rgb | undefined }> = [];
+        const rows: string[] = [];
+        let row = "";
+
+        for (const token of html.matchAll(TOKENS)) {
+            if (token[1] !== undefined) {
+                const scope = scopeOf(token[1]);
+
+                stack.push({ scope, colour: paletteColour(scope) ?? stack.at(-1)?.colour });
+                continue;
+            }
+
+            if (token[0] === "</span>") {
+                stack.pop();
+                continue;
+            }
+
+            const top = stack.at(-1);
+
+            token[0].split("\n").forEach((piece, index) => {
+                if (index > 0) {
+                    rows.push(row);
+                    row = "";
+                }
+
+                if (piece.length === 0) {
+                    return;
+                }
+
+                const shown = decode(piece);
+                const colour = top?.scope === "keyword" && STORAGE_WORDS.has(shown) ? STORAGE : top?.colour;
+
+                row += colour ? `${colourCode(colour, mode)}${shown}\u001b[0m` : shown;
+            });
+        }
+
+        rows.push(row);
+
+        return rows.some((painted) => painted.includes("\u001b[")) ? rows : null;
+    } catch (err) {
+        hookDiag("highlight.js could not colour a diff, so bat does", { err, path });
+
+        return null;
+    }
+}
diff --git a/src/agents/lib/hooks/set-config.ts b/src/agents/lib/hooks/set-config.ts
index 9174aa285a..8f869f38ec 100644
--- a/src/agents/lib/hooks/set-config.ts
+++ b/src/agents/lib/hooks/set-config.ts
@@ -4,6 +4,7 @@ import {
     FILL_MODES,
     type HarnessName,
     HIGHLIGHT_MODES,
+    HIGHLIGHTERS,
     type HookOutcome,
     type HooksConfig,
     hooksConfigPath,
@@ -43,6 +44,7 @@ export const SETTABLE_KEYS = [
     "diff.othersSummary",
     "diff.theme",
     "diff.highlight",
+    "diff.highlighter",
     "diff.fill",
     "diff.fillMax",
     "diff.columns",
@@ -315,6 +317,17 @@ export function applySetting(
         );
     }
 
+    if (key === "diff.highlighter") {
+        const name = HIGHLIGHTERS.find((candidate) => candidate === value);
+
+        if (!name) {
+            throw new Error(`${key} takes ${HIGHLIGHTERS.join(", ")}, not ${SafeJSON.stringify(value)}`);
+        }
+
+        next.diff.highlighter = name;
+        return next;
+    }
+
     if (key === "diff.fill") {
         const mode = FILL_MODES.find((candidate) => candidate === value);
 

From d5990964a2c1bc6c956a314139160fdeff66480c Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 20:50:50 +0200
Subject: [PATCH 25/32] feat(agents, hooks): the diff message names its command
 in a dim first line, so a folded "ran N shell commands" row says what changed
 the files

(cherry picked from commit 990ab535e65d43facab5ddee311d13939aba1222)
---
 src/agents/README.md                   |  4 ++-
 src/agents/lib/hooks/diff/diff.test.ts | 31 +++++++++++++++++++++++
 src/agents/lib/hooks/diff/run.ts       | 34 ++++++++++++++++++++++----
 3 files changed, 63 insertions(+), 6 deletions(-)

diff --git a/src/agents/README.md b/src/agents/README.md
index 9fb457b327..ecc9ba228c 100644
--- a/src/agents/README.md
+++ b/src/agents/README.md
@@ -202,7 +202,9 @@ Every mode drops escape codes that change nothing (a reset before a new colour,
 colour on blanks); that loses no colour, so there is no raw mode. A message that cuts lines links
 the call's full diff (`diff.fullDiff`: `genesis`, `path` or `off`). The `genesis` link is printed
 only while the browser router routes Markdown on this Mac; otherwise the message names the path.
-`tools agents hooks diff show <call>` prints it too. A file or a whole folder moved with `mv` or
+`tools agents hooks diff show <call>` prints it too. The message starts with a dim line that names
+the call's command (its first line, at most 60 characters): Claude Code folds a finished call into
+"ran N shell commands" and leaves only the hook message under the fold. A file or a whole folder moved with `mv` or
 `git mv` is one line, `old/ → new/ (284 files)`, when the new copies match the old ones byte for byte
 (up to 4,000 files; a file over 4 MiB is not compared).
 
diff --git a/src/agents/lib/hooks/diff/diff.test.ts b/src/agents/lib/hooks/diff/diff.test.ts
index 2f14aeeb62..6d5d334fc6 100644
--- a/src/agents/lib/hooks/diff/diff.test.ts
+++ b/src/agents/lib/hooks/diff/diff.test.ts
@@ -58,6 +58,7 @@ import {
     captureChunks,
     capturedBefore,
     capturedBefores,
+    commandLine,
     composePostDiff,
     type DiffDecision,
     flushDeferred,
@@ -4303,6 +4304,36 @@ describe("the misfires of 2026-10-14", () => {
         }
     });
 
+    it("names the call's command in a dim first line, cut to 60 characters, and only above its own message", () => {
+        const target = join(repo, "command-line-probe.ts");
+        const long = `sed -i s/a/b/ ${target} # ${"x".repeat(80)}`;
+
+        try {
+            const quiet = composePostDiff({ payload: begin({ command: "true" }), config: plain });
+
+            expect(quiet.message).toBe("");
+
+            const call = begin({ command: `${long}\nsecond line` });
+
+            writeFileSync(target, "COMMAND-LINE\n");
+
+            const { message } = composePostDiff({ payload: call, config: plain });
+            const [first, second] = stripAnsi(message).split("\n");
+
+            expect(message.startsWith("\u001b[2m$ ")).toBe(true);
+            expect(first).toBe(`$ ${long.slice(0, 59)}…`);
+            expect(second).toMatch(/^Added .*command-line-probe\.ts \(\+1 -0\)$/);
+            expect(
+                readMessage(message)
+                    .blocks.map((block) => block.path)
+                    .join(" ")
+            ).toContain("command-line-probe.ts");
+            expect(stripAnsi(commandLine("bun x.ts <<'EOF'\nbody\nEOF"))).toBe("$ bun x.ts <<'EOF' …");
+        } finally {
+            rmSync(target, { force: true });
+        }
+    });
+
     it("puts the call's own diff before the background tasks it prints, so diff log can split them", () => {
         const project = `gt-bg-order-${process.pid}`;
         const tasks = join(tmpdir(), `claude-${process.getuid?.() ?? 0}`, project, "gt-diff-test", "tasks");
diff --git a/src/agents/lib/hooks/diff/run.ts b/src/agents/lib/hooks/diff/run.ts
index 681f9019b2..d3c2020890 100644
--- a/src/agents/lib/hooks/diff/run.ts
+++ b/src/agents/lib/hooks/diff/run.ts
@@ -531,6 +531,30 @@ function fitDecision(decision: DiffDecision, room: number | undefined): DiffDeci
     return { ...decision, message, ...(stats ? { stats } : {}) };
 }
 
+/** The most characters of a command that `commandLine` shows, the "…" included. */
+const COMMAND_CHARS = 60;
+
+/**
+ * The dim line above a call's own message: the first line of its command, cut to `COMMAND_CHARS`.
+ * Claude Code folds a finished call into "ran N shell commands" and leaves only the hook message
+ * under the fold, so without this line nothing says which command changed the files.
+ */
+export function commandLine(command: string): string {
+    const lines = command.trim().split("\n");
+    const first = [...(lines[0] ?? "").replace(/\p{Cc}/gu, " ").trimEnd()];
+
+    if (first.length === 0) {
+        return "";
+    }
+
+    const shown =
+        first.length > COMMAND_CHARS
+            ? `${first.slice(0, COMMAND_CHARS - 1).join("")}…`
+            : `${first.join("")}${lines.length > 1 ? " …" : ""}`;
+
+    return `\u001b[2m$ ${shown}\u001b[0m`;
+}
+
 /** Headings plus messages, in the order `composePostDiff` joins them after the call's own diff. */
 export function deferredMessageParts(flushed: DiffDecision[]): string[] {
     return flushed.flatMap((item) =>
@@ -558,11 +582,11 @@ export function composePostDiff({
     const flushedParts = deferredMessageParts(flushed);
     // `+ 2` per part is the `\n\n` between parts, including the one after this call's own diff.
     const flushedChars = flushedParts.reduce((total, part) => total + part.length + 2, 0);
-    const decision = fitDecision(
-        runDiffPost({ payload, config, record, maxChars: Math.max(0, maxChars - flushedChars) }),
-        Math.max(0, maxChars - flushedChars)
-    );
-    const message = [...(decision.message ? [decision.message] : []), ...flushedParts].join("\n\n");
+    const heading = commandLine(payload.command);
+    const room = Math.max(0, maxChars - flushedChars - (heading ? heading.length + 1 : 0));
+    const decision = fitDecision(runDiffPost({ payload, config, record, maxChars: room }), room);
+    const own = decision.message ? [heading ? `${heading}\n${decision.message}` : decision.message] : [];
+    const message = [...own, ...flushedParts].join("\n\n");
 
     return { flushed, decision, message };
 }

From ee009d2081fb4f6a818331ce5cba754960236ba9 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Thu, 15 Oct 2026 21:05:41 +0200
Subject: [PATCH 26/32] feat(agents, hooks): diff.commandLines heads a message
 with the first lines of its command, and tools agents hooks mods installs
 genesis-tools-mods, a Claude Code mod that draws a cut diff in full under its
 call

(cherry picked from commit 5310375ae9ee038a3edec0a77070dfffd3363b94)
---
 .claude-plugin/marketplace.json               |  10 ++
 .../.claude-plugin/plugin.json                |   8 ++
 plugins/genesis-tools-mods/hooks/hooks.json   |   3 +
 plugins/genesis-tools-mods/hooks/register.tsx | 100 ++++++++++++++++++
 .../genesis-tools-mods/hooks/sections.test.ts |  78 ++++++++++++++
 plugins/genesis-tools-mods/hooks/sections.ts  |  96 +++++++++++++++++
 src/agents/README.md                          |  16 ++-
 src/agents/commands/hooks.ts                  | 100 ++++++++++++++++++
 src/agents/lib/hooks/config.ts                |  28 +++++
 src/agents/lib/hooks/diff/diff.test.ts        |  29 +++--
 src/agents/lib/hooks/diff/run.ts              |  40 ++++---
 src/agents/lib/hooks/hooks.test.ts            |  33 ++++++
 src/agents/lib/hooks/mods.ts                  |  74 +++++++++++++
 src/agents/lib/hooks/set-config.ts            |  12 +++
 14 files changed, 602 insertions(+), 25 deletions(-)
 create mode 100644 plugins/genesis-tools-mods/.claude-plugin/plugin.json
 create mode 100644 plugins/genesis-tools-mods/hooks/hooks.json
 create mode 100644 plugins/genesis-tools-mods/hooks/register.tsx
 create mode 100644 plugins/genesis-tools-mods/hooks/sections.test.ts
 create mode 100644 plugins/genesis-tools-mods/hooks/sections.ts
 create mode 100644 src/agents/lib/hooks/mods.ts

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index a699039b86..3d19366cc2 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -24,6 +24,16 @@
                 "./skills/"
             ]
         },
+        {
+            "name": "genesis-tools-mods",
+            "description": "Claude Code mods for GenesisTools: draws the whole diff of a Bash call whose diff-hook message was cut, with Claude Code's own diff element, under the call's row. Install with: tools agents hooks mods install --write.",
+            "version": "1.0.0",
+            "author": {
+                "name": "GenesisTools"
+            },
+            "source": "./plugins/genesis-tools-mods",
+            "category": "development"
+        },
         {
             "name": "genesis-tools-server",
             "description": "A single Claude Code command for Linux server security auditing: log analysis, intrusion detection, malware scanning, and rootkit detection. Not an MCP server, despite the name.",
diff --git a/plugins/genesis-tools-mods/.claude-plugin/plugin.json b/plugins/genesis-tools-mods/.claude-plugin/plugin.json
new file mode 100644
index 0000000000..61797ff8c8
--- /dev/null
+++ b/plugins/genesis-tools-mods/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+    "name": "genesis-tools-mods",
+    "version": "1.0.0",
+    "description": "Claude Code mods for GenesisTools: draws the whole diff of a Bash call whose diff-hook message was cut, with Claude Code's own diff element, under the call's row. Configured in the hooks file: tools agents hooks config set mods.fullDiff true|false.",
+    "author": {
+        "name": "GenesisTools"
+    }
+}
diff --git a/plugins/genesis-tools-mods/hooks/hooks.json b/plugins/genesis-tools-mods/hooks/hooks.json
new file mode 100644
index 0000000000..f4cb24bf8d
--- /dev/null
+++ b/plugins/genesis-tools-mods/hooks/hooks.json
@@ -0,0 +1,3 @@
+{
+    "modules": ["./register.tsx"]
+}
diff --git a/plugins/genesis-tools-mods/hooks/register.tsx b/plugins/genesis-tools-mods/hooks/register.tsx
new file mode 100644
index 0000000000..76c1e7645f
--- /dev/null
+++ b/plugins/genesis-tools-mods/hooks/register.tsx
@@ -0,0 +1,100 @@
+import type { EngineInterface, Register } from "claude-code";
+import { type CallSection, fullDiffEnabled, sectionsOfCalls } from "./sections";
+
+// The full-diff mod. When the diff hook (`tools agents hooks`) cut a Bash call's message, it wrote the
+// whole diff to ~/.genesis-tools/agents/hook-diffs/<tool_use_id>.md. This draws those hunks with Claude
+// Code's own Code element under the call's row, so the colours, the gutters and the wrapping are the
+// engine's and nothing counts against the 10,000-character hook message.
+//
+// 🛑 Two rows, two hooks. Outside `--verbose` and the ctrl+o transcript the engine draws a group of calls
+// as ONE `ToolGroup` line ("ran 3 shell commands") and no `ToolUse` row at all (`ToolGroup.isExpanded`
+// in the engine types), so the diffs go under that line. An expanded group draws each call as its own
+// `ToolUse` row, and the diff goes under the call. A spike that hooked only `ToolResult`, then only
+// `ToolUse`, drew nothing in the normal view (checked on screen 2026-10-15).
+
+// One drawing may hold 100,000 characters in all (CodeProps.source); stay well inside it.
+const MAX_CHARS = 60_000;
+
+/** `<home>/.genesis-tools/agents`; `GENESIS_TOOLS_HOME` replaces the home, as it does for every tool. */
+async function agentsDir($: EngineInterface): Promise<string | undefined> {
+    const home = (await $.env.get("GENESIS_TOOLS_HOME")) ?? (await $.env.get("HOME"));
+
+    return home ? `${home}/.genesis-tools/agents` : undefined;
+}
+
+async function fullDiffs($: EngineInterface, ids: readonly string[]): Promise<CallSection[]> {
+    const dir = ids.length > 0 ? await agentsDir($) : undefined;
+
+    if (!dir) {
+        return [];
+    }
+
+    const hooksFile = await $.fs.read(`${dir}/hooks.json`).catch(() => undefined);
+
+    if (!fullDiffEnabled(hooksFile)) {
+        return [];
+    }
+
+    return sectionsOfCalls({ ids, read: (id) => $.fs.read(`${dir}/hook-diffs/${id}.md`), maxChars: MAX_CHARS });
+}
+
+export const register: Register = (on) => {
+    on("ui.render", { component: "ToolGroup" }, async ($, e, next) => {
+        const drawn = await next(e);
+
+        if (e.props.isExpanded) {
+            return drawn;
+        }
+
+        const ids = e.props.calls.flatMap((call) =>
+            call.tool === "Bash" && !call.isRunning && call.tool_use_id ? [call.tool_use_id] : []
+        );
+        const sections = await fullDiffs($, ids);
+
+        if (sections.length === 0) {
+            return drawn;
+        }
+
+        const { Box, Code, Text } = $.ui.resolve(e);
+
+        return (
+            <Box flexDirection="column">
+                {drawn}
+                {sections.map((section) => (
+                    <Box key={`${section.call}:${section.path}`} flexDirection="column">
+                        <Text dimColor>{section.path}</Text>
+                        <Code source={section.patch} format="diff" path={section.path} />
+                    </Box>
+                ))}
+            </Box>
+        );
+    });
+
+    on("ui.render", { component: "ToolUse" }, async ($, e, next) => {
+        const drawn = await next(e);
+
+        if (e.props.tool !== "Bash" || e.props.isRunning) {
+            return drawn;
+        }
+
+        const sections = await fullDiffs($, [e.props.tool_use_id]);
+
+        if (sections.length === 0) {
+            return drawn;
+        }
+
+        const { Box, Code, Text } = $.ui.resolve(e);
+
+        return (
+            <Box flexDirection="column">
+                {drawn}
+                {sections.map((section) => (
+                    <Box key={section.path} flexDirection="column">
+                        <Text dimColor>{section.path}</Text>
+                        <Code source={section.patch} format="diff" path={section.path} />
+                    </Box>
+                ))}
+            </Box>
+        );
+    });
+};
diff --git a/plugins/genesis-tools-mods/hooks/sections.test.ts b/plugins/genesis-tools-mods/hooks/sections.test.ts
new file mode 100644
index 0000000000..5270ab7955
--- /dev/null
+++ b/plugins/genesis-tools-mods/hooks/sections.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from "bun:test";
+import { fullDiffEnabled, sectionsOf, sectionsOfCalls } from "./sections";
+
+const NOTE = [
+    "# Diff of toolu_x",
+    "",
+    "```sh",
+    "sed -i s/a/b/ src/a.ts src/b.ts",
+    "```",
+    "",
+    "## /repo/src/a.ts (+1 -1)",
+    "",
+    "```diff",
+    "diff --git a/a.ts b/a.ts",
+    "index 111..222 100644",
+    "--- a/a.ts",
+    "+++ b/a.ts",
+    "@@ -1,2 +1,2 @@",
+    "-a",
+    "+b",
+    " same",
+    "```",
+    "",
+    "## /repo/src/b.ts (+0 -1)",
+    "",
+    "```diff",
+    "@@ -1,1 +0,0 @@",
+    "-gone",
+    "```",
+    "",
+    "## Changed, past the file cap",
+    "- /repo/src/c.ts",
+].join("\n");
+
+describe("the full-diff mod's note reader", () => {
+    it("reads each file of a note from its first hunk, and nothing else", () => {
+        const sections = sectionsOf(NOTE);
+
+        expect(sections.map((section) => section.path)).toEqual(["/repo/src/a.ts", "/repo/src/b.ts"]);
+        expect(sections[0]?.patch).toBe("@@ -1,2 +1,2 @@\n-a\n+b\n same");
+        expect(sections[1]?.patch).toBe("@@ -1,1 +0,0 @@\n-gone");
+        expect(sectionsOf("# Diff of toolu_y\n\n```sh\nls\n```\n")).toEqual([]);
+    });
+
+    it("reads a group's notes in call order, skips a call with no note, and stops at the budget", async () => {
+        const notes: Record<string, string> = { first: NOTE, third: NOTE };
+        const read = async (id: string) => {
+            const note = notes[id];
+
+            if (note === undefined) {
+                throw new Error(`no note for ${id}`);
+            }
+
+            return note;
+        };
+
+        const all = await sectionsOfCalls({ ids: ["first", "second", "third"], read, maxChars: 1_000 });
+
+        expect(all.map((section) => `${section.call} ${section.path}`)).toEqual([
+            "first /repo/src/a.ts",
+            "first /repo/src/b.ts",
+            "third /repo/src/a.ts",
+            "third /repo/src/b.ts",
+        ]);
+
+        const cut = await sectionsOfCalls({ ids: ["first", "third"], read, maxChars: 40 });
+
+        expect(cut.map((section) => section.path)).toEqual(["/repo/src/a.ts"]);
+    });
+
+    it("is on unless the hooks file sets mods.fullDiff to false", () => {
+        expect(fullDiffEnabled(undefined)).toBe(true);
+        expect(fullDiffEnabled("not json")).toBe(true);
+        expect(fullDiffEnabled('{"mods":{"fullDiff":"no"}}')).toBe(true);
+        expect(fullDiffEnabled('{"mods":{"fullDiff":false}}')).toBe(false);
+        expect(fullDiffEnabled('{"diff":{}}')).toBe(true);
+    });
+});
diff --git a/plugins/genesis-tools-mods/hooks/sections.ts b/plugins/genesis-tools-mods/hooks/sections.ts
new file mode 100644
index 0000000000..ed1f8ca70d
--- /dev/null
+++ b/plugins/genesis-tools-mods/hooks/sections.ts
@@ -0,0 +1,96 @@
+/** One file of a diff-hook full-diff note: its path and its unified-diff hunks. */
+export interface Section {
+    path: string;
+    patch: string;
+}
+
+export interface CallSection extends Section {
+    call: string;
+}
+
+/**
+ * The files of `~/.genesis-tools/agents/hook-diffs/<call>.md`, which `tools agents hooks` writes when
+ * a message cuts lines: `## <path> (+a -b)`, a blank line, then the hunks in a ```diff fence.
+ */
+const SECTION = /^## (.+?) \(\+\d+ -\d+\)\n\n```diff\n([\s\S]*?)\n```$/gm;
+
+/**
+ * The hunks only. The note's fence starts with git's `diff --git` and `index` lines, which the Code
+ * element's diff parser is not documented to read past (it reads past `---` and `+++`), so the patch
+ * starts at the first hunk header.
+ */
+function hunksOf(patch: string): string {
+    const at = patch.search(/^@@ /m);
+
+    return at < 0 ? "" : patch.slice(at);
+}
+
+export function sectionsOf(text: string): Section[] {
+    return [...text.matchAll(SECTION)]
+        .map((match) => ({ path: match[1] ?? "", patch: hunksOf(match[2] ?? "") }))
+        .filter((section) => section.patch.length > 0);
+}
+
+/**
+ * The sections of several calls' notes, in call order, while their patches fit `maxChars` together.
+ * A call with no note (the hook did not cut its message, or it changed nothing) adds nothing.
+ */
+export async function sectionsOfCalls({
+    ids,
+    read,
+    maxChars,
+}: {
+    ids: readonly string[];
+    read: (id: string) => Promise<string>;
+    maxChars: number;
+}): Promise<CallSection[]> {
+    const found: CallSection[] = [];
+    let spent = 0;
+
+    for (const call of ids) {
+        let note: string;
+
+        try {
+            note = await read(call);
+        } catch {
+            continue;
+        }
+
+        for (const section of sectionsOf(note)) {
+            spent += section.patch.length;
+
+            if (spent > maxChars) {
+                return found;
+            }
+
+            found.push({ ...section, call });
+        }
+    }
+
+    return found;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null;
+}
+
+/**
+ * `mods.fullDiff` from the hooks file (`~/.genesis-tools/agents/hooks.json`), which
+ * `tools agents hooks config set mods.fullDiff false` writes. A file that is missing, unreadable or
+ * not JSON, and a value that is not a boolean, leave the default: on.
+ */
+export function fullDiffEnabled(hooksFile: string | undefined): boolean {
+    if (hooksFile === undefined) {
+        return true;
+    }
+
+    try {
+        const stored: unknown = JSON.parse(hooksFile);
+        const mods = isRecord(stored) ? stored.mods : undefined;
+        const value = isRecord(mods) ? mods.fullDiff : undefined;
+
+        return typeof value === "boolean" ? value : true;
+    } catch {
+        return true;
+    }
+}
diff --git a/src/agents/README.md b/src/agents/README.md
index ecc9ba228c..ab059549ef 100644
--- a/src/agents/README.md
+++ b/src/agents/README.md
@@ -202,9 +202,19 @@ Every mode drops escape codes that change nothing (a reset before a new colour,
 colour on blanks); that loses no colour, so there is no raw mode. A message that cuts lines links
 the call's full diff (`diff.fullDiff`: `genesis`, `path` or `off`). The `genesis` link is printed
 only while the browser router routes Markdown on this Mac; otherwise the message names the path.
-`tools agents hooks diff show <call>` prints it too. The message starts with a dim line that names
-the call's command (its first line, at most 60 characters): Claude Code folds a finished call into
-"ran N shell commands" and leaves only the hook message under the fold. A file or a whole folder moved with `mv` or
+`tools agents hooks diff show <call>` prints it too. The message starts with the call's command, dim:
+its first `diff.commandLines` lines (3; 0 shows none), each cut to 80 characters, then how many lines were
+left out. Claude Code folds a finished call into "ran N shell commands" and leaves only the hook message
+under the fold, so without them nothing says which command changed the files.
+
+**The full-diff mod.** `tools agents hooks mods install --write` installs the plugin `genesis-tools-mods`
+from this repository's marketplace (`plugins/genesis-tools-mods/`). It is a Claude Code mod: when a hook
+message cut lines, it draws the call's whole diff (the `hook-diffs/<call>.md` note) with Claude Code's own
+diff element under the call's row, so the 10,000-character message limit no longer hides the rest. A running
+session needs `/reload-plugins`. `tools agents hooks mods` shows whether it is installed;
+`tools agents hooks config set mods.fullDiff false --write` turns it off without an uninstall (the mod reads
+the hooks file). It draws nothing while `diff.fullDiff` is `off`. The mod API is early access in Claude Code
+(2.1.287 and later), so a release can change it; the mod then draws nothing and the hook message is unchanged. A file or a whole folder moved with `mv` or
 `git mv` is one line, `old/ → new/ (284 files)`, when the new copies match the old ones byte for byte
 (up to 4,000 files; a file over 4 MiB is not compared).
 
diff --git a/src/agents/commands/hooks.ts b/src/agents/commands/hooks.ts
index e0df16ead9..f005ae2760 100644
--- a/src/agents/commands/hooks.ts
+++ b/src/agents/commands/hooks.ts
@@ -41,6 +41,7 @@ import {
     uninstallHooks,
     wiringStatus,
 } from "../lib/hooks/install";
+import { claudePlugin, MODS_PLUGIN, MODS_SCOPES, type ModsScope, modsPluginState } from "../lib/hooks/mods";
 import { nativeDiffForced, nativeDiffState, setNativeDiff } from "../lib/hooks/native-diff";
 import { SETTABLE_KEYS, type SetResult, setHooksConfig } from "../lib/hooks/set-config";
 import { registerRuleCommands, registerRulePicker, ruleState, shortPath } from "./hooks-rules";
@@ -524,6 +525,8 @@ export function registerHooksCommands(program: Command): void {
             }
         });
 
+    registerMods(hooks);
+
     const diffCommand = hooks.command("diff").description("The Bash diff hook");
 
     diffCommand
@@ -709,3 +712,100 @@ export function registerHooksCommands(program: Command): void {
             }
         });
 }
+
+/**
+ * `hooks mods`: the Claude Code mods of this repository (the `genesis-tools-mods` plugin). They share the
+ * hooks file: `mods.fullDiff` switches the full-diff mod, which reads the diff hook's `hook-diffs` notes.
+ */
+function registerMods(hooks: Command): void {
+    const mods = hooks
+        .command("mods")
+        .description(
+            `Claude Code mods (${MODS_PLUGIN}): status, install, uninstall. Settings: mods.* in the hooks config`
+        );
+
+    mods.command("status", { isDefault: true })
+        .description("Whether the mods plugin is installed and enabled, and what the hooks config sets for it")
+        .action(() => {
+            const list = claudePlugin(["list", "--json"]);
+
+            if (!list.ok) {
+                ui.err(`claude plugin list failed: ${list.stderr.trim() || list.stdout.trim()}`);
+                process.exitCode = 1;
+                return;
+            }
+
+            const state = modsPluginState(list.stdout);
+            const config = loadHooksConfig();
+            const fullDiff = diffFor(config, "claude").fullDiff;
+
+            ui.raw(
+                `${pc.bold(MODS_PLUGIN)}: ${state.installed ? (state.enabled ? pc.green("installed, enabled") : pc.yellow("installed, disabled")) : pc.red("not installed")}`
+            );
+
+            if (state.installed) {
+                ui.raw(
+                    pc.dim(
+                        `  scope ${state.scope ?? "?"} · version ${state.version ?? "?"} · read from ${state.readFrom ?? "its install copy"}`
+                    )
+                );
+            }
+
+            ui.raw(`mods.fullDiff: ${config.mods.fullDiff ? pc.green("on") : pc.dim("off")}`);
+
+            if (config.mods.fullDiff && fullDiff === "off") {
+                ui.raw(pc.yellow(`diff.fullDiff is off, so no call has a full-diff note for the mod to draw.`));
+            }
+
+            if (!state.installed) {
+                ui.raw(`Install: ${toolCommand("agents hooks mods install", "--write")}`);
+            }
+        });
+
+    mods.command("install")
+        .description("Install the mods plugin from this repository's marketplace")
+        .option("--scope <scope>", `Where Claude Code records it: ${MODS_SCOPES.join(", ")}`, "user")
+        .option("--write", "Actually install; without it this is a dry run")
+        .action((options: { scope: string; write?: boolean }) => {
+            const scope = MODS_SCOPES.find((candidate): candidate is ModsScope => candidate === options.scope);
+
+            if (!scope) {
+                ui.raw(suggestEnumFlag("tools agents hooks mods install", "--scope", MODS_SCOPES));
+                process.exitCode = 1;
+                return;
+            }
+
+            runPluginCommand({ args: ["install", MODS_PLUGIN, "--scope", scope], write: Boolean(options.write) });
+        });
+
+    mods.command("uninstall")
+        .description("Uninstall the mods plugin")
+        .option("--write", "Actually uninstall; without it this is a dry run")
+        .action((options: { write?: boolean }) => {
+            runPluginCommand({ args: ["uninstall", MODS_PLUGIN], write: Boolean(options.write) });
+        });
+}
+
+function runPluginCommand({ args, write }: { args: string[]; write: boolean }): void {
+    const shown = `claude plugin ${args.join(" ")}`;
+
+    if (!write) {
+        ui.raw(`would run: ${shown}`);
+        ui.raw(pc.yellow("dry run: nothing was changed. Pass --write to apply."));
+        return;
+    }
+
+    const run = claudePlugin(args);
+    const said = `${run.stdout}${run.stderr}`.trim();
+
+    if (!run.ok) {
+        ui.err(`${shown} failed${said ? `: ${said}` : ""}`);
+        process.exitCode = 1;
+        return;
+    }
+
+    ui.raw(said || `${shown}: done`);
+    ui.raw(
+        pc.dim("A running Claude Code session picks it up after /reload-plugins; a new session loads it by itself.")
+    );
+}
diff --git a/src/agents/lib/hooks/config.ts b/src/agents/lib/hooks/config.ts
index 419e051a47..04168da546 100644
--- a/src/agents/lib/hooks/config.ts
+++ b/src/agents/lib/hooks/config.ts
@@ -154,6 +154,12 @@ export interface DiffConfig {
      * costs far more than its visible width.
      */
     maxMessageChars: number;
+    /**
+     * How many lines of the call's command head its message, dim, each cut to 80 characters; 0 shows
+     * none. Claude Code folds a finished call into "ran N shell commands" and leaves only the hook
+     * message under the fold, so without them nothing says which command changed the files.
+     */
+    commandLines: number;
     /**
      * Which KINDS of change are printed. `source` is anything that is not one of the others.
      *
@@ -256,6 +262,18 @@ export interface AgentsTalkConfig {
     hint: boolean;
 }
 
+/**
+ * The Claude Code mods of the `genesis-tools-mods` plugin (`tools agents hooks mods install`). The plugin
+ * reads this section of the hooks file itself, so a change here needs no reinstall.
+ */
+export interface ModsConfig {
+    /**
+     * Draw the whole diff of a call whose hook message was cut, with Claude Code's own diff element,
+     * under the call's row. Reads `hook-diffs/<call>.md`, so it needs `diff.fullDiff` not `off`.
+     */
+    fullDiff: boolean;
+}
+
 /**
  * The Stop-phase reminder about commits that are not pushed yet. It fires for a branch with an
  * upstream when MORE than `maxCommits` commits are unpushed, or when the oldest unpushed commit
@@ -274,6 +292,7 @@ export interface HooksConfig {
     diff: DiffConfig;
     decisions: DecisionsHookConfig;
     agentsTalk: AgentsTalkConfig;
+    mods: ModsConfig;
     unpushed: UnpushedConfig;
     logPath: string;
     /**
@@ -376,6 +395,7 @@ export const DEFAULT_HOOKS_CONFIG: HooksConfig = {
         dedupeAcrossSessions: true,
         othersSummary: "line",
         maxMessageChars: 9_900,
+        commandLines: 3,
         categories: { source: true, formatting: true, log: false, generated: false },
         harnesses: {
             // 🛑 OFF for Grok, because Grok cannot show a diff. Observed 2026-09-22 on a real
@@ -397,6 +417,7 @@ export const DEFAULT_HOOKS_CONFIG: HooksConfig = {
         staleness: { warnAfterMinutes: 30, alarmAfterMinutes: 120, notify: true },
     },
     agentsTalk: { hint: true },
+    mods: { fullDiff: true },
     unpushed: { enabled: true, maxCommits: 3, maxAgeMinutes: 60, remindEveryMinutes: 30 },
     logPath: defaultLogPath(),
     // 🛑 `shadow: true` AND `logCommands: "shadow"` together mean `keepsCommand()` is true out
@@ -579,6 +600,12 @@ function mergeDiff(stored: StoredHooksConfig["diff"]): DiffConfig {
         highlighter: HIGHLIGHTERS.find((name) => name === stored?.highlighter) ?? base.highlighter,
         fill: FILL_MODES.find((mode) => mode === stored?.fill) ?? base.fill,
         fillMax: countOr({ field: "diff.fillMax", value: stored?.fillMax, fallback: base.fillMax, min: 0 }),
+        commandLines: countOr({
+            field: "diff.commandLines",
+            value: stored?.commandLines,
+            fallback: base.commandLines,
+            min: 0,
+        }),
         theme: themeOr(stored?.theme, base.theme),
         columns: columnsOr(stored?.columns, base.columns),
         fullDiff: FULL_DIFF_MODES.find((mode) => mode === stored?.fullDiff) ?? base.fullDiff,
@@ -947,6 +974,7 @@ export function mergeStoredConfig(stored: StoredHooksConfig): HooksConfig {
         diff: mergeDiff(stored.diff),
         decisions: mergeDecisions(stored.decisions),
         agentsTalk: { hint: boolOr(stored.agentsTalk?.hint, DEFAULT_HOOKS_CONFIG.agentsTalk.hint) },
+        mods: { fullDiff: boolOr(stored.mods?.fullDiff, DEFAULT_HOOKS_CONFIG.mods.fullDiff) },
         unpushed: mergeUnpushed(stored.unpushed),
         shadow: boolOr(stored.shadow, DEFAULT_HOOKS_CONFIG.shadow),
         logCommands: logCommandsOr(stored.logCommands, DEFAULT_HOOKS_CONFIG.logCommands),
diff --git a/src/agents/lib/hooks/diff/diff.test.ts b/src/agents/lib/hooks/diff/diff.test.ts
index 6d5d334fc6..11c5b8b361 100644
--- a/src/agents/lib/hooks/diff/diff.test.ts
+++ b/src/agents/lib/hooks/diff/diff.test.ts
@@ -58,7 +58,7 @@ import {
     captureChunks,
     capturedBefore,
     capturedBefores,
-    commandLine,
+    commandLines,
     composePostDiff,
     type DiffDecision,
     flushDeferred,
@@ -4304,7 +4304,7 @@ describe("the misfires of 2026-10-14", () => {
         }
     });
 
-    it("names the call's command in a dim first line, cut to 60 characters, and only above its own message", () => {
+    it("heads the call's own message with dim command lines, each cut to 80 characters, as diff.commandLines sets", () => {
         const target = join(repo, "command-line-probe.ts");
         const long = `sed -i s/a/b/ ${target} # ${"x".repeat(80)}`;
 
@@ -4318,20 +4318,35 @@ describe("the misfires of 2026-10-14", () => {
             writeFileSync(target, "COMMAND-LINE\n");
 
             const { message } = composePostDiff({ payload: call, config: plain });
-            const [first, second] = stripAnsi(message).split("\n");
+            const [first, second, third] = stripAnsi(message).split("\n");
 
-            expect(message.startsWith("\u001b[2m$ ")).toBe(true);
-            expect(first).toBe(`$ ${long.slice(0, 59)}…`);
-            expect(second).toMatch(/^Added .*command-line-probe\.ts \(\+1 -0\)$/);
+            expect(message.slice(0, 6)).toBe("\u001b[2m$ ");
+            expect(first).toBe(`$ ${long.slice(0, 79)}…`);
+            expect(second).toBe("  second line");
+            expect(third).toMatch(/^Added .*command-line-probe\.ts \(\+1 -0\)$/);
             expect(
                 readMessage(message)
                     .blocks.map((block) => block.path)
                     .join(" ")
             ).toContain("command-line-probe.ts");
-            expect(stripAnsi(commandLine("bun x.ts <<'EOF'\nbody\nEOF"))).toBe("$ bun x.ts <<'EOF' …");
+
+            const off = { ...plain, diff: { ...plain.diff, commandLines: 0 } };
+            const again = begin({ command: long });
+
+            writeFileSync(target, "COMMAND-LINE\nAGAIN\n");
+
+            const bare = composePostDiff({ payload: again, config: off }).message;
+
+            expect(stripAnsi(bare)).toMatch(/^Updated .*command-line-probe\.ts \(\+1 -0\)/);
         } finally {
             rmSync(target, { force: true });
         }
+
+        const heredoc = "bun x.ts <<'EOF'\nbody\nEOF";
+
+        expect(stripAnsi(commandLines(heredoc, 3))).toBe("$ bun x.ts <<'EOF'\n  body\n  EOF");
+        expect(stripAnsi(commandLines(heredoc, 1))).toBe("$ bun x.ts <<'EOF'\n  … 2 more line(s)");
+        expect(commandLines(heredoc, 0)).toBe("");
     });
 
     it("puts the call's own diff before the background tasks it prints, so diff log can split them", () => {
diff --git a/src/agents/lib/hooks/diff/run.ts b/src/agents/lib/hooks/diff/run.ts
index d3c2020890..06a30164d7 100644
--- a/src/agents/lib/hooks/diff/run.ts
+++ b/src/agents/lib/hooks/diff/run.ts
@@ -531,28 +531,38 @@ function fitDecision(decision: DiffDecision, room: number | undefined): DiffDeci
     return { ...decision, message, ...(stats ? { stats } : {}) };
 }
 
-/** The most characters of a command that `commandLine` shows, the "…" included. */
-const COMMAND_CHARS = 60;
+/** The most characters of one command line that `commandLines` shows, the "…" included. */
+const COMMAND_CHARS = 80;
 
 /**
- * The dim line above a call's own message: the first line of its command, cut to `COMMAND_CHARS`.
- * Claude Code folds a finished call into "ran N shell commands" and leaves only the hook message
- * under the fold, so without this line nothing says which command changed the files.
+ * The dim lines above a call's own message: the first `count` lines of its command, each cut to
+ * `COMMAND_CHARS`, then how many lines were left out (`diff.commandLines`; 0 shows none). Claude Code
+ * folds a finished call into "ran N shell commands" and leaves only the hook message under the fold,
+ * so without them nothing says which command changed the files.
  */
-export function commandLine(command: string): string {
-    const lines = command.trim().split("\n");
-    const first = [...(lines[0] ?? "").replace(/\p{Cc}/gu, " ").trimEnd()];
+export function commandLines(command: string, count: number): string {
+    const lines = command
+        .trim()
+        .split("\n")
+        .map((line) => line.replace(/\p{Cc}/gu, " ").trimEnd());
 
-    if (first.length === 0) {
+    if (count <= 0 || !lines[0]) {
         return "";
     }
 
-    const shown =
-        first.length > COMMAND_CHARS
-            ? `${first.slice(0, COMMAND_CHARS - 1).join("")}…`
-            : `${first.join("")}${lines.length > 1 ? " …" : ""}`;
+    const shown = lines.slice(0, count).map((line) => {
+        const chars = [...line];
+
+        return chars.length > COMMAND_CHARS ? `${chars.slice(0, COMMAND_CHARS - 1).join("")}…` : line;
+    });
+    const left = lines.length - shown.length;
+    const rows = [
+        `$ ${shown[0]}`,
+        ...shown.slice(1).map((line) => `  ${line}`),
+        ...(left > 0 ? [`  … ${left} more line(s)`] : []),
+    ];
 
-    return `\u001b[2m$ ${shown}\u001b[0m`;
+    return rows.map((row) => `\u001b[2m${row}\u001b[0m`).join("\n");
 }
 
 /** Headings plus messages, in the order `composePostDiff` joins them after the call's own diff. */
@@ -582,7 +592,7 @@ export function composePostDiff({
     const flushedParts = deferredMessageParts(flushed);
     // `+ 2` per part is the `\n\n` between parts, including the one after this call's own diff.
     const flushedChars = flushedParts.reduce((total, part) => total + part.length + 2, 0);
-    const heading = commandLine(payload.command);
+    const heading = commandLines(payload.command, diffFor(config, payload.harness).commandLines);
     const room = Math.max(0, maxChars - flushedChars - (heading ? heading.length + 1 : 0));
     const decision = fitDecision(runDiffPost({ payload, config, record, maxChars: room }), room);
     const own = decision.message ? [heading ? `${heading}\n${decision.message}` : decision.message] : [];
diff --git a/src/agents/lib/hooks/hooks.test.ts b/src/agents/lib/hooks/hooks.test.ts
index 48916722d5..6e7b4b9a02 100644
--- a/src/agents/lib/hooks/hooks.test.ts
+++ b/src/agents/lib/hooks/hooks.test.ts
@@ -54,6 +54,7 @@ import {
     wiringStatus,
 } from "./install";
 import { logDecision, releaseRotationLock, setDiagLogPath, setMaxLogBytes, takeRotationLock } from "./log";
+import { MODS_PLUGIN, modsPluginState } from "./mods";
 import { nativeDiffState } from "./native-diff";
 import { matchesGlob, resolveOutcome } from "./outcome";
 import { callDir, hookDataRoot, safeSegment, sessionDir } from "./paths";
@@ -633,6 +634,38 @@ describe("applySetting", () => {
         expect(() => applySetting(DEFAULT_HOOKS_CONFIG, "rules.find-from-root", "loud")).toThrow("takes one of");
     });
 
+    it("diff.commandLines and mods.fullDiff are set, checked and loaded", () => {
+        expect(DEFAULT_HOOKS_CONFIG.diff.commandLines).toBe(3);
+        expect(DEFAULT_HOOKS_CONFIG.mods.fullDiff).toBe(true);
+        expect(applySetting(DEFAULT_HOOKS_CONFIG, "diff.commandLines", "0").diff.commandLines).toBe(0);
+        expect(applySetting(DEFAULT_HOOKS_CONFIG, "mods.fullDiff", "false").mods.fullDiff).toBe(false);
+        expect(() => applySetting(DEFAULT_HOOKS_CONFIG, "diff.commandLines", "-1")).toThrow();
+        expect(() => applySetting(DEFAULT_HOOKS_CONFIG, "mods.fullDiff", "off")).toThrow("true or false");
+
+        const path = join(mkdtempSync(join(tmpdir(), "gt-cfg-mods-")), "hooks.json");
+
+        writeFileSync(path, SafeJSON.stringify({ diff: { commandLines: 5 }, mods: { fullDiff: false } }));
+        expect(loadHooksConfig(path).diff.commandLines).toBe(5);
+        expect(loadHooksConfig(path).mods.fullDiff).toBe(false);
+    });
+
+    it("reads the mods plugin's row from claude plugin list --json", () => {
+        const listed = SafeJSON.stringify([
+            { id: "other@somewhere", enabled: true },
+            { id: MODS_PLUGIN, enabled: false, scope: "user", version: "1.0.0", readFromFolder: "/repo/plugins/x" },
+        ]);
+
+        expect(modsPluginState(listed)).toEqual({
+            installed: true,
+            enabled: false,
+            scope: "user",
+            version: "1.0.0",
+            readFrom: "/repo/plugins/x",
+        });
+        expect(modsPluginState("[]")).toEqual({ installed: false, enabled: false });
+        expect(modsPluginState("not json")).toEqual({ installed: false, enabled: false });
+    });
+
     it("agentsTalk.hint is a boolean switch that ships on and survives a load", () => {
         expect(DEFAULT_HOOKS_CONFIG.agentsTalk.hint).toBe(true);
         expect(applySetting(DEFAULT_HOOKS_CONFIG, "agentsTalk.hint", "false").agentsTalk.hint).toBe(false);
diff --git a/src/agents/lib/hooks/mods.ts b/src/agents/lib/hooks/mods.ts
new file mode 100644
index 0000000000..243dd9117b
--- /dev/null
+++ b/src/agents/lib/hooks/mods.ts
@@ -0,0 +1,74 @@
+import { SafeJSON } from "@genesiscz/utils/json";
+import { logger } from "@genesiscz/utils/logger";
+
+/**
+ * The plugin of Claude Code mods in this repository's marketplace (`plugins/genesis-tools-mods/`). The
+ * marketplace is a folder, so an installed copy is read from the checkout and an edit needs only
+ * `/reload-plugins`, never a reinstall.
+ */
+export const MODS_PLUGIN = "genesis-tools-mods@genesis-tools";
+
+export const MODS_SCOPES = ["user", "project", "local"] as const;
+export type ModsScope = (typeof MODS_SCOPES)[number];
+
+export interface ModsPluginState {
+    installed: boolean;
+    enabled: boolean;
+    scope?: string;
+    version?: string;
+    /** The folder Claude Code reads it from (a folder marketplace), when it says. */
+    readFrom?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null;
+}
+
+/** The mods plugin's row in `claude plugin list --json`, which is an array of installed plugins. */
+export function modsPluginState(listJson: string): ModsPluginState {
+    let rows: unknown;
+
+    try {
+        rows = SafeJSON.parse(listJson, { strict: true });
+    } catch (err) {
+        logger.debug({ err }, "claude plugin list --json did not parse");
+        return { installed: false, enabled: false };
+    }
+
+    const row: unknown = Array.isArray(rows)
+        ? rows.find((item: unknown) => isRecord(item) && item.id === MODS_PLUGIN)
+        : undefined;
+
+    if (!isRecord(row)) {
+        return { installed: false, enabled: false };
+    }
+
+    const field = (key: string): unknown => row[key];
+    const text = (key: string): string | undefined => {
+        const value = field(key);
+        return typeof value === "string" ? value : undefined;
+    };
+
+    return {
+        installed: true,
+        enabled: field("enabled") === true,
+        scope: text("scope"),
+        version: text("version"),
+        readFrom: text("readFromFolder"),
+    };
+}
+
+export interface ClaudePluginRun {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+
+/** `claude plugin <args>`, waited for; the caller reads `ok` and the output. */
+export function claudePlugin(args: string[]): ClaudePluginRun {
+    const command = ["claude", "plugin", ...args];
+    logger.debug({ command }, "Running the Claude Code plugin command");
+    const run = Bun.spawnSync(command, { stdout: "pipe", stderr: "pipe" });
+
+    return { ok: run.exitCode === 0, stdout: run.stdout.toString(), stderr: run.stderr.toString() };
+}
diff --git a/src/agents/lib/hooks/set-config.ts b/src/agents/lib/hooks/set-config.ts
index 8f869f38ec..c82a653b90 100644
--- a/src/agents/lib/hooks/set-config.ts
+++ b/src/agents/lib/hooks/set-config.ts
@@ -47,6 +47,7 @@ export const SETTABLE_KEYS = [
     "diff.highlighter",
     "diff.fill",
     "diff.fillMax",
+    "diff.commandLines",
     "diff.columns",
     "diff.fullDiff",
     "diff.replaceNative",
@@ -67,6 +68,7 @@ export const SETTABLE_KEYS = [
     "decisions.injectAnswers",
     "decisions.staleness.<warnAfterMinutes|alarmAfterMinutes|notify>",
     "agentsTalk.hint",
+    "mods.fullDiff",
 ] as const;
 
 /** One `decisions.*` key. The stop hook takes off|warn|block; `harnesses` a comma list. */
@@ -365,6 +367,11 @@ export function applySetting(
         return next;
     }
 
+    if (key === "diff.commandLines") {
+        next.diff.commandLines = asCount(key, value, 0);
+        return next;
+    }
+
     if (key === "diff.fullDiff") {
         const mode = FULL_DIFF_MODES.find((candidate) => candidate === value);
 
@@ -414,6 +421,11 @@ export function applySetting(
         return next;
     }
 
+    if (key === "mods.fullDiff") {
+        next.mods = { ...config.mods, fullDiff: asBoolean(key, value) };
+        return next;
+    }
+
     if (key === "maxLogMB") {
         next.maxLogMB = asMegabytes(key, value);
         return next;

From 84a8efe8d93d65a2ffdeec9e15fa4bb9e59ef3a9 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Fri, 16 Oct 2026 14:02:29 +0200
Subject: [PATCH 27/32] feat(agents, hooks): genesis-tools-mods compacts an
 idle session 56 min after its last turn, before the 1-hour cache expires,
 because the built-in idle compaction gives up at its first refused gate

(cherry picked from commit 6229f65516aadbf35254136070964ba509e9f5ea)
---
 .claude-plugin/marketplace.json               |  4 +-
 .../.claude-plugin/plugin.json                |  4 +-
 plugins/genesis-tools-mods/hooks/idle.ts      | 94 +++++++++++++++++++
 .../hooks/{sections.test.ts => mods.test.ts}  | 37 ++++++++
 plugins/genesis-tools-mods/hooks/register.tsx | 87 ++++++++++++++++-
 src/agents/README.md                          | 13 ++-
 src/agents/commands/hooks.ts                  |  6 +-
 src/agents/lib/hooks/config.ts                | 35 ++++++-
 src/agents/lib/hooks/hooks.test.ts            | 18 ++++
 src/agents/lib/hooks/set-config.ts            | 21 ++++-
 10 files changed, 307 insertions(+), 12 deletions(-)
 create mode 100644 plugins/genesis-tools-mods/hooks/idle.ts
 rename plugins/genesis-tools-mods/hooks/{sections.test.ts => mods.test.ts} (55%)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 3d19366cc2..6f5618edcf 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -26,8 +26,8 @@
         },
         {
             "name": "genesis-tools-mods",
-            "description": "Claude Code mods for GenesisTools: draws the whole diff of a Bash call whose diff-hook message was cut, with Claude Code's own diff element, under the call's row. Install with: tools agents hooks mods install --write.",
-            "version": "1.0.0",
+            "description": "Claude Code mods for GenesisTools: draws the whole diff of a Bash call whose diff-hook message was cut, with Claude Code's own diff element, under the call's row, and compacts an idle session before its 1-hour prompt cache expires. Install with: tools agents hooks mods install --write.",
+            "version": "1.1.0",
             "author": {
                 "name": "GenesisTools"
             },
diff --git a/plugins/genesis-tools-mods/.claude-plugin/plugin.json b/plugins/genesis-tools-mods/.claude-plugin/plugin.json
index 61797ff8c8..9b02302176 100644
--- a/plugins/genesis-tools-mods/.claude-plugin/plugin.json
+++ b/plugins/genesis-tools-mods/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
     "name": "genesis-tools-mods",
-    "version": "1.0.0",
-    "description": "Claude Code mods for GenesisTools: draws the whole diff of a Bash call whose diff-hook message was cut, with Claude Code's own diff element, under the call's row. Configured in the hooks file: tools agents hooks config set mods.fullDiff true|false.",
+    "version": "1.1.0",
+    "description": "Claude Code mods for GenesisTools: draws the whole diff of a Bash call whose diff-hook message was cut, with Claude Code's own diff element, under the call's row, and compacts an idle session before its 1-hour prompt cache expires. Configured in the hooks file: tools agents hooks config set mods.fullDiff|mods.idleCompact true|false.",
     "author": {
         "name": "GenesisTools"
     }
diff --git a/plugins/genesis-tools-mods/hooks/idle.ts b/plugins/genesis-tools-mods/hooks/idle.ts
new file mode 100644
index 0000000000..3c5c9cb7b6
--- /dev/null
+++ b/plugins/genesis-tools-mods/hooks/idle.ts
@@ -0,0 +1,94 @@
+/** The idle-compaction mod's settings, from the `mods` section of the hooks file. */
+export interface IdleCompactSettings {
+    enabled: boolean;
+    /** Minutes after the last main-loop turn. Under 60, so the compaction still reads the 1-hour cache. */
+    minutes: number;
+    /** Below this many context tokens a compaction saves too little to pay for itself. */
+    minTokens: number;
+}
+
+/**
+ * 56 minutes: Claude Code's own idle compaction fires at 54 (0.9 of the hour) and goes first; the cache
+ * written by the last request expires at 60. 200,000 tokens is the built-in's floor
+ * (`CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` on this machine).
+ */
+export const IDLE_COMPACT_DEFAULTS: IdleCompactSettings = { enabled: true, minutes: 56, minTokens: 200_000 };
+
+/** The start of the notice the mod appends. GenesisClaude's session-analyzer `idle-compact.ts scan` counts it. */
+export const IDLE_NOTICE = "Compacted while idle";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null;
+}
+
+function wholeIn(value: unknown, min: number, max: number): value is number {
+    return typeof value === "number" && Number.isInteger(value) && value >= min && value <= max;
+}
+
+/**
+ * `mods.idleCompact`, `mods.idleCompactMinutes` and `mods.idleCompactMinTokens` from the hooks file
+ * (`tools agents hooks config set mods.idleCompact false --write`). A missing or broken file, and a value
+ * of the wrong kind, leave that value's default.
+ */
+export function idleCompactSettings(hooksFile: string | undefined): IdleCompactSettings {
+    let mods: unknown;
+
+    try {
+        const stored: unknown = hooksFile === undefined ? undefined : JSON.parse(hooksFile);
+        mods = isRecord(stored) ? stored.mods : undefined;
+    } catch {
+        mods = undefined;
+    }
+
+    const held = isRecord(mods) ? mods : {};
+
+    return {
+        enabled: typeof held.idleCompact === "boolean" ? held.idleCompact : IDLE_COMPACT_DEFAULTS.enabled,
+        minutes: wholeIn(held.idleCompactMinutes, 1, 59) ? held.idleCompactMinutes : IDLE_COMPACT_DEFAULTS.minutes,
+        minTokens: wholeIn(held.idleCompactMinTokens, 0, Number.MAX_SAFE_INTEGER)
+            ? held.idleCompactMinTokens
+            : IDLE_COMPACT_DEFAULTS.minTokens,
+    };
+}
+
+/** Why the timer did not compact, or `undefined` to compact. */
+export function idleCompactSkip({
+    settings,
+    surfaces,
+    tokens,
+}: {
+    settings: IdleCompactSettings;
+    surfaces: number;
+    tokens: number | undefined;
+}): string | undefined {
+    if (!settings.enabled) {
+        return "mods.idleCompact is off";
+    }
+
+    if (surfaces === 0) {
+        return "no surface draws the session (claude -p)";
+    }
+
+    if (tokens === undefined || tokens < settings.minTokens) {
+        return `context ${tokens ?? "unknown"} tokens, under the floor of ${settings.minTokens}`;
+    }
+
+    return undefined;
+}
+
+export function idleNotice({
+    minutes,
+    tokensBefore,
+    tokensAfter,
+}: {
+    minutes: number;
+    tokensBefore: number | undefined;
+    tokensAfter: number | undefined;
+}): string {
+    const sizes =
+        tokensBefore !== undefined && tokensAfter !== undefined
+            ? ` (${tokensBefore.toLocaleString("en-US")} to ${tokensAfter.toLocaleString("en-US")} tokens)`
+            : "";
+
+    return `${IDLE_NOTICE}, before the prompt cache expired: genesis-tools-mods after ${minutes} min${sizes}`;
+}
diff --git a/plugins/genesis-tools-mods/hooks/sections.test.ts b/plugins/genesis-tools-mods/hooks/mods.test.ts
similarity index 55%
rename from plugins/genesis-tools-mods/hooks/sections.test.ts
rename to plugins/genesis-tools-mods/hooks/mods.test.ts
index 5270ab7955..7580c096ee 100644
--- a/plugins/genesis-tools-mods/hooks/sections.test.ts
+++ b/plugins/genesis-tools-mods/hooks/mods.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from "bun:test";
+import { IDLE_COMPACT_DEFAULTS, IDLE_NOTICE, idleCompactSettings, idleCompactSkip, idleNotice } from "./idle";
 import { fullDiffEnabled, sectionsOf, sectionsOfCalls } from "./sections";
 
 const NOTE = [
@@ -76,3 +77,39 @@ describe("the full-diff mod's note reader", () => {
         expect(fullDiffEnabled('{"diff":{}}')).toBe(true);
     });
 });
+
+describe("idle compaction", () => {
+    it("reads its settings from the mods section and keeps the default for a bad value", () => {
+        expect(idleCompactSettings(undefined)).toEqual(IDLE_COMPACT_DEFAULTS);
+        expect(idleCompactSettings("not json")).toEqual(IDLE_COMPACT_DEFAULTS);
+        expect(
+            idleCompactSettings(
+                JSON.stringify({ mods: { idleCompact: false, idleCompactMinutes: 50, idleCompactMinTokens: 0 } })
+            )
+        ).toEqual({ enabled: false, minutes: 50, minTokens: 0 });
+        // 60 minutes or more would fire after the cache expired.
+        expect(idleCompactSettings(JSON.stringify({ mods: { idleCompactMinutes: 60, idleCompact: "no" } }))).toEqual(
+            IDLE_COMPACT_DEFAULTS
+        );
+    });
+
+    it("compacts only when on, drawn and over the floor", () => {
+        const settings = { enabled: true, minutes: 56, minTokens: 200_000 };
+
+        expect(idleCompactSkip({ settings, surfaces: 1, tokens: 300_000 })).toBeUndefined();
+        expect(idleCompactSkip({ settings: { ...settings, enabled: false }, surfaces: 1, tokens: 300_000 })).toBe(
+            "mods.idleCompact is off"
+        );
+        expect(idleCompactSkip({ settings, surfaces: 0, tokens: 300_000 })).toContain("no surface");
+        expect(idleCompactSkip({ settings, surfaces: 1, tokens: 199_999 })).toContain("under the floor");
+        expect(idleCompactSkip({ settings, surfaces: 1, tokens: undefined })).toContain("unknown");
+    });
+
+    it("writes a notice that starts with the text the session scan counts", () => {
+        const text = idleNotice({ minutes: 56, tokensBefore: 550_000, tokensAfter: 40_000 });
+
+        expect(text.startsWith(IDLE_NOTICE)).toBe(true);
+        expect(text).toContain("550,000 to 40,000 tokens");
+        expect(idleNotice({ minutes: 56, tokensBefore: undefined, tokensAfter: 1 })).not.toContain("tokens)");
+    });
+});
diff --git a/plugins/genesis-tools-mods/hooks/register.tsx b/plugins/genesis-tools-mods/hooks/register.tsx
index 76c1e7645f..1acaf4d175 100644
--- a/plugins/genesis-tools-mods/hooks/register.tsx
+++ b/plugins/genesis-tools-mods/hooks/register.tsx
@@ -1,4 +1,5 @@
-import type { EngineInterface, Register } from "claude-code";
+import type { EngineInterface, Register, Timer } from "claude-code";
+import { idleCompactSettings, idleCompactSkip, idleNotice } from "./idle";
 import { type CallSection, fullDiffEnabled, sectionsOfCalls } from "./sections";
 
 // The full-diff mod. When the diff hook (`tools agents hooks`) cut a Bash call's message, it wrote the
@@ -22,6 +23,10 @@ async function agentsDir($: EngineInterface): Promise<string | undefined> {
     return home ? `${home}/.genesis-tools/agents` : undefined;
 }
 
+async function readHooksFile($: EngineInterface, dir: string | undefined): Promise<string | undefined> {
+    return dir ? $.fs.read(`${dir}/hooks.json`).catch(() => undefined) : undefined;
+}
+
 async function fullDiffs($: EngineInterface, ids: readonly string[]): Promise<CallSection[]> {
     const dir = ids.length > 0 ? await agentsDir($) : undefined;
 
@@ -29,7 +34,7 @@ async function fullDiffs($: EngineInterface, ids: readonly string[]): Promise<Ca
         return [];
     }
 
-    const hooksFile = await $.fs.read(`${dir}/hooks.json`).catch(() => undefined);
+    const hooksFile = await readHooksFile($, dir);
 
     if (!fullDiffEnabled(hooksFile)) {
         return [];
@@ -38,7 +43,85 @@ async function fullDiffs($: EngineInterface, ids: readonly string[]): Promise<Ca
     return sectionsOfCalls({ ids, read: (id) => $.fs.read(`${dir}/hook-diffs/${id}.md`), maxChars: MAX_CHARS });
 }
 
+// The idle-compaction mod. Claude Code's own idle compaction fires once, 54 minutes after the last
+// request, and gives up at the first gate that refuses (`near_limit` refuses while the account's last reply
+// carried a rate-limit warning, even after the window reset). Then the 1-hour cache expires and the next
+// prompt pays for the whole context again. This timer compacts at `mods.idleCompactMinutes` (56) after the
+// last main-loop turn, unless a compaction already happened. A reload of the mod drops the timer; the next
+// turn arms it again.
+let idleTimer: Timer | undefined;
+
+function stopIdleTimer(): void {
+    idleTimer?.cancel();
+    idleTimer = undefined;
+}
+
+async function compactIfIdle($: EngineInterface): Promise<void> {
+    idleTimer = undefined;
+
+    // Read again at the fire time, so `config set mods.idleCompact false` stops a timer already armed.
+    const settings = idleCompactSettings(await readHooksFile($, await agentsDir($)));
+    const [surfaces, usage] = await Promise.all([$.session.surfaces(), $.session.usage()]);
+
+    if (idleCompactSkip({ settings, surfaces: surfaces.length, tokens: usage.context.tokens }) !== undefined) {
+        return;
+    }
+
+    try {
+        const compacted = await $.session.compact({});
+
+        if (compacted.skip !== undefined) {
+            return;
+        }
+
+        const text = idleNotice({
+            minutes: settings.minutes,
+            tokensBefore: compacted.tokensBefore,
+            tokensAfter: compacted.tokensAfter,
+        });
+
+        await $.session.append({ message: { type: "system", content: [{ type: "text", text }] } });
+    } catch {
+        // `compact` rejects while a turn runs: the person came back, and that turn arms the timer again.
+    }
+}
+
 export const register: Register = (on) => {
+    on("turn.start", (_$, e, next) => {
+        stopIdleTimer();
+
+        return next(e);
+    });
+
+    on("turn.complete", async ($, e, next) => {
+        const done = await next(e);
+
+        if (e.agentId === undefined) {
+            stopIdleTimer();
+
+            const settings = idleCompactSettings(await readHooksFile($, await agentsDir($)));
+
+            if (settings.enabled) {
+                idleTimer = $.clock.after(settings.minutes * 60_000, () => {
+                    void compactIfIdle($);
+                });
+            }
+        }
+
+        return done;
+    });
+
+    on("session.compact", async (_$, e, next) => {
+        const result = await next(e);
+
+        // The person's /compact, the engine's own auto or idle compaction: nothing is left to save.
+        if (e.agentId === undefined && result.skip === undefined) {
+            stopIdleTimer();
+        }
+
+        return result;
+    });
+
     on("ui.render", { component: "ToolGroup" }, async ($, e, next) => {
         const drawn = await next(e);
 
diff --git a/src/agents/README.md b/src/agents/README.md
index ab059549ef..d4f717c50a 100644
--- a/src/agents/README.md
+++ b/src/agents/README.md
@@ -214,7 +214,18 @@ diff element under the call's row, so the 10,000-character message limit no long
 session needs `/reload-plugins`. `tools agents hooks mods` shows whether it is installed;
 `tools agents hooks config set mods.fullDiff false --write` turns it off without an uninstall (the mod reads
 the hooks file). It draws nothing while `diff.fullDiff` is `off`. The mod API is early access in Claude Code
-(2.1.287 and later), so a release can change it; the mod then draws nothing and the hook message is unchanged. A file or a whole folder moved with `mv` or
+(2.1.287 and later), so a release can change it; the mod then draws nothing and the hook message is unchanged.
+
+**The idle-compaction mod.** The same plugin compacts an idle Claude session 56 minutes after its last turn
+(`mods.idleCompactMinutes`, 1 to 59), while the 1-hour prompt cache is still warm, so the next prompt does not
+pay for the whole context again. Claude Code's own idle compaction tries once at 54 minutes and gives up at its
+first refused check (a rate-limit warning on the last reply is enough); the mod does not run that check, so a
+compaction can be spent while the account is in its warning. It skips a session that compacted after its last
+turn, a context under `mods.idleCompactMinTokens` (200,000) and a session with no screen (`claude -p`), and it
+appends a notice that starts `Compacted while idle`. `tools agents hooks config set mods.idleCompact false --write`
+turns it off, also for a timer already armed. A reload of the mod drops the timer until the next turn ends.
+
+A file or a whole folder moved with `mv` or
 `git mv` is one line, `old/ → new/ (284 files)`, when the new copies match the old ones byte for byte
 (up to 4,000 files; a file over 4 MiB is not compared).
 
diff --git a/src/agents/commands/hooks.ts b/src/agents/commands/hooks.ts
index f005ae2760..726f14b7ff 100644
--- a/src/agents/commands/hooks.ts
+++ b/src/agents/commands/hooks.ts
@@ -715,7 +715,8 @@ export function registerHooksCommands(program: Command): void {
 
 /**
  * `hooks mods`: the Claude Code mods of this repository (the `genesis-tools-mods` plugin). They share the
- * hooks file: `mods.fullDiff` switches the full-diff mod, which reads the diff hook's `hook-diffs` notes.
+ * hooks file: `mods.fullDiff` switches the full-diff mod, which reads the diff hook's `hook-diffs` notes, and
+ * `mods.idleCompact` the idle-compaction mod.
  */
 function registerMods(hooks: Command): void {
     const mods = hooks
@@ -752,6 +753,9 @@ function registerMods(hooks: Command): void {
             }
 
             ui.raw(`mods.fullDiff: ${config.mods.fullDiff ? pc.green("on") : pc.dim("off")}`);
+            ui.raw(
+                `mods.idleCompact: ${config.mods.idleCompact ? pc.green("on") : pc.dim("off")}${pc.dim(` · after ${config.mods.idleCompactMinutes} min · floor ${config.mods.idleCompactMinTokens} tokens`)}`
+            );
 
             if (config.mods.fullDiff && fullDiff === "off") {
                 ui.raw(pc.yellow(`diff.fullDiff is off, so no call has a full-diff note for the mod to draw.`));
diff --git a/src/agents/lib/hooks/config.ts b/src/agents/lib/hooks/config.ts
index 04168da546..5486c917b5 100644
--- a/src/agents/lib/hooks/config.ts
+++ b/src/agents/lib/hooks/config.ts
@@ -272,6 +272,15 @@ export interface ModsConfig {
      * under the call's row. Reads `hook-diffs/<call>.md`, so it needs `diff.fullDiff` not `off`.
      */
     fullDiff: boolean;
+    /**
+     * Compact an idle Claude session `idleCompactMinutes` after its last turn, before the 1-hour prompt
+     * cache expires, when the engine's own idle compaction did not (it gives up at its first refused gate,
+     * such as a rate-limit warning). Skips a context under `idleCompactMinTokens`.
+     */
+    idleCompact: boolean;
+    /** 1 to 59: after the engine's own try at 54 minutes, before the cache expires at 60. */
+    idleCompactMinutes: number;
+    idleCompactMinTokens: number;
 }
 
 /**
@@ -417,7 +426,7 @@ export const DEFAULT_HOOKS_CONFIG: HooksConfig = {
         staleness: { warnAfterMinutes: 30, alarmAfterMinutes: 120, notify: true },
     },
     agentsTalk: { hint: true },
-    mods: { fullDiff: true },
+    mods: { fullDiff: true, idleCompact: true, idleCompactMinutes: 56, idleCompactMinTokens: 200_000 },
     unpushed: { enabled: true, maxCommits: 3, maxAgeMinutes: 60, remindEveryMinutes: 30 },
     logPath: defaultLogPath(),
     // 🛑 `shadow: true` AND `logCommands: "shadow"` together mean `keepsCommand()` is true out
@@ -974,7 +983,7 @@ export function mergeStoredConfig(stored: StoredHooksConfig): HooksConfig {
         diff: mergeDiff(stored.diff),
         decisions: mergeDecisions(stored.decisions),
         agentsTalk: { hint: boolOr(stored.agentsTalk?.hint, DEFAULT_HOOKS_CONFIG.agentsTalk.hint) },
-        mods: { fullDiff: boolOr(stored.mods?.fullDiff, DEFAULT_HOOKS_CONFIG.mods.fullDiff) },
+        mods: mergeMods(stored.mods),
         unpushed: mergeUnpushed(stored.unpushed),
         shadow: boolOr(stored.shadow, DEFAULT_HOOKS_CONFIG.shadow),
         logCommands: logCommandsOr(stored.logCommands, DEFAULT_HOOKS_CONFIG.logCommands),
@@ -990,6 +999,28 @@ export function mergeStoredConfig(stored: StoredHooksConfig): HooksConfig {
 const STOP_HOOK_MODES: readonly DecisionStopHook[] = ["off", "warn", "block"];
 
 /** Field by field, like `diff`: a stored value of the wrong type falls back to the default. */
+function mergeMods(stored: Partial<ModsConfig> | undefined): ModsConfig {
+    const base = DEFAULT_HOOKS_CONFIG.mods;
+    const minutes = countOr({
+        field: "mods.idleCompactMinutes",
+        value: stored?.idleCompactMinutes,
+        fallback: base.idleCompactMinutes,
+    });
+
+    return {
+        fullDiff: boolOr(stored?.fullDiff, base.fullDiff),
+        idleCompact: boolOr(stored?.idleCompact, base.idleCompact),
+        // The mod reads the file itself and drops 60 or more the same way.
+        idleCompactMinutes: minutes < 60 ? minutes : base.idleCompactMinutes,
+        idleCompactMinTokens: countOr({
+            field: "mods.idleCompactMinTokens",
+            value: stored?.idleCompactMinTokens,
+            fallback: base.idleCompactMinTokens,
+            min: 0,
+        }),
+    };
+}
+
 function mergeUnpushed(stored: Partial<UnpushedConfig> | undefined): UnpushedConfig {
     const base = DEFAULT_HOOKS_CONFIG.unpushed;
 
diff --git a/src/agents/lib/hooks/hooks.test.ts b/src/agents/lib/hooks/hooks.test.ts
index 6e7b4b9a02..6eb9d2a25a 100644
--- a/src/agents/lib/hooks/hooks.test.ts
+++ b/src/agents/lib/hooks/hooks.test.ts
@@ -649,6 +649,24 @@ describe("applySetting", () => {
         expect(loadHooksConfig(path).mods.fullDiff).toBe(false);
     });
 
+    it("mods.idleCompact* are set, checked and loaded", () => {
+        expect(DEFAULT_HOOKS_CONFIG.mods.idleCompactMinutes).toBe(56);
+        expect(applySetting(DEFAULT_HOOKS_CONFIG, "mods.idleCompact", "false").mods.idleCompact).toBe(false);
+        expect(applySetting(DEFAULT_HOOKS_CONFIG, "mods.idleCompactMinutes", "50").mods.idleCompactMinutes).toBe(50);
+        expect(applySetting(DEFAULT_HOOKS_CONFIG, "mods.idleCompactMinTokens", "0").mods.idleCompactMinTokens).toBe(0);
+        expect(() => applySetting(DEFAULT_HOOKS_CONFIG, "mods.idleCompactMinutes", "60")).toThrow("1 to 59");
+
+        const path = join(mkdtempSync(join(tmpdir(), "gt-cfg-idle-")), "hooks.json");
+
+        writeFileSync(path, SafeJSON.stringify({ mods: { idleCompactMinutes: 75, idleCompactMinTokens: 1000 } }));
+        expect(loadHooksConfig(path).mods).toEqual({
+            fullDiff: true,
+            idleCompact: true,
+            idleCompactMinutes: 56,
+            idleCompactMinTokens: 1000,
+        });
+    });
+
     it("reads the mods plugin's row from claude plugin list --json", () => {
         const listed = SafeJSON.stringify([
             { id: "other@somewhere", enabled: true },
diff --git a/src/agents/lib/hooks/set-config.ts b/src/agents/lib/hooks/set-config.ts
index c82a653b90..8e6f735b86 100644
--- a/src/agents/lib/hooks/set-config.ts
+++ b/src/agents/lib/hooks/set-config.ts
@@ -69,6 +69,7 @@ export const SETTABLE_KEYS = [
     "decisions.staleness.<warnAfterMinutes|alarmAfterMinutes|notify>",
     "agentsTalk.hint",
     "mods.fullDiff",
+    "mods.<idleCompact|idleCompactMinutes|idleCompactMinTokens>",
 ] as const;
 
 /** One `decisions.*` key. The stop hook takes off|warn|block; `harnesses` a comma list. */
@@ -421,8 +422,24 @@ export function applySetting(
         return next;
     }
 
-    if (key === "mods.fullDiff") {
-        next.mods = { ...config.mods, fullDiff: asBoolean(key, value) };
+    if (key === "mods.fullDiff" || key === "mods.idleCompact") {
+        next.mods = { ...config.mods, [key.slice("mods.".length)]: asBoolean(key, value) };
+        return next;
+    }
+
+    if (key === "mods.idleCompactMinutes") {
+        const minutes = asCount(key, value);
+
+        if (minutes > 59) {
+            throw new Error(`${key} takes 1 to 59: at 60 the 1-hour prompt cache has expired`);
+        }
+
+        next.mods = { ...config.mods, idleCompactMinutes: minutes };
+        return next;
+    }
+
+    if (key === "mods.idleCompactMinTokens") {
+        next.mods = { ...config.mods, idleCompactMinTokens: asCount(key, value, 0) };
         return next;
     }
 

From a587de1a21e4795890ca3c46a26a074e1408d4a6 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Fri, 16 Oct 2026 15:11:57 +0200
Subject: [PATCH 28/32] fix(agents, hooks): a precompute no longer cancels the
 idle-compaction timer, because it installs nothing and resolves after the
 turn that armed it

(cherry picked from commit e6728b4c489fc9b381561822527c54fef64ff4c6)
---
 plugins/genesis-tools-mods/hooks/idle.ts      | 17 +++++++++++++++++
 plugins/genesis-tools-mods/hooks/mods.test.ts | 17 ++++++++++++++++-
 plugins/genesis-tools-mods/hooks/register.tsx |  6 ++++--
 3 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/plugins/genesis-tools-mods/hooks/idle.ts b/plugins/genesis-tools-mods/hooks/idle.ts
index 3c5c9cb7b6..6968c99fab 100644
--- a/plugins/genesis-tools-mods/hooks/idle.ts
+++ b/plugins/genesis-tools-mods/hooks/idle.ts
@@ -51,6 +51,23 @@ export function idleCompactSettings(hooksFile: string | undefined): IdleCompactS
     };
 }
 
+/**
+ * Whether a compaction leaves nothing for the timer to save: a main-loop one that ran. A `precompute`
+ * installs nothing (the engine keeps its summary for a later threshold compaction), and it resolves after
+ * the turn that started it, so cancelling on it would drop the timer of exactly the largest sessions.
+ */
+export function compactionEndsIdleWait({
+    agentId,
+    trigger,
+    skipped,
+}: {
+    agentId: string | undefined;
+    trigger: string;
+    skipped: boolean;
+}): boolean {
+    return agentId === undefined && trigger !== "precompute" && !skipped;
+}
+
 /** Why the timer did not compact, or `undefined` to compact. */
 export function idleCompactSkip({
     settings,
diff --git a/plugins/genesis-tools-mods/hooks/mods.test.ts b/plugins/genesis-tools-mods/hooks/mods.test.ts
index 7580c096ee..f092db2d93 100644
--- a/plugins/genesis-tools-mods/hooks/mods.test.ts
+++ b/plugins/genesis-tools-mods/hooks/mods.test.ts
@@ -1,5 +1,12 @@
 import { describe, expect, it } from "bun:test";
-import { IDLE_COMPACT_DEFAULTS, IDLE_NOTICE, idleCompactSettings, idleCompactSkip, idleNotice } from "./idle";
+import {
+    compactionEndsIdleWait,
+    IDLE_COMPACT_DEFAULTS,
+    IDLE_NOTICE,
+    idleCompactSettings,
+    idleCompactSkip,
+    idleNotice,
+} from "./idle";
 import { fullDiffEnabled, sectionsOf, sectionsOfCalls } from "./sections";
 
 const NOTE = [
@@ -105,6 +112,14 @@ describe("idle compaction", () => {
         expect(idleCompactSkip({ settings, surfaces: 1, tokens: undefined })).toContain("unknown");
     });
 
+    it("a precompute, a skipped and a subagent compaction leave the armed timer alone", () => {
+        expect(compactionEndsIdleWait({ agentId: undefined, trigger: "auto", skipped: false })).toBe(true);
+        expect(compactionEndsIdleWait({ agentId: undefined, trigger: "manual", skipped: false })).toBe(true);
+        expect(compactionEndsIdleWait({ agentId: undefined, trigger: "precompute", skipped: false })).toBe(false);
+        expect(compactionEndsIdleWait({ agentId: undefined, trigger: "auto", skipped: true })).toBe(false);
+        expect(compactionEndsIdleWait({ agentId: "a1", trigger: "auto", skipped: false })).toBe(false);
+    });
+
     it("writes a notice that starts with the text the session scan counts", () => {
         const text = idleNotice({ minutes: 56, tokensBefore: 550_000, tokensAfter: 40_000 });
 
diff --git a/plugins/genesis-tools-mods/hooks/register.tsx b/plugins/genesis-tools-mods/hooks/register.tsx
index 1acaf4d175..17590fdc53 100644
--- a/plugins/genesis-tools-mods/hooks/register.tsx
+++ b/plugins/genesis-tools-mods/hooks/register.tsx
@@ -1,5 +1,5 @@
 import type { EngineInterface, Register, Timer } from "claude-code";
-import { idleCompactSettings, idleCompactSkip, idleNotice } from "./idle";
+import { compactionEndsIdleWait, idleCompactSettings, idleCompactSkip, idleNotice } from "./idle";
 import { type CallSection, fullDiffEnabled, sectionsOfCalls } from "./sections";
 
 // The full-diff mod. When the diff hook (`tools agents hooks`) cut a Bash call's message, it wrote the
@@ -68,6 +68,8 @@ async function compactIfIdle($: EngineInterface): Promise<void> {
     }
 
     try {
+        // A full compaction: only the engine's threshold path uses a ready precomputed summary, so this one
+        // makes its own summary request (over the still-warm cache) and a ready precompute is dropped.
         const compacted = await $.session.compact({});
 
         if (compacted.skip !== undefined) {
@@ -115,7 +117,7 @@ export const register: Register = (on) => {
         const result = await next(e);
 
         // The person's /compact, the engine's own auto or idle compaction: nothing is left to save.
-        if (e.agentId === undefined && result.skip === undefined) {
+        if (compactionEndsIdleWait({ agentId: e.agentId, trigger: e.trigger, skipped: result.skip !== undefined })) {
             stopIdleTimer();
         }
 

From a40c79cf1c16ba800a56eee564a69d49e66b0144 Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Fri, 16 Oct 2026 15:33:17 +0200
Subject: [PATCH 29/32] fix(ai): warmup names why an account is refused
 (organization blocks OAuth, terms update, used-up quota) instead of "No
 output generated", because a streamed call never read the SDK's error part

(cherry picked from commit 6828768ec8496fdbc0c41e53c96c0f2d8182a634)
---
 src/ai/commands/warmup.ts                     | 20 +++-
 src/utils/ai/core/call-stream-error.test.ts   | 92 ++++++++++++++++++
 src/utils/ai/core/call.ts                     | 23 ++++-
 src/utils/ai/providers/account-features.ts    | 17 ++++
 .../plugins/anthropic-sub/failure.test.ts     | 95 +++++++++++++++++++
 .../plugins/anthropic-sub/failure.ts          | 72 ++++++++++++++
 .../plugins/anthropic-sub/warmup.test.ts      | 58 +++++++++++
 .../providers/plugins/anthropic-sub/warmup.ts | 27 +++++-
 src/utils/ai/warmup/index.test.ts             | 24 +++++
 src/utils/ai/warmup/index.ts                  | 26 ++++-
 10 files changed, 439 insertions(+), 15 deletions(-)
 create mode 100644 src/utils/ai/core/call-stream-error.test.ts
 create mode 100644 src/utils/ai/providers/plugins/anthropic-sub/failure.test.ts
 create mode 100644 src/utils/ai/providers/plugins/anthropic-sub/failure.ts

diff --git a/src/ai/commands/warmup.ts b/src/ai/commands/warmup.ts
index 79ea2242f5..beaa42759a 100644
--- a/src/ai/commands/warmup.ts
+++ b/src/ai/commands/warmup.ts
@@ -18,9 +18,15 @@ function viaHint(result: WarmupResult): string {
 }
 
 function renderResult(result: WarmupResult): string {
-    const icon = result.ok ? pc.green("✓") : pc.red("✗");
-    const tail = result.ok ? pc.dim(viaHint(result)) : pc.red(` ${result.error ?? "failed"}`);
-    return `  ${icon} ${result.accountName} ${pc.dim(`(${providerAliasOf(result.provider)}, ${result.durationMs}ms)`)}${tail}`;
+    const icon = result.ok ? pc.green("✓") : result.skipped ? pc.yellow("–") : pc.red("✗");
+    const reason = result.error ?? "failed";
+    const tail = result.ok
+        ? pc.dim(viaHint(result))
+        : result.skipped
+          ? pc.yellow(` skipped: ${reason}`)
+          : pc.red(` ${reason}`);
+    const line = `  ${icon} ${result.accountName} ${pc.dim(`(${providerAliasOf(result.provider)}, ${result.durationMs}ms)`)}${tail}`;
+    return result.hint ? `${line}\n      ${pc.dim(result.hint)}` : line;
 }
 
 /**
@@ -83,9 +89,13 @@ export function registerWarmupCommand(program: Command, opts: { provider?: strin
         const spinner = flags.json ? undefined : p.spinner();
         spinner?.start(`Warming up ${names.length > 0 ? names.join(", ") : "every account"}...`);
         const results = await warmupAccounts({ store, ...selection });
-        const failed = results.filter((r) => !r.ok).length;
+        const skipped = results.filter((r) => r.skipped).length;
+        const failed = results.filter((r) => !r.ok && !r.skipped).length;
+        const skippedNote = skipped > 0 ? `, ${skipped} skipped (no quota left)` : "";
         spinner?.stop(
-            failed === 0 ? `${results.length} account(s) warmed up` : `${failed} of ${results.length} failed`
+            failed === 0
+                ? `${results.length - skipped} account(s) warmed up${skippedNote}`
+                : `${failed} of ${results.length} failed${skippedNote}`
         );
 
         if (flags.json) {
diff --git a/src/utils/ai/core/call-stream-error.test.ts b/src/utils/ai/core/call-stream-error.test.ts
new file mode 100644
index 0000000000..41d951ad2a
--- /dev/null
+++ b/src/utils/ai/core/call-stream-error.test.ts
@@ -0,0 +1,92 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { env } from "@genesiscz/utils/env";
+import { APICallError, type LanguageModel } from "ai";
+import { MockLanguageModelV4 } from "ai/test";
+import { type CallTarget, coreChat } from "./call";
+
+/**
+ * A streamed call whose request is refused used to end with "No output generated. Check the
+ * stream for errors." while the SDK printed the raw error to stderr: the real cause sat in an
+ * `error` part nobody read. Fourteen minutes of `tools claude warmup` output on 2026-10-16 showed
+ * six accounts failing with that one line, each for a different reason.
+ */
+
+function refusal(statusCode: number, message: string): APICallError {
+    return new APICallError({
+        message,
+        url: "https://api.example.test/v1/messages",
+        requestBodyValues: {},
+        statusCode,
+        isRetryable: statusCode === 429,
+    });
+}
+
+function target(doStream: () => Promise<never>): CallTarget {
+    return {
+        model: new MockLanguageModelV4({ doStream }) as unknown as LanguageModel,
+        providerType: "anthropic",
+        label: "work/claude-haiku-5-5",
+        accountId: "acc_work",
+        provider: "anthropic-sub",
+        modelId: "claude-haiku-5-5",
+        app: "warmup",
+    };
+}
+
+beforeEach(() => {
+    env.testing.set("GENESIS_TOOLS_HOME", mkdtempSync(join(tmpdir(), "gt-core-stream-error-")));
+});
+
+afterEach(() => {
+    env.testing.unset("GENESIS_TOOLS_HOME");
+});
+
+describe("coreChat streaming errors", () => {
+    test("rejects with the provider's own error and prints nothing to stderr", async () => {
+        const error = refusal(403, "organization does not allow this");
+        const printed = spyOn(console, "error").mockImplementation(() => {});
+
+        try {
+            const outcome = await coreChat({
+                target: target(async () => {
+                    throw error;
+                }),
+                prompt: "hi",
+                stream: true,
+                onChunk: () => {},
+            }).then(
+                () => undefined,
+                (caught: unknown) => caught
+            );
+
+            expect(outcome).toBe(error);
+            expect(printed).not.toHaveBeenCalled();
+        } finally {
+            printed.mockRestore();
+        }
+    });
+
+    test("maxRetries: 0 asks a retryable refusal once", async () => {
+        let asked = 0;
+
+        const outcome = await coreChat({
+            target: target(async () => {
+                asked += 1;
+                throw refusal(429, "rate limited");
+            }),
+            prompt: "hi",
+            stream: true,
+            maxRetries: 0,
+            onChunk: () => {},
+        }).then(
+            () => undefined,
+            (caught: unknown) => caught
+        );
+
+        expect(APICallError.isInstance(outcome)).toBe(true);
+        expect(asked).toBe(1);
+    });
+});
diff --git a/src/utils/ai/core/call.ts b/src/utils/ai/core/call.ts
index daf562b518..ee9f5a6d4a 100644
--- a/src/utils/ai/core/call.ts
+++ b/src/utils/ai/core/call.ts
@@ -74,6 +74,8 @@ export interface CallLLMOptions {
      * an answer nobody would read.
      */
     abortSignal?: AbortSignal;
+    /** Retries after a retryable failure (429, 5xx). The SDK default is 2; a throwaway request such as a warmup wants fewer. */
+    maxRetries?: number;
 }
 
 export interface CallLLMResult {
@@ -169,6 +171,7 @@ export interface CoreChatOptions {
      * partial answer — that is what `MiniAgent.interject` keeps in history.
      */
     abortSignal?: AbortSignal;
+    maxRetries?: number;
     stream?: boolean;
     /** Required when `stream` is set: where text deltas go. */
     onChunk?: (text: string) => void;
@@ -215,6 +218,7 @@ export async function coreChat(options: CoreChatOptions): Promise<CoreChatResult
         providerOptions: buildProviderOptions(target.providerType),
         ...(options.headers ? { headers: options.headers } : {}),
         ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+        ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
         ...(options.maxTokens ? { maxOutputTokens: options.maxTokens } : {}),
         ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
         ...(hasTools && tools ? { tools, stopWhen: stepCountIs(options.maxSteps ?? DEFAULT_MAX_STEPS) } : {}),
@@ -239,14 +243,23 @@ export async function coreChat(options: CoreChatOptions): Promise<CoreChatResult
         };
     }
 
-    const result = await streamText(args);
+    // The SDK's default `onError` prints the raw error to stderr, and the stream then ends
+    // with "No output generated" while the real cause is only in an `error` part. The part
+    // is read below and thrown, so the default dump has nothing left to add.
+    const result = await streamText({
+        ...args,
+        onError: ({ error }) => log.debug({ model: target.label, error }, "stream error"),
+    });
     let content = "";
+    const streamErrors: unknown[] = [];
 
     // fullStream rather than textStream: reasoning models emit thinking deltas
     // long before the first content token, and a tool loop reports its calls the
     // same way. A caller that only wants text simply passes no onThinking.
     for await (const part of result.fullStream) {
-        if (part.type === "text-delta") {
+        if (part.type === "error") {
+            streamErrors.push(part.error);
+        } else if (part.type === "text-delta") {
             content += part.text;
             options.onChunk?.(part.text);
         } else if (part.type === "reasoning-delta") {
@@ -266,6 +279,10 @@ export async function coreChat(options: CoreChatOptions): Promise<CoreChatResult
         return { content };
     }
 
+    if (streamErrors.length > 0) {
+        throw streamErrors[0];
+    }
+
     const usage = await result.usage;
     const response = await result.response;
     const costUsd = upstreamCostUsd(await result.providerMetadata);
@@ -427,6 +444,7 @@ async function runCall(target: CallTarget, options: CallLLMOptions): Promise<Cal
             temperature: options.temperature,
             headers: options.headers,
             ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+            ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
         });
 
         return { content: result.content, usage: result.usage };
@@ -457,6 +475,7 @@ async function runCall(target: CallTarget, options: CallLLMOptions): Promise<Cal
         temperature: options.temperature,
         headers: options.headers,
         ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+        ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
         stream: true,
         onChunk: write,
     });
diff --git a/src/utils/ai/providers/account-features.ts b/src/utils/ai/providers/account-features.ts
index 845717b9d5..2a898e8a4c 100644
--- a/src/utils/ai/providers/account-features.ts
+++ b/src/utils/ai/providers/account-features.ts
@@ -362,6 +362,23 @@ export interface WarmupContext {
 export interface WarmupOutcome {
     /** Which route sent the request, for the CLI's hint column (`oauth`, `login-long`, ...). */
     via: string;
+    /**
+     * Set when nothing was sent because the account has no quota left to start: the reason, with
+     * the reset time. A skip is not a failure, so the report and the exit code leave it out of the
+     * failed count.
+     */
+    skipped?: string;
+}
+
+/** A warmup refusal a person can act on; `hint` says how. */
+export class WarmupFailure extends Error {
+    readonly hint?: string;
+
+    constructor(message: string, hint?: string) {
+        super(message);
+        this.name = "WarmupFailure";
+        this.hint = hint;
+    }
 }
 
 export interface AccountFeatures {
diff --git a/src/utils/ai/providers/plugins/anthropic-sub/failure.test.ts b/src/utils/ai/providers/plugins/anthropic-sub/failure.test.ts
new file mode 100644
index 0000000000..cb176139d6
--- /dev/null
+++ b/src/utils/ai/providers/plugins/anthropic-sub/failure.test.ts
@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+import { APICallError, RetryError } from "ai";
+import { describeAnthropicFailure } from "./failure";
+
+function refusal(input: { statusCode: number; body: string; headers?: Record<string, string> }): APICallError {
+    return new APICallError({
+        message: "refused",
+        url: "https://api.example.test/v1/messages",
+        requestBodyValues: {},
+        statusCode: input.statusCode,
+        responseBody: input.body,
+        ...(input.headers ? { responseHeaders: input.headers } : {}),
+        isRetryable: input.statusCode === 429,
+    });
+}
+
+const WEEKLY_RESET = 1_792_364_400;
+const FIVE_HOUR_RESET = 1_792_174_800;
+
+/** The headers of a real 429, values rounded: the weekly window full, the 5-hour window empty. */
+const WEEKLY_FULL: Record<string, string> = {
+    "anthropic-ratelimit-unified-5h-reset": String(FIVE_HOUR_RESET),
+    "anthropic-ratelimit-unified-5h-status": "allowed",
+    "anthropic-ratelimit-unified-5h-utilization": "0.0",
+    "anthropic-ratelimit-unified-7d-reset": String(WEEKLY_RESET),
+    "anthropic-ratelimit-unified-7d-status": "rejected",
+    "anthropic-ratelimit-unified-7d-utilization": "1.0",
+};
+
+describe("describeAnthropicFailure", () => {
+    test("a 403 that blocks OAuth for the organization has no action a login can take", () => {
+        const failure = describeAnthropicFailure(
+            refusal({
+                statusCode: 403,
+                body: '{"type":"error","error":{"type":"permission_error","message":"OAuth authentication is currently not allowed for this organization.","details":{"error_code":"oauth_not_allowed_for_organization"}}}',
+            })
+        );
+
+        expect(failure?.kind).toBe("org-oauth-blocked");
+        expect(failure?.message).toContain("403");
+        expect(failure?.action).toContain("organization owner");
+    });
+
+    test("a 400 about the updated Consumer Terms says where to accept them", () => {
+        const failure = describeAnthropicFailure(
+            refusal({
+                statusCode: 400,
+                body: "We've updated our Consumer Terms and Privacy Policy. You'll need to accept them in claude.ai",
+            })
+        );
+
+        expect(failure?.kind).toBe("terms-update");
+        expect(failure?.action).toContain("claude.ai");
+    });
+
+    test("a 429 with the weekly window full is a weekly limit with its reset time, also inside a RetryError", () => {
+        const api = refusal({ statusCode: 429, body: "{}", headers: WEEKLY_FULL });
+        const wrapped = new RetryError({
+            message: "Failed after 3 attempts",
+            reason: "maxRetriesExceeded",
+            errors: [api, api, api],
+        });
+
+        for (const err of [api, wrapped]) {
+            const failure = describeAnthropicFailure(err);
+
+            expect(failure?.kind).toBe("weekly-limit");
+            expect(failure?.message).toMatch(/^weekly limit used up, resets \d{4}-\d{2}-\d{2} \d{2}:\d{2}$/);
+            expect(failure?.action).toBeUndefined();
+        }
+    });
+
+    test("a 429 with only the 5-hour window full is a session limit", () => {
+        const failure = describeAnthropicFailure(
+            refusal({
+                statusCode: 429,
+                body: "{}",
+                headers: {
+                    ...WEEKLY_FULL,
+                    "anthropic-ratelimit-unified-5h-utilization": "1.0",
+                    "anthropic-ratelimit-unified-7d-utilization": "0.4",
+                },
+            })
+        );
+
+        expect(failure?.kind).toBe("session-limit");
+        expect(failure?.message).toStartWith("5-hour limit used up, resets ");
+    });
+
+    test("anything else is not recognised, so the caller keeps the original error", () => {
+        expect(describeAnthropicFailure(refusal({ statusCode: 429, body: "{}" }))).toBeUndefined();
+        expect(describeAnthropicFailure(refusal({ statusCode: 500, body: "boom" }))).toBeUndefined();
+        expect(describeAnthropicFailure(new Error("socket hang up"))).toBeUndefined();
+    });
+});
diff --git a/src/utils/ai/providers/plugins/anthropic-sub/failure.ts b/src/utils/ai/providers/plugins/anthropic-sub/failure.ts
new file mode 100644
index 0000000000..fb740c4a23
--- /dev/null
+++ b/src/utils/ai/providers/plugins/anthropic-sub/failure.ts
@@ -0,0 +1,72 @@
+import { formatLocalDateTimeStamp } from "@genesiscz/utils/date";
+import { APICallError, RetryError } from "ai";
+import { usageFromQuotaHeaders } from "./quota-headers";
+
+export type AnthropicFailureKind = "org-oauth-blocked" | "terms-update" | "weekly-limit" | "session-limit";
+
+export interface AnthropicFailure {
+    kind: AnthropicFailureKind;
+    /** One sentence for a report line. */
+    message: string;
+    /** What a person has to do; absent when nothing they can do changes it. */
+    action?: string;
+}
+
+/** The SDK wraps a retried 429 or 5xx in a `RetryError`; the API answer is its last error. */
+function apiError(err: unknown): APICallError | undefined {
+    const inner = RetryError.isInstance(err) ? err.lastError : err;
+    return APICallError.isInstance(inner) ? inner : undefined;
+}
+
+/**
+ * Name the refusals an Anthropic subscription account answers with that no retry or fallback
+ * token changes (measured 2026-10-16 on the account list: a 403 `oauth_not_allowed_for_organization`,
+ * a 400 asking for the updated Consumer Terms, a 429 with the weekly window at 100 %). Anything else
+ * is not recognised, so the caller surfaces the original error unchanged.
+ */
+export function describeAnthropicFailure(err: unknown): AnthropicFailure | undefined {
+    const error = apiError(err);
+
+    if (!error) {
+        return undefined;
+    }
+
+    const body = error.responseBody ?? error.message;
+
+    if (
+        error.statusCode === 403 &&
+        /oauth_not_allowed_for_organization|not allowed for this organization/i.test(body)
+    ) {
+        return {
+            kind: "org-oauth-blocked",
+            message: "HTTP 403: Anthropic refuses OAuth for this organization",
+            action: "Only the organization owner or Anthropic can allow it.",
+        };
+    }
+
+    if (error.statusCode === 400 && /Consumer Terms/i.test(body)) {
+        return {
+            kind: "terms-update",
+            message: "HTTP 400: Anthropic wants the updated Consumer Terms accepted",
+            action: "Sign in at claude.ai with this account's email and accept them.",
+        };
+    }
+
+    if (error.statusCode === 429 && error.responseHeaders) {
+        const usage = usageFromQuotaHeaders(new Headers(error.responseHeaders));
+
+        for (const [kind, label, bucket] of [
+            ["weekly-limit", "weekly", usage?.seven_day],
+            ["session-limit", "5-hour", usage?.five_hour],
+        ] as const) {
+            if (bucket && bucket.utilization >= 100) {
+                const resets = bucket.resets_at
+                    ? `, resets ${formatLocalDateTimeStamp(bucket.resets_at, { seconds: false })}`
+                    : "";
+                return { kind, message: `${label} limit used up${resets}` };
+            }
+        }
+    }
+
+    return undefined;
+}
diff --git a/src/utils/ai/providers/plugins/anthropic-sub/warmup.test.ts b/src/utils/ai/providers/plugins/anthropic-sub/warmup.test.ts
index 093286df38..bffe8afd5d 100644
--- a/src/utils/ai/providers/plugins/anthropic-sub/warmup.test.ts
+++ b/src/utils/ai/providers/plugins/anthropic-sub/warmup.test.ts
@@ -1,6 +1,8 @@
 import { describe, expect, test } from "bun:test";
 import type { AccountEntry } from "@genesiscz/utils/ai/config/schema";
+import { WarmupFailure } from "@genesiscz/utils/ai/providers/account-features";
 import { LONG_TOKEN_MIN_LENGTH } from "@genesiscz/utils/claude/token-verify";
+import { APICallError, RetryError } from "ai";
 import { anthropicWarmup, type LongLivedTokens } from "./warmup";
 
 const LONG = "x".repeat(LONG_TOKEN_MIN_LENGTH);
@@ -106,6 +108,62 @@ describe("anthropicWarmup", () => {
         expect(calls.longLived).toEqual([]);
     });
 
+    test("an organization that blocks OAuth fails with the action, and never pings login-long", async () => {
+        const { outcome, calls } = run({
+            tokens: { longLivedToken: LONG },
+            generic: async () => {
+                throw new APICallError({
+                    message: "OAuth authentication is currently not allowed for this organization.",
+                    url: "https://api.example.test/v1/messages",
+                    requestBodyValues: {},
+                    statusCode: 403,
+                    responseBody: '{"error":{"details":{"error_code":"oauth_not_allowed_for_organization"}}}',
+                    isRetryable: false,
+                });
+            },
+        });
+        const failure = await outcome.then(
+            () => undefined,
+            (caught: unknown) => caught
+        );
+
+        expect(failure).toBeInstanceOf(WarmupFailure);
+        expect(failure instanceof WarmupFailure && failure.hint).toContain("organization owner");
+        expect(calls.longLived).toEqual([]);
+    });
+
+    test("a used-up weekly quota is a skip carrying the reset time, not a failure", async () => {
+        const full = new APICallError({
+            message: "This request would exceed your account's rate limit.",
+            url: "https://api.example.test/v1/messages",
+            requestBodyValues: {},
+            statusCode: 429,
+            responseBody: "{}",
+            responseHeaders: {
+                "anthropic-ratelimit-unified-5h-reset": "1792174800",
+                "anthropic-ratelimit-unified-5h-utilization": "0.0",
+                "anthropic-ratelimit-unified-7d-reset": "1792364400",
+                "anthropic-ratelimit-unified-7d-utilization": "1.0",
+            },
+            isRetryable: true,
+        });
+        const { outcome, calls } = run({
+            tokens: { longLivedToken: LONG },
+            generic: async () => {
+                throw new RetryError({
+                    message: "Failed after 2 attempts",
+                    reason: "maxRetriesExceeded",
+                    errors: [full, full],
+                });
+            },
+        });
+        const result = await outcome;
+
+        expect(result.via).toBe("oauth");
+        expect(result.skipped).toMatch(/^weekly limit used up, resets /);
+        expect(calls.longLived).toEqual([]);
+    });
+
     test("login-long invalid after invalid_grant is a failure naming both", async () => {
         const { outcome } = run({
             tokens: { longLivedToken: LONG },
diff --git a/src/utils/ai/providers/plugins/anthropic-sub/warmup.ts b/src/utils/ai/providers/plugins/anthropic-sub/warmup.ts
index d37d6697a9..26e4be76d5 100644
--- a/src/utils/ai/providers/plugins/anthropic-sub/warmup.ts
+++ b/src/utils/ai/providers/plugins/anthropic-sub/warmup.ts
@@ -1,6 +1,6 @@
 import { AIConfig } from "@genesiscz/utils/ai/AIConfig";
 import type { AccountEntry } from "@genesiscz/utils/ai/config/schema";
-import type { WarmupContext, WarmupOutcome } from "@genesiscz/utils/ai/providers/account-features";
+import { type WarmupContext, WarmupFailure, type WarmupOutcome } from "@genesiscz/utils/ai/providers/account-features";
 import {
     longLivedTokenUsable,
     sendLongLivedInferencePing,
@@ -8,6 +8,7 @@ import {
 } from "@genesiscz/utils/claude/token-verify";
 import { toolCommand } from "@genesiscz/utils/cli/tool-command";
 import { logger } from "@genesiscz/utils/logger";
+import { describeAnthropicFailure } from "./failure";
 
 export interface LongLivedTokens {
     longLivedToken?: string;
@@ -30,6 +31,25 @@ function hasOAuthPair(account: AccountEntry): boolean {
     return Boolean(c.accessToken || c.refreshToken || c.authFile);
 }
 
+/**
+ * A refusal no token change fixes (the organization blocks OAuth, the terms need accepting, the
+ * quota is used up) is reported as what it is. A used-up quota is a skip: nothing is wrong, there
+ * is no session to start. Any other error is rethrown unchanged.
+ */
+function explainRefusal(err: unknown): WarmupOutcome {
+    const failure = describeAnthropicFailure(err);
+
+    if (!failure) {
+        throw err;
+    }
+
+    if (failure.kind === "weekly-limit" || failure.kind === "session-limit") {
+        return { via: "oauth", skipped: failure.message };
+    }
+
+    throw new WarmupFailure(failure.message, failure.action);
+}
+
 async function defaultLoadLongLived(accountName: string): Promise<LongLivedTokens | undefined> {
     const config = await AIConfig.load();
     return config.getAccount(accountName)?.tokens;
@@ -55,7 +75,8 @@ async function pingLongLived(
 /**
  * Anthropic's warmup: the shared chat turn on the OAuth pair, and the inference ping on a
  * usable long-lived (`tools claude login-long`) token when there is no pair or the pair is
- * dead. A non-auth failure surfaces unchanged; an account with no credential at all fails
+ * dead. A refusal the account cannot fix by logging in again is named (`explainRefusal`), any
+ * other non-auth failure surfaces unchanged, and an account with no credential at all fails
  * before any request.
  */
 export async function anthropicWarmup(
@@ -82,7 +103,7 @@ export async function anthropicWarmup(
         return { via: "oauth" };
     } catch (err) {
         if (!isOAuthAuthFailure(err)) {
-            throw err;
+            return explainRefusal(err);
         }
 
         if (!longLived) {
diff --git a/src/utils/ai/warmup/index.test.ts b/src/utils/ai/warmup/index.test.ts
index 64ceb64253..66e2f6cd4e 100644
--- a/src/utils/ai/warmup/index.test.ts
+++ b/src/utils/ai/warmup/index.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import type { AccountEntry } from "@genesiscz/utils/ai/config/schema";
+import { WarmupFailure } from "@genesiscz/utils/ai/providers/account-features";
 import { selectWarmupAccounts, type WarmupStore, warmupAccounts, warmupModelRef } from "./index";
 
 function account(id: string, provider: string, overrides: Partial<AccountEntry> = {}): AccountEntry {
@@ -86,4 +87,27 @@ describe("warmupAccounts", () => {
         ]);
         expect(results.every((r) => Number.isFinite(r.durationMs))).toBe(true);
     });
+
+    test("a skipped account is not a success and not a failure, and a refusal keeps its hint", async () => {
+        const results = await warmupAccounts({
+            store,
+            send: async (a) => {
+                if (a.id === "acc_work") {
+                    return { via: "oauth", skipped: "weekly limit used up, resets 2026-10-19 01:00" };
+                }
+
+                if (a.id === "acc_cdx") {
+                    throw new WarmupFailure("HTTP 403: refused", "Ask the owner.");
+                }
+
+                return { via: "chat" };
+            },
+        });
+
+        expect(results.map((r) => [r.accountName, r.ok, r.skipped, r.error, r.hint])).toEqual([
+            ["work", false, true, "weekly limit used up, resets 2026-10-19 01:00", undefined],
+            ["cdx", false, undefined, "HTTP 403: refused", "Ask the owner."],
+            ["grk", true, undefined, undefined, undefined],
+        ]);
+    });
 });
diff --git a/src/utils/ai/warmup/index.ts b/src/utils/ai/warmup/index.ts
index 3e1fb37377..f929d7d0ea 100644
--- a/src/utils/ai/warmup/index.ts
+++ b/src/utils/ai/warmup/index.ts
@@ -1,6 +1,7 @@
 import { Writable } from "node:stream";
 import { AiConfigStore } from "@genesiscz/utils/ai/config/AiConfigStore";
 import type { AccountEntry } from "@genesiscz/utils/ai/config/schema";
+import { WarmupFailure, type WarmupOutcome } from "@genesiscz/utils/ai/providers/account-features";
 import { registerBuiltInPlugins } from "@genesiscz/utils/ai/providers/plugins";
 import { providerPlugin } from "@genesiscz/utils/ai/providers/registry";
 import { ai } from "@genesiscz/utils/ai/tasks/facade";
@@ -16,6 +17,10 @@ export interface WarmupResult {
     /** Which path sent the request: `chat` (the facade) or a plugin-specific route. */
     via: string;
     error?: string;
+    /** What a person can do about `error`, when they can do anything. */
+    hint?: string;
+    /** Nothing was sent because the account has no quota left. Not a failure: `ok` is false, `error` holds the reason. */
+    skipped?: boolean;
 }
 
 /** The two reads the warmup needs; tests hand in a plain object. */
@@ -28,7 +33,7 @@ export interface WarmupOptions {
     names?: string[];
     store?: WarmupStore;
     /** Test seam: the per-account sender. Production sends one tiny chat turn. */
-    send?: (account: AccountEntry) => Promise<{ via: string }>;
+    send?: (account: AccountEntry) => Promise<WarmupOutcome>;
 }
 
 /**
@@ -58,6 +63,9 @@ export async function sendWarmupChat(account: AccountEntry): Promise<void> {
         task: "chat",
         app: "warmup",
         maxTokens: 5,
+        // A throwaway request: one retry rides out a blip, and a refusal that repeats (a used-up
+        // weekly quota answers 429 with a retry-after of days) does not cost 6 s of backoff.
+        maxRetries: 1,
         streaming: true,
         streamTarget: new Writable({
             write(_chunk, _encoding, callback) {
@@ -71,7 +79,7 @@ export async function sendWarmupChat(account: AccountEntry): Promise<void> {
  * The provider's own route when it declares one (anthropic falls back to its long-lived
  * token when the OAuth grant is dead), the shared chat turn otherwise.
  */
-export async function sendWarmup(account: AccountEntry): Promise<{ via: string }> {
+export async function sendWarmup(account: AccountEntry): Promise<WarmupOutcome> {
     registerBuiltInPlugins();
     const custom = providerPlugin(account.provider).accounts?.warmup;
 
@@ -121,15 +129,23 @@ export async function warmupAccounts(opts: WarmupOptions = {}): Promise<WarmupRe
         const base = { accountId: account.id, accountName: account.name, provider: account.provider };
 
         try {
-            const { via } = await send(account);
+            const { via, skipped } = await send(account);
             const durationMs = Math.round(performance.now() - started);
+
+            if (skipped) {
+                logger.info({ ...base, via, skipped, durationMs }, "[warmup] skipped");
+                results.push({ ...base, ok: false, skipped: true, via, durationMs, error: skipped });
+                continue;
+            }
+
             logger.info({ ...base, via, durationMs }, "[warmup] sent");
             results.push({ ...base, ok: true, via, durationMs });
         } catch (err) {
             const durationMs = Math.round(performance.now() - started);
             const error = err instanceof Error ? err.message : String(err);
-            logger.warn({ ...base, error, durationMs }, "[warmup] failed");
-            results.push({ ...base, ok: false, via: "none", durationMs, error });
+            const hint = err instanceof WarmupFailure ? err.hint : undefined;
+            logger.warn({ ...base, error, ...(hint ? { hint } : {}), durationMs }, "[warmup] failed");
+            results.push({ ...base, ok: false, via: "none", durationMs, error, ...(hint ? { hint } : {}) });
         }
     }
 

From f1ba23e1a541b7f3c6362d89983f5267940e13fd Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Fri, 16 Oct 2026 18:59:08 +0200
Subject: [PATCH 30/32] fix(ai, GenesisHub): the vault gate counts the
 launcher's orphan-watchdog preload and gt-<tool> links of bun as
 GenesisTools' own, and its audit line records the command, parents, warnings
 and every fact the window showed

(cherry picked from commit 4adadd8700cdbb8aed90a3253158f3f73fdfc9fc)
---
 .../GenesisTools/Sources/VaultUnlock.swift    | 28 ++++++++--
 .../GenesisTools/Tests/VaultUnlockTests.swift | 10 ++++
 src/utils/ai/gate/client-identity.test.ts     | 52 ++++++++++++++++++-
 src/utils/ai/gate/client-identity.ts          | 24 +++++++--
 4 files changed, 105 insertions(+), 9 deletions(-)

diff --git a/src/macos/GenesisTools/Sources/VaultUnlock.swift b/src/macos/GenesisTools/Sources/VaultUnlock.swift
index a774a4ab9a..f4bacf5a10 100644
--- a/src/macos/GenesisTools/Sources/VaultUnlock.swift
+++ b/src/macos/GenesisTools/Sources/VaultUnlock.swift
@@ -60,7 +60,10 @@ struct VaultCaller {
     /// The preloads the `tools` wrapper passes to every tool, relative to the checkout the script is in. They are
     /// GenesisTools' own code, so they load no extra code (2026-10-15: every `tools claude login` could only be
     /// allowed once, and the window named the preload as the program).
-    static let ownPreloads = ["src/utils/bun/preload-solid-scoped.ts", "src/utils/search/stores/sqlite-vec-preload.ts"]
+    static let ownPreloads = [
+        "src/utils/bun/preload-solid-scoped.ts", "src/utils/search/stores/sqlite-vec-preload.ts",
+        "src/utils/bun/preload-orphan-watchdog.ts",
+    ]
 
     /// The interpreter's flags before the script, each with its value (`--preload=x` or `--preload x`).
     private var leadingFlags: [(flag: String, value: String?)] {
@@ -622,7 +625,11 @@ enum VaultKeychain {
     }
 }
 
-private func vaultAudit(_ event: String, params: VaultUnlockParams, caller: VaultCaller, session: VaultSessionInfo, detail: String = "") {
+/// Every request's line in `audit.jsonl` carries what decides it (the command, its parents, the folder, any loaded-code
+/// signal, why it is once-only) and, for `prompted`, everything the window showed, warnings included: an approval can
+/// be audited later from the file alone (Martin, 2026-10-16).
+private func vaultAudit(_ event: String, params: VaultUnlockParams, caller: VaultCaller, session: VaultSessionInfo, detail: String = "",
+                        shown: VaultWindowContent? = nil) {
     var parts = ["purpose: \(params.purpose)"]
     if let secret = params.secret { parts.append("secret: \(secret)") }
     if let summary = session.summary { parts.append("session: \(summary)") }
@@ -633,14 +640,27 @@ private func vaultAudit(_ event: String, params: VaultUnlockParams, caller: Vaul
     client["executable"] = caller.executable
     client["script"] = caller.script
     client["cwd"] = caller.cwd
+    client["argv"] = caller.args?.arguments
+    client["parents"] = caller.ancestors.map { ["pid": Int($0.pid), "command": $0.command] }
+    client["injected"] = caller.injected
 
-    let entry: [String: Any] = [
+    var entry: [String: Any] = [
         "at": ISO8601DateFormatter().string(from: Date()),
         "event": event,
         "client": client,
         "account": "vault",
         "detail": parts.joined(separator: "; "),
     ]
+    entry["onceOnly"] = caller.onceOnlyReason
+    if let shown {
+        entry["shown"] = [
+            "title": shown.title,
+            "purpose": shown.purpose,
+            "facts": (shown.facts + shown.details).map { ["label": $0.label, "value": $0.help ?? $0.value] },
+            "warning": shown.warning as Any,
+            "onceOnly": shown.onceOnlyReason as Any,
+        ]
+    }
     guard let data = try? JSONSerialization.data(withJSONObject: entry, options: [.sortedKeys]) else { return }
     let path = (VaultGrants.directory as NSString).appendingPathComponent("audit.jsonl")
     try? FileManager.default.createDirectory(atPath: VaultGrants.directory, withIntermediateDirectories: true)
@@ -751,7 +771,7 @@ func unlockVault(_ params: VaultUnlockParams) {
             }
         }
 
-        vaultAudit("prompted", params: params, caller: caller, session: session)
+        vaultAudit("prompted", params: params, caller: caller, session: session, shown: content)
         vaultPresenter.present(model)
     }
 }
diff --git a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
index 4048bfbd12..0389815eb6 100644
--- a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
+++ b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
@@ -78,6 +78,16 @@ final class VaultUnlockTests: XCTestCase {
         XCTAssertEqual(login.injected, [])
         XCTAssertNil(login.onceOnlyReason)
 
+        // The gateway as the app's launcher starts it: the orphan watchdog comes first (2026-10-16: "Extra code may be
+        // loaded" on every gateway start, so its approval could never be remembered).
+        let gateway = caller(arguments: ["gt-mcp-manager", "--preload", "/repo/src/utils/bun/preload-orphan-watchdog.ts",
+                                         "--preload", "/repo/src/utils/bun/preload-solid-scoped.ts",
+                                         "--preload", "/repo/src/utils/search/stores/sqlite-vec-preload.ts",
+                                         "/repo/src/mcp-manager/index.ts", "gateway", "start", "--supervised"])
+        XCTAssertEqual(gateway.script, "/repo/src/mcp-manager/index.ts")
+        XCTAssertEqual(gateway.injected, [])
+        XCTAssertNil(gateway.onceOnlyReason)
+
         // The same file from another checkout, or another file in this one, is still extra code.
         let foreign = caller(arguments: ["gt-claude", "--preload", "/other/src/utils/bun/preload-solid-scoped.ts",
                                          "/repo/src/claude/index.ts"])
diff --git a/src/utils/ai/gate/client-identity.test.ts b/src/utils/ai/gate/client-identity.test.ts
index 8c685400fc..146e72be04 100644
--- a/src/utils/ai/gate/client-identity.test.ts
+++ b/src/utils/ai/gate/client-identity.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { PsRow } from "@genesiscz/utils/process/ps";
@@ -11,10 +11,60 @@ import {
     fileStamps,
     isAncestorPid,
     isInterpreter,
+    OWN_PRELOADS,
     type ProcessLookup,
     scriptOf,
 } from "./client-identity";
 
+const REPO = join(import.meta.dirname, "../../../..");
+
+// Every tool the app started carried the launcher's orphan-watchdog preload, which neither list named, so the vault
+// window said "Extra code may be loaded" and could never remember an approval (2026-10-16).
+describe("the checkout's own preloads", () => {
+    test("name every preload the launcher passes, and the Swift vault window keeps the same list", () => {
+        const launcher = `${readFileSync(join(REPO, "tools"), "utf8")}\n${readFileSync(join(REPO, "src/utils/cli/tool-exec.ts"), "utf8")}`;
+        const passed = [...launcher.matchAll(/"(src\/[^"]*preload[^"]*\.ts)"/g)].map((match) => match[1]);
+        const swift = readFileSync(join(REPO, "src/macos/GenesisTools/Sources/VaultUnlock.swift"), "utf8");
+        const swiftList = swift.match(/static let ownPreloads = \[([^\]]*)\]/)?.[1] ?? "";
+
+        expect(passed.length).toBeGreaterThan(0);
+        expect(OWN_PRELOADS).toEqual(expect.arrayContaining(passed));
+        expect([...swiftList.matchAll(/"([^"]+)"/g)].map((match) => match[1]).sort()).toEqual([...OWN_PRELOADS].sort());
+    });
+
+    test("a gt-<tool> link of bun reads --preload <file> like bun does", () => {
+        const root = "/work/GenesisTools";
+        const preloads = OWN_PRELOADS.map((relative) => `--preload ${root}/${relative}`).join(" ");
+        const gt = "/Users/x/.genesis-tools/bin/gt-mcp-manager";
+        expect(
+            codeInjectionSignals(`${gt} ${preloads} ${root}/src/mcp-manager/index.ts gateway start`, null, gt)
+        ).toEqual([]);
+        expect(isInterpreter(gt)).toBe(true);
+        expect(scriptOf(`${gt} ${preloads} ${root}/src/mcp-manager/index.ts gateway start`, "/", gt)).toBe(
+            `${root}/src/mcp-manager/index.ts`
+        );
+    });
+
+    test("a tool the launcher starts with all its preloads shows no loaded-code signal", () => {
+        const root = "/work/GenesisTools";
+        const preloads = OWN_PRELOADS.map((relative) => `--preload ${root}/${relative}`).join(" ");
+        expect(
+            codeInjectionSignals(
+                `/usr/bin/bun ${preloads} ${root}/src/mcp-manager/index.ts gateway start`,
+                null,
+                "/usr/bin/bun"
+            )
+        ).toEqual([]);
+        expect(
+            codeInjectionSignals(
+                `/usr/bin/bun --preload /tmp/other.ts ${root}/src/mcp-manager/index.ts`,
+                null,
+                "/usr/bin/bun"
+            )
+        ).toEqual(["flag --preload"]);
+    });
+});
+
 function row(pid: number, ppid: number, command: string): PsRow {
     return { pid, ppid, user: "martin", stat: "S", cpu: 0, rss: 0, startTime: null, command };
 }
diff --git a/src/utils/ai/gate/client-identity.ts b/src/utils/ai/gate/client-identity.ts
index 4626641ca9..f8a2485277 100644
--- a/src/utils/ai/gate/client-identity.ts
+++ b/src/utils/ai/gate/client-identity.ts
@@ -41,19 +41,35 @@ const VALUE_FLAGS = new Set([
 ]);
 const VALUE_FLAG_RUNNERS = /^(node|nodejs|bun)$/i;
 
+/**
+ * The runner an executable is: a `gt-<tool>` file in `~/.genesis-tools/bin` is a hard link of bun under the tool's
+ * name (its own keychain identity), so it parses and runs exactly like `bun`. Read by its own name, `--preload <file>`
+ * was a bare flag and the gateway's own preloads read as foreign code (2026-10-16).
+ */
+function runnerName(executable: string): string {
+    const name = basename(executable);
+    return /^gt-[a-z0-9][a-z0-9-]*$/i.test(name) ? "bun" : name;
+}
+
 /**
  * The preloads the `tools` wrapper passes to every tool, relative to the checkout the script is in. They are
  * GenesisTools' own code, so they load no extra code (2026-10-15: every `tools claude login` could be allowed only
  * once, and the preload was taken for the script). The Swift vault window keeps the same list (`ownPreloads`).
  */
-export const OWN_PRELOADS = ["src/utils/bun/preload-solid-scoped.ts", "src/utils/search/stores/sqlite-vec-preload.ts"];
+export const OWN_PRELOADS = [
+    "src/utils/bun/preload-solid-scoped.ts",
+    "src/utils/search/stores/sqlite-vec-preload.ts",
+    // The launcher's orphan watchdog (`tools`, src/utils/cli/tool-exec.ts). Missing here, every tool the app started
+    // was "extra code may be loaded" and its vault approval could never be remembered (2026-10-16).
+    "src/utils/bun/preload-orphan-watchdog.ts",
+];
 
 /** The interpreter's flags before the script, each with its value, and the arguments from the script on. */
 function splitLeadingFlags(
     args: string[],
     executable: string
 ): { flags: Array<{ flag: string; value: string | null }>; rest: string[] } {
-    const takesValues = VALUE_FLAG_RUNNERS.test(basename(executable));
+    const takesValues = VALUE_FLAG_RUNNERS.test(runnerName(executable));
     const flags: Array<{ flag: string; value: string | null }> = [];
     let index = 0;
 
@@ -204,7 +220,7 @@ export function executableOf(command: string): string {
 }
 
 export function isInterpreter(executable: string): boolean {
-    return INTERPRETERS.test(basename(executable));
+    return INTERPRETERS.test(runnerName(executable));
 }
 
 /**
@@ -216,7 +232,7 @@ export function isInterpreter(executable: string): boolean {
 function scriptArgs(command: string, executable: string): string[] | null {
     const [, ...args] = command.trim().split(/\s+/);
 
-    if (!SUBCOMMAND_RUNNERS.test(basename(executable))) {
+    if (!SUBCOMMAND_RUNNERS.test(runnerName(executable))) {
         return args;
     }
 

From d6d93c0fb3ab122a6f21bd05663239a085ec38fd Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Fri, 16 Oct 2026 19:20:15 +0200
Subject: [PATCH 31/32] feat(GenesisKit, permissions): every permission gate
 (vault key, AI account token, link commands and Touch ID, privacy-permission
 dialogs) writes one shared audit line with what it showed and decided

(cherry picked from commit 189a4569dcbd2872e4c387b94e873610b74ba661)
---
 src/browser-router/lib/launch.ts              | 10 +++
 .../GenesisKit/Permissions/GateAudit.swift    | 71 +++++++++++++++++++
 .../Permissions/PermissionCenter.swift        |  9 +++
 .../GenesisKitTests/GateAuditTests.swift      | 33 +++++++++
 .../GenesisTools/Sources/BrowserURL.swift     | 28 +++++++-
 src/macos/GenesisTools/Sources/Gate.swift     | 28 ++++++++
 .../GenesisTools/Sources/VaultUnlock.swift    |  1 +
 src/utils/ai/gate/grants.test.ts              | 19 +++++
 src/utils/ai/gate/grants.ts                   |  3 +
 src/utils/audit/gates.ts                      | 43 +++++++++++
 10 files changed, 243 insertions(+), 2 deletions(-)
 create mode 100644 src/macos/GenesisKit/Sources/GenesisKit/Permissions/GateAudit.swift
 create mode 100644 src/macos/GenesisKit/Tests/GenesisKitTests/GateAuditTests.swift
 create mode 100644 src/utils/audit/gates.ts

diff --git a/src/browser-router/lib/launch.ts b/src/browser-router/lib/launch.ts
index 5e00814222..5ba7c3bad6 100644
--- a/src/browser-router/lib/launch.ts
+++ b/src/browser-router/lib/launch.ts
@@ -1,3 +1,4 @@
+import { appendGateAudit } from "@genesiscz/utils/audit/gates";
 import {
     type RouteDecision,
     RouteError,
@@ -107,6 +108,15 @@ export async function openMintedLink(
 export async function perform(decision: RouteDecision): Promise<void> {
     if (decision.kind === "run") {
         if (decision.needsApproval) {
+            appendGateAudit({
+                gate: "link-command",
+                event: "denied",
+                check: "approval-card",
+                detail: "asked outside the app: only GenesisTools.app shows the card",
+                link: decision.original,
+                route: decision.routeIndex,
+                argv: decision.argv,
+            });
             throw new Error(`route ${decision.routeIndex} asks before running ${decision.argv.join(" ")}`);
         }
 
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Permissions/GateAudit.swift b/src/macos/GenesisKit/Sources/GenesisKit/Permissions/GateAudit.swift
new file mode 100644
index 0000000000..25228e6ef9
--- /dev/null
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Permissions/GateAudit.swift
@@ -0,0 +1,71 @@
+import Foundation
+
+/// One audit trail for every gate a person answers: the vault key, an AI account's token, a link that runs a saved
+/// command, Touch ID, and the privacy-permission dialogs. `~/.genesis-tools/audit/gates.jsonl` (under
+/// `GENESIS_TOOLS_HOME` when set), one JSON object per line, readable only by its owner. Each line names the gate, the
+/// event (`prompted`, `allowed`, `denied`, `remembered`, `granted`, `not-now`, `recorded`, ...), the process that wrote
+/// it, and everything the gate showed, warnings included, so a decision can be audited later from the file alone
+/// (Martin, 2026-10-16: "I want all permission gates to be audited"). Secrets are never written. The TypeScript side
+/// writes the same file (`src/utils/audit/gates.ts`).
+public enum GateAudit {
+    public static var path: String {
+        let override = ProcessInfo.processInfo.environment["GENESIS_TOOLS_HOME"]
+        let home = override?.isEmpty == false ? override! : NSHomeDirectory()
+        return (home as NSString).appendingPathComponent(".genesis-tools/audit/gates.jsonl")
+    }
+
+    private static let lock = NSLock()
+
+    /// What an approval window showed: its title, why, every fact and detail with its full value, the warning.
+    public static func shown(title: String, purpose: String, facts: [ApprovalFact], warning: String?,
+                             onceOnly: String? = nil) -> [String: Any] {
+        var shown: [String: Any] = [
+            "title": title,
+            "purpose": purpose,
+            "facts": facts.map { ["label": $0.label, "value": $0.help ?? $0.value] },
+        ]
+        if let warning { shown["warning"] = warning }
+        if let onceOnly { shown["onceOnly"] = onceOnly }
+        return shown
+    }
+
+    /// Appends one line. A value that is not JSON (an optional left in, a custom type) is dropped from the line and
+    /// logged, never thrown: an audit write must not stop a gate.
+    public static func write(gate: String, event: String, _ fields: [String: Any] = [:]) {
+        var entry = fields.filter { JSONSerialization.isValidJSONObject(["value": $0.value]) }
+        if entry.count != fields.count {
+            GenesisKit.log("gate audit \(gate) \(event): dropped non-JSON fields \(Set(fields.keys).subtracting(entry.keys).sorted())")
+        }
+        entry["at"] = ISO8601DateFormatter().string(from: Date())
+        entry["gate"] = gate
+        entry["event"] = event
+        entry["writer"] = [
+            "pid": Int(getpid()),
+            "app": Bundle.main.bundleIdentifier ?? "",
+            "executable": Bundle.main.executablePath ?? "",
+        ]
+
+        guard let data = try? JSONSerialization.data(withJSONObject: entry, options: [.sortedKeys]) else {
+            GenesisKit.log("gate audit \(gate) \(event): the entry is not JSON")
+            return
+        }
+
+        lock.lock()
+        defer { lock.unlock() }
+        let file = path
+        let directory = (file as NSString).deletingLastPathComponent
+        do {
+            try FileManager.default.createDirectory(atPath: directory, withIntermediateDirectories: true,
+                                                    attributes: [.posixPermissions: 0o700])
+            if !FileManager.default.fileExists(atPath: file) {
+                FileManager.default.createFile(atPath: file, contents: nil, attributes: [.posixPermissions: 0o600])
+            }
+            let handle = try FileHandle(forWritingTo: URL(fileURLWithPath: file))
+            defer { try? handle.close() }
+            try handle.seekToEnd()
+            try handle.write(contentsOf: data + Data("\n".utf8))
+        } catch {
+            GenesisKit.log("gate audit \(gate) \(event): could not write \(file): \(error)")
+        }
+    }
+}
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Permissions/PermissionCenter.swift b/src/macos/GenesisKit/Sources/GenesisKit/Permissions/PermissionCenter.swift
index e3338da349..1199e68d30 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Permissions/PermissionCenter.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Permissions/PermissionCenter.swift
@@ -256,6 +256,10 @@ public final class PermissionCenter {
 
         let dialog = PermissionDialogModel(need: need, status: status, center: self)
         dialogs[need.kind] = dialog
+        GateAudit.write(gate: "privacy-permission", event: "prompted", [
+            "kind": need.kind.rawValue, "status": String(describing: status), "reason": need.reason,
+            "trigger": String(describing: need.trigger),
+        ])
         if let waiting = waitingElsewhere.removeValue(forKey: need.kind) {
             waiting.poll.cancel()
             waiting.needs.forEach(dialog.merge)
@@ -348,6 +352,10 @@ public final class PermissionCenter {
         presenter.close(open)
         let dialog = PermissionDialogModel(need: need, status: status, center: self)
         dialogs[need.kind] = dialog
+        GateAudit.write(gate: "privacy-permission", event: "prompted", [
+            "kind": need.kind.rawValue, "status": String(describing: status), "reason": need.reason,
+            "trigger": String(describing: need.trigger),
+        ])
         GenesisKit.log("permission \(need.kind.rawValue) still missing here after its dialog saw the grant; dialog shown again")
         presenter.present(dialog, takesFocus: need.trigger == .userAction)
         dialog.startWatching()
@@ -360,6 +368,7 @@ public final class PermissionCenter {
         dialogs[dialog.kind] = nil
         dialog.didClose()
         if dismissedByUser { dismissed.insert(dialog.kind) }
+        GateAudit.write(gate: "privacy-permission", event: dismissedByUser ? "not-now" : "granted", ["kind": dialog.kind.rawValue])
         lock?.release(dialog.kind)
         presenter.close(dialog)
         GenesisKit.log("permission \(dialog.kind.rawValue) dialog closed (\(dismissedByUser ? "not now" : "granted"))")
diff --git a/src/macos/GenesisKit/Tests/GenesisKitTests/GateAuditTests.swift b/src/macos/GenesisKit/Tests/GenesisKitTests/GateAuditTests.swift
new file mode 100644
index 0000000000..6a6d2ba953
--- /dev/null
+++ b/src/macos/GenesisKit/Tests/GenesisKitTests/GateAuditTests.swift
@@ -0,0 +1,33 @@
+import XCTest
+@testable import GenesisKit
+
+/// Every gate writes one line to the shared trail (Martin, 2026-10-16: "I want all permission gates to be audited").
+final class GateAuditTests: XCTestCase {
+    func testALineCarriesTheGateTheEventTheWriterAndWhatTheWindowShowed() throws {
+        let home = FileManager.default.temporaryDirectory.appendingPathComponent("gate-audit-\(UUID().uuidString)").path
+        setenv("GENESIS_TOOLS_HOME", home, 1)
+        defer {
+            unsetenv("GENESIS_TOOLS_HOME")
+            try? FileManager.default.removeItem(atPath: home)
+        }
+
+        let shown = GateAudit.shown(title: "“x” wants the vault key", purpose: "Why.",
+                                    facts: [ApprovalFact("Folder", "~/work", help: "/Users/x/work")],
+                                    warning: "Extra code may be loaded.", onceOnly: "extra code may be loaded")
+        GateAudit.write(gate: "vault", event: "prompted", ["shown": shown, "optional": Optional<String>.none as Any])
+
+        let path = GateAudit.path
+        XCTAssertTrue(path.hasPrefix(home))
+        let text = try String(contentsOfFile: path, encoding: .utf8)
+        let line = try XCTUnwrap(text.split(separator: "\n").last)
+        let entry = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(line.utf8)) as? [String: Any])
+        XCTAssertEqual(entry["gate"] as? String, "vault")
+        XCTAssertEqual(entry["event"] as? String, "prompted")
+        XCTAssertNotNil(entry["writer"])
+        let written = try XCTUnwrap(entry["shown"] as? [String: Any])
+        XCTAssertEqual(written["warning"] as? String, "Extra code may be loaded.")
+        XCTAssertEqual((written["facts"] as? [[String: String]])?.first?["value"], "/Users/x/work")
+        let mode = try XCTUnwrap(FileManager.default.attributesOfItem(atPath: path)[.posixPermissions] as? Int)
+        XCTAssertEqual(mode & 0o777, 0o600)
+    }
+}
diff --git a/src/macos/GenesisTools/Sources/BrowserURL.swift b/src/macos/GenesisTools/Sources/BrowserURL.swift
index b0ccb49959..d9b911a6c4 100644
--- a/src/macos/GenesisTools/Sources/BrowserURL.swift
+++ b/src/macos/GenesisTools/Sources/BrowserURL.swift
@@ -544,8 +544,19 @@ private enum BrowserOutcome {
 private func performBrowserDecision(_ decision: RouteDecision, toastEnabled: Bool) async throws -> BrowserOutcome {
     if decision.kind == "run" {
         let argv = decision.argv ?? []
-        if decision.touchId && !requireBrowserTouchID() { return .denied }
-        if decision.needsApproval == true && !confirmBrowser(argv, open: decision.open) { return .denied }
+        if decision.touchId {
+            let ok = requireBrowserTouchID()
+            auditRoute(decision, gate: "touch-id", event: ok ? "allowed" : "denied")
+            if !ok { return .denied }
+        }
+        if decision.needsApproval == true {
+            auditRoute(decision, gate: "approval-card", event: "prompted")
+            let ok = confirmBrowser(argv, open: decision.open)
+            auditRoute(decision, gate: "approval-card", event: ok ? "allowed" : "denied")
+            if !ok { return .denied }
+        } else {
+            auditRoute(decision, gate: "no-approval", event: "allowed")
+        }
         let output = try await Task.detached(priority: .userInitiated) { try runBrowserArgv(argv) }.value
         if !toastEnabled {
             notifyBrowser(decision.notify?.isEmpty == false ? decision.notify! : (output.isEmpty ? "Done" : output))
@@ -559,6 +570,7 @@ private func performBrowserDecision(_ decision: RouteDecision, toastEnabled: Boo
         // The shared contract (src/utils/browser-router/route.ts): a `tool` action "is recorded and not
         // executed", and the CLI's perform() refuses it. The app keeps the same boundary.
         let message = "Tool routes are recorded, not run: " + (["tools", decision.tool ?? ""] + (decision.args ?? [])).joined(separator: " ")
+        auditRoute(decision, gate: "tool-route", event: "recorded")
         if !toastEnabled {
             notifyBrowser(message)
         }
@@ -570,6 +582,18 @@ private func performBrowserDecision(_ decision: RouteDecision, toastEnabled: Boo
     return .ran
 }
 
+/// A link that runs a saved command is a gate (Touch ID, the Allow / Deny card, or a route set to run without asking):
+/// each decision goes to the shared gate audit with the link, the route and the command (GenesisKit `GateAudit`).
+private func auditRoute(_ decision: RouteDecision, gate: String, event: String) {
+    var fields: [String: Any] = ["check": gate, "link": decision.original, "url": decision.url, "via": decision.via]
+    fields["route"] = decision.routeIndex
+    fields["argv"] = decision.argv ?? (["tools", decision.tool ?? ""] + (decision.args ?? []))
+    fields["open"] = decision.open
+    fields["approval"] = decision.approval
+    fields["touchId"] = decision.touchId
+    GateAudit.write(gate: "link-command", event: event, fields)
+}
+
 private func requireBrowserTouchID() -> Bool {
     let context = LAContext()
     var error: NSError?
diff --git a/src/macos/GenesisTools/Sources/Gate.swift b/src/macos/GenesisTools/Sources/Gate.swift
index 239fa13afa..8641fc4b9f 100644
--- a/src/macos/GenesisTools/Sources/Gate.swift
+++ b/src/macos/GenesisTools/Sources/Gate.swift
@@ -191,8 +191,29 @@ struct GateWindowContent {
 
 @MainActor private let gatePresenter = ApprovalPanelPresenter()
 
+/// What the shared gate audit (GenesisKit `GateAudit`) records for an AI-account request: who asked, how it runs, and
+/// which account and token kind. The token itself is never in it.
+private func gateAuditFields(_ params: GateApproveParams) -> [String: Any] {
+    let client = params.client
+    var fields: [String: Any] = ["name": client.name]
+    fields["pid"] = client.pid
+    fields["executable"] = client.executable
+    fields["script"] = client.script
+    fields["command"] = client.command
+    fields["cwd"] = client.cwd
+    fields["parents"] = client.ancestors?.map { ["pid": $0.pid, "command": $0.command] }
+    fields["injected"] = client.injected
+    fields["verified"] = client.verified
+    return ["client": fields, "provider": params.provider, "account": params.account.name,
+            "tokenKind": params.tokenKind ?? "token"]
+}
+
 func approveGate(_ params: GateApproveParams) {
     let content = GateWindowContent.build(params)
+    let audit = gateAuditFields(params)
+    func record(_ event: String, _ extra: [String: Any] = [:]) {
+        GateAudit.write(gate: "ai-account", event: event, audit.merging(extra) { _, new in new })
+    }
     let biometric = LAContext().canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: nil)
 
     DispatchQueue.main.async {
@@ -207,6 +228,7 @@ func approveGate(_ params: GateApproveParams) {
 
         // The NSAlert this replaces ran a modal loop on the main queue, so this timer never fired there.
         let deadline = DispatchWorkItem {
+            record("denied", ["detail": "no answer within \(Int(gateDeadlineSeconds))s"])
             gateEmit(decision: "deny", rememberSeconds: 0, method: "none", reason: "no answer within \(Int(gateDeadlineSeconds))s")
         }
         DispatchQueue.main.asyncAfter(deadline: .now() + gateDeadlineSeconds, execute: deadline)
@@ -214,6 +236,7 @@ func approveGate(_ params: GateApproveParams) {
         model.onDeny = {
             deadline.cancel()
             gatePresenter.close()
+            record("denied", ["detail": "denied in the approval window"])
             gateEmit(decision: "deny", rememberSeconds: 0, method: "none", reason: "denied in the approval window")
         }
 
@@ -227,13 +250,18 @@ func approveGate(_ params: GateApproveParams) {
 
             authenticate(reason: reason) { method, failure in
                 guard let method else {
+                    record("denied", ["detail": failure])
                     gateEmit(decision: "deny", rememberSeconds: 0, method: "none", reason: failure)
                 }
 
+                record("allowed", ["method": method, "rememberSeconds": remember])
                 gateEmit(decision: "allow", rememberSeconds: remember, method: method, reason: "")
             }
         }
 
+        record("prompted", ["shown": GateAudit.shown(title: content.title, purpose: content.purpose,
+                                                     facts: content.facts + content.details, warning: content.warning,
+                                                     onceOnly: content.rememberChoices.count > 1 ? nil : "only once")])
         gatePresenter.present(model)
     }
 }
diff --git a/src/macos/GenesisTools/Sources/VaultUnlock.swift b/src/macos/GenesisTools/Sources/VaultUnlock.swift
index f4bacf5a10..b6c6e796d0 100644
--- a/src/macos/GenesisTools/Sources/VaultUnlock.swift
+++ b/src/macos/GenesisTools/Sources/VaultUnlock.swift
@@ -661,6 +661,7 @@ private func vaultAudit(_ event: String, params: VaultUnlockParams, caller: Vaul
             "onceOnly": shown.onceOnlyReason as Any,
         ]
     }
+    GateAudit.write(gate: "vault", event: event, entry)
     guard let data = try? JSONSerialization.data(withJSONObject: entry, options: [.sortedKeys]) else { return }
     let path = (VaultGrants.directory as NSString).appendingPathComponent("audit.jsonl")
     try? FileManager.default.createDirectory(atPath: VaultGrants.directory, withIntermediateDirectories: true)
diff --git a/src/utils/ai/gate/grants.test.ts b/src/utils/ai/gate/grants.test.ts
index 971183a2bc..7c34023c9e 100644
--- a/src/utils/ai/gate/grants.test.ts
+++ b/src/utils/ai/gate/grants.test.ts
@@ -2,7 +2,9 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { gatesAuditPath } from "@genesiscz/utils/audit/gates";
 import { env } from "@genesiscz/utils/env";
+import { SafeJSON } from "@genesiscz/utils/json";
 import {
     appendAudit,
     auditPath,
@@ -157,4 +159,21 @@ describe("grants", () => {
         expect(statSync(auditPath()).mode & 0o777).toBe(0o600);
         expect(readFileSync(auditPath(), "utf8")).toContain('"event":"allowed"');
     });
+
+    // Every gate goes to one trail (Martin, 2026-10-16: "I want all permission gates to be audited").
+    test("a decision also lands in the shared gate audit, private to the user", async () => {
+        await appendAudit({
+            at: "2026-09-23T00:00:00Z",
+            event: "denied",
+            client: identity,
+            account: "alice",
+            detail: "no",
+        });
+
+        const lines = readFileSync(gatesAuditPath(), "utf8").trim().split("\n");
+        const last = SafeJSON.parse(lines.at(-1) ?? "{}") as Record<string, unknown>;
+        expect(last).toMatchObject({ gate: "ai-account", event: "denied", account: "alice", detail: "no" });
+        expect(last.writer).toMatchObject({ pid: process.pid });
+        expect(statSync(gatesAuditPath()).mode & 0o777).toBe(0o600);
+    });
 });
diff --git a/src/utils/ai/gate/grants.ts b/src/utils/ai/gate/grants.ts
index df2cb67f38..abd42e3167 100644
--- a/src/utils/ai/gate/grants.ts
+++ b/src/utils/ai/gate/grants.ts
@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { appendFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { aiDataDir } from "@genesiscz/utils/ai/config/paths";
+import { appendGateAudit } from "@genesiscz/utils/audit/gates";
 import { readTailBytes } from "@genesiscz/utils/claude/session.utils";
 import { parseJSON, SafeJSON } from "@genesiscz/utils/json";
 import { logger } from "@genesiscz/utils/logger";
@@ -205,6 +206,8 @@ export async function appendAudit(entry: AuditEntry): Promise<void> {
     const path = auditPath();
     mkdirSync(dirname(path), { recursive: true });
     await appendFile(path, `${SafeJSON.stringify(entry)}\n`, { mode: 0o600 });
+    // The shared trail of every gate (src/utils/audit/gates.ts) gets the same decision.
+    appendGateAudit({ gate: "ai-account", ...entry });
     // File-only: a client that runs `tools ai gate request` reads stderr for the deny reason, so
     // the audit must not land there. `-v` promotes it to the console, and the audit file has it all.
     log.debug(
diff --git a/src/utils/audit/gates.ts b/src/utils/audit/gates.ts
new file mode 100644
index 0000000000..dd08bfafc8
--- /dev/null
+++ b/src/utils/audit/gates.ts
@@ -0,0 +1,43 @@
+import { appendFileSync, chmodSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { SafeJSON } from "@genesiscz/utils/json";
+import { logger } from "@genesiscz/utils/logger";
+import { genesisToolsDir } from "@genesiscz/utils/storage/root";
+
+/**
+ * The one audit trail of every gate a person answers or that decides for them: the vault key, an AI account's token,
+ * a link that runs a saved command, Touch ID, the privacy-permission dialogs. One JSON object per line in
+ * `~/.genesis-tools/audit/gates.jsonl`, readable only by its owner. The app writes the same file
+ * (GenesisKit `GateAudit.swift`); both use `gate`, `event`, `at` and `writer`. Secrets are never written.
+ */
+export function gatesAuditPath(): string {
+    return genesisToolsDir("audit", "gates.jsonl");
+}
+
+export interface GateAuditEntry {
+    gate: string;
+    event: string;
+    [field: string]: unknown;
+}
+
+/** Appends one line. Never throws: an audit write must not stop a gate, so a failure is logged instead. */
+export function appendGateAudit(entry: GateAuditEntry): void {
+    const path = gatesAuditPath();
+
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const created = !existsSync(path);
+        const line = {
+            ...entry,
+            at: new Date().toISOString(),
+            writer: { pid: process.pid, argv: process.argv.slice(1, 3) },
+        };
+        appendFileSync(path, `${SafeJSON.stringify(line)}\n`, { mode: 0o600 });
+
+        if (created) {
+            chmodSync(path, 0o600);
+        }
+    } catch (error) {
+        logger.warn({ error, path, gate: entry.gate, event: entry.event }, "gate audit: could not write the line");
+    }
+}

From 10b2775b53751e694664071746d7299493ee946a Mon Sep 17 00:00:00 2001
From: Martin <admin@phpcode.eu>
Date: Sat, 17 Oct 2026 04:44:51 +0200
Subject: [PATCH 32/32] fix(ai, GenesisKit, GenesisHub): address PR review (14
 commits)

- fix(ai, GenesisHub): #534 followup - close vault grant and audit gaps
- fix(ai, GenesisHub): #534 followup - share approvals and protect audited links
- fix(ai, GenesisKit): #534 followup - audit redaction also covers the URL fragment, where an OAuth callback carries its tokens
- fix(ai, GenesisKit): #534 followup - redact HTTP header credentials
- fix(GenesisKit): #534 followup - the header redaction test reads the safe header from the parsed entry, because the Swift writer escapes its slash
- fix(ai, GenesisKit): #534 followup - mask quoted header values in audit commands
- fix(ai, GenesisKit): #534 followup - cover mixed quotes in audit commands
- fix(ai, GenesisKit): #534 followup - tighten audit scanning and review regressions
- fix(GenesisHub): #534 followup - release the vault key only to the verified caller
- fix(GenesisKit): #534 followup - the audit redaction tests call GateCredentialRedactor, the type that has arguments and text
- fix(GenesisHub): #534 followup - the vault recipient check skips exited and protected system processes
- fix(GenesisHub): #534 followup - the protected-system exception excludes the writable data volume
- fix(ai, GenesisKit, GenesisHub): #534 followup - bound rename scans and preserve audit safety
- fix(ai, GenesisKit, GenesisHub): #534 followup - parse runner flags and stream turn history
---
 .claude-plugin/marketplace.json               |   4 +-
 .../genesis-tools/.claude-plugin/plugin.json  |   2 +-
 .../skills/handoff-to/references/grok.md      |   8 +-
 src/agents/lib/hooks/diff/diff.test.ts        | 121 +++++++-
 src/agents/lib/hooks/diff/run.ts              |  65 +++-
 src/agents/lib/hooks/diff/syntax.ts           |  49 +--
 src/codex/lib/tail-events.test.ts             | 119 +++++++-
 src/codex/lib/tail-events.ts                  |  71 +++--
 .../GenesisKit/Permissions/GateAudit.swift    | 215 ++++++++++++--
 .../GenesisKitTests/GateAuditTests.swift      | 241 +++++++++++++++
 .../GenesisTools/Sources/VaultRecipient.swift | 233 +++++++++++++++
 .../GenesisTools/Sources/VaultUnlock.swift    | 161 ++++++----
 .../GenesisTools/Tests/VaultUnlockTests.swift | 209 +++++++++++++
 src/mcp-manager/README.md                     |   4 +-
 .../claude-code-disable-evidence.md           |  45 +++
 src/mcp-manager/utils/providers/claude.ts     |   4 +-
 src/utils/ai/core/call-stream-error.test.ts   |  30 +-
 src/utils/ai/gate/client-identity.test.ts     |  35 +++
 src/utils/ai/gate/client-identity.ts          |   7 +-
 src/utils/ai/gate/grants.test.ts              | 280 +++++++++++++++++-
 src/utils/ai/gate/grants.ts                   |  29 +-
 src/utils/audit/gates.ts                      |   5 +-
 src/utils/security/keyring/app-gate.test.ts   |  79 +++++
 src/utils/security/keyring/app-gate.ts        |  23 +-
 src/utils/security/vault-purpose.test.ts      |  94 ++++++
 src/utils/security/vault-purpose.ts           | 239 ++++++++++++++-
 26 files changed, 2210 insertions(+), 162 deletions(-)
 create mode 100644 src/macos/GenesisTools/Sources/VaultRecipient.swift
 create mode 100644 src/mcp-manager/claude-code-disable-evidence.md
 create mode 100644 src/utils/security/vault-purpose.test.ts

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 6f5618edcf..08f3aaa85f 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -1,7 +1,7 @@
 {
     "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
     "name": "genesis-tools",
-    "version": "1.0.107",
+    "version": "1.0.109",
     "description": "Plugins for GenesisTools CLI development and management",
     "owner": {
         "name": "genesiscz",
@@ -11,7 +11,7 @@
         {
             "name": "genesis-tools",
             "description": "Skills and utilities for working with GenesisTools CLI toolkit. Provides guidance for discovering, executing, and troubleshooting genesis tools with integrated workflow support.",
-            "version": "1.0.107",
+            "version": "1.0.109",
             "author": {
                 "name": "GenesisTools"
             },
diff --git a/plugins/genesis-tools/.claude-plugin/plugin.json b/plugins/genesis-tools/.claude-plugin/plugin.json
index dcd975f2fb..9413ff0080 100644
--- a/plugins/genesis-tools/.claude-plugin/plugin.json
+++ b/plugins/genesis-tools/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
     "name": "genesis-tools",
-    "version": "1.0.107",
+    "version": "1.0.109",
     "description": "Skills and utilities for working with GenesisTools CLI toolkit. Provides guidance for discovering, executing, and troubleshooting genesis tools with integrated workflow support.",
     "author": {
         "name": "GenesisTools"
diff --git a/plugins/genesis-tools/skills/handoff-to/references/grok.md b/plugins/genesis-tools/skills/handoff-to/references/grok.md
index 7e1804d9fb..9c45776dfd 100644
--- a/plugins/genesis-tools/skills/handoff-to/references/grok.md
+++ b/plugins/genesis-tools/skills/handoff-to/references/grok.md
@@ -65,9 +65,9 @@ tools grok sessions [--json]
 
 🛑 Never reach past the harness for safety flags — two raw-grok flags LOOK like safety dials and are not (both verified): `--permission-mode plan` does not restrict a headless run (the worker edited a file under it), and `--disallowed-tools` silently refuses to remove `run_terminal_command` (the worker appended via the shell instead).
 
-There are no mid-turn approvals. The Auto-mode jail plus the checkpoint contract below are the only brakes.
+There are no mid-turn approvals or project jail. A disposable worktree keeps changes away from the live checkout; the checkpoint contract below tells the worker when to stop, but does not enforce a filesystem boundary.
 
-🛑 **A dispatch the user did not ask for is `--readonly`.** The skill triggers proactively, and the default mode edits and runs commands inside `--cwd` with no confirmation. So when *you* decided to hand the task off, pass `--readonly`, or give the worker a disposable worktree (`git worktree add`) that is not the user's live checkout. A writable run against a real working tree needs the user to have asked for the handoff, or to have said yes to it. Being inside the project jail is not consent: the jail only stops writes *outside* `--cwd`, and everything the user cares about is inside it.
+🛑 **A dispatch the user did not ask for is `--readonly`.** The skill triggers proactively, and the default mode edits and runs commands inside `--cwd` with no confirmation. So when *you* decided to hand the task off, pass `--readonly`, or give the worker a disposable worktree (`git worktree add`) that is not the user's live checkout. A writable run against a real working tree needs the user to have asked for the handoff, or to have said yes to it. The default grants broad write access; `--cwd` selects a working directory and does not constrain filesystem access.
 
 ### 🛑 `--readonly` costs more than editing
 
@@ -75,10 +75,10 @@ The read-only worker gets `read_file,list_dir,grep` and **no terminal tool at al
 
 So for a read-only grok review, plan for it up front:
 
-- If the deliverable is a file (Obsidian vault, report.md), do **not** pass `--readonly`. Use the default jail with `--cwd` at the note folder, or write `/tmp` and let the orchestrator copy. Same class of miss as Codex `--write deny` on 2026-08-31.
+- If the deliverable is a file (Obsidian vault, report.md), do **not** pass `--readonly`. Use a disposable worktree and let the orchestrator copy the report to the note folder. Same class of miss as Codex `--write deny` on 2026-08-31.
 - Make **inline output the deliverable** only when the review is actually inline. Say so in the brief; do not ask for a file.
 - Expect **zero executed verification**. If the worker reports on test quality or runtime behavior, it inferred that from reading. Say so when you relay it, or re-run the claim yourself.
-- If the review genuinely needs to run something, do not reach for `--writable`. Give the worker a disposable worktree and let it run in the default Auto-mode jail there.
+- If the review genuinely needs to run something, do not reach for `--writable`. Give the worker a disposable worktree and let it run there under the checkpoint contract, with broad write access.
 
 ## Checkpoints
 
diff --git a/src/agents/lib/hooks/diff/diff.test.ts b/src/agents/lib/hooks/diff/diff.test.ts
index 11c5b8b361..72d247dd4b 100644
--- a/src/agents/lib/hooks/diff/diff.test.ts
+++ b/src/agents/lib/hooks/diff/diff.test.ts
@@ -16,6 +16,7 @@ import {
 } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, join, relative } from "node:path";
+import { withSpawnCounter } from "@app/benchmark/lib/spawn-counter";
 import { env } from "@genesiscz/utils/env";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { stripAnsi } from "@genesiscz/utils/string";
@@ -63,10 +64,11 @@ import {
     type DiffDecision,
     flushDeferred,
     noteFileToolInput,
+    renamesIn,
     runDiffPost,
     silentReason,
 } from "./run";
-import { languageOf, syntaxRows } from "./syntax";
+import { createSyntaxEngineLoader, languageOf, syntaxRows } from "./syntax";
 import { resolvePalette } from "./theme";
 import { writerChanges } from "./writers";
 
@@ -3813,6 +3815,33 @@ describe("syntax colour from highlight.js", () => {
         throw new Error("claude-dark has a palette");
     }
 
+    it("caches a missing optional language and still loads a different language", () => {
+        const loads: string[] = [];
+        const registered = new Set<string>();
+        const painter = {
+            getLanguage: (language: string) => registered.has(language),
+            registerLanguage: (language: string) => {
+                registered.add(language);
+            },
+            highlight: () => ({ value: "painted" }),
+        };
+        const load = createSyntaxEngineLoader((name) => {
+            loads.push(name);
+            if (name.endsWith("/missing")) {
+                throw new Error("fixture missing optional language");
+            }
+            return painter;
+        });
+        expect(load("missing")).toBeNull();
+        expect(load("missing")).toBeNull();
+        expect(load("typescript")).toBe(painter);
+        expect(loads).toEqual([
+            "highlight.js/lib/core",
+            "highlight.js/lib/languages/missing",
+            "highlight.js/lib/languages/typescript",
+        ]);
+    });
+
     it("colours a TypeScript row in Claude Code's own palette", () => {
         const rows = syntaxRows({
             text: 'const label = "a"; // note\nreturn 42;',
@@ -4459,6 +4488,96 @@ describe("the misfires of 2026-10-14", () => {
         git(["commit", "-qm", "owned done"]);
     });
 
+    it("pairs one real destination only once when files and status use symlink aliases", () => {
+        writeFileSync(join(repo, "alias-a.ts"), "identical alias fixture\n");
+        writeFileSync(join(repo, "alias-b.ts"), "identical alias fixture\n");
+        git(["add", "alias-a.ts", "alias-b.ts"]);
+        git(["commit", "-qm", "alias sources"]);
+        const alias = join(repo, "checkout-alias");
+        symlinkSync(repo, alias, "dir");
+        try {
+            renameSync(join(repo, "alias-a.ts"), join(repo, "alias-new.ts"));
+            rmSync(join(repo, "alias-b.ts"));
+            const pairs = renamesIn({
+                root: repo,
+                base: "HEAD",
+                files: [
+                    { path: join(repo, "alias-a.ts"), root: repo, deleted: true, untracked: false },
+                    { path: join(repo, "alias-b.ts"), root: repo, deleted: true, untracked: false },
+                    { path: join(alias, "alias-new.ts"), root: repo, deleted: false, untracked: true },
+                ],
+                entries: statusEntries(repo),
+            });
+            expect(pairs).toHaveLength(1);
+            expect(pairs[0]?.to).toBe(join(realpathSync(repo), "alias-new.ts"));
+        } finally {
+            rmSync(alias);
+            git(["add", "alias-a.ts", "alias-b.ts", "alias-new.ts"]);
+            git(["commit", "-qm", "alias move done"]);
+        }
+    });
+
+    it("bounds rename directory scans before expansion and shares the remaining candidate budget", async () => {
+        const dirs = ["budget-a", "budget-b", "budget-c"];
+        for (const dir of dirs) {
+            mkdirSync(join(repo, dir));
+            writeFileSync(join(repo, dir, "one.ts"), "one\n");
+            writeFileSync(join(repo, dir, "two.ts"), "two\n");
+        }
+        try {
+            const entries = statusEntries(repo).filter((entry) => entry.path.startsWith("budget-"));
+            expect(entries).toHaveLength(3);
+            const gone = (count: number) =>
+                Array.from({ length: count }, (_, index) => ({
+                    path: join(repo, `deleted-${index}.ts`),
+                    root: repo,
+                    deleted: true,
+                    untracked: false,
+                }));
+            const known = ["one.ts", "two.ts"].map((name) => ({
+                path: join(repo, "budget-a", name),
+                root: repo,
+                deleted: false,
+                untracked: true,
+            }));
+            const overKnown = await withSpawnCounter(async () =>
+                renamesIn({
+                    root: repo,
+                    base: "HEAD",
+                    files: [...gone(3_999), ...known],
+                    entries,
+                })
+            );
+            const overDirectories = await withSpawnCounter(async () =>
+                renamesIn({
+                    root: repo,
+                    base: "HEAD",
+                    files: gone(3_997),
+                    entries,
+                })
+            );
+            const disappeared = await withSpawnCounter(async () =>
+                renamesIn({
+                    root: repo,
+                    base: "HEAD",
+                    files: gone(3_997),
+                    entries: Array.from({ length: 50 }, (_, index) => ({
+                        ...entries[0],
+                        path: `budget-missing-${index}/`,
+                    })),
+                })
+            );
+            expect(overKnown.result).toEqual([]);
+            expect(overDirectories.result).toEqual([]);
+            expect(disappeared.result).toEqual([]);
+            expect([overKnown.count, overDirectories.count, disappeared.count]).toEqual([0, 2, 3]);
+        } finally {
+            for (const dir of dirs) {
+                rmSync(join(repo, dir), { recursive: true, force: true });
+            }
+        }
+    });
+
     it("pairs a whole folder moved with one mv, past the expansion cap and the old scan limit", () => {
         const names = Array.from({ length: 450 }, (_, index) => `note-${String(index).padStart(3, "0")}.md`);
 
diff --git a/src/agents/lib/hooks/diff/run.ts b/src/agents/lib/hooks/diff/run.ts
index 06a30164d7..fd80528a2a 100644
--- a/src/agents/lib/hooks/diff/run.ts
+++ b/src/agents/lib/hooks/diff/run.ts
@@ -242,7 +242,7 @@ const OVERFLOW_PATCHES_PER_FILE = 3;
  * fixtures folder, 18 blocks); now one line names them. Two git spawns, only when a root has both
  * a deletion and another change.
  */
-function renamesIn({
+export function renamesIn({
     root,
     base,
     files,
@@ -267,20 +267,53 @@ function renamesIn({
     // passed only when the write and the move fell in one second). A folder moved whole is one
     // collapsed `? new-folder/` entry; it is expanded here, past `untrackedExpansionCap`, because the
     // cap bounds what is shown and a rename costs no row.
-    const collapsed = entries
-        .filter((entry) => entry.kind === "untracked" && entry.path.endsWith("/"))
-        .flatMap((entry) =>
-            (untrackedFilesIn(root, entry.path, RENAME_SCAN_LIMIT) ?? []).map((name) => join(root, name))
-        );
-    const fresh = [
-        ...new Set([
-            ...files.filter((file) => !file.deleted).map((file) => file.path),
-            ...entries
-                .filter((entry) => (entry.kind === "untracked" && !entry.path.endsWith("/")) || entry.index === "A")
-                .map((entry) => join(root, entry.path)),
-            ...collapsed,
-        ]),
-    ].filter((path) => {
+    const freshPaths = new Set<string>();
+    let remaining = RENAME_SCAN_LIMIT - gone.length;
+    if (remaining <= 0) {
+        return [];
+    }
+
+    const addKnown = (path: string): boolean => {
+        const normalized = canonical(path);
+        if (!freshPaths.has(normalized)) {
+            freshPaths.add(normalized);
+            remaining--;
+        }
+        return remaining >= 0;
+    };
+    for (const file of files) {
+        if (!file.deleted && !addKnown(file.path)) {
+            return [];
+        }
+    }
+    for (const entry of entries) {
+        if (
+            ((entry.kind === "untracked" && !entry.path.endsWith("/")) || entry.index === "A") &&
+            !addKnown(join(root, entry.path))
+        ) {
+            return [];
+        }
+    }
+
+    // Discovery shares one work budget with the known candidates. A stale empty directory costs
+    // one slot too, so many vanished directories cannot cause unbounded synchronous git spawns.
+    for (const entry of entries) {
+        if (entry.kind !== "untracked" || !entry.path.endsWith("/")) {
+            continue;
+        }
+        if (remaining === 0) {
+            return [];
+        }
+        const names = untrackedFilesIn(root, entry.path, remaining + 1);
+        if (!names || names.length > remaining) {
+            return [];
+        }
+        remaining -= Math.max(1, names.length);
+        for (const name of names) {
+            freshPaths.add(canonical(join(root, name)));
+        }
+    }
+    const fresh = [...freshPaths].filter((path) => {
         try {
             return statSync(path).size <= RENAME_MAX_BYTES;
         } catch {
@@ -288,7 +321,7 @@ function renamesIn({
         }
     });
 
-    if (fresh.length === 0 || fresh.length + gone.length > RENAME_SCAN_LIMIT) {
+    if (fresh.length === 0) {
         return [];
     }
 
diff --git a/src/agents/lib/hooks/diff/syntax.ts b/src/agents/lib/hooks/diff/syntax.ts
index 72352858d3..adc4a6c05f 100644
--- a/src/agents/lib/hooks/diff/syntax.ts
+++ b/src/agents/lib/hooks/diff/syntax.ts
@@ -128,24 +128,35 @@ interface Engine {
     getLanguage(name: string): unknown;
 }
 
-let engine: Engine | undefined;
-
-function engineFor(language: string): Engine {
-    // lazy: saves 7.4 ms of cold import (highlight.js core plus one language) on every hook call that
-    // paints nothing, and a language is loaded only when a diff holds it (measured 2026-10-15)
-    engine ??= require("highlight.js/lib/core");
-
-    if (!engine) {
-        throw new Error("highlight.js did not load");
-    }
-
-    if (!engine.getLanguage(language)) {
-        engine.registerLanguage(language, require(`highlight.js/lib/languages/${language}`));
-    }
-
-    return engine;
+/** Missing optional modules fall back once, without repeated loads or diagnostics. */
+export function createSyntaxEngineLoader(
+    load: (name: string) => unknown = require
+): (language: string) => Engine | null {
+    let engine: Engine | undefined;
+    const failed = new Set<string>();
+    return (language) => {
+        if (failed.has(language)) {
+            return null;
+        }
+        try {
+            engine ??= load("highlight.js/lib/core") as Engine;
+            if (!engine) {
+                throw new Error("highlight.js did not load");
+            }
+            if (!engine.getLanguage(language)) {
+                engine.registerLanguage(language, load(`highlight.js/lib/languages/${language}`));
+            }
+            return engine;
+        } catch (error) {
+            failed.add(language);
+            hookDiag("highlight.js language could not load, so bat does", { err: error, language });
+            return null;
+        }
+    };
 }
 
+const engineFor = createSyntaxEngineLoader();
+
 /** The xterm 256-colour index nearest to a colour: the grey ramp for greys, else the 6x6x6 cube. */
 function nearest256([red, green, blue]: Rgb): number {
     if (red === green && green === blue) {
@@ -221,7 +232,11 @@ export function syntaxRows({
     }
 
     try {
-        const html = engineFor(language).highlight(text, { language, ignoreIllegals: true }).value;
+        const painter = engineFor(language);
+        if (!painter) {
+            return null;
+        }
+        const html = painter.highlight(text, { language, ignoreIllegals: true }).value;
         const stack: Array<{ scope: string; colour: Rgb | undefined }> = [];
         const rows: string[] = [];
         let row = "";
diff --git a/src/codex/lib/tail-events.test.ts b/src/codex/lib/tail-events.test.ts
index 6b17e91242..b83e783106 100644
--- a/src/codex/lib/tail-events.test.ts
+++ b/src/codex/lib/tail-events.test.ts
@@ -1,6 +1,21 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
+import * as fs from "node:fs";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { env } from "@genesiscz/utils/env";
 import { SafeJSON } from "@genesiscz/utils/json";
-import { countStartedTurns, numberTurnLine, planFollowRead, takeCompleteLines } from "./tail-events";
+import { out } from "@genesiscz/utils/logger";
+import * as adapter from "./adapter";
+import { sessionEventsPath } from "./paths";
+import { type CodexSessionMeta, CodexSessionStore } from "./store";
+import {
+    countStartedTurns,
+    followSessionEvents,
+    numberTurnLine,
+    planFollowRead,
+    takeCompleteLines,
+} from "./tail-events";
 
 describe("takeCompleteLines", () => {
     // The regression: a size snapshot cut a record in half, the half failed to
@@ -75,6 +90,106 @@ describe("planFollowRead", () => {
         expect(planFollowRead(40, 5_000)).toEqual({ from: 0, rewound: true });
     });
 
+    test("the real follower restarts rendered turn numbers on rewind and preserves them on append", async () => {
+        const home = mkdtempSync(join(tmpdir(), "gt-codex-tail-rewind-"));
+        await env.testing.withOverrides({ GENESIS_TOOLS_HOME: home }, async () => {
+            const started = `${SafeJSON.stringify({ source: "app-server", method: "turn/started", params: { threadId: "t" } })}\n`;
+            const done = `${SafeJSON.stringify({ source: "app-server", method: "turn/completed", params: { threadId: "t", turn: {} } })}\n`;
+            const path = sessionEventsPath("rewind");
+            mkdirSync(dirname(path), { recursive: true });
+            const meta: CodexSessionMeta = {
+                name: "rewind",
+                daemonPid: process.pid,
+                cwd: "/repo",
+                sandbox: "read-only",
+                approvalPolicy: "never",
+                writePolicy: "deny",
+                status: "running",
+                agentName: "fixture",
+                rendezvousSession: "parent",
+                agentsEnabled: false,
+                startedAt: "2026-01-01T00:00:00Z",
+                lastEventAt: "2026-01-01T00:00:00Z",
+                codexVersion: "fixture",
+                pendingApprovals: {},
+            };
+            for (const rewound of [true, false]) {
+                writeFileSync(path, started.repeat(3));
+                let reads = 0;
+                const output: string[] = [];
+                const metadata = spyOn(CodexSessionStore.prototype, "readMeta").mockImplementation(() => {
+                    if (++reads === 1) {
+                        writeFileSync(path, (rewound ? "" : started.repeat(3)) + started + done);
+                        return meta;
+                    }
+                    return null;
+                });
+                const print = spyOn(out, "println").mockImplementation((line) => {
+                    output.push(String(line));
+                });
+                const sleep = spyOn(Bun, "sleep").mockResolvedValue(undefined);
+                try {
+                    await followSessionEvents("rewind", true);
+                    expect(output).toHaveLength(2);
+                    expect(output[0]).toContain(`turn ${rewound ? 1 : 4} started`);
+                    expect(output[1]).toContain(`turn ${rewound ? 1 : 4} completed`);
+                } finally {
+                    metadata.mockRestore();
+                    print.mockRestore();
+                    sleep.mockRestore();
+                }
+            }
+        });
+    });
+
+    test("seeds historical turns through bounded reads without formatting skipped output", async () => {
+        const home = mkdtempSync(join(tmpdir(), "gt-codex-tail-history-"));
+        await env.testing.withOverrides({ GENESIS_TOOLS_HOME: home }, async () => {
+            const path = sessionEventsPath("history");
+            mkdirSync(dirname(path), { recursive: true });
+            const started = SafeJSON.stringify({ method: "turn/started", source: "app-server" });
+            const output = SafeJSON.stringify({
+                source: "app-server",
+                method: "item/completed",
+                params: { item: { type: "commandExecution", aggregatedOutput: "x".repeat(128 * 1024) } },
+            });
+            const body = `${[started, ...Array.from({ length: 20 }, () => output), started].join("\n")}\n`;
+            writeFileSync(path, body);
+            const file = Bun.file(path);
+            const originalSlice = file.slice.bind(file);
+            const slices = spyOn(file, "slice").mockImplementation(
+                (start?: number | string, end?: number | string, type?: string) => {
+                    const begin = typeof start === "number" ? start : 0;
+                    const until = typeof end === "number" ? end : file.size;
+                    const contentType = typeof start === "string" ? start : typeof end === "string" ? end : type;
+                    expect(until - begin).toBeLessThanOrEqual(64 * 1024);
+                    return originalSlice(begin, until, contentType);
+                }
+            );
+            const files = spyOn(Bun, "file").mockReturnValue(file);
+            const reads = spyOn(fs, "createReadStream");
+            const formatted = spyOn(adapter, "formatStoredEventLine");
+            const metadata = spyOn(CodexSessionStore.prototype, "readMeta").mockReturnValue(null);
+            try {
+                await followSessionEvents("history", true);
+                expect(reads).toHaveBeenCalledTimes(1);
+                expect(reads.mock.calls[0]?.[1]).toMatchObject({
+                    highWaterMark: 64 * 1024,
+                    end: Buffer.byteLength(body) - 1,
+                });
+                expect(formatted).not.toHaveBeenCalled();
+                expect(countStartedTurns(body)).toBe(2);
+                expect(formatted).not.toHaveBeenCalled();
+            } finally {
+                metadata.mockRestore();
+                formatted.mockRestore();
+                reads.mockRestore();
+                files.mockRestore();
+                slices.mockRestore();
+            }
+        });
+    });
+
     test("an emptied file rewinds too", () => {
         expect(planFollowRead(0, 120)).toEqual({ from: 0, rewound: true });
     });
diff --git a/src/codex/lib/tail-events.ts b/src/codex/lib/tail-events.ts
index 6f4cc854f7..5cb369a79e 100644
--- a/src/codex/lib/tail-events.ts
+++ b/src/codex/lib/tail-events.ts
@@ -1,4 +1,5 @@
-import { existsSync, statSync } from "node:fs";
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { createInterface } from "node:readline";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { logger, out } from "@genesiscz/utils/logger";
 import { formatStoredEventLine, type StoredCodexEvent } from "./adapter";
@@ -41,30 +42,59 @@ export function numberTurnLine(line: string, turns: TurnCounter): string {
     return line;
 }
 
-function renderedLines(text: string): string[] {
-    const lines: string[] = [];
+function isTurnStartLine(rawLine: string): boolean {
+    if (!rawLine.trim()) {
+        return false;
+    }
 
-    for (const rawLine of text.split("\n")) {
-        if (!rawLine.trim()) {
-            continue;
-        }
+    try {
+        const event = SafeJSON.parse(rawLine, { strict: true }) as StoredCodexEvent | null;
+        return event?.method === "turn/started";
+    } catch (err) {
+        logger.debug({ err, rawLine: rawLine.slice(0, 200) }, "[codex:tail] skipping unparseable event line");
+        return false;
+    }
+}
 
-        try {
-            const line = formatStoredEventLine(SafeJSON.parse(rawLine, { strict: true }) as StoredCodexEvent);
-            if (line) {
-                lines.push(line);
-            }
-        } catch (err) {
-            logger.debug({ err, rawLine: rawLine.slice(0, 200) }, "[codex:tail] skipping unparseable event line");
+/** How many turns the skipped part of the log already started, without rendering or retaining output. */
+export function countStartedTurns(text: string): number {
+    let count = 0;
+    let from = 0;
+    while (from < text.length) {
+        const newline = text.indexOf("\n", from);
+        const end = newline === -1 ? text.length : newline;
+        if (isTurnStartLine(text.slice(from, end))) {
+            count++;
         }
+        from = end + 1;
     }
-
-    return lines;
+    return count;
 }
 
-/** How many turns the skipped part of the log already started, so the first followed turn gets the next number. */
-export function countStartedTurns(text: string): number {
-    return renderedLines(text).filter((line) => line.startsWith("▶ turn")).length;
+/** Read only the snapshotted prefix, in 64 KiB blocks, retaining at most one JSONL record. */
+async function countHistoricalTurns(path: string, bytes: number): Promise<number> {
+    const input = createReadStream(path, { encoding: "utf8", highWaterMark: 64 * 1024, start: 0, end: bytes - 1 });
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    let failure: Error | undefined;
+    input.once("error", (error) => {
+        failure = error;
+        lines.close();
+    });
+    let count = 0;
+    try {
+        for await (const line of lines) {
+            if (isTurnStartLine(line)) {
+                count++;
+            }
+        }
+        if (failure) {
+            throw failure;
+        }
+        return count;
+    } finally {
+        lines.close();
+        input.destroy();
+    }
 }
 
 export function printFollowedChunk(text: string, asEvents: boolean, turns: TurnCounter = { n: 0 }): void {
@@ -126,7 +156,7 @@ export async function followSessionEvents(name: string, asEvents: boolean): Prom
     let offset = existsSync(path) ? statSync(path).size : 0;
     let carry = "";
     const turns: TurnCounter = {
-        n: asEvents && offset > 0 ? countStartedTurns(await Bun.file(path).slice(0, offset).text()) : 0,
+        n: asEvents && offset > 0 ? await countHistoricalTurns(path, offset) : 0,
     };
     // A streaming decoder, not `.text()` per read: a size snapshot can cut
     // a multi-byte codepoint in half, and decoding each byte slice on its
@@ -143,6 +173,7 @@ export async function followSessionEvents(name: string, asEvents: boolean): Prom
 
             if (plan?.rewound) {
                 logger.debug({ path, size, offset }, "[codex:tail] events file shrank, following from 0");
+                turns.n = 0;
                 carry = "";
                 decoder = new TextDecoder("utf-8");
             }
diff --git a/src/macos/GenesisKit/Sources/GenesisKit/Permissions/GateAudit.swift b/src/macos/GenesisKit/Sources/GenesisKit/Permissions/GateAudit.swift
index 25228e6ef9..7db064564a 100644
--- a/src/macos/GenesisKit/Sources/GenesisKit/Permissions/GateAudit.swift
+++ b/src/macos/GenesisKit/Sources/GenesisKit/Permissions/GateAudit.swift
@@ -1,3 +1,4 @@
+import Darwin
 import Foundation
 
 /// One audit trail for every gate a person answers: the vault key, an AI account's token, a link that runs a saved
@@ -7,6 +8,180 @@ import Foundation
 /// it, and everything the gate showed, warnings included, so a decision can be audited later from the file alone
 /// (Martin, 2026-10-16: "I want all permission gates to be audited"). Secrets are never written. The TypeScript side
 /// writes the same file (`src/utils/audit/gates.ts`).
+public enum GateCredentialRedactor {
+    private static let flags: Set<String> = ["--token", "--api-key", "--key", "--password", "--secret"]
+
+    private static func shortToken(_ words: [String]) -> Bool {
+        words.contains { ["wakeup", "gt-wakeup"].contains(($0 as NSString).lastPathComponent) || $0.contains("/src/wakeup/") }
+            && words.contains("daemon") && words.contains("register")
+    }
+
+    public static func arguments(_ words: [String]) -> [String] {
+        let short = shortToken(words)
+        var hideNext = false
+        return words.map { word in
+            if hideNext { hideNext = false; return "[REDACTED]" }
+            let parts = word.split(separator: "=", maxSplits: 1, omittingEmptySubsequences: false)
+            let flag = parts.first.map(String.init) ?? ""
+            guard flags.contains(flag) || (short && flag == "-t") else { return headers(word) }
+            hideNext = parts.count == 1
+            return parts.count == 1 ? word : "\(flag)=[REDACTED]"
+        }
+    }
+
+    private static let sensitiveQueryNames: Set<String> = [
+        "token", "accesstoken", "refreshtoken", "idtoken", "apikey", "key", "password", "passwd", "secret",
+        "clientsecret", "authorization", "auth", "credential", "credentials", "prompt", "command", "cmd", "argv", "args",
+    ]
+
+    private static func url(_ raw: String, depth: Int) -> String {
+        guard var url = URLComponents(string: raw) else { return "[REDACTED URL]" }
+        if url.user != nil || url.password != nil { url.user = "[REDACTED]"; url.password = nil }
+        if let items = url.queryItems {
+            url.queryItems = params(items, depth: depth)
+        }
+        // An OAuth implicit-flow callback carries its tokens in the fragment (`#access_token=…`).
+        if let fragment = url.percentEncodedFragment, fragment.contains("=") {
+            var pairs = URLComponents()
+            pairs.percentEncodedQuery = fragment
+            pairs.queryItems = params(pairs.queryItems ?? [], depth: depth)
+            url.percentEncodedFragment = pairs.percentEncodedQuery
+        }
+        return url.string ?? "[REDACTED URL]"
+    }
+
+    private static func params(_ items: [URLQueryItem], depth: Int) -> [URLQueryItem] {
+        items.map { item in
+            let name = item.name.lowercased().replacingOccurrences(of: "-", with: "").replacingOccurrences(of: "_", with: "")
+            let value: String? = sensitiveQueryNames.contains(name) ? "[REDACTED]" : item.value.map { text($0, depth: depth + 1) }
+            return URLQueryItem(name: item.name, value: value)
+        }
+    }
+
+    /// Use UTF-16 units to match NSRegularExpression offsets and treat CRLF as two newline units.
+    private static func headerValueEnd(_ units: [UInt16], from start: Int, outer: UInt16?) -> Int {
+        func space(_ index: Int) -> Bool { index < units.count && (units[index] == 32 || units[index] == 9) }
+        func lineEnd(_ index: Int) -> Bool { index >= units.count || units[index] == 13 || units[index] == 10 }
+        func letter(_ unit: UInt16) -> Bool { (65...90).contains(unit) || (97...122).contains(unit) }
+        func name(_ unit: UInt16) -> Bool { letter(unit) || (48...57).contains(unit) || [95, 46, 45].contains(unit) }
+        func boundary(_ index: Int) -> (next: Int, found: Bool) {
+            var next = index
+            while space(next) { next += 1 }
+            if next == index { return (next, false) }
+            var token = next
+            while token < units.count && (units[token] == 34 || units[token] == 39) { token += 1 }
+            var flag = token
+            if flag < units.count && units[flag] == 45 {
+                flag += 1
+                if flag < units.count && units[flag] == 45 { flag += 1 }
+            }
+            let isFlag = flag > token && flag < units.count && letter(units[flag])
+            let nameStart = token
+            while token < units.count && name(units[token]) { token += 1 }
+            let named = token > nameStart
+            while space(token) { token += 1 }
+            return (next, isFlag || (named && token < units.count && units[token] == 58))
+        }
+        var index = start
+        var previous: UInt16 = 0
+        while !lineEnd(index) {
+            if space(index) {
+                let run = boundary(index)
+                if run.found { return index }
+                index = run.next
+                continue
+            }
+            let quote = units[index]
+            if quote != 34 && quote != 39 { previous = quote; index += 1; continue }
+            // A wrapper before a flag/header is complete; a value quote after '=' is still secret.
+            let next = index + 1
+            if outer == quote && index > start && previous != 61 && (lineEnd(next) || boundary(next).found) {
+                return index
+            }
+            var close = next
+            while !lineEnd(close) && units[close] != quote {
+                close += units[close] == 92 && !lineEnd(close + 1) ? 2 : 1
+            }
+            if lineEnd(close) { return close }
+            previous = quote
+            index = close + 1
+        }
+        return index
+    }
+
+    private static func redactedHeaderValue(_ name: String, value: String) -> String {
+        let pattern = try! NSRegularExpression(pattern: #"^([a-z][a-z0-9+.-]*)[ \t]+\S"#, options: .caseInsensitive)
+        var scheme = ""
+        if ["authorization", "proxy-authorization"].contains(name.lowercased()),
+           let match = pattern.firstMatch(in: value, range: NSRange(value.startIndex..., in: value)) {
+            scheme = String(value[Range(match.range(at: 1), in: value)!]) + " "
+        }
+        return scheme + "[REDACTED]"
+    }
+
+    private static func headers(_ value: String) -> String {
+        let names = #"(?:Proxy-)?Authorization|[a-z0-9_.-]*(?:key|token|secret|cookie)[a-z0-9_.-]*"#
+        let exact = try! NSRegularExpression(pattern: #"^([ \t]*)("# + names + #")([ \t]*:[ \t]*)([^\r\n]*)$"#, options: .caseInsensitive)
+        let range = NSRange(value.startIndex..., in: value)
+        if let match = exact.firstMatch(in: value, range: range) {
+            let payload = Range(match.range(at: 4), in: value)!
+            let name = String(value[Range(match.range(at: 2), in: value)!])
+            return String(value[..<payload.lowerBound]) + redactedHeaderValue(name, value: String(value[payload]))
+                + String(value[payload.upperBound...])
+        }
+        let inline = try! NSRegularExpression(pattern: #"(^|[\s"']|(?:--header|-H)=["']?)("# + names + #")([ \t]*:[ \t]*)"#, options: .caseInsensitive)
+        let units = Array(value.utf16)
+        let source = value as NSString
+        var safe = ""
+        var copied = 0
+        var cursor = 0
+        while cursor < units.count,
+              let match = inline.firstMatch(in: value, options: .withoutAnchoringBounds,
+                                            range: NSRange(location: cursor, length: units.count - cursor)) {
+            let start = NSMaxRange(match.range)
+            let prefix = source.substring(with: match.range(at: 1)).utf16.last
+            let name = source.substring(with: match.range(at: 2))
+            let beforeFlag = match.range.location > 0 ? units[match.range.location - 1] : nil
+            let wrapper = prefix == 34 || prefix == 39 ? prefix : beforeFlag
+            let outer = wrapper == 34 || wrapper == 39 ? wrapper : nil
+            let end = headerValueEnd(units, from: start, outer: outer)
+            safe += source.substring(with: NSRange(location: copied, length: start - copied))
+                + redactedHeaderValue(name, value: source.substring(with: NSRange(location: start, length: end - start)))
+            copied = end
+            cursor = end
+        }
+        return safe + source.substring(from: copied)
+    }
+
+    public static func text(_ value: String) -> String { text(value, depth: 0) }
+
+    private static func text(_ value: String, depth: Int) -> String {
+        guard depth < 8 else { return "[REDACTED]" }
+        let links = try! NSRegularExpression(pattern: #"\b[a-z][a-z0-9+.-]*://\S+"#, options: .caseInsensitive)
+        let matches = links.matches(in: value, range: NSRange(value.startIndex..., in: value))
+        var safe = value
+        for match in matches.reversed() {
+            guard let range = Range(match.range, in: safe) else { continue }
+            safe.replaceSubrange(range, with: url(String(safe[range]), depth: depth))
+        }
+        let words = safe.components(separatedBy: .whitespacesAndNewlines)
+        let flags = shortToken(words) ? "--(?:token|api-key|key|password|secret)|-t" : "--(?:token|api-key|key|password|secret)"
+        let pattern = #"(^|[\s"'])("# + flags + #")(=|\s+)("(?:\\[^\r\n]|[^"\\\r\n])*(?:"|\\?(?=$|[\r\n]))|'(?:\\[^\r\n]|[^'\\\r\n])*(?:'|\\?(?=$|[\r\n]))|[^\s;]+)"#
+        guard let regex = try? NSRegularExpression(pattern: pattern) else { return "[REDACTED]" }
+        let redacted = regex.stringByReplacingMatches(in: safe, range: NSRange(safe.startIndex..., in: safe),
+                                                      withTemplate: "$1$2$3[REDACTED]")
+        return headers(redacted)
+    }
+
+    public static func fields(_ value: Any) -> Any {
+        if let text = value as? String { return self.text(text) }
+        if let words = value as? [String] { return arguments(words).map(text) }
+        if let array = value as? [Any] { return array.map(fields) }
+        if let object = value as? [String: Any] { return object.mapValues(fields) }
+        return value
+    }
+}
+
 public enum GateAudit {
     public static var path: String {
         let override = ProcessInfo.processInfo.environment["GENESIS_TOOLS_HOME"]
@@ -14,15 +189,29 @@ public enum GateAudit {
         return (home as NSString).appendingPathComponent(".genesis-tools/audit/gates.jsonl")
     }
 
-    private static let lock = NSLock()
+    /// O_APPEND makes the single write atomic with other Swift and TypeScript writers, including file creation.
+    public static func appendLine(_ data: Data, to file: String) {
+        do {
+            try FileManager.default.createDirectory(atPath: (file as NSString).deletingLastPathComponent,
+                                                    withIntermediateDirectories: true, attributes: [.posixPermissions: 0o700])
+            let fd = open(file, O_WRONLY | O_CREAT | O_APPEND, 0o600)
+            guard fd >= 0 else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) }
+            defer { close(fd) }
+            let line = data + Data("\n".utf8)
+            let written = line.withUnsafeBytes { Darwin.write(fd, $0.baseAddress, $0.count) }
+            guard written == line.count else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) }
+        } catch {
+            GenesisKit.log("gate audit: could not append to \(file): \(error)")
+        }
+    }
 
     /// What an approval window showed: its title, why, every fact and detail with its full value, the warning.
     public static func shown(title: String, purpose: String, facts: [ApprovalFact], warning: String?,
                              onceOnly: String? = nil) -> [String: Any] {
         var shown: [String: Any] = [
             "title": title,
-            "purpose": purpose,
-            "facts": facts.map { ["label": $0.label, "value": $0.help ?? $0.value] },
+            "purpose": GateCredentialRedactor.text(purpose),
+            "facts": facts.map { ["label": $0.label, "value": GateCredentialRedactor.text($0.help ?? $0.value)] },
         ]
         if let warning { shown["warning"] = warning }
         if let onceOnly { shown["onceOnly"] = onceOnly }
@@ -45,27 +234,11 @@ public enum GateAudit {
             "executable": Bundle.main.executablePath ?? "",
         ]
 
-        guard let data = try? JSONSerialization.data(withJSONObject: entry, options: [.sortedKeys]) else {
+        guard let data = try? JSONSerialization.data(withJSONObject: GateCredentialRedactor.fields(entry), options: [.sortedKeys]) else {
             GenesisKit.log("gate audit \(gate) \(event): the entry is not JSON")
             return
         }
 
-        lock.lock()
-        defer { lock.unlock() }
-        let file = path
-        let directory = (file as NSString).deletingLastPathComponent
-        do {
-            try FileManager.default.createDirectory(atPath: directory, withIntermediateDirectories: true,
-                                                    attributes: [.posixPermissions: 0o700])
-            if !FileManager.default.fileExists(atPath: file) {
-                FileManager.default.createFile(atPath: file, contents: nil, attributes: [.posixPermissions: 0o600])
-            }
-            let handle = try FileHandle(forWritingTo: URL(fileURLWithPath: file))
-            defer { try? handle.close() }
-            try handle.seekToEnd()
-            try handle.write(contentsOf: data + Data("\n".utf8))
-        } catch {
-            GenesisKit.log("gate audit \(gate) \(event): could not write \(file): \(error)")
-        }
+        appendLine(data, to: path)
     }
 }
diff --git a/src/macos/GenesisKit/Tests/GenesisKitTests/GateAuditTests.swift b/src/macos/GenesisKit/Tests/GenesisKitTests/GateAuditTests.swift
index 6a6d2ba953..4c81835f5c 100644
--- a/src/macos/GenesisKit/Tests/GenesisKitTests/GateAuditTests.swift
+++ b/src/macos/GenesisKit/Tests/GenesisKitTests/GateAuditTests.swift
@@ -3,6 +3,247 @@ import XCTest
 
 /// Every gate writes one line to the shared trail (Martin, 2026-10-16: "I want all permission gates to be audited").
 final class GateAuditTests: XCTestCase {
+    func testCredentialRedactionCoversArgumentsPurposesAndFullFactHelp() throws {
+        let token = "fixture-secret-never-real"
+        for flag in ["--token", "--api-key", "--key", "--password", "--secret"] {
+            for args in [[flag, token], ["\(flag)=\(token)"]] {
+                XCTAssertFalse(GateCredentialRedactor.arguments(args).joined(separator: " ").contains(token))
+                XCTAssertFalse(GateCredentialRedactor.text("tools claude " + args.joined(separator: " ")).contains(token))
+            }
+        }
+        XCTAssertEqual(GateCredentialRedactor.arguments(["tools", "wakeup", "daemon", "register", "-t", token]).last, "[REDACTED]")
+        XCTAssertEqual(GateCredentialRedactor.arguments(["bun", "/repo/src/wakeup/index.ts", "daemon", "register", "-t=\(token)"]).last, "-t=[REDACTED]")
+        XCTAssertEqual(GateCredentialRedactor.arguments(["tools", "claude", "tail", "-t", "5"]).last, "5")
+        let command = "tools claude --token=\(token)"
+        let shown = GateAudit.shown(title: "Approve", purpose: command,
+                                    facts: [ApprovalFact("Command", "short", help: command)], warning: nil)
+        let data = try JSONSerialization.data(withJSONObject: shown)
+        XCTAssertFalse(String(decoding: data, as: UTF8.self).contains(token))
+    }
+
+    func testAuditHeaderCredentialsAreRedactedWhileSafeHeadersRemain() throws {
+        let home = FileManager.default.temporaryDirectory.appendingPathComponent("gate-headers-\(UUID().uuidString)").path
+        setenv("GENESIS_TOOLS_HOME", home, 1)
+        defer { unsetenv("GENESIS_TOOLS_HOME"); try? FileManager.default.removeItem(atPath: home) }
+        let token = "fixture-header-secret-never-real"
+        let headers = [
+            ("Authorization: Bearer {token}", "Authorization: Bearer [REDACTED]"),
+            ("authorization:Basic {token}", "authorization:Basic [REDACTED]"),
+            ("Proxy-Authorization: Basic {token}", "Proxy-Authorization: Basic [REDACTED]"),
+            ("pRoXy-AuThOrIzAtIoN:Bearer {token}", "pRoXy-AuThOrIzAtIoN:Bearer [REDACTED]"),
+            ("Authorization:{token}", "Authorization:[REDACTED]"),
+            ("X-Api-Key:{token}", "X-Api-Key:[REDACTED]"),
+            ("x-aUtH-tOkEn: {token}", "x-aUtH-tOkEn: [REDACTED]"),
+            ("X-Client-Secret: {token}", "X-Client-Secret: [REDACTED]"),
+            ("Cookie:session={token}; other={token}", "Cookie:[REDACTED]"),
+            ("Set-Cookie: session={token}; Path=/", "Set-Cookie: [REDACTED]"),
+        ]
+        let argv = ["curl"] + headers.flatMap { ["--header", $0.0.replacingOccurrences(of: "{token}", with: token)] }
+            + ["--header", "Accept: application/json", "https://api.example.test/deploy"]
+        let command = argv.map { "\"\($0)\"" }.joined(separator: " ")
+        GateAudit.write(gate: "link-command", event: "prompted",
+                        ["argv": argv, "shown": ["facts": [["label": "Command", "help": command],
+                                                           ["label": "Unquoted command", "help": argv.joined(separator: " ")]]]])
+        let text = try String(contentsOfFile: GateAudit.path, encoding: .utf8)
+        XCTAssertFalse(text.contains(token))
+        // JSONSerialization writes "/" as "\/", so the safe header is checked in the parsed entry, not the raw line.
+        let entry = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(text.utf8)) as? [String: Any])
+        let written = try XCTUnwrap(entry["argv"] as? [String])
+        XCTAssertTrue(written.contains("Accept: application/json"))
+        for (_, expected) in headers { XCTAssertTrue(written.contains(expected), expected) }
+        let shown = try XCTUnwrap(entry["shown"] as? [String: Any])
+        let facts = try XCTUnwrap(shown["facts"] as? [[String: String]])
+        XCTAssertEqual(facts.count, 2)
+        for fact in facts {
+            let help = try XCTUnwrap(fact["help"])
+            XCTAssertTrue(help.contains("Accept: application/json"))
+            XCTAssertTrue(help.contains("Authorization: Bearer [REDACTED]"))
+        }
+    }
+
+    func testQuotedHeaderValuesAreRedactedInAccountCommandsAndShownFacts() throws {
+        let home = FileManager.default.temporaryDirectory.appendingPathComponent("gate-quoted-headers-\(UUID().uuidString)").path
+        setenv("GENESIS_TOOLS_HOME", home, 1)
+        defer { unsetenv("GENESIS_TOOLS_HOME"); try? FileManager.default.removeItem(atPath: home) }
+        let cookie = "fixture-cookie"
+        let bearer = "fixture-bearer"
+        for header in ["Cookie: session=\"\(cookie)\"", "Cookie: session='\(cookie)'", "X-Api-Key: \"\(cookie)\"",
+                       "Cookie: session=\"prefix --header \(cookie)\"", "Cookie: session=\"prefix Accept: \(cookie)\"",
+                       "Cookie: session= \" --header \(cookie)\""] {
+            let argv = ["curl", "--header", header, "--header", "Authorization: Bearer \(bearer)",
+                        "--header", "Accept: application/json", "https://api.example.test/deploy"]
+            let original = argv
+            let command = String((["bun", "/fixture/client.ts"] + Array(argv.dropFirst())).joined(separator: " ").prefix(200))
+            let shown = GateAudit.shown(title: "Account approval", purpose: "Read account", facts: [
+                ApprovalFact("Quoted command", argv.map { "\"\($0)\"" }.joined(separator: " ")),
+                ApprovalFact("Unquoted command", argv.joined(separator: " ")),
+                ApprovalFact("Mixed quoted command", "curl -H \"Cookie: session='\(cookie)'\" --header Authorization: Bearer \(bearer) --header Accept: application/json"),
+            ], warning: nil)
+            GateAudit.write(gate: "ai-account", event: "prompted", ["argv": argv, "client": ["command": command],
+                "command": command, "shown": shown,
+                "ambiguous": "bun --header Cookie: session=\"\(cookie) --header Accept: application/json"])
+            let text = try String(contentsOfFile: GateAudit.path, encoding: .utf8)
+            XCTAssertFalse(text.contains(cookie))
+            XCTAssertFalse(text.contains(bearer))
+            let line = try XCTUnwrap(text.split(separator: "\n").last)
+            let entry = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(line.utf8)) as? [String: Any])
+            let written = try XCTUnwrap(entry["argv"] as? [String])
+            XCTAssertTrue(written.contains("Accept: application/json"))
+            let client = try XCTUnwrap(entry["client"] as? [String: String])
+            let savedShown = try XCTUnwrap(entry["shown"] as? [String: Any])
+            let facts = try XCTUnwrap(savedShown["facts"] as? [[String: String]])
+            XCTAssertEqual(facts.count, 3)
+            let commands = [try XCTUnwrap(client["command"]), try XCTUnwrap(entry["command"] as? String)]
+                + facts.compactMap { $0["value"] }
+            for saved in commands {
+                XCTAssertFalse(saved.contains(cookie))
+                XCTAssertFalse(saved.contains(bearer))
+                XCTAssertTrue(saved.contains("Accept: application/json"))
+                XCTAssertTrue(saved.contains("Authorization: Bearer [REDACTED]"))
+            }
+            XCTAssertTrue((entry["ambiguous"] as? String)?.contains("[REDACTED]") == true)
+            XCTAssertEqual(argv, original)
+        }
+    }
+
+    func testQuotedShellHeaderBoundariesAndEqualsFlags() throws {
+        let secret = "fixture-cookie-r5"
+        let safe = "Accept: application/json"
+        var commands = [
+            "curl -H \"Cookie: session=\(secret)\" -H \"\(safe)\"",
+            "curl -H \"Cookie: session=\(secret)\" -H \"Authorization: Bearer \(secret)\" -H \"\(safe)\"",
+            "curl -H \"Cookie: session='\(secret)'\" -H \"\(safe)\"",
+            "curl --header Cookie: session=\"prefix --header \(secret)\" --header \(safe)",
+        ]
+        for flag in ["--header", "-H"] {
+            for header in ["Authorization: Bearer \(secret)", "Proxy-Authorization: Basic \(secret)",
+                           "Cookie: session='\(secret)'", "X-Api-Key:\(secret)"] {
+                let argv = ["wget", "\(flag)=\(header)", "\(flag)=\(safe)"]
+                let original = argv
+                let sanitized = GateCredentialRedactor.arguments(argv).joined(separator: " ")
+                XCTAssertFalse(sanitized.contains(secret))
+                XCTAssertTrue(sanitized.contains(safe))
+                XCTAssertEqual(argv, original)
+                commands += [argv.joined(separator: " "), argv.map { "\"\($0)\"" }.joined(separator: " ")]
+            }
+        }
+        let home = FileManager.default.temporaryDirectory.appendingPathComponent("gate-r5-\(UUID().uuidString)").path
+        setenv("GENESIS_TOOLS_HOME", home, 1)
+        defer { unsetenv("GENESIS_TOOLS_HOME"); try? FileManager.default.removeItem(atPath: home) }
+        for command in commands {
+            GateAudit.write(gate: "ai-account", event: "prompted", ["command": command])
+            let lines = try String(contentsOfFile: GateAudit.path, encoding: .utf8).split(separator: "\n")
+            let line = try XCTUnwrap(lines.last)
+            let entry = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(line.utf8)) as? [String: Any])
+            let saved = try XCTUnwrap(entry["command"] as? String)
+            XCTAssertFalse(saved.contains(secret), command)
+            XCTAssertTrue(saved.contains(safe), command)
+            if command.contains("Authorization: Bearer") {
+                XCTAssertTrue(saved.contains("Authorization: Bearer [REDACTED]"), command)
+            }
+        }
+    }
+
+    func testCredentialFlagValuesConsumeEscapedQuotesAndMalformedRemainders() throws {
+        let secret = "fixture-secret-suffix-r6"
+        let home = FileManager.default.temporaryDirectory.appendingPathComponent("gate-flags-r6-\(UUID().uuidString)").path
+        setenv("GENESIS_TOOLS_HOME", home, 1)
+        defer { unsetenv("GENESIS_TOOLS_HOME"); try? FileManager.default.removeItem(atPath: home) }
+        for flag in ["--token", "--api-key", "--key", "--password", "--secret"] {
+            for separator in [" ", "="] {
+                for quote in ["\"", "'"] {
+                    let value = [quote, "prefix\\", quote, secret, quote].joined()
+                    let input = ["tools claude", flag + separator + value, "--format json"].joined(separator: " ")
+                    let expected = ["tools claude", flag + separator + "[REDACTED]", "--format json"].joined(separator: " ")
+                    XCTAssertEqual(GateCredentialRedactor.text(input), expected)
+                    let unfinished = ["tools claude", flag + separator + String(value.dropLast()), "--format json\\"].joined(separator: " ")
+                    XCTAssertEqual(GateCredentialRedactor.text(unfinished),
+                                   ["tools claude", flag + separator + "[REDACTED]"].joined(separator: " "))
+                    GateAudit.write(gate: "vault", event: "prompted", ["command": input, "shown": [["help": input]]])
+                    let text = try String(contentsOfFile: GateAudit.path, encoding: .utf8)
+                    XCTAssertFalse(text.contains(secret))
+                    let line = try XCTUnwrap(text.split(separator: "\n").last)
+                    let entry = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(line.utf8)) as? [String: Any])
+                    XCTAssertEqual(entry["command"] as? String, expected)
+                    let shown = try XCTUnwrap(entry["shown"] as? [[String: String]])
+                    XCTAssertEqual(shown.first?["help"], expected)
+                }
+            }
+        }
+        let relay = ["tools wakeup daemon register -t \"prefix\\\"", secret, "\" --format json"].joined()
+        XCTAssertEqual(GateCredentialRedactor.text(relay), "tools wakeup daemon register -t [REDACTED] --format json")
+        XCTAssertEqual(GateCredentialRedactor.text("tools claude tail -t \"safe\\\"value\""),
+                       "tools claude tail -t \"safe\\\"value\"")
+    }
+
+    func testHeaderNewlinesUseCodeUnitsAndLongRunsAreLinear() {
+        let safe = "Accept: application/json"
+        for newline in ["\r", "\n", "\r\n"] {
+            XCTAssertEqual(GateCredentialRedactor.text("Cookie: session=🔒fixture-cookie-r5\(newline)\(safe)"),
+                           "Cookie: [REDACTED]\(newline)\(safe)")
+        }
+        let started = Date()
+        for value in ["x" + String(repeating: " ", count: 131_072) + "!", String(repeating: "\"x\"", count: 43_691)] {
+            XCTAssertEqual(GateCredentialRedactor.text("curl --header Cookie: \(value)"), "curl --header Cookie: [REDACTED]")
+        }
+        XCTAssertLessThan(Date().timeIntervalSince(started), 2)
+    }
+
+    func testAuditURLsRedactUserinfoQueryCredentialsAndEncodedPrompts() throws {
+        let home = FileManager.default.temporaryDirectory.appendingPathComponent("gate-url-\(UUID().uuidString)").path
+        setenv("GENESIS_TOOLS_HOME", home, 1)
+        defer { unsetenv("GENESIS_TOOLS_HOME"); try? FileManager.default.removeItem(atPath: home) }
+        let token = "fixture'url-secret"
+        var link = URLComponents(string: "https://example.com/run")!
+        link.user = "fixture-user"
+        link.password = token
+        link.queryItems = [URLQueryItem(name: "token", value: token), URLQueryItem(name: "api_key", value: token),
+                           URLQueryItem(name: "prompt", value: "tools claude --token \(token)"), URLQueryItem(name: "safe", value: "kept")]
+        let url = try XCTUnwrap(link.string)
+        var nested = URLComponents(string: "https://example.com/open")!
+        nested.queryItems = [URLQueryItem(name: "next", value: url)]
+        var callback = URLComponents(string: "genesis://oauth/callback")!
+        var fragment = URLComponents()
+        fragment.queryItems = [URLQueryItem(name: "access_token", value: token), URLQueryItem(name: "state", value: "kept-state")]
+        callback.percentEncodedFragment = fragment.percentEncodedQuery
+        GateAudit.write(gate: "link-command", event: "denied",
+                        ["link": url, "url": try XCTUnwrap(nested.string), "open": [url, try XCTUnwrap(callback.string)]])
+        let text = try String(contentsOfFile: GateAudit.path, encoding: .utf8)
+        XCTAssertFalse(text.contains(token))
+        XCTAssertFalse(text.contains("fixture-user"))
+        XCTAssertFalse(text.contains("url-secret"))
+        XCTAssertTrue(text.contains("safe=kept"))
+        XCTAssertTrue(text.contains("state=kept-state"))
+        XCTAssertTrue(text.contains("example.com"))
+        XCTAssertTrue(text.contains("REDACTED"))
+    }
+
+    func testConcurrentProcessesAppendWithoutOverwritingDecisions() throws {
+        let home = FileManager.default.temporaryDirectory.appendingPathComponent("gate-append-\(UUID().uuidString)").path
+        setenv("GENESIS_TOOLS_HOME", home, 1)
+        defer { unsetenv("GENESIS_TOOLS_HOME"); try? FileManager.default.removeItem(atPath: home) }
+        let path = GateAudit.path
+        try FileManager.default.createDirectory(atPath: (path as NSString).deletingLastPathComponent, withIntermediateDirectories: true)
+        let writers = (0..<4).map { index -> Process in
+            let process = Process()
+            process.executableURL = URL(fileURLWithPath: "/bin/sh")
+            process.arguments = ["-c", #"i=0; while [ "$i" -lt 200 ]; do printf '{"external":%s,"i":%s}\n' "$1" "$i" >> "$2"; i=$((i+1)); done"#, "audit-writer", "\(index)", path]
+            return process
+        }
+        let completed = expectation(description: "external audit writers finished")
+        completed.expectedFulfillmentCount = writers.count
+        for writer in writers {
+            writer.terminationHandler = { _ in completed.fulfill() }
+            try writer.run()
+        }
+        for index in 0..<200 { GateAudit.write(gate: "test", event: "allowed", ["i": index]) }
+        wait(for: [completed], timeout: 10)
+        for writer in writers { XCTAssertEqual(writer.terminationStatus, 0) }
+        let lines = try String(contentsOfFile: path, encoding: .utf8).split(separator: "\n")
+        XCTAssertEqual(lines.count, 1_000)
+        for line in lines { XCTAssertNoThrow(try JSONSerialization.jsonObject(with: Data(line.utf8))) }
+    }
+
     func testALineCarriesTheGateTheEventTheWriterAndWhatTheWindowShowed() throws {
         let home = FileManager.default.temporaryDirectory.appendingPathComponent("gate-audit-\(UUID().uuidString)").path
         setenv("GENESIS_TOOLS_HOME", home, 1)
diff --git a/src/macos/GenesisTools/Sources/VaultRecipient.swift b/src/macos/GenesisTools/Sources/VaultRecipient.swift
new file mode 100644
index 0000000000..133aa6ec6c
--- /dev/null
+++ b/src/macos/GenesisTools/Sources/VaultRecipient.swift
@@ -0,0 +1,233 @@
+import Darwin
+import Foundation
+
+/// A release-time snapshot, not an atomic transport authentication: libproc cannot prevent a holder
+/// from forking or passing an fd after inspection. Unknown or incomplete observations deny release,
+/// except confirmed exits and EPERM on the fd tables of protected system executables. A holder that
+/// execs into such a binary while keeping the read end is not seen. That exception trusts the system
+/// binary's code not to relay the bytes; it does not prove the read end was closed.
+enum VaultRecipient {
+    struct Identity: Equatable {
+        var pid: pid_t
+        var startSeconds: UInt64
+        var startMicroseconds: UInt64
+        var executable: String
+    }
+
+    enum Endpoint: Equatable {
+        case pipe(handle: UInt64, peer: UInt64)
+        case socket(pcb: UInt64, peer: UInt64)
+        case other
+
+        var connected: Bool {
+            switch self {
+            case let .pipe(handle, peer), let .socket(handle, peer):
+                return handle != 0 && peer != 0 && handle != peer
+            case .other:
+                return false
+            }
+        }
+
+        func isPeer(of output: Endpoint) -> Bool {
+            switch (self, output) {
+            case let (.pipe(handle, peer), .pipe(outputHandle, outputPeer)),
+                 let (.socket(handle, peer), .socket(outputHandle, outputPeer)):
+                return handle == outputPeer && peer == outputHandle
+            default:
+                return false
+            }
+        }
+    }
+
+    enum ReadFailure {
+        case exited
+        case unavailable(code: Int32, executable: String?)
+
+        var maySkip: Bool {
+            switch self {
+            case .exited:
+                return true
+            case let .unavailable(code, executable):
+                // /System/Volumes/Data is the user's writable data volume, not the sealed system volume.
+                guard code == EPERM, let executable,
+                      executable == (executable as NSString).standardizingPath,
+                      !executable.hasPrefix("/System/Volumes/") else { return false }
+                return ["/usr/bin/", "/usr/sbin/", "/usr/libexec/", "/bin/", "/sbin/", "/System/"]
+                    .contains { executable.hasPrefix($0) }
+            }
+        }
+    }
+
+    struct ProcessFDs {
+        var pid: pid_t
+        /// nil means the table, or any relevant descriptor in it, could not be read completely.
+        var endpoints: [Endpoint]?
+        var failure: ReadFailure? = nil
+
+        var maySkip: Bool { endpoints == nil && failure?.maySkip == true }
+    }
+
+    static func rejection(stdout: Endpoint, caller: Identity?, current: Identity?, processes: [ProcessFDs]) -> String? {
+        guard stdout.connected else { return "vault stdout must be a connected pipe or Unix-domain socket" }
+        guard let caller, let current else { return "the caller's process identity could not be read" }
+        guard current == caller else { return "the caller's process instance or executable changed before key release" }
+        guard processes.allSatisfy({ $0.endpoints != nil || $0.maySkip }) else {
+            return "the vault recipient could not be verified because a process fd table was unreadable"
+        }
+        let holders = Set(processes.filter { process in
+            process.endpoints?.contains(where: { $0.isPeer(of: stdout) }) == true
+        }.map(\.pid))
+        guard holders.subtracting([caller.pid]).isEmpty else { return "another process holds the output" }
+        guard holders == Set([caller.pid]) else {
+            return "the verified caller must be the sole holder of vault stdout's other end"
+        }
+        return nil
+    }
+
+    static func identity(_ pid: pid_t) -> Identity? {
+        var info = proc_bsdinfo()
+        let size = Int32(MemoryLayout<proc_bsdinfo>.stride)
+        guard proc_pidinfo(pid, PROC_PIDTBSDINFO, 0, &info, size) == size,
+              info.pbi_pid == UInt32(pid), info.pbi_start_tvsec != 0 else { return nil }
+        var buffer = [CChar](repeating: 0, count: 4 * Int(MAXPATHLEN))
+        guard proc_pidpath(pid, &buffer, UInt32(buffer.count)) > 0 else { return nil }
+        return Identity(pid: pid, startSeconds: info.pbi_start_tvsec, startMicroseconds: info.pbi_start_tvusec,
+                        executable: String(cString: buffer))
+    }
+
+    private struct InspectionFailure: Error {
+        var reason: String
+        var code: Int32 = 0
+        var fdTable: Bool = false
+    }
+
+    private static func hasExited(_ pid: pid_t) -> Bool {
+        kill(pid, 0) == -1 && errno == ESRCH
+    }
+
+    private static func executablePath(_ pid: pid_t) -> String? {
+        var buffer = [CChar](repeating: 0, count: 4 * Int(MAXPATHLEN))
+        guard proc_pidpath(pid, &buffer, UInt32(buffer.count)) > 0 else { return nil }
+        return String(cString: buffer)
+    }
+
+    private static func pids(kind: UInt32, uid: uid_t) throws -> Set<pid_t> {
+        let needed = proc_listpids(kind, uid, nil, 0)
+        guard needed > 0 else { throw InspectionFailure(reason: "the user's process list could not be read") }
+        var buffer = [pid_t](repeating: 0, count: Int(needed) / MemoryLayout<pid_t>.stride + 128)
+        let capacity = Int32(buffer.count * MemoryLayout<pid_t>.stride)
+        let bytes = buffer.withUnsafeMutableBytes { proc_listpids(kind, uid, $0.baseAddress, capacity) }
+        guard bytes > 0, bytes < capacity, Int(bytes) % MemoryLayout<pid_t>.stride == 0 else {
+            throw InspectionFailure(reason: "the user's process list was incomplete")
+        }
+        return Set(buffer.prefix(Int(bytes) / MemoryLayout<pid_t>.stride).filter { $0 > 0 })
+    }
+
+    private static func userPids() throws -> Set<pid_t> {
+        // Include processes with this real uid even if their effective uid has changed.
+        try pids(kind: UInt32(PROC_UID_ONLY), uid: getuid())
+            .union(pids(kind: UInt32(PROC_RUID_ONLY), uid: getuid()))
+    }
+
+    private static func descriptors(_ pid: pid_t) throws -> [proc_fdinfo] {
+        errno = 0
+        let needed = proc_pidinfo(pid, PROC_PIDLISTFDS, 0, nil, 0)
+        let sizeError = errno
+        guard needed >= 0, sizeError == 0 else {
+            throw InspectionFailure(reason: "the fd table for process \(pid) could not be read", code: sizeError, fdTable: true)
+        }
+        let stride = MemoryLayout<proc_fdinfo>.stride
+        var buffer = [proc_fdinfo](repeating: proc_fdinfo(), count: Int(needed) / stride + 32)
+        let capacity = Int32(buffer.count * stride)
+        errno = 0
+        let bytes = buffer.withUnsafeMutableBytes { proc_pidinfo(pid, PROC_PIDLISTFDS, 0, $0.baseAddress, capacity) }
+        let readError = errno
+        guard bytes >= 0, readError == 0, bytes < capacity, Int(bytes) % stride == 0 else {
+            throw InspectionFailure(reason: "the fd table for process \(pid) was incomplete", code: readError, fdTable: true)
+        }
+        return Array(buffer.prefix(Int(bytes) / stride))
+    }
+
+    private static func endpoint(_ pid: pid_t, fd: Int32, type: UInt32) throws -> Endpoint {
+        if type == UInt32(PROX_FDTYPE_PIPE) {
+            var info = pipe_fdinfo()
+            let size = Int32(MemoryLayout<pipe_fdinfo>.stride)
+            guard proc_pidfdinfo(pid, fd, PROC_PIDFDPIPEINFO, &info, size) == size else {
+                throw InspectionFailure(reason: "pipe \(fd) of process \(pid) could not be inspected", code: errno)
+            }
+            return .pipe(handle: info.pipeinfo.pipe_handle, peer: info.pipeinfo.pipe_peerhandle)
+        }
+        if type == UInt32(PROX_FDTYPE_SOCKET) {
+            var info = socket_fdinfo()
+            let size = Int32(MemoryLayout<socket_fdinfo>.stride)
+            guard proc_pidfdinfo(pid, fd, PROC_PIDFDSOCKETINFO, &info, size) == size else {
+                throw InspectionFailure(reason: "socket \(fd) of process \(pid) could not be inspected", code: errno)
+            }
+            guard info.psi.soi_family == AF_UNIX, info.psi.soi_kind == SOCKINFO_UN else { return .other }
+            return .socket(pcb: info.psi.soi_pcb, peer: info.psi.soi_proto.pri_un.unsi_conn_pcb)
+        }
+        return .other
+    }
+
+    private static func stdoutEndpoint() throws -> Endpoint {
+        var status = stat()
+        guard fstat(STDOUT_FILENO, &status) == 0 else {
+            throw InspectionFailure(reason: "vault stdout could not be inspected")
+        }
+        switch status.st_mode & mode_t(S_IFMT) {
+        case mode_t(S_IFIFO):
+            return try endpoint(getpid(), fd: STDOUT_FILENO, type: UInt32(PROX_FDTYPE_PIPE))
+        case mode_t(S_IFSOCK):
+            return try endpoint(getpid(), fd: STDOUT_FILENO, type: UInt32(PROX_FDTYPE_SOCKET))
+        default:
+            return .other
+        }
+    }
+
+    private static func processFDs(_ pid: pid_t, output: Endpoint) -> ProcessFDs {
+        do {
+            let fds = try descriptors(pid)
+            var endpoints: [Endpoint] = []
+            for fd in fds {
+                switch (output, fd.proc_fdtype) {
+                case (.pipe, UInt32(PROX_FDTYPE_PIPE)), (.socket, UInt32(PROX_FDTYPE_SOCKET)):
+                    endpoints.append(try endpoint(pid, fd: fd.proc_fd, type: fd.proc_fdtype))
+                default:
+                    break
+                }
+            }
+            return ProcessFDs(pid: pid, endpoints: endpoints)
+        } catch let error as InspectionFailure {
+            if error.code == ESRCH || hasExited(pid) {
+                return ProcessFDs(pid: pid, endpoints: nil, failure: .exited)
+            }
+            // Only a refused fd TABLE qualifies for the protected-system exception. A descriptor
+            // changing or becoming unreadable inside an otherwise readable table still denies release.
+            let failure: ReadFailure? = error.fdTable
+                ? .unavailable(code: error.code, executable: executablePath(pid)) : nil
+            return ProcessFDs(pid: pid, endpoints: nil, failure: failure)
+        } catch {
+            return ProcessFDs(pid: pid, endpoints: nil, failure: hasExited(pid) ? .exited : nil)
+        }
+    }
+
+    static func releaseRejection(caller: Identity?) -> String? {
+        do {
+            let output = try stdoutEndpoint()
+            guard output.connected else { return "vault stdout must be a connected pipe or Unix-domain socket" }
+            let pids = try userPids()
+            let tables = pids.sorted().map { processFDs($0, output: output) }
+            let currentPids = try userPids()
+            // Exits cannot introduce a new reader; new processes or uid changes still require a fresh request.
+            guard currentPids.isSubset(of: pids), pids.subtracting(currentPids).allSatisfy(hasExited) else {
+                return "the user's process list changed during vault recipient inspection"
+            }
+            guard try stdoutEndpoint() == output else { return "vault stdout changed during recipient inspection" }
+            return rejection(stdout: output, caller: caller, current: caller.flatMap { identity($0.pid) }, processes: tables)
+        } catch let error as InspectionFailure {
+            return error.reason
+        } catch {
+            return "the vault recipient could not be inspected"
+        }
+    }
+}
diff --git a/src/macos/GenesisTools/Sources/VaultUnlock.swift b/src/macos/GenesisTools/Sources/VaultUnlock.swift
index b6c6e796d0..aec54cdc97 100644
--- a/src/macos/GenesisTools/Sources/VaultUnlock.swift
+++ b/src/macos/GenesisTools/Sources/VaultUnlock.swift
@@ -49,6 +49,7 @@ struct VaultCaller {
     var args: ProcArgs?
     var cwd: String?
     var ancestors: [(pid: pid_t, command: String)]
+    var identity: VaultRecipient.Identity? = nil
 
     private static let scriptExtensions = [".ts", ".tsx", ".js", ".mjs", ".cjs"]
 
@@ -65,14 +66,24 @@ struct VaultCaller {
         "src/utils/bun/preload-orphan-watchdog.ts",
     ]
 
+    private var supportsRunSubcommand: Bool {
+        let name = executable.map { ($0 as NSString).lastPathComponent.lowercased() } ?? ""
+        return ["bun", "deno"].contains(name) || name.hasPrefix("gt-")
+    }
+
     /// The interpreter's flags before the script, each with its value (`--preload=x` or `--preload x`).
     private var leadingFlags: [(flag: String, value: String?)] {
         guard let arguments = args?.arguments, arguments.count > 1 else { return [] }
         var flags: [(flag: String, value: String?)] = []
         var index = 1
+        var skippedRun = false
         while index < arguments.count {
             let argument = arguments[index]
-            if argument == "run" { index += 1; continue }
+            if supportsRunSubcommand, !skippedRun, argument == "run" {
+                skippedRun = true
+                index += 1
+                continue
+            }
             guard argument.hasPrefix("-") else { break }
             if let equals = argument.firstIndex(of: "=") {
                 flags.append((String(argument[..<equals]), String(argument[argument.index(after: equals)...])))
@@ -93,9 +104,14 @@ struct VaultCaller {
     private var scriptIndex: Int? {
         guard let arguments = args?.arguments, arguments.count > 1 else { return nil }
         var index = 1
+        var skippedRun = false
         while index < arguments.count {
             let argument = arguments[index]
-            if argument == "run" { index += 1; continue }
+            if supportsRunSubcommand, !skippedRun, argument == "run" {
+                skippedRun = true
+                index += 1
+                continue
+            }
             guard argument.hasPrefix("-") else { break }
             index += !argument.contains("=") && Self.valueFlags.contains(argument) ? 2 : 1
         }
@@ -115,16 +131,21 @@ struct VaultCaller {
         return ((cwd as NSString).appendingPathComponent(raw) as NSString).standardizingPath
     }
 
-    /// bun, node, deno, or a `gt-<tool>` link of bun: the program is the script, not the executable.
-    var isInterpreter: Bool {
-        let name = executable.map { ($0 as NSString).lastPathComponent } ?? ""
-        return ["bun", "node", "deno"].contains(name) || name.hasPrefix("gt-")
+    static func isInterpreter(_ executable: String) -> Bool {
+        let name = (executable as NSString).lastPathComponent.lowercased()
+        return name.hasPrefix("gt-") || name.range(of:
+            #"^(node|nodejs|bun|deno|python[0-9.]*|pypy[0-9.]*|ruby[0-9.]*|perl[0-9.]*|php[0-9.]*|lua[0-9.]*|luajit|tclsh[0-9.]*|wish|osascript|java|pwsh|sh|bash|zsh|fish|dash|ksh|mksh|tcsh|csh)$"#,
+            options: .regularExpression) != nil
     }
 
+    /// An interpreter's executable alone never identifies the program it runs.
+    var isInterpreter: Bool { executable.map(Self.isInterpreter) ?? false }
+
     /// The tool as GenesisTools names it, from the kernel's view: `src/<tool>/` in the script, else the `gt-<tool>` link.
     var toolName: String? {
-        if let script, let range = script.range(of: #"/src/([^/]+)/"#, options: .regularExpression) {
-            return String(script[range].dropFirst(5).dropLast())
+        if let script, let range = script.range(of: "/src/", options: .backwards),
+           let slash = script[range.upperBound...].firstIndex(of: "/") {
+            return String(script[range.upperBound..<slash])
         }
 
         let name = executable.map { ($0 as NSString).lastPathComponent } ?? ""
@@ -134,24 +155,23 @@ struct VaultCaller {
     /// Flags and environment that load code the script path does not name. Any of them: no remembered approval.
     var injected: [String] {
         var found: [String] = []
-        let environment = args?.environmentValue
-        if let value = environment?("DYLD_INSERT_LIBRARIES"), !value.isEmpty {
-            found.append("DYLD_INSERT_LIBRARIES")
-        }
-
-        for name in ["NODE_OPTIONS", "BUN_OPTIONS"] {
-            if let value = environment?(name), ["--require", "-r ", "--import", "--loader", "--preload"].contains(where: value.contains) {
-                found.append(name)
-            }
+        let loaderEnvironment = ["LD_PRELOAD", "LD_LIBRARY_PATH", "DYLD_INSERT_LIBRARIES", "DYLD_LIBRARY_PATH", "DYLD_FRAMEWORK_PATH"]
+        let interpreterEnvironment = [
+            "NODE_OPTIONS", "NODE_PATH", "BUN_OPTIONS", "BUN_INSPECT_PRELOAD", "DENO_AUTH_TOKENS",
+            "PYTHONSTARTUP", "PYTHONPATH", "PYTHONHOME", "RUBYOPT", "RUBYLIB", "PERL5OPT", "PERL5LIB", "PERLLIB",
+            "BASH_ENV", "ZDOTDIR", "ENV",
+        ]
+        for name in loaderEnvironment + (isInterpreter ? interpreterEnvironment : []) {
+            if args?.environmentValue(name) != nil { found.append(name) }
         }
 
         // A checkout's own preloads are part of the program; any other preload, or any other loading flag, is not.
-        let checkout = script.flatMap { path in path.range(of: "/src/").map { String(path[..<$0.lowerBound]) } }
+        let checkout = script.flatMap { path in path.range(of: "/src/", options: .backwards).map { String(path[..<$0.lowerBound]) } }
         let own = Set(Self.ownPreloads.compactMap { relative in checkout.map { root in "\(root)/\(relative)" } })
         let foreign = leadingFlags.filter { flag in
             !(flag.flag == "--preload" && flag.value.map { value in own.contains((value as NSString).standardizingPath) } == true)
         }
-        if foreign.contains(where: { ["--preload", "-r", "--require", "--import", "--loader"].contains($0.flag) }) {
+        if !foreign.isEmpty {
             let shown = foreign.map { flag in flag.value.map { value in "\(flag.flag) \(value)" } ?? flag.flag }
             found.append("interpreter flags \(shown.joined(separator: " "))")
         }
@@ -161,6 +181,7 @@ struct VaultCaller {
 
     /// Why this request can only be allowed once, or nil when an allow may be remembered.
     var onceOnlyReason: String? {
+        if args == nil { return "the caller's arguments and environment could not be read" }
         if !injected.isEmpty { return "extra code may be loaded" }
         if isInterpreter, script == nil { return "the script it runs is not known" }
         return nil
@@ -245,6 +266,7 @@ enum VaultProcess {
     }
 
     static func caller(_ pid: pid_t) -> VaultCaller {
+        let identity = VaultRecipient.identity(pid)
         var ancestors: [(pid: pid_t, command: String)] = []
         var current = parent(pid)
         while let ancestor = current, ancestor > 1, ancestors.count < 8 {
@@ -252,7 +274,10 @@ enum VaultProcess {
             current = parent(ancestor)
         }
 
-        return VaultCaller(pid: pid, executable: path(pid), args: procArgs(pid), cwd: cwd(pid), ancestors: ancestors)
+        var caller = VaultCaller(pid: pid, executable: identity?.executable, args: procArgs(pid), cwd: cwd(pid), ancestors: ancestors)
+        // Bracket the caller metadata reads so a changed process cannot inherit this approval snapshot.
+        if identity == VaultRecipient.identity(pid) { caller.identity = identity }
+        return caller
     }
 }
 
@@ -345,8 +370,7 @@ struct VaultGrant: Codable, Equatable {
     /// grants for `bun run <script>` callers. They match nothing and go on the next write.
     var isTooBroad: Bool {
         guard script == nil else { return false }
-        let name = (executable as NSString).lastPathComponent
-        return ["bun", "node", "deno"].contains(name) || name.hasPrefix("gt-")
+        return VaultCaller.isInterpreter(executable)
     }
 }
 
@@ -411,14 +435,43 @@ enum VaultGrants {
         return next
     }
 
-    static func save(_ file: VaultGrantsFile, to path: String = path) {
+    /// The TypeScript revoker uses O_EXCL at this same path and understands a bare PID record. Its proper-lockfile
+    /// claim arbiter is a directory with the suffix below; hold it while creating the PID record and updating.
+    /// Never steal here: TypeScript owns stale recovery; an unavailable lock makes this allow once-only.
+    static func store(_ grant: VaultGrant, now: Int64, to path: String = path, timeout: TimeInterval = 10) async -> Bool {
+        let lockPath = path + ".lock"
+        do {
+            try FileManager.default.createDirectory(atPath: (path as NSString).deletingLastPathComponent,
+                                                    withIntermediateDirectories: true, attributes: [.posixPermissions: 0o700])
+        } catch { return false }
+        let deadline = Date().addingTimeInterval(timeout)
+        let arbiter = lockPath + ".claim-arbitration.lock"
+        while true {
+            if mkdir(arbiter, 0o700) == 0 {
+                defer { rmdir(arbiter) }
+                let fd = open(lockPath, O_WRONLY | O_CREAT | O_EXCL, 0o600)
+                if fd >= 0 {
+                    defer { close(fd); unlink(lockPath) }
+                    let pid = Data("\(getpid())\n".utf8)
+                    guard pid.withUnsafeBytes({ Darwin.write(fd, $0.baseAddress, $0.count) }) == pid.count else { return false }
+                    return save(remember(grant, now: now, in: load(from: path)), to: path)
+                }
+                guard errno == EEXIST else { return false }
+            } else if errno != EEXIST { return false }
+            guard Date() < deadline else { return false }
+            do { try await Task.sleep(nanoseconds: 100_000_000) } catch { return false }
+        }
+    }
+
+    @discardableResult
+    static func save(_ file: VaultGrantsFile, to path: String = path) -> Bool {
         let encoder = JSONEncoder()
         encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
-        guard let data = try? encoder.encode(file) else { return }
+        guard let data = try? encoder.encode(file) else { return false }
         try? FileManager.default.createDirectory(atPath: (path as NSString).deletingLastPathComponent, withIntermediateDirectories: true)
         let temporary = path + ".tmp-\(getpid())"
-        guard FileManager.default.createFile(atPath: temporary, contents: data, attributes: [.posixPermissions: 0o600]) else { return }
-        _ = rename(temporary, path)
+        guard FileManager.default.createFile(atPath: temporary, contents: data, attributes: [.posixPermissions: 0o600]) else { return false }
+        return rename(temporary, path) == 0
     }
 }
 
@@ -469,7 +522,7 @@ struct VaultWindowContent {
     /// A script inside a project reads from the project's folder: `GenesisTools/src/ai/commands/usage/poll-daemon.ts`,
     /// not a home path cut in the middle (Martin's screenshot, 2026-10-15 00:46).
     static func programPath(_ path: String, home: String = NSHomeDirectory()) -> String {
-        guard let range = path.range(of: "/src/") else { return shortPath(path, home: home) }
+        guard let range = path.range(of: "/src/", options: .backwards) else { return shortPath(path, home: home) }
         let project = (String(path[..<range.lowerBound]) as NSString).lastPathComponent
         return project.isEmpty ? shortPath(path, home: home) : project + path[range.lowerBound...]
     }
@@ -513,7 +566,7 @@ struct VaultWindowContent {
         var details = [ApprovalFact("Process", "pid \(caller.pid)"),
                        ApprovalFact("Executable", caller.executable ?? "unknown", monospaced: true)]
         if let arguments = caller.args?.arguments, !arguments.isEmpty {
-            let command = arguments.joined(separator: " ")
+            let command = GateCredentialRedactor.arguments(arguments).joined(separator: " ")
             details.append(ApprovalFact("Command", command.count > 400 ? String(command.prefix(399)) + "…" : command,
                                         help: command, monospaced: true))
         }
@@ -533,7 +586,7 @@ struct VaultWindowContent {
         let injected = caller.injected
         return VaultWindowContent(
             title: "“\(tool)” wants the vault key",
-            purpose: sentence(params.purpose),
+            purpose: sentence(GateCredentialRedactor.text(params.purpose)),
             facts: facts,
             details: details,
             warning: injected.isEmpty ? nil : "Extra code may be loaded (\(injected.joined(separator: ", "))). It can only be allowed once.",
@@ -628,7 +681,7 @@ enum VaultKeychain {
 /// Every request's line in `audit.jsonl` carries what decides it (the command, its parents, the folder, any loaded-code
 /// signal, why it is once-only) and, for `prompted`, everything the window showed, warnings included: an approval can
 /// be audited later from the file alone (Martin, 2026-10-16).
-private func vaultAudit(_ event: String, params: VaultUnlockParams, caller: VaultCaller, session: VaultSessionInfo, detail: String = "",
+func vaultAudit(_ event: String, params: VaultUnlockParams, caller: VaultCaller, session: VaultSessionInfo, detail: String = "",
                         shown: VaultWindowContent? = nil) {
     var parts = ["purpose: \(params.purpose)"]
     if let secret = params.secret { parts.append("secret: \(secret)") }
@@ -640,7 +693,7 @@ private func vaultAudit(_ event: String, params: VaultUnlockParams, caller: Vaul
     client["executable"] = caller.executable
     client["script"] = caller.script
     client["cwd"] = caller.cwd
-    client["argv"] = caller.args?.arguments
+    client["argv"] = caller.args.map { GateCredentialRedactor.arguments($0.arguments) }
     client["parents"] = caller.ancestors.map { ["pid": Int($0.pid), "command": $0.command] }
     client["injected"] = caller.injected
 
@@ -661,24 +714,22 @@ private func vaultAudit(_ event: String, params: VaultUnlockParams, caller: Vaul
             "onceOnly": shown.onceOnlyReason as Any,
         ]
     }
+    entry = entry.mapValues(GateCredentialRedactor.fields)
     GateAudit.write(gate: "vault", event: event, entry)
     guard let data = try? JSONSerialization.data(withJSONObject: entry, options: [.sortedKeys]) else { return }
     let path = (VaultGrants.directory as NSString).appendingPathComponent("audit.jsonl")
-    try? FileManager.default.createDirectory(atPath: VaultGrants.directory, withIntermediateDirectories: true)
-    if !FileManager.default.fileExists(atPath: path) {
-        FileManager.default.createFile(atPath: path, contents: nil, attributes: [.posixPermissions: 0o600])
-    }
-
-    guard let handle = FileHandle(forWritingAtPath: path) else { return }
-    defer { try? handle.close() }
-    _ = try? handle.seekToEnd()
-    try? handle.write(contentsOf: data + Data("\n".utf8))
+    GateAudit.appendLine(data, to: path)
 }
 
-private func emitVaultKey(remembered: Bool) -> Never {
+private func emitVaultKey(remembered: Bool, params: VaultUnlockParams, caller: VaultCaller, session: VaultSessionInfo) -> Never {
     switch VaultKeychain.key() {
     case let .key(key, fromCopy):
         logClick("vault.unlock key from=\(fromCopy ? "app copy" : "keychain item")")
+        // Keychain access can block: inspect the recipient after it finishes, immediately before serialization.
+        if let reason = VaultRecipient.releaseRejection(caller: caller.identity) {
+            vaultAudit("denied", params: params, caller: caller, session: session, detail: reason)
+            vaultDeny(reason)
+        }
         emitResult(["decision": "allow", "key": key, "remembered": remembered])
     case .missing:
         emitError(code: "no_key", message: "the keychain holds no genesis-tools master key", exitCode: 66)
@@ -709,7 +760,7 @@ func unlockVault(_ params: VaultUnlockParams) {
 
     if rememberable, VaultGrants.live(executable: executable, script: caller.script, now: now, in: VaultGrants.load()) != nil {
         vaultAudit("remembered", params: params, caller: caller, session: session)
-        emitVaultKey(remembered: true)
+        emitVaultKey(remembered: true, params: params, caller: caller, session: session)
     }
 
     guard VaultWindowLock.acquire(VaultWindowLock.path(for: "vault|\(VaultGrants.runtime(of: executable))|\(caller.script ?? "")")) != nil else {
@@ -756,18 +807,22 @@ func unlockVault(_ params: VaultUnlockParams) {
                         vaultDeny(failure)
                     }
 
-                    let forever = rememberable && choice != nil && choice?.seconds == nil
-                    if rememberable, remember != 0 || forever {
-                        let until = forever ? nil : Optional(now + Int64(remember) * 1_000)
-                        let grant = VaultGrant(key: key, tool: tool, executable: executable, script: caller.script,
-                                               grantedAt: now, until: until, method: method)
-                        VaultGrants.save(VaultGrants.remember(grant, now: now, in: VaultGrants.load()))
+                    Task { @MainActor in
+                        let forever = rememberable && choice != nil && choice?.seconds == nil
+                        var stored = false
+                        if rememberable, remember != 0 || forever {
+                            let until = forever ? nil : Optional(now + Int64(remember) * 1_000)
+                            let grant = VaultGrant(key: key, tool: tool, executable: executable, script: caller.script,
+                                                   grantedAt: now, until: until, method: method)
+                            stored = await VaultGrants.store(grant, now: now)
+                            if !stored { logClick("vault.unlock could not remember approval: grant lock or write failed") }
+                        }
+
+                        vaultAudit("allowed", params: params, caller: caller, session: session,
+                                   detail: "method: \(method); remembered: \(!stored ? "once" : forever ? "always" : "\(remember / 3_600) h")")
+                        logClick("vault.unlock decision=allow tool=\(tool) method=\(method)")
+                        emitVaultKey(remembered: false, params: params, caller: caller, session: session)
                     }
-
-                    vaultAudit("allowed", params: params, caller: caller, session: session,
-                               detail: "method: \(method); remembered: \(forever ? "always" : remember == 0 ? "once" : "\(remember / 3_600) h")")
-                    logClick("vault.unlock decision=allow tool=\(tool) method=\(method)")
-                    emitVaultKey(remembered: false)
                 }
             }
         }
diff --git a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
index 0389815eb6..7ce3027f53 100644
--- a/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
+++ b/src/macos/GenesisTools/Tests/VaultUnlockTests.swift
@@ -29,6 +29,85 @@ final class VaultUnlockTests: XCTestCase {
                     cwd: "/Users/alice/project", ancestors: ancestors.map { (pid: $0.0, command: $0.1) })
     }
 
+    func testVaultRecipientRequiresTheCallerToBeTheOnlyPeerHolder() {
+        let identity = VaultRecipient.Identity(pid: 42, startSeconds: 100, startMicroseconds: 7, executable: "/bin/client")
+        let channels: [(VaultRecipient.Endpoint, VaultRecipient.Endpoint)] = [
+            (.pipe(handle: 10, peer: 20), .pipe(handle: 20, peer: 10)),
+            (.socket(pcb: 10, peer: 20), .socket(pcb: 20, peer: 10)),
+        ]
+        for (output, peer) in channels {
+            let caller = VaultRecipient.ProcessFDs(pid: 42, endpoints: [peer, peer])
+            let unrelated = VaultRecipient.ProcessFDs(pid: 43, endpoints: [.pipe(handle: 30, peer: 40), output])
+            XCTAssertNil(VaultRecipient.rejection(stdout: output, caller: identity, current: identity,
+                                                  processes: [caller, unrelated]), "duplicated fds in one process are allowed")
+            let child = VaultRecipient.ProcessFDs(pid: 44, endpoints: [peer])
+            XCTAssertNotNil(VaultRecipient.rejection(stdout: output, caller: identity, current: identity,
+                                                     processes: [caller, child]), "a forked reader denies release")
+            XCTAssertNotNil(VaultRecipient.rejection(stdout: output, caller: identity, current: identity,
+                                                     processes: [child]), "the sole reader must be the verified caller")
+            XCTAssertNotNil(VaultRecipient.rejection(stdout: output, caller: identity, current: identity,
+                                                     processes: [unrelated]), "no reader denies release")
+            XCTAssertNotNil(VaultRecipient.rejection(stdout: output, caller: identity, current: identity,
+                                                     processes: [caller, .init(pid: 45, endpoints: nil)]))
+        }
+    }
+
+    func testVaultRecipientSkipsOnlyExitedOrPermissionDeniedSystemProcesses() {
+        let identity = VaultRecipient.Identity(pid: 42, startSeconds: 100, startMicroseconds: 7, executable: "/bin/client")
+        let output = VaultRecipient.Endpoint.pipe(handle: 10, peer: 20)
+        let caller = VaultRecipient.ProcessFDs(pid: 42, endpoints: [.pipe(handle: 20, peer: 10)])
+        let exited = VaultRecipient.ProcessFDs(pid: 43, endpoints: nil, failure: .exited)
+        XCTAssertNil(VaultRecipient.rejection(stdout: output, caller: identity, current: identity, processes: [caller, exited]))
+        for executable in ["/usr/bin/login", "/usr/sbin/service", "/usr/libexec/service", "/bin/sh", "/sbin/service", "/System/Library/service"] {
+            let protected = VaultRecipient.ProcessFDs(pid: 43, endpoints: nil,
+                failure: .unavailable(code: EPERM, executable: executable))
+            XCTAssertNil(VaultRecipient.rejection(stdout: output, caller: identity, current: identity,
+                                                  processes: [caller, protected]), executable)
+        }
+        for executable in ["/Users/x/evil", "/usr/local/bin/evil", "/usr/bin-evil/program", "/Systematic/evil", "/usr/bin/../local/bin/evil", "/System/Volumes/Data/Users/x/evil", nil] {
+            let unreadable = VaultRecipient.ProcessFDs(pid: 43, endpoints: nil,
+                failure: .unavailable(code: EPERM, executable: executable))
+            XCTAssertNotNil(VaultRecipient.rejection(stdout: output, caller: identity, current: identity,
+                                                     processes: [caller, unreadable]))
+        }
+        let otherError = VaultRecipient.ProcessFDs(pid: 43, endpoints: nil,
+            failure: .unavailable(code: EIO, executable: "/usr/bin/login"))
+        XCTAssertNotNil(VaultRecipient.rejection(stdout: output, caller: identity, current: identity, processes: [caller, otherError]))
+        let reader = VaultRecipient.ProcessFDs(pid: 43, endpoints: [.pipe(handle: 20, peer: 10)],
+            failure: .unavailable(code: EPERM, executable: "/usr/bin/login"))
+        XCTAssertEqual(VaultRecipient.rejection(stdout: output, caller: identity, current: identity, processes: [caller, reader]),
+                       "another process holds the output", "readable holders are never skipped")
+        XCTAssertNotNil(VaultRecipient.rejection(stdout: output, caller: identity, current: identity, processes: [exited]),
+                        "skipping an exited caller cannot authorize release")
+    }
+
+    func testVaultRecipientRejectsChangedOrUnknownProcessIdentity() {
+        let identity = VaultRecipient.Identity(pid: 42, startSeconds: 100, startMicroseconds: 7, executable: "/bin/client")
+        let output = VaultRecipient.Endpoint.pipe(handle: 10, peer: 20)
+        let processes = [VaultRecipient.ProcessFDs(pid: 42, endpoints: [.pipe(handle: 20, peer: 10)])]
+        var changedSeconds = identity
+        changedSeconds.startSeconds += 1
+        var changedMicroseconds = identity
+        changedMicroseconds.startMicroseconds += 1
+        var changedPath = identity
+        changedPath.executable = "/bin/other"
+        var changedPid = identity
+        changedPid.pid += 1
+        for current in [changedSeconds, changedMicroseconds, changedPath, changedPid, nil] {
+            XCTAssertNotNil(VaultRecipient.rejection(stdout: output, caller: identity, current: current, processes: processes))
+        }
+        XCTAssertNotNil(VaultRecipient.rejection(stdout: output, caller: nil, current: identity, processes: processes))
+    }
+
+    func testVaultRecipientRejectsUnsupportedDisconnectedAndWrongKindEndpoints() {
+        let identity = VaultRecipient.Identity(pid: 42, startSeconds: 100, startMicroseconds: 7, executable: "/bin/client")
+        let processes = [VaultRecipient.ProcessFDs(pid: 42, endpoints: [.pipe(handle: 20, peer: 10)])]
+        for output in [VaultRecipient.Endpoint.other, .pipe(handle: 10, peer: 0), .socket(pcb: 0, peer: 20),
+                       .pipe(handle: 10, peer: 10), .socket(pcb: 10, peer: 20)] {
+            XCTAssertNotNil(VaultRecipient.rejection(stdout: output, caller: identity, current: identity, processes: processes))
+        }
+    }
+
     func testTheKernelBytesSplitIntoExecutableArgumentsAndEnvironment() throws {
         let bytes = procArgsBytes(argc: 3, executable: "/Users/alice/.genesis-tools/bin/gt-claude",
                                   arguments: ["gt-claude", "/repo/src/claude/index.ts", "info"],
@@ -59,6 +138,136 @@ final class VaultUnlockTests: XCTestCase {
         XCTAssertEqual(bare.onceOnlyReason, "the script it runs is not known")
     }
 
+    func testCheckoutUnderSourceParentUsesLastSourceSegment() {
+        let root = "/work/src/GenesisTools"
+        let preloads = VaultCaller.ownPreloads.flatMap { ["--preload", "\(root)/\($0)"] }
+        let who = caller("/usr/bin/bun", arguments: ["bun"] + preloads + ["\(root)/src/claude/index.ts"])
+        XCTAssertEqual(who.toolName, "claude")
+        XCTAssertNil(who.onceOnlyReason)
+        XCTAssertEqual(VaultWindowContent.programPath("\(root)/src/claude/index.ts"), "GenesisTools/src/claude/index.ts")
+    }
+
+    func testOtherInterpretersWithoutAKnownScriptCannotRememberOrMatchABroadGrant() {
+        for name in ["Python", "python3.12", "pypy3", "ruby", "perl", "php", "lua", "tclsh", "osascript", "java", "pwsh", "sh", "bash", "zsh", "fish"] {
+            let executable = "/usr/bin/\(name)"
+            let who = caller(executable, arguments: [executable, "program.py"])
+            XCTAssertTrue(who.isInterpreter, name)
+            XCTAssertEqual(who.onceOnlyReason, "the script it runs is not known", name)
+            let broad = VaultGrant(key: name, tool: name, executable: executable, script: nil,
+                                   grantedAt: 1_000, until: nil, method: "touch-id")
+            XCTAssertTrue(broad.isTooBroad, name)
+            XCTAssertNil(VaultGrants.live(executable: executable, script: nil, now: 1_500,
+                                          in: VaultGrantsFile(version: 1, grants: [broad])), name)
+        }
+        XCTAssertNil(caller("/usr/bin/python3", arguments: ["python3", "run", "/approved/script.ts"]).script)
+        XCTAssertNil(caller("/usr/bin/bun", arguments: ["bun", "run", "run", "/approved/script.ts"]).script)
+        XCTAssertFalse(caller("/usr/bin/native-client", arguments: ["native-client"]).isInterpreter)
+        XCTAssertNil(caller("/usr/bin/native-client", arguments: ["native-client"]).onceOnlyReason)
+    }
+
+    func testInlineCodeAndUnknownLeadingFlagsCannotUseAnApprovedScriptGrant() {
+        let executable = "/Users/alice/.bun/bin/bun"
+        let script = "/repo/src/claude/index.ts"
+        let grant = VaultGrant(key: "k", tool: "claude", executable: executable, script: script,
+                               grantedAt: 1_000, until: nil, method: "touch-id")
+        let file = VaultGrantsFile(version: 1, grants: [grant])
+        for flags in [["--eval=arbitrary()"], ["--print=arbitrary()"], ["-e", "arbitrary()"], ["-p", "arbitrary()"],
+                      ["--eval", "arbitrary()"], ["--print", "arbitrary()"], ["-e=arbitrary()"], ["-p=arbitrary()"], ["--unknown"]] {
+            let who = caller(executable, arguments: [executable] + flags + [script])
+            XCTAssertEqual(who.onceOnlyReason, "extra code may be loaded", flags.joined(separator: " "))
+            let matched = who.onceOnlyReason == nil
+                ? VaultGrants.live(executable: executable, script: who.script, now: 1_500, in: file) : nil
+            XCTAssertNil(matched)
+        }
+    }
+
+    func testVaultAuditRedactsBothFilesAndTheCommandHelp() throws {
+        let home = (NSTemporaryDirectory() as NSString).appendingPathComponent("vault-audit-\(UUID().uuidString)")
+        setenv("GENESIS_TOOLS_HOME", home, 1)
+        defer { unsetenv("GENESIS_TOOLS_HOME"); try? FileManager.default.removeItem(atPath: home) }
+        let token = "fixture-secret-never-real"
+        let command = "tools claude config add work --token \(token)"
+        let params = VaultUnlockParams(tool: "claude", purpose: "run \(command)", secret: nil, command: command)
+        let who = caller(arguments: ["gt-claude", "/repo/src/claude/index.ts", "config", "add", "work", "--token", token])
+        let content = VaultWindowContent.build(params, caller: who, session: VaultSessionInfo())
+        let fact = try XCTUnwrap(content.details.first { $0.label == "Command" })
+        XCTAssertFalse(content.purpose.contains(token))
+        XCTAssertFalse((fact.help ?? "").contains(token))
+        vaultAudit("prompted", params: params, caller: who, session: VaultSessionInfo(), shown: content)
+        for path in [GateAudit.path, (VaultGrants.directory as NSString).appendingPathComponent("audit.jsonl")] {
+            let text = try String(contentsOfFile: path, encoding: .utf8)
+            XCTAssertFalse(text.contains(token), path)
+            XCTAssertTrue(text.contains("[REDACTED]"), path)
+            XCTAssertTrue(text.contains("config add work"), path)
+        }
+    }
+
+    func testGrantTransactionsWaitForTheSharedPidLockAndReloadAfterRevocation() async throws {
+        let directory = (NSTemporaryDirectory() as NSString).appendingPathComponent("vault-store-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(atPath: directory, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(atPath: directory) }
+        let path = (directory as NSString).appendingPathComponent("vault-grants.json")
+        let lock = path + ".lock"
+        let old = VaultGrant(key: "old", tool: "old", executable: "/bin/native-old", script: nil,
+                             grantedAt: 1_000, until: nil, method: "touch-id")
+        let next = VaultGrant(key: "next", tool: "next", executable: "/bin/native-next", script: nil,
+                              grantedAt: 1_000, until: nil, method: "touch-id")
+        XCTAssertTrue(VaultGrants.save(VaultGrantsFile(version: 1, grants: [old]), to: path))
+        try Data("\(getpid())\n".utf8).write(to: URL(fileURLWithPath: lock))
+        let blocked = await VaultGrants.store(next, now: 1_500, to: path, timeout: 0)
+        XCTAssertFalse(blocked, "a TypeScript lock must prevent the native write")
+        XCTAssertEqual(VaultGrants.load(from: path).grants, [old])
+        // The TypeScript revoker publishes its empty snapshot before releasing this lock.
+        XCTAssertTrue(VaultGrants.save(VaultGrantsFile(version: 1, grants: []), to: path))
+        try FileManager.default.removeItem(atPath: lock)
+        let arbiter = lock + ".claim-arbitration.lock"
+        try FileManager.default.createDirectory(atPath: arbiter, withIntermediateDirectories: false)
+        let arbitrating = await VaultGrants.store(next, now: 1_500, to: path, timeout: 0)
+        XCTAssertFalse(arbitrating, "the TypeScript claim/stale-takeover arbiter must also be respected")
+        try FileManager.default.removeItem(atPath: arbiter)
+        let stored = await VaultGrants.store(next, now: 1_500, to: path)
+        XCTAssertTrue(stored)
+        XCTAssertEqual(VaultGrants.load(from: path).grants, [next], "revoked grants are never resurrected")
+        async let first = VaultGrants.store(old, now: 1_500, to: path)
+        async let second = VaultGrants.store(next, now: 1_500, to: path)
+        let results = await [first, second]
+        XCTAssertEqual(results, [true, true])
+        XCTAssertEqual(Set(VaultGrants.load(from: path).grants.map(\.key)), ["old", "next"])
+    }
+
+    func testLoaderEnvironmentAndUnreadableArgumentsCannotReuseNativeGrants() {
+        let executable = "/usr/bin/native-client"
+        let grant = VaultGrant(key: "native", tool: "native", executable: executable, script: nil,
+                               grantedAt: 1_000, until: nil, method: "touch-id")
+        let grants = VaultGrantsFile(version: 1, grants: [grant])
+        for name in ["LD_PRELOAD", "LD_LIBRARY_PATH", "DYLD_INSERT_LIBRARIES", "DYLD_LIBRARY_PATH", "DYLD_FRAMEWORK_PATH"] {
+            let who = caller(executable, arguments: [executable], environment: ["\(name)=/fixture/library"])
+            XCTAssertTrue(who.injected.contains(name), name)
+            XCTAssertEqual(who.onceOnlyReason, "extra code may be loaded", name)
+            XCTAssertNil(who.onceOnlyReason == nil
+                ? VaultGrants.live(executable: executable, script: nil, now: 1_500, in: grants) : nil)
+        }
+        var unreadable = caller(executable, arguments: [executable])
+        unreadable.args = nil
+        XCTAssertEqual(unreadable.onceOnlyReason, "the caller's arguments and environment could not be read")
+        let normal = caller(executable, arguments: [executable], environment: ["PATH=/usr/bin", "NODE_OPTIONS=--conditions=fixture"])
+        XCTAssertNil(normal.onceOnlyReason, "native code does not execute Node options")
+        XCTAssertNotNil(VaultGrants.live(executable: executable, script: nil, now: 1_500, in: grants))
+    }
+
+    func testInterpreterEnvironmentChecksMatchTheAccountGateConservativePolicy() {
+        let names = ["NODE_OPTIONS", "NODE_PATH", "BUN_OPTIONS", "BUN_INSPECT_PRELOAD", "DENO_AUTH_TOKENS",
+                     "PYTHONSTARTUP", "PYTHONPATH", "PYTHONHOME", "RUBYOPT", "RUBYLIB", "PERL5OPT", "PERL5LIB", "PERLLIB",
+                     "BASH_ENV", "ZDOTDIR", "ENV"]
+        for name in names {
+            let who = caller(arguments: ["gt-claude", "/repo/src/claude/index.ts"], environment: ["\(name)=fixture"])
+            XCTAssertTrue(who.injected.contains(name), name)
+            XCTAssertEqual(who.onceOnlyReason, "extra code may be loaded", name)
+        }
+        XCTAssertFalse(caller(arguments: ["gt-claude", "/repo/src/claude/index.ts"], environment: ["NODE_OPTIONS="]).injected.isEmpty)
+        XCTAssertNil(caller(arguments: ["gt-claude", "/repo/src/claude/index.ts"], environment: ["PATH=/usr/bin"]).onceOnlyReason)
+    }
+
     func testLoadedExtraCodeAllowsOnlyOnce() {
         XCTAssertEqual(caller(arguments: ["gt-claude", "/repo/src/claude/index.ts"]).injected, [])
         XCTAssertFalse(caller(arguments: ["gt-claude", "--preload", "/tmp/x.ts", "/repo/src/claude/index.ts"]).injected.isEmpty)
diff --git a/src/mcp-manager/README.md b/src/mcp-manager/README.md
index eddc16a0e9..19ba60fd3e 100644
--- a/src/mcp-manager/README.md
+++ b/src/mcp-manager/README.md
@@ -161,8 +161,8 @@ The tool uses a unified configuration file at `~/.genesis-tools/mcp-manager/conf
 
 #### Claude enable/disable semantics
 
-Verified against the Claude Code binary (2.1.296, research note
-`2026-10-13-ClaudeCodeGlobalMcpSwitch.md`): Claude Code reads `disabledMcpServers`
+Recorded against Claude Code 2.1.296 on 2026-10-13 ([maintained evidence and
+recheck procedure](claude-code-disable-evidence.md)): Claude Code reads `disabledMcpServers`
 **only** from per-project entries (`.projects[<cwd>].disabledMcpServers`). The
 **top-level `disabledMcpServers` key is never read by Claude Code** — it is an
 mcp-manager-only marker. The only mechanism Claude Code honors globally
diff --git a/src/mcp-manager/claude-code-disable-evidence.md b/src/mcp-manager/claude-code-disable-evidence.md
new file mode 100644
index 0000000000..aacc2b5786
--- /dev/null
+++ b/src/mcp-manager/claude-code-disable-evidence.md
@@ -0,0 +1,45 @@
+# Claude Code MCP disable evidence
+
+This records the local investigation of **Claude Code 2.1.296** on 2026-10-13,
+not a claim about every future version. The full local research note was titled
+`2026-10-13-ClaudeCodeGlobalMcpSwitch.md`; this maintained repository excerpt
+keeps the evidence used by mcp-manager's provider contract.
+
+The investigator extracted the native binary's embedded JavaScript. The
+exported `isMcpServerDisabled` function was named `Ao` in that build:
+
+```js
+function Ao(e) {
+    let n = Xi();
+    if (mge(e)) return !yge(n.enabledMcpServers).includes(e);
+    return yge(n.disabledMcpServers).includes(e);
+}
+```
+
+`Xi()` selected `config.projects[currentProjectPath]`, falling back to the
+empty project configuration. The five occurrences of `disabledMcpServers` in
+the extracted bundle were project reads/writes or prompt text. None read the
+top-level field. The MCP toggle wrote the same project entry. The policy
+check separately rejected `deniedMcpServers` from merged settings before
+checking any allow entry.
+
+The investigation also used scratch `CLAUDE_CONFIG_DIR` directories. Server
+names below use an invented fixture label:
+
+| Configuration | Observed behavior |
+| --- | --- |
+| Top-level `disabledMcpServers: ["fixture-server"]` | Server remained enabled |
+| Current project's `disabledMcpServers: ["fixture-server"]` | Disabled only in that project |
+| User settings `deniedMcpServers: [{"serverName":"fixture-server"}]` | Server absent in registered and unregistered projects |
+| Same deny plus a project allow entry | Still denied; enabling reported managed-policy blocking |
+
+To recheck after an upgrade, use fresh temporary configuration directories and
+an inert local stdio MCP fixture. Run `claude mcp list` in two fresh project
+directories for each row, setting `CLAUDE_CONFIG_DIR` for every call. Do not use
+a real account or the user's configuration. Record the binary version and
+observed output here if behavior changes.
+
+The provider removes a globally disabled server from generated `mcpServers`,
+retaining its definition in unified configuration. The top-level disabled list
+is mcp-manager's marker. `commands/__tests__/claude-global-disable.test.ts`
+verifies those writes; it does not validate an installed Claude Code binary.
diff --git a/src/mcp-manager/utils/providers/claude.ts b/src/mcp-manager/utils/providers/claude.ts
index f128dbc987..42fb988385 100644
--- a/src/mcp-manager/utils/providers/claude.ts
+++ b/src/mcp-manager/utils/providers/claude.ts
@@ -50,8 +50,8 @@ function isDeniedByClaude(denied: unknown[], registeredName: string, url: string
  * Claude Desktop MCP provider.
  * Manages MCP servers in ~/.claude.json
  *
- * IMPORTANT (verified against the Claude Code binary 2.1.296, research note
- * 2026-10-13-ClaudeCodeGlobalMcpSwitch.md): Claude Code reads
+ * Recorded against Claude Code 2.1.296 on 2026-10-13; maintained excerpts and a
+ * recheck procedure: src/mcp-manager/claude-code-disable-evidence.md. That version reads
  * `disabledMcpServers` ONLY from per-project entries
  * (`.projects[<cwd>].disabledMcpServers`). The TOP-LEVEL `disabledMcpServers`
  * key is NEVER read by Claude Code — it is an mcp-manager-only marker. The only
diff --git a/src/utils/ai/core/call-stream-error.test.ts b/src/utils/ai/core/call-stream-error.test.ts
index 41d951ad2a..456d68c9dc 100644
--- a/src/utils/ai/core/call-stream-error.test.ts
+++ b/src/utils/ai/core/call-stream-error.test.ts
@@ -24,7 +24,7 @@ function refusal(statusCode: number, message: string): APICallError {
     });
 }
 
-function target(doStream: () => Promise<never>): CallTarget {
+function target(doStream: MockLanguageModelV4["doStream"]): CallTarget {
     return {
         model: new MockLanguageModelV4({ doStream }) as unknown as LanguageModel,
         providerType: "anthropic",
@@ -69,6 +69,34 @@ describe("coreChat streaming errors", () => {
         }
     });
 
+    test("rejects the provider error after a stream has already produced text", async () => {
+        const error = refusal(403, "fixture stream refused after starting");
+        const chunks: string[] = [];
+        const outcome = await coreChat({
+            target: target(async () => ({
+                stream: new ReadableStream({
+                    start(controller) {
+                        controller.enqueue({ type: "stream-start", warnings: [] });
+                        controller.enqueue({ type: "text-start", id: "part" });
+                        controller.enqueue({ type: "text-delta", id: "part", delta: "before error" });
+                        controller.enqueue({ type: "error", error });
+                        controller.close();
+                    },
+                }),
+            })),
+            prompt: "hi",
+            stream: true,
+            onChunk: (chunk) => {
+                chunks.push(chunk);
+            },
+        }).then(
+            () => undefined,
+            (caught: unknown) => caught
+        );
+        expect(chunks.join("")).toBe("before error");
+        expect(outcome).toBe(error);
+    });
+
     test("maxRetries: 0 asks a retryable refusal once", async () => {
         let asked = 0;
 
diff --git a/src/utils/ai/gate/client-identity.test.ts b/src/utils/ai/gate/client-identity.test.ts
index 146e72be04..f2e98a9cbf 100644
--- a/src/utils/ai/gate/client-identity.test.ts
+++ b/src/utils/ai/gate/client-identity.test.ts
@@ -45,6 +45,41 @@ describe("the checkout's own preloads", () => {
         );
     });
 
+    test("separated own preloads before run preserve the script and verified identity", () => {
+        const root = "/repo";
+        const script = `${root}/src/claude/index.ts`;
+        const before = `--preload ${root}/${OWN_PRELOADS[0]}`;
+        const after = `--preload ${root}/${OWN_PRELOADS[1]}`;
+        for (const executable of ["/opt/bun/bin/bun", "/fixture/bin/gt-claude"]) {
+            const command = [executable, before, "run", after, script, "info"].join(" ");
+            expect(scriptOf(command, "/work", executable)).toBe(script);
+            expect(codeInjectionSignals(command, null, executable)).toEqual([]);
+            const lookup = lookupOf(
+                [row(700, 1, command), row(800, 700, "tools ai gate request")],
+                { 700: "/work" },
+                { 700: executable },
+                { 700: command }
+            );
+            expect(describeClient({ name: "work", pid: 700 }, lookup, 800)).toMatchObject({
+                script,
+                verified: true,
+                injected: [],
+            });
+            expect(scriptOf([executable, before, "test", script].join(" "), "/work", executable)).toBeNull();
+            expect(
+                codeInjectionSignals([executable, "--preload /other.ts run", script].join(" "), null, executable)
+            ).toEqual(["flag --preload"]);
+        }
+    });
+
+    test("own preloads stay trusted under a parent folder named src", () => {
+        const root = "/work/src/GenesisTools";
+        const preloads = OWN_PRELOADS.map((relative) => `--preload ${root}/${relative}`).join(" ");
+        expect(
+            codeInjectionSignals(`/usr/bin/bun ${preloads} ${root}/src/claude/index.ts`, null, "/usr/bin/bun")
+        ).toEqual([]);
+    });
+
     test("a tool the launcher starts with all its preloads shows no loaded-code signal", () => {
         const root = "/work/GenesisTools";
         const preloads = OWN_PRELOADS.map((relative) => `--preload ${root}/${relative}`).join(" ");
diff --git a/src/utils/ai/gate/client-identity.ts b/src/utils/ai/gate/client-identity.ts
index f8a2485277..56b4d0a0ff 100644
--- a/src/utils/ai/gate/client-identity.ts
+++ b/src/utils/ai/gate/client-identity.ts
@@ -236,8 +236,9 @@ function scriptArgs(command: string, executable: string): string[] | null {
         return args;
     }
 
-    const index = args.findIndex((arg) => !arg.startsWith("-"));
-    const word = index === -1 ? undefined : args[index];
+    const { rest } = splitLeadingFlags(args, executable);
+    const index = args.length - rest.length;
+    const word = rest[0];
 
     if (word === "run") {
         return [...args.slice(0, index), ...args.slice(index + 1)];
@@ -285,7 +286,7 @@ export function codeInjectionSignals(
     const { flags, rest } = splitLeadingFlags(scriptArgs(command, executable) ?? [], executable);
     const script = rest[0];
     const checkout =
-        script && isAbsolute(script) && script.includes("/src/") ? script.slice(0, script.indexOf("/src/")) : null;
+        script && isAbsolute(script) && script.includes("/src/") ? script.slice(0, script.lastIndexOf("/src/")) : null;
     const own = new Set(checkout ? OWN_PRELOADS.map((relative) => join(checkout, relative)) : []);
 
     for (const { flag, value } of flags) {
diff --git a/src/utils/ai/gate/grants.test.ts b/src/utils/ai/gate/grants.test.ts
index 7c34023c9e..64af44982b 100644
--- a/src/utils/ai/gate/grants.test.ts
+++ b/src/utils/ai/gate/grants.test.ts
@@ -1,19 +1,23 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
-import { gatesAuditPath } from "@genesiscz/utils/audit/gates";
+import { appendGateAudit, gatesAuditPath } from "@genesiscz/utils/audit/gates";
+import { defaultRouterConfig, route } from "@genesiscz/utils/browser-router/route";
 import { env } from "@genesiscz/utils/env";
-import { SafeJSON } from "@genesiscz/utils/json";
+import { parseJSON, SafeJSON } from "@genesiscz/utils/json";
 import {
     appendAudit,
     auditPath,
     findGrant,
     grantsPath,
     listGrants,
+    listVaultGrants,
     readAuditTail,
     rememberGrant,
     revokeGrants,
+    revokeVaultGrants,
+    vaultGrantsPath,
 } from "./grants";
 import type { ClientIdentity, GateGrant } from "./types";
 
@@ -70,6 +74,276 @@ afterEach(() => {
 });
 
 describe("grants", () => {
+    test("Swift's omitted nil expiry is normalized and remains visible until revoked", async () => {
+        const base = {
+            key: "vault|ai|bun|daemon.ts",
+            tool: "ai",
+            executable: "/bin/bun",
+            script: "/repo/daemon.ts",
+            grantedAt: NOW,
+            method: "touch-id",
+        };
+        mkdirSync(dirname(vaultGrantsPath()), { recursive: true });
+        writeFileSync(
+            vaultGrantsPath(),
+            SafeJSON.stringify({
+                version: 1,
+                grants: [
+                    base,
+                    { ...base, key: "explicit", until: null },
+                    { ...base, key: "timed", until: T(60) },
+                    { ...base, key: "expired", until: NOW - 1 },
+                ],
+            })
+        );
+
+        expect(listVaultGrants(NOW).map((item) => [item.key, item.until])).toEqual([
+            [base.key, null],
+            ["explicit", null],
+            ["timed", T(60)],
+        ]);
+        expect(await revokeVaultGrants(base.key)).toBe(1);
+        expect(listVaultGrants(NOW).map((item) => item.key)).toEqual(["explicit", "timed"]);
+    });
+
+    test("vault revocation preserves malformed input before recovering, while listing stays read-only", async () => {
+        const file = vaultGrantsPath();
+        const dir = dirname(file);
+        mkdirSync(dir, { recursive: true });
+        for (const planted of [
+            "{not valid json",
+            SafeJSON.stringify({ version: 1, grants: {} }),
+            SafeJSON.stringify({ version: 1 }),
+            SafeJSON.stringify({ version: 2, grants: [] }),
+            SafeJSON.stringify({ version: 1, grants: [null] }),
+        ]) {
+            writeFileSync(file, planted);
+            const before = new Set(readdirSync(dir));
+            expect(listVaultGrants(NOW)).toEqual([]);
+            expect(readFileSync(file, "utf8")).toBe(planted);
+            expect(readdirSync(dir).filter((name) => !before.has(name))).toEqual([]);
+            expect(await revokeVaultGrants("work")).toBe(0);
+            const copies = readdirSync(dir).filter(
+                (name) => name.startsWith("vault-grants.json.corrupt-") && !before.has(name)
+            );
+            expect(copies).toHaveLength(1);
+            expect(readFileSync(join(dir, copies[0]), "utf8")).toBe(planted);
+            expect(parseJSON<{ version: 1; grants: unknown[] }>(readFileSync(file, "utf8"))).toEqual({
+                version: 1,
+                grants: [],
+            });
+            expect(statSync(file).mode & 0o777).toBe(0o600);
+        }
+    });
+
+    test("revocation observes the native writer's bare PID lock and reloads after it releases", async () => {
+        const file = vaultGrantsPath();
+        const lock = `${file}.lock`;
+        const base = { key: "old", tool: "ai", executable: "/bin/bun", grantedAt: NOW, method: "touch-id" };
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, SafeJSON.stringify({ version: 1, grants: [base] }));
+        writeFileSync(lock, `${process.pid}\n`, { flag: "wx" });
+        let finished = false;
+        const revoke = revokeVaultGrants("*").then((removed) => {
+            finished = true;
+            return removed;
+        });
+        await Bun.sleep(100);
+        expect(finished).toBe(false);
+        // The native transaction publishes a second grant before releasing the same O_EXCL lock.
+        writeFileSync(file, SafeJSON.stringify({ version: 1, grants: [base, { ...base, key: "new" }] }));
+        unlinkSync(lock);
+        expect(await revoke).toBe(2);
+        expect(listVaultGrants(NOW)).toEqual([]);
+    });
+
+    test("both audit trails redact argv credentials and command help text", async () => {
+        const token = "fixture-secret-never-real";
+        const client = {
+            ...identity,
+            command: `tools claude config add work --token ${token}`,
+            argv: ["tools", "claude", "config", "add", "work", `--api-key=${token}`],
+        };
+        await appendAudit({
+            at: "2026-09-23T00:00:00Z",
+            event: "prompted",
+            client,
+            detail: `purpose: run tools claude config add work --token ${token}`,
+        });
+        appendGateAudit({
+            gate: "vault",
+            event: "prompted",
+            shown: {
+                purpose: `run tools claude --token=${token}`,
+                facts: [{ label: "Command", help: `tools claude --password "${token}"` }],
+            },
+        });
+        for (const file of [auditPath(), gatesAuditPath()]) {
+            const text = readFileSync(file, "utf8");
+            expect(text).not.toContain(token);
+            expect(text).toContain("[REDACTED]");
+            expect(text).toContain("config add work");
+        }
+    });
+
+    test("gate audit URLs redact userinfo, credential queries and encoded command payloads", () => {
+        const token = "fixture'url-secret";
+        const query = new URLSearchParams({
+            token,
+            api_key: token,
+            prompt: `tools claude --token ${token}`,
+            safe: "kept",
+        });
+        const url = `https://fixture-user:${token}@example.com/run?${query}`;
+        const nested = `https://example.com/open?next=${encodeURIComponent(url)}`;
+        const callback = `genesis://oauth/callback#access_token=${encodeURIComponent(token)}&state=kept-state`;
+        appendGateAudit({ gate: "link-command", event: "denied", link: url, url: nested, open: [url, callback] });
+        const text = readFileSync(gatesAuditPath(), "utf8");
+        expect(text).not.toContain(token);
+        expect(text).not.toContain("fixture-user");
+        expect(text).not.toContain("url-secret");
+        expect(text).not.toContain(encodeURIComponent(`tools claude --token ${token}`));
+        expect(text).toContain("safe=kept");
+        expect(text).toContain("state=kept-state");
+        expect(text).toContain("example.com");
+        expect(text).toContain("REDACTED");
+    });
+
+    test("expanded HTTP header credentials are redacted from argv and rendered command facts", () => {
+        const token = "fixture-header-secret-never-real";
+        const headers = [
+            ["Authorization: Bearer {token}", "Authorization: Bearer [REDACTED]"],
+            ["authorization:Basic {token}", "authorization:Basic [REDACTED]"],
+            ["Proxy-Authorization: Basic {token}", "Proxy-Authorization: Basic [REDACTED]"],
+            ["pRoXy-AuThOrIzAtIoN:Bearer {token}", "pRoXy-AuThOrIzAtIoN:Bearer [REDACTED]"],
+            ["Authorization:{token}", "Authorization:[REDACTED]"],
+            ["X-Api-Key:{token}", "X-Api-Key:[REDACTED]"],
+            ["x-aUtH-tOkEn: {token}", "x-aUtH-tOkEn: [REDACTED]"],
+            ["X-Client-Secret: {token}", "X-Client-Secret: [REDACTED]"],
+            ["Cookie:session={token}; other={token}", "Cookie:[REDACTED]"],
+            ["Set-Cookie: session={token}; Path=/", "Set-Cookie: [REDACTED]"],
+        ];
+        const decision = route(`https://links.example.test/deploy?token=${token}`, {
+            ...defaultRouterConfig(),
+            routes: [
+                {
+                    pattern: "https://links\\.example\\.test/deploy",
+                    action: {
+                        type: "run",
+                        approval: "ask",
+                        argv: [
+                            "curl",
+                            ...headers.flatMap(([header]) => ["--header", header]),
+                            "--header",
+                            "Accept: application/json",
+                            "https://api.example.test/deploy",
+                        ],
+                    },
+                },
+            ],
+        });
+        expect(decision.kind).toBe("run");
+        if (decision.kind !== "run") {
+            throw new Error("expected a saved-command decision");
+        }
+
+        expect(decision.needsApproval).toBe(true);
+        expect(decision.argv.join(" ")).toContain(token);
+        appendGateAudit({
+            gate: "link-command",
+            event: "prompted",
+            link: decision.original,
+            url: decision.url,
+            argv: decision.argv,
+            shown: {
+                facts: [
+                    { label: "Command", help: decision.argv.map((word) => `"${word}"`).join(" ") },
+                    { label: "Unquoted command", help: decision.argv.join(" ") },
+                ],
+            },
+        });
+        const text = readFileSync(gatesAuditPath(), "utf8");
+        expect(text).not.toContain(token);
+        expect(text).toContain("Accept: application/json");
+        for (const [, expected] of headers) {
+            expect(text).toContain(expected);
+        }
+        const entry = parseJSON<{ shown: { facts: Array<{ help: string }> } }>(text.trim());
+        expect(entry?.shown.facts).toHaveLength(2);
+        for (const fact of entry?.shown.facts ?? []) {
+            expect(fact.help).toContain("Accept: application/json");
+            expect(fact.help).toContain("Authorization: Bearer [REDACTED]");
+        }
+    });
+
+    test("quoted header values stay redacted in account commands and shown command facts", () => {
+        const cookie = "fixture-cookie";
+        const bearer = "fixture-bearer";
+        for (const header of [
+            `Cookie: session="${cookie}"`,
+            `Cookie: session='${cookie}'`,
+            `X-Api-Key: "${cookie}"`,
+            `Cookie: session="prefix --header ${cookie}"`,
+            `Cookie: session="prefix Accept: ${cookie}"`,
+            `Cookie: session= " --header ${cookie}"`,
+        ]) {
+            const argv = [
+                "curl",
+                "--header",
+                header,
+                "--header",
+                `Authorization: Bearer ${bearer}`,
+                "--header",
+                "Accept: application/json",
+                "https://api.example.test/deploy",
+            ];
+            const original = SafeJSON.stringify(argv);
+            const command = ["bun", "/fixture/client.ts", ...argv.slice(1)].join(" ").slice(0, 200);
+            appendGateAudit({
+                gate: "ai-account",
+                event: "prompted",
+                argv,
+                client: { command },
+                command,
+                shown: {
+                    facts: [
+                        { label: "Quoted command", value: argv.map((word) => `"${word}"`).join(" ") },
+                        { label: "Unquoted command", value: argv.join(" ") },
+                        {
+                            label: "Mixed quoted command",
+                            value: `curl -H "Cookie: session='${cookie}'" --header Authorization: Bearer ${bearer} --header Accept: application/json`,
+                        },
+                    ],
+                },
+                ambiguous: `bun --header Cookie: session="${cookie} --header Accept: application/json`,
+            });
+            const text = readFileSync(gatesAuditPath(), "utf8");
+            expect(text).not.toContain(cookie);
+            expect(text).not.toContain(bearer);
+            const entry = parseJSON<{
+                argv: string[];
+                client: { command: string };
+                command: string;
+                shown: { facts: Array<{ value: string }> };
+                ambiguous: string;
+            }>(text.trim().split("\n").at(-1) ?? "");
+            if (!entry) {
+                throw new Error("expected the audit fixture to parse");
+            }
+
+            expect(entry.argv).toContain("Accept: application/json");
+            expect(entry.shown.facts).toHaveLength(3);
+            for (const saved of [entry.client.command, entry.command, ...entry.shown.facts.map((fact) => fact.value)]) {
+                expect(saved).not.toContain(cookie);
+                expect(saved).not.toContain(bearer);
+                expect(saved).toContain("Accept: application/json");
+                expect(saved).toContain("Authorization: Bearer [REDACTED]");
+            }
+            expect(entry.ambiguous).toContain("[REDACTED]");
+            expect(SafeJSON.stringify(argv)).toBe(original);
+        }
+    });
+
     test("a remembered grant is found until it expires", async () => {
         await rememberGrant(grant());
 
diff --git a/src/utils/ai/gate/grants.ts b/src/utils/ai/gate/grants.ts
index abd42e3167..4105f7c0ea 100644
--- a/src/utils/ai/gate/grants.ts
+++ b/src/utils/ai/gate/grants.ts
@@ -6,6 +6,7 @@ import { appendGateAudit } from "@genesiscz/utils/audit/gates";
 import { readTailBytes } from "@genesiscz/utils/claude/session.utils";
 import { parseJSON, SafeJSON } from "@genesiscz/utils/json";
 import { logger } from "@genesiscz/utils/logger";
+import { redactCredentialFields } from "@genesiscz/utils/security/vault-purpose";
 import { isJsonObject, readJsonFileForUpdateSync } from "@genesiscz/utils/storage/atomic-file";
 import { withFileLock } from "@genesiscz/utils/storage/file-lock";
 import { atomicWriteFileSync } from "@genesiscz/utils/storage/storage";
@@ -128,18 +129,35 @@ export function vaultGrantsPath(): string {
     return join(gateDir(), "vault-grants.json");
 }
 
-function isVaultGrant(value: unknown): value is VaultGrant {
+type VaultGrantWire = Omit<VaultGrant, "until"> & { until?: number | null };
+
+function isVaultGrant(value: unknown): value is VaultGrantWire {
     return isJsonObject(value) && typeof value.key === "string" && typeof value.tool === "string";
 }
 
+interface VaultGrantsFile {
+    version: 1;
+    grants: VaultGrantWire[];
+}
+
+function isVaultGrantsFile(value: unknown): value is VaultGrantsFile {
+    return (
+        isJsonObject(value) && value.version === 1 && Array.isArray(value.grants) && value.grants.every(isVaultGrant)
+    );
+}
+
+function normalizedVaultGrants(grants: VaultGrantWire[]): VaultGrant[] {
+    return grants.map((grant) => ({ ...grant, until: grant.until ?? null }));
+}
+
 function readVaultGrants(): VaultGrant[] {
     const path = vaultGrantsPath();
     if (!existsSync(path)) {
         return [];
     }
 
-    const parsed = parseJSON<{ grants?: unknown[] }>(readFileSync(path, "utf8"));
-    return (parsed?.grants ?? []).filter(isVaultGrant);
+    const parsed = parseJSON<unknown>(readFileSync(path, "utf8"));
+    return isVaultGrantsFile(parsed) ? normalizedVaultGrants(parsed.grants) : [];
 }
 
 /** Vault-key approvals GenesisTools.app remembers that have not ended. */
@@ -159,7 +177,8 @@ export async function revokeVaultGrants(selector: string): Promise<number> {
     await withFileLock(
         `${path}.lock`,
         async () => {
-            const grants = readVaultGrants();
+            const existing = readJsonFileForUpdateSync(path, { accepts: isVaultGrantsFile });
+            const grants = existing.state === "ok" ? normalizedVaultGrants(existing.value.grants) : [];
             const kept = grants.filter(
                 (grant) => selector !== "*" && grant.key !== selector && grant.tool !== selector
             );
@@ -205,7 +224,7 @@ export interface AuditEntry {
 export async function appendAudit(entry: AuditEntry): Promise<void> {
     const path = auditPath();
     mkdirSync(dirname(path), { recursive: true });
-    await appendFile(path, `${SafeJSON.stringify(entry)}\n`, { mode: 0o600 });
+    await appendFile(path, `${SafeJSON.stringify(redactCredentialFields(entry))}\n`, { mode: 0o600 });
     // The shared trail of every gate (src/utils/audit/gates.ts) gets the same decision.
     appendGateAudit({ gate: "ai-account", ...entry });
     // File-only: a client that runs `tools ai gate request` reads stderr for the deny reason, so
diff --git a/src/utils/audit/gates.ts b/src/utils/audit/gates.ts
index dd08bfafc8..21ddc72738 100644
--- a/src/utils/audit/gates.ts
+++ b/src/utils/audit/gates.ts
@@ -2,6 +2,7 @@ import { appendFileSync, chmodSync, existsSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { SafeJSON } from "@genesiscz/utils/json";
 import { logger } from "@genesiscz/utils/logger";
+import { redactCredentialArgs, redactCredentialFields } from "@genesiscz/utils/security/vault-purpose";
 import { genesisToolsDir } from "@genesiscz/utils/storage/root";
 
 /**
@@ -30,9 +31,9 @@ export function appendGateAudit(entry: GateAuditEntry): void {
         const line = {
             ...entry,
             at: new Date().toISOString(),
-            writer: { pid: process.pid, argv: process.argv.slice(1, 3) },
+            writer: { pid: process.pid, argv: redactCredentialArgs(process.argv).slice(1, 3) },
         };
-        appendFileSync(path, `${SafeJSON.stringify(line)}\n`, { mode: 0o600 });
+        appendFileSync(path, `${SafeJSON.stringify(redactCredentialFields(line))}\n`, { mode: 0o600 });
 
         if (created) {
             chmodSync(path, 0o600);
diff --git a/src/utils/security/keyring/app-gate.test.ts b/src/utils/security/keyring/app-gate.test.ts
index 69a682c29a..125ce5e79e 100644
--- a/src/utils/security/keyring/app-gate.test.ts
+++ b/src/utils/security/keyring/app-gate.test.ts
@@ -5,6 +5,8 @@ import {
     currentCommandLine,
     currentToolName,
     noteVaultSecret,
+    redactCredentialArgs,
+    redactCredentialText,
     setVaultPurpose,
 } from "../vault-purpose";
 import { appGateKey, createAppGateKeyProvider, VaultKeyDeniedError, type VaultUnlockRequest } from "./app-gate";
@@ -50,6 +52,59 @@ describe("the app rung", () => {
         expect(rung.getSync?.()).toEqual(KEY);
     });
 
+    test("concurrent cold reads share one delayed approval without poisoning later reads", async () => {
+        const approval = Promise.withResolvers<typeof allow>();
+        let asked = 0;
+        const app = createAppGateKeyProvider({
+            available: () => true,
+            rpc: async () => {
+                asked++;
+                return approval.promise;
+            },
+        });
+        const first = app.get();
+        const second = app.get();
+        expect(asked).toBe(1);
+        approval.resolve(allow);
+        expect(await Promise.all([first, second])).toEqual([KEY, KEY]);
+        expect(await app.get()).toEqual(KEY);
+        expect(asked).toBe(2);
+    });
+
+    test("concurrent denials share one decision and keep the existing refusal policy", async () => {
+        const approval = Promise.withResolvers<typeof deny>();
+        let asked = 0;
+        const app = createAppGateKeyProvider({
+            available: () => true,
+            rpc: async () => {
+                asked++;
+                return approval.promise;
+            },
+        });
+        const reads = Promise.allSettled([app.get(), app.get()]);
+        expect(asked).toBe(1);
+        approval.resolve(deny);
+        expect((await reads).map((read) => read.status)).toEqual(["rejected", "rejected"]);
+        await expect(app.get()).rejects.toThrow("denied in the approval window");
+        expect(asked).toBe(1);
+    });
+
+    test("an RPC failure releases the in-flight request so a later read can retry", async () => {
+        let asked = 0;
+        const app = createAppGateKeyProvider({
+            available: () => true,
+            rpc: async () => {
+                if (++asked === 1) {
+                    throw new Error("fixture transport failure");
+                }
+                return allow;
+            },
+        });
+        await expect(app.get()).rejects.toThrow("fixture transport failure");
+        expect(await app.get()).toEqual(KEY);
+        expect(asked).toBe(2);
+    });
+
     test("a deny throws with the window's reason and never reaches the keychain", () => {
         const keychain = fakeKeychain(KEY, true);
         _setMasterKeyProvidersForTest([
@@ -156,6 +211,30 @@ describe("the app rung", () => {
 });
 
 describe("the caller's name and command", () => {
+    test("credential arguments are redacted before commands and purposes are built", () => {
+        const token = "fixture-secret-never-real";
+        for (const flag of ["--token", "--api-key", "--key", "--password", "--secret"]) {
+            for (const args of [[flag, token], [`${flag}=${token}`]]) {
+                const argv = ["gt-claude", "/repo/src/claude/index.ts", "config", "add", "work", ...args];
+                expect(currentCommandLine(argv)).not.toContain(token);
+                expect(redactCredentialArgs(argv).join(" ")).toContain("[REDACTED]");
+                expect(redactCredentialText(`run ${argv.join(" ")}`)).not.toContain(token);
+            }
+        }
+
+        expect(redactCredentialText('run tools claude --token="fixture with spaces"')).toBe(
+            "run tools claude --token=[REDACTED]"
+        );
+        expect(redactCredentialArgs(["tools", "wakeup", "daemon", "register", "-t", token]).at(-1)).toBe("[REDACTED]");
+        expect(
+            redactCredentialArgs(["bun", "/repo/src/wakeup/index.ts", "daemon", "register", `-t=${token}`]).at(-1)
+        ).toBe("-t=[REDACTED]");
+        expect(redactCredentialArgs(["tools", "claude", "tail", "-t", "5"]).at(-1)).toBe("5");
+        expect(currentCommandLine(["gt-claude", "/repo/src/claude/index.ts", "--token", token], 40)).not.toContain(
+            "fixture"
+        );
+    });
+
     test("from the tool's entry script, else from its gt- launcher", () => {
         expect(currentToolName(["/Users/x/.genesis-tools/bin/gt-claude", "/repo/src/claude/index.ts", "info"])).toBe(
             "claude"
diff --git a/src/utils/security/keyring/app-gate.ts b/src/utils/security/keyring/app-gate.ts
index 268fca81a1..f1377caaea 100644
--- a/src/utils/security/keyring/app-gate.ts
+++ b/src/utils/security/keyring/app-gate.ts
@@ -5,7 +5,13 @@ import {
     genesisAppRpcSync,
     isGenesisAppRpcAvailable,
 } from "@genesiscz/utils/macos/genesis-app-rpc";
-import { currentCommandLine, currentToolName, vaultPurpose, vaultSecretAsked } from "../vault-purpose";
+import {
+    currentCommandLine,
+    currentToolName,
+    redactCredentialText,
+    vaultPurpose,
+    vaultSecretAsked,
+} from "../vault-purpose";
 import { decodeMasterKey, isTestProcess, type MasterKeyProvider } from "./types";
 
 /**
@@ -62,7 +68,7 @@ export function vaultUnlockRequest(): VaultUnlockRequest {
 
     return {
         tool: currentToolName(),
-        purpose: vaultPurpose() ?? `run ${command}`,
+        purpose: redactCredentialText(vaultPurpose() ?? `run ${command}`),
         secret: vaultSecretAsked(),
         command,
     };
@@ -124,6 +130,7 @@ export function createAppGateKeyProvider(deps: AppGateDeps = {}): MasterKeyProvi
             genesisAppRpcSync<VaultUnlockReply>("vault.unlock", params(request), options));
 
     let refusal: VaultKeyDeniedError | undefined;
+    let pending: Promise<Buffer | undefined> | undefined;
     const answer = (outcome: GenesisAppRpcOutcome<VaultUnlockReply>, tool: string): Buffer | undefined => {
         try {
             return keyFromReply(outcome, tool);
@@ -150,8 +157,16 @@ export function createAppGateKeyProvider(deps: AppGateDeps = {}): MasterKeyProvi
                 throw refusal;
             }
 
-            const request = vaultUnlockRequest();
-            return answer(await rpc(request), request.tool);
+            if (!pending) {
+                const request = vaultUnlockRequest();
+                pending = rpc(request).then((outcome) => answer(outcome, request.tool));
+            }
+
+            try {
+                return await pending;
+            } finally {
+                pending = undefined;
+            }
         },
         getSync() {
             if (!available()) {
diff --git a/src/utils/security/vault-purpose.test.ts b/src/utils/security/vault-purpose.test.ts
new file mode 100644
index 0000000000..2250119b9c
--- /dev/null
+++ b/src/utils/security/vault-purpose.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { currentToolName, redactCredentialArgs, redactCredentialFields, redactCredentialText } from "./vault-purpose";
+
+describe("credential header boundaries", () => {
+    const secret = "fixture-cookie-r5";
+    const safe = "Accept: application/json";
+    test("keeps harmless quoted headers after one or several sensitive headers", () => {
+        for (const input of [
+            `curl -H "Cookie: session=${secret}" -H "${safe}"`,
+            `curl -H "Cookie: session=${secret}" -H "Authorization: Bearer ${secret}" -H "${safe}"`,
+            `curl -H "Cookie: session='${secret}'" -H "${safe}"`,
+            `curl --header Cookie: session="prefix --header ${secret}" --header ${safe}`,
+        ]) {
+            const output = redactCredentialText(input);
+            expect(output).not.toContain(secret);
+            expect(output).toContain(safe);
+            if (input.includes("Authorization: Bearer")) {
+                expect(output).toContain("Authorization: Bearer [REDACTED]");
+            }
+        }
+    });
+
+    test("redacts equals-form header flags in argv and joined commands", () => {
+        for (const flag of ["--header", "-H"]) {
+            for (const header of [
+                `Authorization: Bearer ${secret}`,
+                `Proxy-Authorization: Basic ${secret}`,
+                `Cookie: session='${secret}'`,
+                `X-Api-Key:${secret}`,
+            ]) {
+                const argv = ["wget", `${flag}=${header}`, `${flag}=${safe}`];
+                const original = [...argv];
+                for (const output of [
+                    redactCredentialArgs(argv).join(" "),
+                    redactCredentialText(argv.join(" ")),
+                    redactCredentialText(argv.map((word) => `"${word}"`).join(" ")),
+                ]) {
+                    expect(output).not.toContain(secret);
+                    expect(output).toContain(safe);
+                    if (header.startsWith("Authorization")) {
+                        expect(output).toContain("Authorization: Bearer [REDACTED]");
+                    }
+                }
+                expect(argv).toEqual(original);
+            }
+        }
+    });
+
+    test("CR, LF and CRLF preserve the following harmless header, including Unicode values", () => {
+        for (const newline of ["\r", "\n", "\r\n"]) {
+            const output = redactCredentialText(`Cookie: session=🔒${secret}${newline}${safe}`);
+            expect(output).toBe(`Cookie: [REDACTED]${newline}${safe}`);
+        }
+    });
+
+    test("scans long whitespace and quoted runs without quadratic work", () => {
+        const started = performance.now();
+        for (const value of [`x${" ".repeat(131_072)}!`, '"x"'.repeat(43_691)]) {
+            const output = redactCredentialText(`curl --header Cookie: ${value}`);
+            expect(output).toBe("curl --header Cookie: [REDACTED]");
+        }
+        expect(performance.now() - started).toBeLessThan(2_000);
+    });
+
+    test("quoted credential flags consume escaped quotes and malformed remainders", () => {
+        const secret = "fixture-secret-suffix-r6";
+        for (const flag of ["--token", "--api-key", "--key", "--password", "--secret"]) {
+            for (const separator of [" ", "="]) {
+                for (const quote of ['"', "'"]) {
+                    const value = [quote, "prefix\\", quote, secret, quote].join("");
+                    const input = ["tools claude", flag + separator + value, "--format json"].join(" ");
+                    const expected = ["tools claude", `${flag}${separator}[REDACTED]`, "--format json"].join(" ");
+                    expect(redactCredentialText(input)).toBe(expected);
+                    expect(redactCredentialFields({ shown: [{ help: input }] })).toEqual({
+                        shown: [{ help: expected }],
+                    });
+                    const unfinished = ["tools claude", flag + separator + value.slice(0, -1), "--format json\\"].join(
+                        " "
+                    );
+                    expect(redactCredentialText(unfinished)).toBe(
+                        ["tools claude", `${flag}${separator}[REDACTED]`].join(" ")
+                    );
+                }
+            }
+        }
+        const relay = ['tools wakeup daemon register -t "prefix\\"', secret, '" --format json'].join("");
+        expect(redactCredentialText(relay)).toBe("tools wakeup daemon register -t [REDACTED] --format json");
+        expect(redactCredentialText('tools claude tail -t "safe\\"value"')).toBe('tools claude tail -t "safe\\"value"');
+    });
+
+    test("uses the last src segment for a tool under a source checkout parent", () => {
+        expect(currentToolName(["bun", "/work/src/GenesisTools/src/claude/index.ts"])).toBe("claude");
+    });
+});
diff --git a/src/utils/security/vault-purpose.ts b/src/utils/security/vault-purpose.ts
index 7e316a2ad2..518e1eb292 100644
--- a/src/utils/security/vault-purpose.ts
+++ b/src/utils/security/vault-purpose.ts
@@ -52,7 +52,7 @@ export function _resetVaultContextForTest(): void {
  */
 export function currentToolName(argv: string[] = process.argv, executable: string = process.execPath): string {
     const script = argv[1] ?? "";
-    const fromScript = script.match(/[/\\]src[/\\]([^/\\]+)[/\\]/)?.[1];
+    const fromScript = script.match(/^.*[/\\]src[/\\]([^/\\]+)[/\\]/)?.[1];
 
     if (fromScript) {
         return fromScript;
@@ -67,9 +67,242 @@ export function currentToolName(argv: string[] = process.argv, executable: strin
     return basename(script).replace(/\.[cm]?[jt]sx?$/, "") || basename(argv[0] ?? "") || "unknown";
 }
 
-/** `tools <tool> <args>`, cut to a length a window can show. Tokens never travel in argv (they go through stdin). */
+const CREDENTIAL_FLAGS = new Set(["--token", "--api-key", "--key", "--password", "--secret"]);
+
+/** The wakeup relay's -t means token; other tools use -t for non-secret options. */
+function hasTokenShortFlag(words: string[]): boolean {
+    return (
+        words.some(
+            (word) =>
+                /^(?:wakeup|gt-wakeup)$/.test(basename(word.replaceAll("\\", "/"))) ||
+                /[/\\]src[/\\]wakeup[/\\]/.test(word)
+        ) &&
+        words.includes("daemon") &&
+        words.includes("register")
+    );
+}
+
+/** Redact before joining or truncating argv so a separated credential cannot lose its flag. */
+export function redactCredentialArgs(argv: string[]): string[] {
+    const shortToken = hasTokenShortFlag(argv);
+    let hideNext = false;
+    return argv.map((word) => {
+        if (hideNext) {
+            hideNext = false;
+            return "[REDACTED]";
+        }
+
+        const equals = word.indexOf("=");
+        const flag = equals < 0 ? word : word.slice(0, equals);
+        if (!CREDENTIAL_FLAGS.has(flag) && !(shortToken && flag === "-t")) {
+            return redactCredentialHeaders(word);
+        }
+
+        hideNext = equals < 0;
+        return equals < 0 ? word : `${flag}=[REDACTED]`;
+    });
+}
+
+const SENSITIVE_QUERY_NAMES = new Set([
+    "token",
+    "accesstoken",
+    "refreshtoken",
+    "idtoken",
+    "apikey",
+    "key",
+    "password",
+    "passwd",
+    "secret",
+    "clientsecret",
+    "authorization",
+    "auth",
+    "credential",
+    "credentials",
+    "prompt",
+    "command",
+    "cmd",
+    "argv",
+    "args",
+]);
+
+function redactCredentialParams(params: URLSearchParams, depth: number): URLSearchParams {
+    const safe = new URLSearchParams();
+    for (const [name, value] of params) {
+        const sensitive = SENSITIVE_QUERY_NAMES.has(name.toLowerCase().replaceAll(/[-_]/g, ""));
+        safe.append(name, sensitive ? "[REDACTED]" : redactText(value, depth + 1));
+    }
+
+    return safe;
+}
+
+function redactCredentialUrl(raw: string, depth: number): string {
+    try {
+        const url = new URL(raw);
+        if (url.username || url.password) {
+            url.username = "[REDACTED]";
+            url.password = "";
+        }
+
+        url.search = redactCredentialParams(url.searchParams, depth).toString();
+
+        // An OAuth implicit-flow callback carries its tokens in the fragment (`#access_token=…`).
+        if (url.hash.includes("=")) {
+            url.hash = redactCredentialParams(new URLSearchParams(url.hash.slice(1)), depth).toString();
+        }
+
+        return url.toString();
+    } catch {
+        return "[REDACTED URL]";
+    }
+}
+
+const CREDENTIAL_HEADER_NAMES = "(?:Proxy-)?Authorization|[a-z0-9_.-]*(?:key|token|secret|cookie)[a-z0-9_.-]*";
+
+/** Scan UTF-16 units once; a whitespace run is inspected only at its start. */
+function headerValueEnd({ text, start, outer }: { text: string; start: number; outer: string | undefined }): number {
+    const space = (index: number) => text[index] === " " || text[index] === "\t";
+    const lineEnd = (index: number) => index >= text.length || text[index] === "\r" || text[index] === "\n";
+    const boundary = (index: number): { next: number; found: boolean } => {
+        let next = index;
+        while (space(next)) {
+            next++;
+        }
+        if (next === index) {
+            return { next, found: false };
+        }
+        let token = next;
+        while (text[token] === '"' || text[token] === "'") {
+            token++;
+        }
+        const flag = /^--?[a-z]/i.test(text.slice(token, token + 3));
+        const nameStart = token;
+        while (token < text.length && /[a-z0-9_.-]/i.test(text[token])) {
+            token++;
+        }
+        const named = token > nameStart;
+        while (space(token)) {
+            token++;
+        }
+        return { next, found: flag || (named && text[token] === ":") };
+    };
+    let index = start;
+    let previous = "";
+    while (!lineEnd(index)) {
+        if (space(index)) {
+            const run = boundary(index);
+            if (run.found) {
+                return index;
+            }
+            index = run.next;
+            continue;
+        }
+        const quote = text[index];
+        if (quote !== '"' && quote !== "'") {
+            previous = quote;
+            index++;
+            continue;
+        }
+        // A completed argument wrapper can precede another quoted header. Embedded value quotes
+        // after '=' (or at the start of the value) still belong to the credential.
+        const next = index + 1;
+        if (outer === quote && index > start && previous !== "=" && (lineEnd(next) || boundary(next).found)) {
+            return index;
+        }
+        let close = next;
+        while (!lineEnd(close) && text[close] !== quote) {
+            close += text[close] === "\\" && !lineEnd(close + 1) ? 2 : 1;
+        }
+        if (lineEnd(close)) {
+            return close;
+        }
+        previous = quote;
+        index = close + 1;
+    }
+    return index;
+}
+
+function redactedHeaderValue(name: string, value: string): string {
+    const scheme = /^(?:Proxy-)?Authorization$/i.test(name)
+        ? value.match(/^([a-z][a-z0-9+.-]*)[ \t]+\S/i)?.[1]
+        : undefined;
+    return `${scheme ? `${scheme} ` : ""}[REDACTED]`;
+}
+
+function redactCredentialHeaders(text: string): string {
+    const exact = new RegExp(`^([ \\t]*)(${CREDENTIAL_HEADER_NAMES})([ \\t]*:[ \\t]*)([^\\r\\n]*)$`, "i");
+    if (exact.test(text)) {
+        return text.replace(
+            exact,
+            (_match, prefix: string, name: string, colon: string, value: string) =>
+                `${prefix}${name}${colon}${redactedHeaderValue(name, value)}`
+        );
+    }
+
+    const inline = new RegExp(`(^|[\\s"']|(?:--header|-H)=["']?)(${CREDENTIAL_HEADER_NAMES})([ \\t]*:[ \\t]*)`, "gi");
+    let safe = "";
+    let copied = 0;
+    for (;;) {
+        const match = inline.exec(text);
+        if (!match) {
+            break;
+        }
+
+        const start = inline.lastIndex;
+        const prefix = match[1].at(-1);
+        const beforeFlag = text[match.index - 1];
+        const wrapper = prefix === '"' || prefix === "'" ? prefix : beforeFlag;
+        const outer = wrapper === '"' || wrapper === "'" ? wrapper : undefined;
+        const end = headerValueEnd({ text, start, outer });
+        safe += text.slice(copied, start) + redactedHeaderValue(match[2], text.slice(start, end));
+        copied = end;
+        inline.lastIndex = end;
+    }
+
+    return safe + text.slice(copied);
+}
+
+/** Also protects command facts, purposes and nested audit fields supplied as text. */
+export function redactCredentialText(text: string): string {
+    return redactText(text, 0);
+}
+
+function redactText(text: string, depth: number): string {
+    if (depth >= 8) {
+        return "[REDACTED]";
+    }
+
+    const safe = text.replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, (url) => redactCredentialUrl(url, depth));
+    const flags = hasTokenShortFlag(safe.split(/[\s/\\]+/))
+        ? "--(?:token|api-key|key|password|secret)|-t"
+        : "--(?:token|api-key|key|password|secret)";
+    const pattern = new RegExp(
+        String.raw`(^|[\s"'])(${flags})(=|\s+)("(?:\\[^\r\n]|[^"\\\r\n])*(?:"|\\?(?=$|[\r\n]))|'(?:\\[^\r\n]|[^'\\\r\n])*(?:'|\\?(?=$|[\r\n]))|[^\s;]+)`,
+        "g"
+    );
+    return redactCredentialHeaders(safe.replace(pattern, "$1$2$3[REDACTED]"));
+}
+
+export function redactCredentialFields(value: unknown): unknown {
+    if (typeof value === "string") {
+        return redactCredentialText(value);
+    }
+
+    if (Array.isArray(value)) {
+        return value.every((word) => typeof word === "string")
+            ? redactCredentialArgs(value).map(redactCredentialText)
+            : value.map(redactCredentialFields);
+    }
+
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, field]) => [key, redactCredentialFields(field)]));
+    }
+
+    return value;
+}
+
+/** `tools <tool> <args>`, with credentials redacted before cutting to a length a window can show. */
 export function currentCommandLine(argv: string[] = process.argv, max = 300): string {
-    const words = ["tools", currentToolName(argv), ...argv.slice(2)].map((word) =>
+    const words = redactCredentialArgs(["tools", currentToolName(argv), ...argv.slice(2)]).map((word) =>
         word.includes(" ") ? `"${word}"` : word
     );
     const line = words.join(" ");