pi-archimedes 2.10.4 → 2.11.0

package/README.md

@@ -23,7 +23,10 @@ One command:
 pi install npm:pi-archimedes
 ```
 
-Your `~/.pi/agent/` stays as it is — Archimedes only adds its namespaces under `settings.json`. Pi's own `auth.json`, `keybindings.json`, agents, and sessions are untouched.
+Your `~/.pi/agent/` stays as it is: Archimedes adds its namespaces under `settings.json`, and Pi's own `auth.json` and your sessions are never written. Two files get written, by the features that own them.
+
+- **`keybindings.json`** — only ever about the paste key, and only via step 6 below. The offer writes the file **only when it is absent and only if you accept** (an existing file is never edited by the offer), and what it writes is the `app.clipboard.pasteImage: []` unbinding from the snippet below, paired with its `"$schema"` line. Setting `archimedes.imagePaste.suppressNativePaste: false` removes that entry again, leaving `{}`. Both directions act on **the suite's own entry only**: a file holding a key of yours, a different `$schema`, a non-empty binding, or JSON that does not parse is left byte-for-byte alone, and you get one warning about it — naming the entry to remove when the file really holds one, and otherwise saying there is nothing of ours to remove. Your own bindings are never rewritten.
+- **`agents.local.json`**, plus any agent definition you create or edit with `/agents` — the subagent package's own files.
 
 Then run `/reload` in your session (or start a new one) to pick it up — that reloads the extensions *and* your keybindings, so any shortcuts you've customized in `~/.pi/agent/keybindings.json` keep working.
 
@@ -56,22 +59,29 @@ Then run `/reload` in your session (or start a new one) to pick it up — that r
    /model
    ```
 
-6. **Make image-paste own the paste keys** — Pi's built-in `app.clipboard.pasteImage` owns `Ctrl+V` (Linux/macOS) / `Alt+V` (Windows), and image-paste (on by default in the suite) binds the same keys — clear the built-in in `~/.pi/agent/keybindings.json` so image-paste takes them cleanly (otherwise both handlers fire on the shared key and the built-in throws warning banners; format in Pi's [keybindings docs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/keybindings.md)). If the file doesn't exist yet, create it with:
+6. **Make image-paste own the paste keys** — Pi's built-in `app.clipboard.pasteImage` owns `Ctrl+V` (Linux/macOS) / `Alt+V` (Windows), and image-paste (on by default in the suite) binds the same keys — clear the built-in in `~/.pi/agent/keybindings.json` so image-paste takes them cleanly. Left as is, **only one handler runs**: an extension shortcut beats a non-reserved built-in, so Pi adds a `[Extension issues]` line (`Extension shortcut conflict: 'ctrl+v' is built-in shortcut for app.clipboard.pasteImage and <ext>. Using <ext>`) and its own action never fires — measured on Pi 1.2.0, one `Ctrl+V`, one insertion, the extension's (format in Pi's [keybindings docs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/keybindings.md)). If the file doesn't exist yet, create it with:
 
    ```json
    {
+     "$schema": "https://pi.dev/schemas/keybindings.schema.json",
      "app.clipboard.pasteImage": []
    }
    ```
 
-   If it already exists, just add/set `"app.clipboard.pasteImage": []` in there and run `/reload`. Or skip the step entirely if the file doesn't exist yet: on the first TUI session the suite offers to create it automatically with the snippet above — accepting creates the file and attempts an automatic reload where the runtime supports it (on current Pi 0.85.1 you're notified to run `/reload`, and the cleared binding applies once it runs); declining or cancelling (Esc) never asks again.
+   The `$schema` line is optional (Pi skips that key when loading the file) — it exists so an editor or a standalone validator can check the file against Pi's published schema, and it's what the first-run offer below writes.
+
+   If it already exists, just add/set `"app.clipboard.pasteImage": []` in there and run `/reload`. Or skip the step entirely if the file doesn't exist yet: on the first TUI session the suite offers to create it automatically with the snippet above — accepting creates the file and then tells you to run `/reload` (measured on Pi 1.2.0: the context an event handler receives has no `reload`, so the automatic path is a notification rather than a reload, and the cleared binding applies once you run it); declining or cancelling (Esc) never asks again. The offer only appears in an install that is going to hold the paste key: if you have set `archimedes.imagePaste.suppressNativePaste: false` first, it never shows, because there is nothing to unbind (and it does not spend its "already asked" flag on that way in, so turning the flag back on still gets you the offer).
+
+   **Want Pi's own paste back?** Set `archimedes.imagePaste.suppressNativePaste: false`. Turning it off removes the suite's `app.clipboard.pasteImage` unbinding from `~/.pi/agent/keybindings.json` (its own entry only, leaving `{}`) **and stops the suite binding that key** — while the flag is off no paste shortcut is registered at all — so Pi's native `app.clipboard.pasteImage` really runs again: `/new` or `/reload` applies it, no restart and no hand-editing files. The cost, in one sentence: with the flag off you get Pi's paste and lose image-paste's image attach, its multi-image queue and the preview **on that key**, because no keypress reaches our handler until you turn it back on. The default (key absent, meaning on) is what keeps the image-attaching paste. If that file holds anything other than the suite's own entry, the suite leaves it alone and tells you so once — and Pi's own paste is answering the key there unless the file itself carries the `[]` unbinding.
 
 `/login` signs you into a supported provider (subscription or API key) and `/model` selects a model from it. Model access comes through the providers you configure in Pi — Pi's [provider docs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md) list the supported ones, and Archimedes doesn't ship a model of its own. For the broader first run, Pi's [quickstart](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md) is worth a read.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/danielcherubini/pi-archimedes/main/docs/images/splash-screen.png" width="600" alt="pi-archimedes splash screen">
+  <img src="https://raw.githubusercontent.com/danielcherubini/pi-archimedes/main/docs/images/splash-screen.png" width="600" alt="The opt-in Archimedes startup splash: the ASCII logo above pi's own startup listing">
 </p>
 
+<p align="center"><sub>The startup splash is opt-in — turn it on with <code>/archimedes</code> → Startup Splash. Out of the box Pi's own startup screen is left in place.</sub></p>
+
 ---
 
 ## Give your agent some backup.
@@ -163,21 +173,27 @@ Only want the diffs or footer? Each component is available separately — see [C
 
 Every component keeps its own namespace under `~/.pi/agent/settings.json`, which Pi parses as **strict JSON**. Each component's README documents its namespace, fields, and defaults — including [core](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/core/README.md) (chrome, spinner, thinking), [footer](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/footer/README.md), [diff](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/diff/README.md), [notify](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/notify/README.md), [image-paste](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/image-paste/README.md), and [sudo](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/sudo/README.md) (also strict JSON). The `/archimedes` panel covers the settings that have a control; not everything does.
 
+### Custom themes must validate against Pi's schema
+
+Pi 1.2.0 validates `~/.pi/agent/themes/*.json` at startup against `theme.schema.json`, and that schema is **`additionalProperties: false`** — on the top-level object and on `colors`. A custom theme that carried extra metadata of its own (`"author"`, `"notes"`, a private palette block, a leftover key from another editor) used to load anyway; now it is refused, the theme is not applied, and Pi reports it as a startup warning. Earlier Pi validated theme JSON too, but without the `additionalProperties` clause, which is why this can arrive as a surprise on upgrade. Move whatever Pi doesn't define out of the theme file, and put `"$schema": "https://pi.dev/schemas/theme.schema.json"` in it so your editor tells you before Pi does. This is Pi's own behaviour — the suite writes no theme files.
+
 ---
 
 ## Components
 
 | Component | npm package | What it adds |
 |-----------|-------------|--------------|
-| **Core** | [`@pi-archimedes/core`](https://www.npmjs.com/package/@pi-archimedes/core) | Shared event bus, splash screen, framed editor, working spinner, thinking blocks |
+| **Core** | [`@pi-archimedes/core`](https://www.npmjs.com/package/@pi-archimedes/core) | Shared plumbing — `pi.events` channel vocabulary, overlay chrome, settings I/O, tool-row rendering |
+| **UI** | [`@pi-archimedes/ui`](https://www.npmjs.com/package/@pi-archimedes/ui) | Framed editor with a working spinner, bash + codemode tool-row styling, thinking collapse, opt-in startup splash |
 | **Subagent** | [`@pi-archimedes/subagent`](https://www.npmjs.com/package/@pi-archimedes/subagent) | Live subagent dispatch, custom agent definitions; `/agents` editor with the suite |
 | **Todo** | [`@pi-archimedes/todo`](https://www.npmjs.com/package/@pi-archimedes/todo) | Multi-column todo board with subagent columns and auto-clear |
 | **Ask** | [`@pi-archimedes/ask`](https://www.npmjs.com/package/@pi-archimedes/ask) | Structured questions — including subagent questions relayed into your terminal |
 | **Sudo** | [`@pi-archimedes/sudo`](https://www.npmjs.com/package/@pi-archimedes/sudo) | `sudo_exec` with masked password prompt and interactive-sudo guard |
-| **Diff** | [`@pi-archimedes/diff`](https://www.npmjs.com/package/@pi-archimedes/diff) | Syntax-highlighted side-by-side and unified diffs with word-level highlights |
+| **Diff** | [`@pi-archimedes/diff`](https://www.npmjs.com/package/@pi-archimedes/diff) | Syntax-highlighted side-by-side and unified diffs with word-level highlights, drawn into pi's `edit`/`write` tool rows |
 | **Footer** | [`@pi-archimedes/footer`](https://www.npmjs.com/package/@pi-archimedes/footer) | Branch, model, context usage, and token/cost status bar |
 | **Image Paste** | [`@pi-archimedes/image-paste`](https://www.npmjs.com/package/@pi-archimedes/image-paste) | Clipboard image paste with inline previews |
 | **Notify** | [`@pi-archimedes/notify`](https://www.npmjs.com/package/@pi-archimedes/notify) | Delayed desktop notifications with input cancellation |
+| **Web** | [`@pi-archimedes/web`](https://www.npmjs.com/package/@pi-archimedes/web) | `web_search`, `fetch_content` and `get_search_content` with multi-provider routing |
 | **Session Name** | [`@pi-archimedes/session-name`](https://www.npmjs.com/package/@pi-archimedes/session-name) | Automatic session titles |
 
 The full suite is the supported connected setup — the integrations above (subagent costs in the footer, subagent columns on the todo board, subagent questions in the terminal) light up when the relevant components are loaded together.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-archimedes",
-  "version": "2.10.4",
+  "version": "2.11.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -16,26 +16,26 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.10.4",
-    "@pi-archimedes/footer": "2.10.4",
-    "@pi-archimedes/diff": "2.10.4",
-    "@pi-archimedes/ask": "2.10.4",
-    "@pi-archimedes/image-paste": "2.10.4",
-    "@pi-archimedes/subagent": "2.10.4",
-    "@pi-archimedes/todo": "2.10.4",
-    "@pi-archimedes/notify": "2.10.4",
-    "@pi-archimedes/session-name": "2.10.4",
-    "@pi-archimedes/sudo": "2.10.4",
-    "@pi-archimedes/ui": "2.10.4",
-    "@pi-archimedes/web": "2.10.4"
+    "@pi-archimedes/core": "2.11.0",
+    "@pi-archimedes/footer": "2.11.0",
+    "@pi-archimedes/diff": "2.11.0",
+    "@pi-archimedes/ask": "2.11.0",
+    "@pi-archimedes/image-paste": "2.11.0",
+    "@pi-archimedes/subagent": "2.11.0",
+    "@pi-archimedes/todo": "2.11.0",
+    "@pi-archimedes/notify": "2.11.0",
+    "@pi-archimedes/session-name": "2.11.0",
+    "@pi-archimedes/sudo": "2.11.0",
+    "@pi-archimedes/ui": "2.11.0",
+    "@pi-archimedes/web": "2.11.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.1.0",
-    "@earendil-works/pi-tui": ">=0.1.0"
+    "@earendil-works/pi-coding-agent": ">=1.2.0",
+    "@earendil-works/pi-tui": ">=1.2.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.87.0",
-    "@earendil-works/pi-tui": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "typescript": "^6.0.0"
   },
   "pi": {

package/src/factory-lifecycle.test.ts

@@ -51,12 +51,18 @@ vi.mock("@pi-archimedes/core/profiler", () => ({
   print: vi.fn(),
   reset: vi.fn(),
 }));
+// Diagnostics go to the log sink, never the console (core/src/log.ts), so the
+// failure assertions below watch `diag`.
+vi.mock("@pi-archimedes/core/log", async (importOriginal) => {
+  const real = await importOriginal<typeof import("@pi-archimedes/core/log")>();
+  return { ...real, diag: vi.fn() };
+});
+import { diag } from "@pi-archimedes/core/log";
 vi.mock("@pi-archimedes/core", () => ({
   registerCore: vi.fn(),
 }));
 vi.mock("@pi-archimedes/ui", () => ({
   registerUI: vi.fn(),
-  unpatchConsoleLog: vi.fn(),
 }));
 vi.mock("@pi-archimedes/footer", () => ({ registerFooter: vi.fn() }));
 vi.mock("@pi-archimedes/todo", () => ({ registerTodo: vi.fn() }));
@@ -78,11 +84,15 @@ vi.mock("@pi-archimedes/image-paste", () => ({
 }));
 vi.mock("@pi-archimedes/image-paste/keybinding-offer", () => ({
   offerKeybindingFix: vi.fn(),
+  runNativePasteRestore: vi.fn(async () => ({ kind: "suppressed" })),
 }));
 vi.mock("@pi-archimedes/subagent", () => ({
   registerSubagent: vi.fn(),
   registerAgentsCommand: vi.fn(),
 }));
+// Mocked so the composed-handler tests can order-check EVERY registration in
+// the lazy-load handler (and so those tests do not load the real web package).
+vi.mock("@pi-archimedes/web", () => ({ registerWeb: vi.fn() }));
 
 // Meta-local modules the factory imports — not under test here
 vi.mock("./config.js", () => ({ loadDiffConfig: vi.fn(() => ({})) }));
@@ -96,10 +106,12 @@ const { default: metaFactory } = await import("./index.js");
 
 const { registerImagePaste, shutdownImagePaste, initImagePasteSession } =
   await import("@pi-archimedes/image-paste");
-const { unpatchConsoleLog } = await import("@pi-archimedes/ui");
 
-const { offerKeybindingFix } =
+const { offerKeybindingFix, runNativePasteRestore } =
   await import("@pi-archimedes/image-paste/keybinding-offer");
+const { registerDiffTools } = await import("@pi-archimedes/diff");
+const { registerSubagent, registerAgentsCommand } = await import("@pi-archimedes/subagent");
+const { registerWeb } = await import("@pi-archimedes/web");
 const { runOnboarding } = await import("./onboarding/index.js");
 
 // ── Stub pi: record pi.on() registrations and command/tool registrations ───
@@ -190,7 +202,6 @@ describe("image-paste factory lifecycle (registration is config-gated, teardown
     // Session ends → cleanup MUST still run for this session's registration.
     shutdownSession();
     expect(vi.mocked(shutdownImagePaste)).toHaveBeenCalledTimes(1);
-    expect(vi.mocked(unpatchConsoleLog)).toHaveBeenCalledTimes(1);
   });
 
   it("registers nothing and tears down nothing when config is off at session start", async () => {
@@ -280,6 +291,8 @@ describe("first-run sequencing (session_start → offerKeybindingFix, then runOn
     vi.mocked(offerKeybindingFix).mockRejectedValueOnce(new Error("boom"));
     const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
 
+    const diagBefore = vi.mocked(diag).mock.calls.length;
+
     const ctx = { ui: { theme: "dark" } };
     const { fireFirstRunHandler } = freshFactory();
 
@@ -289,14 +302,139 @@ describe("first-run sequencing (session_start → offerKeybindingFix, then runOn
     // Drain the microtask queue so the .catch() branch has had time to run.
     await new Promise((r) => setTimeout(r, 0));
 
-    // The rejection must have been swallowed and logged — not re-thrown.
-    expect(consoleSpy).toHaveBeenCalledWith(
-      "[archimedes] keybinding offer failed:",
-      expect.any(Error),
-    );
+    // The rejection must have been swallowed and diagnosed — not re-thrown,
+    // and not printed to the console.
+    const lines = vi.mocked(diag).mock.calls.slice(diagBefore).map(([scope, message]) => `${scope} ${message}`);
+    expect(lines.some((l) => l.includes("keybinding offer failed") && l.includes("boom"))).toBe(true);
     // A failed offer must not block the onboarding (reloaded stays false).
     expect(vi.mocked(runOnboarding)).toHaveBeenCalledTimes(1);
+    // …and nothing about the failure reaches the console.
+    expect(consoleSpy).not.toHaveBeenCalled();
+
+    consoleSpy.mockRestore();
+  });
+});
+
+// ── the composed-suite call site for restoreNativePaste (ADR 0030 amendment) ─
+//
+// `suppressNativePaste: false` has to give ctrl+v back on a machine that already
+// accepted the first-run offer. The composed suite — not image-paste's own
+// standalone handler — is what loads the package here, so meta's session_start
+// is the call site. Registration stays gated: a disabled image-paste must not
+// reach into the user's keybindings.json (ADR 0012 — the plugin gate is
+// registration, not an in-package `enabled` read).
+describe("native-paste restore call site (composed suite)", () => {
+  // The placement of the restore in the composed handler is a deliberate
+  // deviation (ADR 0030 amendment): it is the LAST statement, because a
+  // successful restore can call ctx.reload(), which invalidates this ctx.
+  // These two tests are the fence around that placement — one for "nothing
+  // earlier is skipped", one for "nothing later touches the ctx".
+  it("runs AFTER every other registration the composed handler performs (it is last)", async () => {
+    const { startSession } = freshFactory();
+
+    await startSession({ ui: { theme: "dark" }, hasUI: true });
+
+    const restoreOrder = vi.mocked(runNativePasteRestore).mock.invocationCallOrder[0];
+    expect(restoreOrder, "the restore did not run").toBeDefined();
+    const before: Array<[string, unknown]> = [
+      ["registerDiffTools", registerDiffTools],
+      ["registerImagePaste", registerImagePaste],
+      ["initImagePasteSession", initImagePasteSession],
+      ["registerSubagent", registerSubagent],
+      ["registerAgentsCommand", registerAgentsCommand],
+      ["registerWeb", registerWeb],
+    ];
+    for (const [name, fn] of before) {
+      const spy = vi.mocked(fn as (...args: unknown[]) => unknown);
+      expect(spy, `${name} never ran`).toHaveBeenCalledTimes(1);
+      expect(
+        spy.mock.invocationCallOrder[0],
+        `${name} must run before the restore — the restore's reload invalidates ctx`,
+      ).toBeLessThan(restoreOrder as number);
+    }
+  });
+
+  it("when the restore reloads, that reload is the LAST interaction with the session ctx", async () => {
+    const used: string[] = [];
+    let reloadCalls = 0;
+    const ui = {
+      theme: "dark",
+      notify: () => {
+        used.push("ui.notify");
+      },
+    };
+    const ctx = {
+      hasUI: true,
+      mode: "tui",
+      ui: new Proxy(ui, {
+        get(target, prop) {
+          used.push(`ui.${String(prop)}`);
+          return (target as Record<string, unknown>)[prop as string];
+        },
+      }),
+      reload: async () => {
+        reloadCalls += 1;
+        used.push("reload");
+      },
+    };
+    // What a real successful restore does: reload, and never use ctx again.
+    vi.mocked(runNativePasteRestore).mockImplementationOnce(async (c: unknown) => {
+      used.push("restore");
+      await (c as { reload: () => Promise<void> }).reload();
+      return { kind: "restored", path: "/tmp/keybindings.json", reloadRequired: false };
+    });
+
+    const { startSession } = freshFactory();
+
+    await startSession(ctx);
+
+    expect(reloadCalls).toBe(1);
+    expect(used[used.length - 1], `ctx used after reload: ${used.join(" → ")}`).toBe("reload");
+  });
+
+  it("runs once per session with that session's ctx when image-paste was loaded", async () => {
+    const ctx = { ui: { theme: "dark" }, hasUI: true };
+    const { startSession } = freshFactory();
 
+    await startSession(ctx);
+
+    expect(vi.mocked(runNativePasteRestore)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(runNativePasteRestore)).toHaveBeenCalledWith(ctx);
+  });
+
+  it("does not run when image-paste is disabled at session start (the plugin gate covers it)", async () => {
+    mockStore["archimedes.imagePaste"] = { enabled: false };
+    const { startSession } = freshFactory();
+
+    await startSession({ ui: { theme: "dark" } });
+
+    expect(vi.mocked(registerImagePaste)).not.toHaveBeenCalled();
+    expect(vi.mocked(runNativePasteRestore)).not.toHaveBeenCalled();
+  });
+
+  it("session_start still resolves when the restore runner rejects, and the failure is diagnosed — never printed", async () => {
+    vi.mocked(runNativePasteRestore).mockRejectedValueOnce(new Error("restore boom"));
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const diagBefore = vi.mocked(diag).mock.calls.length;
+
+    const { startSession } = freshFactory();
+
+    let thrown: unknown = null;
+    try {
+      await startSession({ ui: { theme: "dark" }, hasUI: true });
+    } catch (error) {
+      thrown = error;
+    }
+
+    expect(thrown).toBeNull();
+    const lines = vi
+      .mocked(diag)
+      .mock.calls.slice(diagBefore)
+      .map(([scope, message]) => `${scope} ${message}`);
+    expect(lines.some((l) => l.includes("native paste restore failed") && l.includes("restore boom"))).toBe(
+      true,
+    );
+    expect(consoleSpy).not.toHaveBeenCalled();
     consoleSpy.mockRestore();
   });
 });

package/src/index.ts

@@ -1,8 +1,10 @@
 import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
 import { time as archTime, print as archPrintTimings, reset as archResetTimings } from "@pi-archimedes/core/profiler";
+import { diag, describeError } from "@pi-archimedes/core/log";
+import { takePiSupportNotice } from "@pi-archimedes/core/pi-support";
 import { registerCore } from "@pi-archimedes/core";
-import { registerUI, unpatchConsoleLog } from "@pi-archimedes/ui";
+import { registerUI } from "@pi-archimedes/ui";
 import { registerFooter } from "@pi-archimedes/footer";
 
 // Mark when module finishes evaluating (before factory runs) for gap analysis
@@ -18,7 +20,12 @@ import { registerSudo } from "@pi-archimedes/sudo";
 // Light module from the image-paste package (no heavy deps) — the offer
 // gates are self-contained, so it is statically imported and sequenced in
 // the first-run session_start handler below, before the lazy-load.
-import { offerKeybindingFix } from "@pi-archimedes/image-paste/keybinding-offer";
+// `runNativePasteRestore` is the composed-suite call site for the same module
+// (ADR 0030 amendment — see the bottom of the lazy-load session_start handler).
+import {
+  offerKeybindingFix,
+  runNativePasteRestore,
+} from "@pi-archimedes/image-paste/keybinding-offer";
 import { runOnboarding } from "./onboarding/index.js";
 import { loadDiffConfig } from "./config.js";
 import { openSettings } from "./settings.js"
@@ -81,7 +88,6 @@ export default function (pi: ExtensionAPI): void {
     // re-execute a stale ref.
     imagePasteShutdown?.();
     imagePasteShutdown = undefined;
-    unpatchConsoleLog();
     archPrintTimings();
   });
 
@@ -95,8 +101,12 @@ export default function (pi: ExtensionAPI): void {
   // is exactly the same key the module's own gate 1 already checks — adding
   // a wrapper here would be a redundant duplicate of the identical check.
   // This handler runs unconditionally on every session_start; the offer's
-  // five gates (and the onboarding's two) make it a no-op when not
-  // applicable.
+  // gates (1, 1b, 2–4; and the onboarding's two) make it a no-op when not
+  // applicable. Gate 1b is the one that keeps the two paste-key flows apart:
+  // under one setting value the offer acts only while the suite will hold the
+  // key and `runNativePasteRestore`, at the end of the registration handler
+  // below, only while it will not — so a single session can never create
+  // keybindings.json and empty it again (issue #133).
   pi.on("session_start", async (_event, ctx: ExtensionContext) => {
     // The offer may block on a user confirm; it must never fail session
     // startup — any throw is logged, never propagated.
@@ -104,13 +114,15 @@ export default function (pi: ExtensionAPI): void {
     try {
       reloaded = await offerKeybindingFix(ctx);
     } catch (e) {
-      console.error("[archimedes] keybinding offer failed:", e);
+      diag("meta", `[archimedes] keybinding offer failed: ${describeError(e)}`);
     }
     // If the offer triggered a reload, the fresh session runs this handler
     // again (where the offer is a no-op — keybindings.json now exists), so
     // do NOT run the onboarding on the now-stale ctx.
     if (reloaded) return;
-    void runOnboarding(ctx).catch((err) => console.error("[archimedes] onboarding failed:", err));
+    void runOnboarding(ctx).catch((err) =>
+      diag("meta", `[archimedes] onboarding failed: ${describeError(err)}`),
+    );
   });
   archTime("first-run handler");
 
@@ -123,17 +135,17 @@ export default function (pi: ExtensionAPI): void {
     // ── Parallel lazy-load all four packages (saves ~100ms vs sequential) ──
     const [diffMod, ipMod, saMod, webMod] = await Promise.all([
       isPluginEnabled("diff")
-        ? import("@pi-archimedes/diff").catch((e) => { console.error("[archimedes] diff load failed:", e); return null; })
+        ? import("@pi-archimedes/diff").catch((e) => { diag("meta", `[archimedes] diff load failed: ${describeError(e)}`); return null; })
         : Promise.resolve(null),
       isPluginEnabled("image-paste")
-        ? import("@pi-archimedes/image-paste").catch((e) => { console.error("[archimedes] image-paste load failed:", e); return null; })
+        ? import("@pi-archimedes/image-paste").catch((e) => { diag("meta", `[archimedes] image-paste load failed: ${describeError(e)}`); return null; })
         : Promise.resolve(null),
       isPluginEnabled("subagent")
-        ? import("@pi-archimedes/subagent").catch((e) => { console.error("[archimedes] subagent load failed:", e); return null; })
+        ? import("@pi-archimedes/subagent").catch((e) => { diag("meta", `[archimedes] subagent load failed: ${describeError(e)}`); return null; })
         : Promise.resolve(null),
       isPluginEnabled("web")
         ? import("@pi-archimedes/web").catch((e) => {
-            console.error("[archimedes] web load failed:", e);
+            diag("meta", `[archimedes] web load failed: ${describeError(e)}`);
             return null;
           })
         : Promise.resolve(null),
@@ -166,6 +178,40 @@ export default function (pi: ExtensionAPI): void {
     if (webMod) {
       webMod.registerWeb(pi);
     }
+
+    // One aggregated host-version notice, never one per package (ADR 0026).
+    // Every package reports during its own registration — the ones above, and
+    // `ui`/`footer`/… from the factory — so this is the only place the suite
+    // shows it. Reading the notice spends it: a second `session_start` (`/new`,
+    // `/fork`) or a `/reload` (fresh modules, same process, and the same pi
+    // version — it cannot change without a restart) stays quiet. `notify` is a
+    // no-op outside a UI, so `diag` records it too: headless runs and subagent
+    // children have no surface to show, but they do have the log file.
+    const piNotice = takePiSupportNotice();
+    if (piNotice) {
+      diag("meta", piNotice);
+      ctx.ui?.notify?.(piNotice, "warning");
+    }
+
+    // ── Native-paste restoration (ADR 0030 amendment, 2026-10-13) ──
+    // `archimedes.imagePaste.suppressNativePaste: false` hands ctrl+v back to
+    // pi in two halves: this call deletes the suite's own
+    // `app.clipboard.pasteImage` unbinding from
+    // ~/.pi/agent/keybindings.json, and the gate inside `registerImagePaste`
+    // (above) stops image-paste registering a shortcut for the key — without it
+    // pi 1.2.0 keeps the extension shortcut and the restored binding never
+    // runs. Gated on ipMod: the registration gate is what ADR 0012 permits (a
+    // package never reads its own `enabled` flag), so a disabled image-paste
+    // never reaches into the file. Deliberately the LAST thing in this handler —
+    // a successful restore can call ctx.reload(), which invalidates this ctx, so
+    // nothing may use it afterwards.
+    if (ipMod) {
+      try {
+        await runNativePasteRestore(ctx);
+      } catch (e) {
+        diag("meta", `[archimedes] native paste restore failed: ${describeError(e)}`);
+      }
+    }
   });
 
   // Register /archimedes command

package/src/onboarding/index.test.ts

@@ -362,6 +362,8 @@ describe("runOnboarding write logic (onDone)", () => {
     // The failed write aborts before the marker write → NOT set (a later
     // session re-runs the onboarding and retries).
     expect(mockStore["archimedes.meta"]?.onboarded).not.toBe(true);
+    // The cause is diagnosed in the log file, never printed to the console.
+    expect(consoleSpy).not.toHaveBeenCalled();
     consoleSpy.mockRestore();
   });
 

package/src/onboarding/index.ts

@@ -1,5 +1,6 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { loadConfig, updateConfig } from "@pi-archimedes/core/settings-io";
+import { diag, describeError } from "@pi-archimedes/core/log";
 import { OVERLAY_CHROME } from "@pi-archimedes/core/overlay";
 import {
   DEFAULT_UI_CONFIG,
@@ -57,7 +58,8 @@ export async function runOnboarding(ctx: ExtensionContext): Promise<void> {
       }
       updateConfig(META_NS, { onboarded: false }, (c) => ({ ...c, onboarded: true })); // marker last
     } catch (err) {
-      console.error("[archimedes] onboarding save failed:", err); // marker NOT set → self-heals
+      // marker NOT set → self-heals; the cause belongs in the log file.
+      diag("meta", `[archimedes] onboarding save failed: ${describeError(err)}`);
     }
   };