pi-archimedes 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-archimedes",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,16 +11,17 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.3.0",
-    "@pi-archimedes/diff": "2.3.0",
-    "@pi-archimedes/footer": "2.3.0",
-    "@pi-archimedes/image-paste": "2.3.0",
-    "@pi-archimedes/notify": "2.3.0",
-    "@pi-archimedes/subagent": "2.3.0",
-    "@pi-archimedes/todo": "2.3.0",
-    "@pi-archimedes/ask": "2.3.0",
-    "@pi-archimedes/session-name": "2.3.0",
-    "@pi-archimedes/mcp": "2.3.0"
+    "@pi-archimedes/core": "2.4.0",
+    "@pi-archimedes/footer": "2.4.0",
+    "@pi-archimedes/diff": "2.4.0",
+    "@pi-archimedes/ask": "2.4.0",
+    "@pi-archimedes/image-paste": "2.4.0",
+    "@pi-archimedes/subagent": "2.4.0",
+    "@pi-archimedes/notify": "2.4.0",
+    "@pi-archimedes/mcp": "2.4.0",
+    "@pi-archimedes/sudo": "2.4.0",
+    "@pi-archimedes/session-name": "2.4.0",
+    "@pi-archimedes/todo": "2.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.1.0",

package/src/config.ts

@@ -92,7 +92,6 @@ import { loadSessionNameConfig } from "@pi-archimedes/session-name";
 export type { SessionNameSettings } from "@pi-archimedes/session-name";
 
 export const DEFAULT_SESSION_NAME_CONFIG: SessionNameSettings = {
-  enabled: true,
   model: undefined,
 };
 

package/src/factory-lifecycle.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ── Factory lifecycle: image-paste registration (session_start) vs ─────────
+// teardown (session_shutdown), gated by a *mutable* config that can be
+// toggled mid-session via /plugins. Teardown must be liveness-based (the
+// module-level ref itself records "this session registered image-paste"),
+// not config-based.
+
+// ── Mock settings-io with an in-memory store (mirrors plugins.test.ts) ────
+
+vi.mock("@pi-archimedes/core/settings-io", () => {
+  const store: Record<string, unknown> = {};
+  return {
+    loadConfig: vi.fn(
+      (ns: string, defaults: object) =>
+        ({ ...defaults, ...((store[ns] as object) ?? {}) }),
+    ),
+    saveConfig: vi.fn((ns: string, config: object) => {
+      store[ns] = config;
+    }),
+    removeConfig: vi.fn((ns: string) => {
+      delete store[ns];
+    }),
+    isConfigEnabled: vi.fn((ns: string) => {
+      const cfg = (store[ns] ?? {}) as Record<string, unknown>;
+      return cfg.enabled !== false;
+    }),
+    setConfigEnabled: vi.fn((ns: string, enabled: boolean) => {
+      if (enabled) {
+        const cfg = { ...((store[ns] as object) ?? {}) } as Record<string, unknown>;
+        delete cfg.enabled;
+        if (Object.keys(cfg).length === 0) delete store[ns];
+        else store[ns] = cfg;
+      } else {
+        store[ns] = { ...((store[ns] as object) ?? {}), enabled: false };
+      }
+    }),
+    // Exposed for test setup/teardown only
+    __store: store,
+  };
+});
+
+const settingsIo = await import("@pi-archimedes/core/settings-io");
+const mockStore = (settingsIo as unknown as { __store: Record<string, unknown> }).__store;
+
+// ── Mock every package the factory touches so the factory test is hermetic ─
+
+// Static top-level imports of the factory
+vi.mock("@pi-archimedes/core/profiler", () => ({
+  time: vi.fn(),
+  print: vi.fn(),
+  reset: vi.fn(),
+}));
+vi.mock("@pi-archimedes/core", () => ({
+  registerCore: vi.fn(),
+  unpatchConsoleLog: vi.fn(),
+}));
+vi.mock("@pi-archimedes/footer", () => ({ registerFooter: vi.fn() }));
+vi.mock("@pi-archimedes/todo", () => ({ registerTodo: vi.fn() }));
+vi.mock("@pi-archimedes/ask", () => ({ registerAsk: vi.fn() }));
+vi.mock("@pi-archimedes/notify", () => ({ registerNotify: vi.fn() }));
+vi.mock("@pi-archimedes/session-name", () => ({ registerSessionName: vi.fn() }));
+
+// Dynamic imports done in the session_start handler — mock EXACTLY the
+// properties index.ts uses via destructured `ipMod.*` / `diffMod` / `saMod` /
+// `mcpMod` access (import result objects, not named destructure).
+vi.mock("@pi-archimedes/diff", () => ({
+  registerDiffTools: vi.fn(),
+}));
+vi.mock("@pi-archimedes/image-paste", () => ({
+  registerImagePaste: vi.fn(),
+  shutdownImagePaste: vi.fn(),
+  initImagePasteSession: vi.fn(),
+}));
+vi.mock("@pi-archimedes/subagent", () => ({
+  registerSubagent: vi.fn(),
+  registerAgentsCommand: vi.fn(),
+}));
+vi.mock("@pi-archimedes/mcp", () => ({
+  registerMcp: vi.fn(),
+}));
+
+// Meta-local modules the factory imports — not under test here
+vi.mock("./config.js", () => ({ loadDiffConfig: vi.fn(() => ({})) }));
+vi.mock("./settings.js", () => ({ openSettings: vi.fn() }));
+vi.mock("./plugin-manager.js", () => ({ registerPluginsCommand: vi.fn() }));
+
+// The real plugins.ts gate semantics are what these tests exercise
+// (read via the mocked settings-io on each call → mutable mid-session).
+const { default: metaFactory } = await import("./index.js");
+
+const { registerImagePaste, shutdownImagePaste, initImagePasteSession } =
+  await import("@pi-archimedes/image-paste");
+
+// ── Stub pi: record pi.on() registrations and command/tool registrations ───
+
+interface PiHarness {
+  pi: never;
+  handlers: Record<string, Array<(...args: unknown[]) => unknown>>;
+  commands: Map<string, unknown>;
+  tools: string[];
+}
+
+function makePi(): PiHarness {
+  const handlers: Record<string, Array<(...args: unknown[]) => unknown>> = {};
+  const commands = new Map<string, unknown>();
+  const tools: string[] = [];
+  const pi = {
+    on(event: string, handler: (...args: unknown[]) => unknown) {
+      (handlers[event] ??= []).push(handler);
+    },
+    registerCommand: (name: string, def: unknown) => {
+      commands.set(name, def);
+    },
+    registerTool: (name: string) => {
+      tools.push(name);
+    },
+  };
+  return { pi: pi as never, handlers, commands, tools };
+}
+
+/** Run the meta factory against a fresh stub pi and expose the latest
+ *  session_start / session_shutdown handlers captured by pi.on(). */
+function freshFactory(): {
+  harness: PiHarness;
+  startSession: (ctx: unknown) => Promise<unknown>;
+  shutdownSession: () => unknown;
+} {
+  const harness = makePi();
+  metaFactory(harness.pi);
+
+  const startRcs = harness.handlers["session_start"] ?? [];
+  const shutdownRcs = harness.handlers["session_shutdown"] ?? [];
+  expect(startRcs.length).toBeGreaterThan(0);
+  expect(shutdownRcs.length).toBeGreaterThan(0);
+  const startRc = (startRcs[startRcs.length - 1] ?? expect.fail("no session_start handler")) as (...args: unknown[]) => unknown;
+  const shutdownRc = (shutdownRcs[shutdownRcs.length - 1] ?? expect.fail("no session_shutdown handler")) as (...args: unknown[]) => unknown;
+
+  return {
+    harness,
+    startSession: (ctx: unknown) => startRc(undefined, ctx) as Promise<unknown>,
+    shutdownSession: () => shutdownRc(undefined, {}),
+  };
+}
+
+beforeEach(() => {
+  for (const key of Object.keys(mockStore)) delete mockStore[key];
+  vi.clearAllMocks();
+});
+
+describe("image-paste factory lifecycle (registration is config-gated, teardown is liveness-gated)", () => {
+  it("still runs shutdownImagePaste when the plugin is toggled OFF mid-session (via /plugins)", async () => {
+    // Store empty → image-paste enabled by default at session start
+    const { startSession, shutdownSession } = freshFactory();
+    await startSession({});
+    expect(vi.mocked(registerImagePaste)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(initImagePasteSession)).toHaveBeenCalledTimes(1);
+
+    // Mid-session: user toggles image-paste OFF via /plugins (persists
+    // immediately to its own namespace).
+    mockStore["archimedes.imagePaste"] = { enabled: false };
+
+    // Session ends → cleanup MUST still run for this session's registration.
+    shutdownSession();
+    expect(vi.mocked(shutdownImagePaste)).toHaveBeenCalledTimes(1);
+  });
+
+  it("registers nothing and tears down nothing when config is off at session start", async () => {
+    mockStore["archimedes.imagePaste"] = { enabled: false };
+    const { startSession, shutdownSession } = freshFactory();
+    await startSession({});
+    expect(vi.mocked(registerImagePaste)).not.toHaveBeenCalled();
+    expect(vi.mocked(initImagePasteSession)).not.toHaveBeenCalled();
+
+    shutdownSession();
+    expect(vi.mocked(shutdownImagePaste)).not.toHaveBeenCalled();
+  });
+
+  it("does not re-execute a stale shutdown ref from a previous session", async () => {
+    // Session A: enabled → registered → shutdown (cleanup runs, once).
+    const { startSession, shutdownSession } = freshFactory();
+    await startSession({});
+    expect(vi.mocked(registerImagePaste)).toHaveBeenCalledTimes(1);
+    shutdownSession();
+    expect(vi.mocked(shutdownImagePaste)).toHaveBeenCalledTimes(1);
+
+    // Session B: toggled off before start → NOT registered.
+    mockStore["archimedes.imagePaste"] = { enabled: false };
+    await startSession({});
+    expect(vi.mocked(registerImagePaste)).toHaveBeenCalledTimes(1); // still 1
+
+    // Session B shutdown must not re-run the (stale) session-A ref.
+    shutdownSession();
+    expect(vi.mocked(shutdownImagePaste)).toHaveBeenCalledTimes(1); // exactly once total
+  });
+});

package/src/index.ts

@@ -10,10 +10,13 @@ const _moduleEvalAt = Date.now();
 // image-paste & subagent — also lazy-loaded below (heavy deps, only needed on use)
 import { registerTodo } from "@pi-archimedes/todo";
 import { registerAsk } from "@pi-archimedes/ask";
+import { isPluginEnabled, migrateLegacyPluginsMap } from "./plugins.js";
 import { registerNotify } from "@pi-archimedes/notify";
 import { registerSessionName } from "@pi-archimedes/session-name";
+import { registerSudo } from "@pi-archimedes/sudo";
 import { loadDiffConfig } from "./config.js";
 import { openSettings } from "./settings.js"
+import { registerPluginsCommand } from "./plugin-manager.js"
 
 // Module-level ref for shutdown (survives session replacements)
 let imagePasteShutdown: (() => void) | undefined;
@@ -23,38 +26,51 @@ let imagePasteShutdown: (() => void) | undefined;
 let currentCtx: ExtensionContext | undefined;
 
 export default function (pi: ExtensionAPI): void {
+  // Must run before any isPluginEnabled gate evaluation: re-points the
+  // legacy archimedes.plugins map onto per-package namespaces, once.
+  migrateLegacyPluginsMap();
   archResetTimings();
   archTime(`factory start (module eval was ${Date.now() - _moduleEvalAt}ms ago)`);
 
   // Register all component extensions (static imports already compiled by jiti above)
   registerCore(pi);
   archTime("registerCore");
-  registerFooter(pi);
+  if (isPluginEnabled("footer")) registerFooter(pi);
   archTime("registerFooter");
 
   // image-paste & subagent lazy-loaded in session_start below — not here
 
   // Register todo (lightweight, registers tool + bus listener)
-  registerTodo(pi);
+  if (isPluginEnabled("todo")) registerTodo(pi);
   archTime("registerTodo");
 
   // Register ask tool
-  registerAsk(pi);
+  if (isPluginEnabled("ask")) registerAsk(pi);
   archTime("registerAsk");
 
   // Register notify
-  registerNotify(pi);
+  if (isPluginEnabled("notify")) registerNotify(pi);
   archTime("registerNotify");
 
   // Register session-name
-  registerSessionName(pi);
+  if (isPluginEnabled("session-name")) registerSessionName(pi);
   archTime("registerSessionName");
 
+  // Register sudo (lightweight: tool + guard + /sudo command + lifecycle)
+  if (isPluginEnabled("sudo")) registerSudo(pi);
+  archTime("registerSudo");
+
   archTime("factory end");
 
   // session_shutdown handler (top-level to prevent accumulation on /reload)
   pi.on("session_shutdown", (_event, _ctx) => {
+    // Liveness-gated on the ref itself: it is set only when image-paste was
+    // registered during THIS session (session_start, gated by config at that
+    // moment). Config may be toggled mid-session via /plugins — cleanup must
+    // still run. Nulled afterwards so a later never-registered session cannot
+    // re-execute a stale ref.
     imagePasteShutdown?.();
+    imagePasteShutdown = undefined;
     unpatchConsoleLog();
     archPrintTimings();
   });
@@ -67,10 +83,18 @@ export default function (pi: ExtensionAPI): void {
 
     // ── Parallel lazy-load all three packages (saves ~100ms vs sequential) ──
     const [diffMod, ipMod, saMod, mcpMod] = await Promise.all([
-      import("@pi-archimedes/diff").catch((e) => { console.error("[archimedes] diff load failed:", e); return null; }),
-      import("@pi-archimedes/image-paste").catch((e) => { console.error("[archimedes] image-paste load failed:", e); return null; }),
-      import("@pi-archimedes/subagent").catch((e) => { console.error("[archimedes] subagent load failed:", e); return null; }),
-      import("@pi-archimedes/mcp").catch((e) => { console.error("[archimedes] mcp load failed:", e); return null; }),
+      isPluginEnabled("diff")
+        ? import("@pi-archimedes/diff").catch((e) => { console.error("[archimedes] diff load failed:", 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; })
+        : Promise.resolve(null),
+      isPluginEnabled("subagent")
+        ? import("@pi-archimedes/subagent").catch((e) => { console.error("[archimedes] subagent load failed:", e); return null; })
+        : Promise.resolve(null),
+      isPluginEnabled("mcp")
+        ? import("@pi-archimedes/mcp").catch((e) => { console.error("[archimedes] mcp load failed:", e); return null; })
+        : Promise.resolve(null),
     ]);
     archTime("4 packages loaded in parallel");
 
@@ -109,4 +133,8 @@ export default function (pi: ExtensionAPI): void {
       await openSettings(pi, ctx);
     },
   });
+
+  // Register /plugins command (plugin manager — single home in plugin-manager.ts)
+  registerPluginsCommand(pi);
+  archTime("registerCommands");
 }

package/src/plugin-manager.ts

@@ -0,0 +1,94 @@
+// ── /plugins — plugin manager ─────────────────────────────────────────────
+//
+// Single registration path for the /plugins command (mirrors the subagent
+// package's registerAgentsCommand pattern). Reuses the settings-manager
+// chrome for a minimal per-plugin list: each row has `values: ["On", "Off"]`
+// cycled with ←/→, and every change persists immediately to the
+// package's own archimedes.* namespace (its `enabled` key). There are
+// deliberately NO prompt descriptors — Enter /
+// Space stay inert in list mode so the rows toggle instead of opening a
+// text prompt.
+
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SettingItem } from "@earendil-works/pi-tui";
+import { OVERLAY_CHROME } from "@pi-archimedes/core/overlay";
+
+import {
+  PLUGINS,
+  isPluginEnabled,
+  setPluginEnabled,
+  type PluginDef,
+} from "./plugins.js";
+import { createSettingsManager } from "./settings-manager.js";
+
+// Free-input descriptors are intentionally empty — no prompt mode.
+const PLUGIN_PROMPTS: Record<string, never> = {};
+
+export function registerPluginsCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("plugins", {
+    description: "Enable or disable optional archimedes plugins",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      await buildPluginManager(ctx);
+    },
+  });
+}
+
+/**
+ * Open the plugin manager overlay. `plugins` defaults to the global
+ * PLUGINS manifest; tests may inject stubbed entries.
+ *
+ * "Installed" probe: a plugin with a rejecting `load()` import is not
+ * installed and is hidden from the menu (same semantics as the /plugins
+ * registration gate — a missing package is simply absent).
+ */
+export async function buildPluginManager(
+  ctx: ExtensionContext,
+  plugins: PluginDef[] = PLUGINS,
+): Promise<void> {
+  const installed = (
+    await Promise.all(
+      plugins.map(async (p): Promise<PluginDef | null> => {
+        try {
+          await p.load();
+          return p;
+        } catch {
+          return null; // not installed (or current broken) — hidden
+        }
+      }),
+    )
+  ).filter((p): p is PluginDef => p !== null);
+
+  if (installed.length === 0) {
+    ctx.ui.notify("No optional plugins installed.", "info");
+    return;
+  }
+
+  const items: SettingItem[] = installed.map((p) => ({
+    id: `plugin:${p.id}`,
+    label: p.label,
+    description: p.description,
+    currentValue: isPluginEnabled(p.id) ? "On" : "Off",
+    values: ["On", "Off"],
+  }));
+
+  await ctx.ui.custom(
+    (_tui, theme, _keybindings, done) => {
+      return createSettingsManager({
+        items,
+        prompts: PLUGIN_PROMPTS,
+        theme,
+        onChange: (id: string, newValue: string) => {
+          const pluginId = id.startsWith("plugin:") ? id.slice("plugin:".length) : id;
+          setPluginEnabled(pluginId, newValue === "On");
+        },
+        onSave: () => {
+          // Toggles already persist on change — nothing to save on exit.
+        },
+        onClose: () => {
+          done(undefined);
+        },
+      });
+    },
+    { overlay: true, overlayOptions: OVERLAY_CHROME },
+  );
+}

package/src/plugins.test.ts

@@ -0,0 +1,417 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { readFileSync } from "node:fs";
+import type { PluginDef } from "./plugins.js";
+
+// ── Mock settings-io with an in-memory store (mirrors core config.test.ts) ──
+
+vi.mock("@pi-archimedes/core/settings-io", () => {
+  const store: Record<string, unknown> = {};
+  return {
+    loadConfig: vi.fn(
+      (ns: string, defaults: object) =>
+        ({ ...defaults, ...((store[ns] as object) ?? {}) }),
+    ),
+    saveConfig: vi.fn((ns: string, config: object) => {
+      store[ns] = config;
+    }),
+    // Core-exact semantics: strict `enabled !== false`; delete-on-On with
+    // empty-namespace removal — so meta's flow is verified through the same
+    // primitives core uses.
+    removeConfig: vi.fn((ns: string) => {
+      delete store[ns];
+    }),
+    isConfigEnabled: vi.fn((ns: string) => {
+      const cfg = (store[ns] ?? {}) as Record<string, unknown>;
+      return cfg.enabled !== false;
+    }),
+    setConfigEnabled: vi.fn((ns: string, enabled: boolean) => {
+      if (enabled) {
+        const cfg = { ...((store[ns] as object) ?? {}) } as Record<string, unknown>;
+        delete cfg.enabled;
+        if (Object.keys(cfg).length === 0) delete store[ns];
+        else store[ns] = cfg;
+      } else {
+        store[ns] = { ...((store[ns] as object) ?? {}), enabled: false };
+      }
+    }),
+    // Exposed for test setup/teardown only
+    __store: store,
+  };
+});
+
+const settingsIo = await import("@pi-archimedes/core/settings-io");
+const mockStore = (settingsIo as unknown as { __store: Record<string, unknown> }).__store;
+
+// ── Mock every package's settings-items provider so meta/settings.ts can be
+// exercised without pulling the real extensions (and shiki) into the test ──
+
+vi.mock("@pi-archimedes/core", () => ({
+  getCoreSettingsItems: vi.fn(() => [
+    { id: "mutedTheme", label: "Muted theme", currentValue: "Off", values: ["On", "Off"] },
+  ]),
+}));
+
+vi.mock("@pi-archimedes/footer/config", () => ({
+  getFooterSettingsItems: vi.fn(() => [
+    { id: "splitThreshold", label: "Footer split threshold", currentValue: "120" },
+  ]),
+}));
+
+vi.mock("@pi-archimedes/notify", () => ({
+  getNotifySettingsItems: vi.fn(() => [
+    { id: "delayMs", label: "Notify delay (seconds)", currentValue: "30s" },
+  ]),
+}));
+
+vi.mock("@pi-archimedes/session-name", () => ({
+  getSessionNameSettingsItems: vi.fn(() => [
+    { id: "sessionNameModel", label: "Session name model", currentValue: "(current model)" },
+  ]),
+}));
+
+// Spy on the diff items so tests can assert the lazy import is skipped when
+// the diff plugin is disabled (shiki must never be pulled in).
+vi.mock("@pi-archimedes/diff", () => ({
+  getDiffSettingsItems: vi.fn(() => [
+    { id: "diffTheme", label: "Diff theme", currentValue: "github-dark" },
+  ]),
+}));
+const {
+  PLUGINS,
+  isPluginEnabled,
+  setPluginEnabled,
+  migrateLegacyPluginsMap,
+} = await import("./plugins.js");
+
+describe("isPluginEnabled (per-namespace gate)", () => {
+  beforeEach(() => {
+    for (const key of Object.keys(mockStore)) delete mockStore[key];
+  });
+
+  it("defaults to enabled when config is empty", () => {
+    expect(isPluginEnabled("mcp")).toBe(true);
+    expect(isPluginEnabled("footer")).toBe(true);
+    expect(isPluginEnabled("diff")).toBe(true);
+  });
+
+  it("returns false only for the plugin disabled in its own namespace", () => {
+    mockStore["archimedes.mcp"] = { enabled: false };
+    expect(isPluginEnabled("mcp")).toBe(false);
+    expect(isPluginEnabled("footer")).toBe(true);
+    expect(isPluginEnabled("todo")).toBe(true);
+  });
+
+  it("treats explicit enabled: true as enabled", () => {
+    mockStore["archimedes.footer"] = { enabled: true };
+    expect(isPluginEnabled("footer")).toBe(true);
+  });
+
+  it("defaults to enabled for unknown ids", () => {
+    expect(isPluginEnabled("does-not-exist")).toBe(true);
+  });
+});
+
+describe("migrateLegacyPluginsMap", () => {
+  beforeEach(() => {
+    for (const key of Object.keys(mockStore)) delete mockStore[key];
+  });
+
+  it("moves explicit false entries to package namespaces, drops true/unknown, removes the map", () => {
+    mockStore["archimedes.plugins"] = { footer: false, ask: true, junk: false };
+    migrateLegacyPluginsMap();
+    expect(mockStore["archimedes.footer"]).toEqual({ enabled: false });
+    // explicit true = default-on: nothing written
+    expect(mockStore["archimedes.ask"]).toBeUndefined();
+    // unknown id: dropped
+    expect(Object.keys(mockStore).some((k) => k.includes("junk"))).toBe(false);
+    // legacy map removed
+    expect("archimedes.plugins" in mockStore).toBe(false);
+  });
+
+  it("is idempotent — a second run changes nothing", () => {
+    mockStore["archimedes.plugins"] = { footer: false, ask: true, junk: false };
+    migrateLegacyPluginsMap();
+    const afterFirst: Record<string, unknown> = JSON.parse(JSON.stringify(mockStore));
+    migrateLegacyPluginsMap();
+    expect(mockStore).toEqual(afterFirst);
+  });
+
+  it("is a no-op when there is no legacy map", () => {
+    mockStore["archimedes.footer"] = { enabled: false };
+    migrateLegacyPluginsMap();
+    expect(mockStore).toEqual({ "archimedes.footer": { enabled: false } });
+  });
+
+  it("merges into a namespace that already carries real settings", () => {
+    mockStore["archimedes.notify"] = { delayMs: 30000 };
+    mockStore["archimedes.plugins"] = { notify: false };
+    migrateLegacyPluginsMap();
+    expect(mockStore["archimedes.notify"]).toEqual({ delayMs: 30000, enabled: false });
+    expect("archimedes.plugins" in mockStore).toBe(false);
+  });
+});
+
+describe("setPluginEnabled (save path)", () => {
+  beforeEach(() => {
+    for (const key of Object.keys(mockStore)) delete mockStore[key];
+  });
+
+  it("off: writes enabled: false to the package's own namespace only", () => {
+    expect(setPluginEnabled("footer", false)).toBe(true);
+    expect(mockStore["archimedes.footer"]).toEqual({ enabled: false });
+    expect("archimedes.plugins" in mockStore).toBe(false);
+    expect(isPluginEnabled("footer")).toBe(false);
+    expect(isPluginEnabled("todo")).toBe(true);
+  });
+
+  it("on: deletes the enabled key and removes a namespace that held nothing else", () => {
+    setPluginEnabled("footer", false);
+    expect(setPluginEnabled("footer", true)).toBe(true);
+    expect("archimedes.footer" in mockStore).toBe(false);
+    expect(isPluginEnabled("footer")).toBe(true);
+  });
+
+  it("on: other keys in the namespace survive the delete", () => {
+    mockStore["archimedes.notify"] = { delayMs: 30000, enabled: false };
+    expect(setPluginEnabled("notify", true)).toBe(true);
+    expect(mockStore["archimedes.notify"]).toEqual({ delayMs: 30000 });
+  });
+
+  it("returns false and writes nothing for an unknown id", () => {
+    expect(setPluginEnabled("does-not-exist", true)).toBe(false);
+    expect(setPluginEnabled("does-not-exist", false)).toBe(false);
+    expect(mockStore).toEqual({});
+  });
+});
+
+describe("PLUGINS manifest integrity", () => {
+  const EXPECTED_IDS = [
+    "footer",
+    "todo",
+    "ask",
+    "notify",
+    "session-name",
+    "diff",
+    "image-paste",
+    "subagent",
+    "mcp",
+    "sudo",
+  ];
+
+  it("lists exactly the 10 non-core packages (no drift)", () => {
+    expect([...PLUGINS.map((p) => p.id)].sort()).toEqual([...EXPECTED_IDS].sort());
+  });
+
+  it("has no duplicate ids", () => {
+    const ids = PLUGINS.map((p) => p.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("gives every entry a unique, non-empty namespace", () => {
+    const namespaces = PLUGINS.map((p) => p.namespace);
+    for (const ns of namespaces) {
+      expect(ns.length).toBeGreaterThan(0);
+      expect(ns).toMatch(/^archimedes\./);
+    }
+    expect(new Set(namespaces).size).toBe(namespaces.length);
+  });
+
+  it("gives every entry a label, description, and load function", () => {
+    for (const plugin of PLUGINS) {
+      expect(plugin.label.length).toBeGreaterThan(0);
+      expect(plugin.description.length).toBeGreaterThan(0);
+      expect(typeof plugin.load).toBe("function");
+    }
+  });
+
+  it("load() resolves for a real installed package (footer probe)", async () => {
+    const footer = PLUGINS.find((p): p is PluginDef => p.id === "footer");
+    expect(footer).toBeDefined();
+    const mod = await footer!.load();
+    expect(mod).toBeTruthy();
+  });
+});
+
+// ── Task 2: settings-item gate, /plugins command, plugin manager ──────────
+
+const { buildSettingsItems } = await import("./settings.js");
+const { getDiffSettingsItems } = await import("@pi-archimedes/diff");
+const { registerPluginsCommand, buildPluginManager } = await import("./plugin-manager.js");
+
+// Raw terminal input for the right-arrow key (legacy sequence)
+const ARROW_RIGHT = "\x1b[C";
+
+/** All enabled — no `enabled` keys persisted anywhere. */
+function fakeAllConfig(): Parameters<typeof buildSettingsItems>[0] {
+  // Minimal shape — buildSettingsItems only reads core/notify/sessionName
+  // through the (mocked) item builders, so missing fields never surface.
+  return {
+    core: { mutedTheme: false },
+    footer: { splitThreshold: 120 },
+    diff: { diffTheme: "github-dark", diffSplitMinWidth: 150, diffSplitMinCodeWidth: 60 },
+    notify: { delayMs: 30000, notifyOnAgentEnd: true, notifyOnQuestion: true },
+    sessionName: {},
+  } as unknown as Parameters<typeof buildSettingsItems>[0];
+}
+
+describe("buildSettingsItems (settings gate)", () => {
+  beforeEach(() => {
+    for (const key of Object.keys(mockStore)) delete mockStore[key];
+    vi.mocked(getDiffSettingsItems).mockClear();
+  });
+
+  it("includes all packages' items when everything is enabled, and lazy-imports diff", async () => {
+    const items = await buildSettingsItems(fakeAllConfig());
+    const ids = items.map((i) => i.id);
+    expect(ids).toEqual(expect.arrayContaining(["mutedTheme", "splitThreshold", "diffTheme", "delayMs", "sessionNameModel"]));
+    expect(vi.mocked(getDiffSettingsItems)).toHaveBeenCalledTimes(1);
+  });
+
+  it("excludes disabled packages' items and never lazy-imports diff when disabled", async () => {
+    mockStore["archimedes.footer"] = { enabled: false };
+    mockStore["archimedes.diff"] = { enabled: false };
+    mockStore["archimedes.sessionName"] = { enabled: false };
+    mockStore["archimedes.notify"] = { enabled: false };
+    const items = await buildSettingsItems(fakeAllConfig());
+    // Core items are always present
+    expect(items.map((i) => i.id)).toContain("mutedTheme");
+    // No item from a disabled package
+    for (const id of ["splitThreshold", "diffTheme", "delayMs", "sessionNameModel"]) {
+      expect(items.map((i) => i.id)).not.toContain(id);
+    }
+    // Diff must never be lazy-imported (shiki stays out of /archimedes)
+    expect(vi.mocked(getDiffSettingsItems)).not.toHaveBeenCalled();
+  });
+
+  it("keeps enabled packages when others are disabled", async () => {
+    mockStore["archimedes.footer"] = { enabled: false };
+    mockStore["archimedes.sessionName"] = { enabled: false };
+    const items = await buildSettingsItems(fakeAllConfig());
+    const ids = items.map((i) => i.id);
+    expect(ids).toEqual(expect.arrayContaining(["mutedTheme", "diffTheme", "delayMs"]));
+    expect(ids).not.toContain("splitThreshold");
+    expect(ids).not.toContain("sessionNameModel");
+  });
+});
+
+// ── /plugins command registration ────────────────────────────────────────
+
+describe("registerPluginsCommand", () => {
+  it("registers a 'plugins' command with a description and handler", () => {
+    const commands = new Map<string, { description?: string; handler?: unknown }>();
+    const fakePi = { registerCommand: (name: string, def: unknown) => commands.set(name, def as never) };
+    registerPluginsCommand(fakePi as never);
+    expect(commands.has("plugins")).toBe(true);
+    expect(typeof commands.get("plugins")?.description).toBe("string");
+    expect(commands.get("plugins")?.description?.length).toBeGreaterThan(0);
+    expect(typeof commands.get("plugins")?.handler).toBe("function");
+  });
+});
+
+// ── Plugin manager (buildPluginManager) ───────────────────────────────────
+
+interface CustomCapture {
+  factory: ((tui: unknown, theme: unknown, kb: unknown, done: () => void) => unknown) | null;
+  options: unknown | null;
+  customCalls: number;
+  notifyMessage: string | null;
+}
+
+function makeCtx(): { ctx: unknown; captured: CustomCapture } {
+  const captured: CustomCapture = { factory: null, options: null, customCalls: 0, notifyMessage: null };
+  const ctx = {
+    ui: {
+      custom: (factory: CustomCapture["factory"], options: unknown) => {
+        captured.factory = factory as never;
+        captured.options = options;
+        captured.customCalls++;
+        return Promise.resolve();
+      },
+      notify: (msg: string) => {
+        captured.notifyMessage = msg;
+      },
+    },
+  };
+  return { ctx, captured };
+}
+
+// Minimal theme stub — render()/handleInput() only ever call theme.fg/error
+const stubTheme = {
+  fg: (_color: string, text?: string) => text ?? "",
+  error: (text?: string) => text ?? "",
+} as never;
+
+const footerPlugin: PluginDef = {
+  id: "footer", label: "Footer status bar", description: "Status bar with cost/timer", namespace: "archimedes.footer",
+  load: () => Promise.resolve({}),
+};
+const ghostPlugin: PluginDef = {
+  id: "ghost", label: "Ghost Plugin", description: "Not installed", namespace: "archimedes.ghost",
+  load: () => Promise.reject(new Error("module not found")),
+};
+
+describe("buildPluginManager", () => {
+  beforeEach(() => {
+    for (const key of Object.keys(mockStore)) delete mockStore[key];
+  });
+
+  it("opens the settings overlay with rows only for installed plugins", async () => {
+    const { ctx, captured } = makeCtx();
+    await buildPluginManager(ctx as never, [footerPlugin, ghostPlugin]);
+
+    expect(captured.customCalls).toBe(1);
+    expect(captured.options).toEqual({ overlay: true, overlayOptions: expect.anything() });
+    expect(captured.factory).not.toBeNull();
+
+    const component = captured.factory!(null, stubTheme, null, () => {});
+    const lines = (component as { render(w: number): string[] }).render(80);
+    const text = lines.join("\n");
+    // Installed plugin visible, load-failing plugin absent
+    expect(text).toContain("Footer status bar");
+    expect(text).not.toContain("Ghost Plugin");
+    // Current state shown as On for a default-enabled plugin
+    expect(text).toContain("On");
+  });
+
+  it("toggling a row On → Off → On persists to the package's own namespace", async () => {
+    mockStore["archimedes.footer"] = { enabled: true };
+    const { ctx, captured } = makeCtx();
+    await buildPluginManager(ctx as never, [footerPlugin]);
+
+    const component = captured.factory!(null, stubTheme, null, () => {});
+    // ←/→ cycle the value on the selected row (single row, pre-selected)
+    (component as { handleInput(d: string): void }).handleInput(ARROW_RIGHT);
+    expect(mockStore["archimedes.footer"]).toEqual({ enabled: false });
+
+    // Cyclic: one more right press goes Off → On — the namespace held only
+    // `enabled`, so the whole namespace key is removed again.
+    (component as { handleInput(d: string): void }).handleInput(ARROW_RIGHT);
+    expect("archimedes.footer" in mockStore).toBe(false);
+  });
+
+  it("starts from Off when the plugin is already disabled", async () => {
+    mockStore["archimedes.footer"] = { enabled: false };
+    const { ctx, captured } = makeCtx();
+    await buildPluginManager(ctx as never, [footerPlugin]);
+    const component = captured.factory!(null, stubTheme, null, () => {});
+    const text = (component as { render(w: number): string[] }).render(80).join("\n");
+    expect(text).toContain("Footer status bar");
+    expect(text).toContain("Off");
+  });
+
+  it("notifies instead of opening the overlay when no optional plugins are installed", async () => {
+    const { ctx, captured } = makeCtx();
+    await buildPluginManager(ctx as never, [ghostPlugin]);
+    expect(captured.customCalls).toBe(0);
+    expect(captured.notifyMessage).toContain("No optional plugins installed");
+  });
+});
+
+// ── Docs ──────────────────────────────────────────────────────────────────
+
+describe("docs", () => {
+  it("README documents the /plugins command", () => {
+    const readme = readFileSync(new URL("../../README.md", import.meta.url), "utf8");
+    expect(readme).toContain("/plugins");
+  });
+});

package/src/plugins.ts

@@ -0,0 +1,66 @@
+// ── Plugin manager: manifest + per-namespace `enabled` gate ──────────────
+//
+// Core is intentionally NOT in the manifest — it is always registered.
+// Every other package meta composes is listed here. A plugin is "enabled"
+// unless settings.json carries `archimedes.<pkg>.enabled === false` (the
+// uniform default-on now lives in isConfigEnabled's strict `!== false`).
+// A plugin is "installed" when its `load()` import resolves; a missing
+// package is simply never registered (and hidden from the /plugins menu).
+
+import { isConfigEnabled, setConfigEnabled, loadConfig, removeConfig } from "@pi-archimedes/core/settings-io";
+
+export interface PluginDef {
+  id: string;              // matches package npm name suffix, e.g. "mcp"
+  label: string;           // human label, e.g. "MCP"
+  description: string;     // one-liner shown in the menu
+  namespace: string;       // "archimedes.mcp" — the settings.json key holding this plugin's { enabled, ...settings }
+  load: () => Promise<unknown>; // lazy import for instance probing + future lazy mount
+}
+
+// Array order = menu display order. There is no separate order constant.
+export const PLUGINS: PluginDef[] = [
+  { id: "footer",       label: "Footer status bar",  description: "Status bar with cost/timer",                      namespace: "archimedes.footer",      load: () => import("@pi-archimedes/footer") },
+  { id: "todo",         label: "Todo list",          description: "manage_todo_list tool + widget",                  namespace: "archimedes.todo",        load: () => import("@pi-archimedes/todo") },
+  { id: "ask",          label: "Ask tool",           description: "Structured in-conversation questions",            namespace: "archimedes.ask",         load: () => import("@pi-archimedes/ask") },
+  { id: "notify",       label: "Notifications",      description: "Delayed desktop notifications",                   namespace: "archimedes.notify",      load: () => import("@pi-archimedes/notify") },
+  { id: "session-name", label: "Session naming",     description: "Auto session name via git diff",                  namespace: "archimedes.sessionName", load: () => import("@pi-archimedes/session-name") },
+  { id: "diff",         label: "Diff rendering",     description: "Shiki-powered diff display",                      namespace: "archimedes.diff",        load: () => import("@pi-archimedes/diff") },
+  { id: "image-paste",  label: "Image paste",        description: "Clipboard image paste",                           namespace: "archimedes.imagePaste",  load: () => import("@pi-archimedes/image-paste") },
+  { id: "subagent",     label: "Subagents",          description: "Live subagent dispatch (general, reviewer, …)",  namespace: "archimedes.subagent",    load: () => import("@pi-archimedes/subagent") },
+  { id: "mcp",          label: "MCP",                description: "MCP client adapter + /mcp commands",             namespace: "archimedes.mcp",         load: () => import("@pi-archimedes/mcp") },
+  { id: "sudo",         label: "Sudo",                 description: "Safe privileged execution",                      namespace: "archimedes.sudo",      load: () => import("@pi-archimedes/sudo") },
+];
+
+// ── Gate: settings[archimedes.<pkg>].enabled, strict `!== false` ─────────
+// Absent file/namespace/key = enabled; explicit false = disabled.
+
+export function isPluginEnabled(id: string): boolean {
+  const def = PLUGINS.find((p) => p.id === id);
+  if (!def) return true; // unknown id defaults on (unchanged plan-031 semantics)
+  return isConfigEnabled(def.namespace);
+}
+
+export function setPluginEnabled(id: string, enabled: boolean): boolean {
+  const def = PLUGINS.find((p) => p.id === id);
+  if (!def) return false;
+  setConfigEnabled(def.namespace, enabled);
+  return true;
+}
+
+// ── One-time migration: legacy archimedes.plugins { id → boolean } map ───
+// Plan 031 stored the gate in a single standalone namespace. Only explicit
+// false entries need moving (true / non-boolean = default-on = nothing to
+// write); unknown ids are dropped and the legacy key is removed afterwards,
+// so a second run is a no-op.
+
+export function migrateLegacyPluginsMap(): void {
+  const legacy = loadConfig("archimedes.plugins", {}) as Record<string, unknown>;
+  if (Object.keys(legacy).length === 0) return; // nothing to do — idempotent on re-run
+  for (const [id, value] of Object.entries(legacy)) {
+    const def = PLUGINS.find((p) => p.id === id);
+    if (!def) continue;                    // unknown id: drop
+    if (value === false) setConfigEnabled(def.namespace, false);
+    // explicit true / non-boolean: equals default-on → nothing to write
+  }
+  removeConfig("archimedes.plugins");
+}

package/src/settings.ts

@@ -4,7 +4,9 @@ import type { SettingItem } from "@earendil-works/pi-tui";
 import { getCoreSettingsItems } from "@pi-archimedes/core";
 import { OVERLAY_CHROME } from "@pi-archimedes/core/overlay";
 import { getFooterSettingsItems } from "@pi-archimedes/footer/config";
-// diff (shiki) is lazy-loaded below to keep shiki out of the startup import chain
+// diff (shiki) is lazy-loaded inside buildSettingsItems AND gated by the
+// per-namespace plugin gate (archimedes.diff.enabled — see ADR 0012) —
+// disabled means shiki is never imported
 import { getNotifySettingsItems } from "@pi-archimedes/notify";
 import { getSessionNameSettingsItems } from "@pi-archimedes/session-name";
 import {
@@ -17,6 +19,7 @@ import {
   type CoreConfig,
   type NotifyConfig,
 } from "./config.js";
+import { isPluginEnabled } from "./plugins.js";
 import { createSettingsManager, type PromptDescriptor } from "./settings-manager.js";
 
 // ── Free-input prompt descriptors (keyed by item.id) ───────────────────────
@@ -33,9 +36,43 @@ const PROMPTS: Record<string, PromptDescriptor> = {
 
 // ── Settings UI ─────────────────────────────────────────────────────────────
 
+// Compose the /archimedes item list. Core is always included; every other
+// package's items are gated by the per-namespace plugin gate
+// (archimedes.<pkg>.enabled — see ADR 0012) so a disabled plugin can
+// not leak back in through the settings overlay. The diff import (heavy —
+// pulls in shiki) is lazy AND inside the gate: disabled diff is never loaded.
+export async function buildSettingsItems(allConfig: ReturnType<typeof loadAllConfig>): Promise<SettingItem[]> {
+  const items: SettingItem[] = [...getCoreSettingsItems({ ...allConfig.core })];
+
+  if (isPluginEnabled("footer")) {
+    items.push(...getFooterSettingsItems());
+  }
+
+  if (isPluginEnabled("diff")) {
+    const { getDiffSettingsItems } = await import("@pi-archimedes/diff");
+    items.push(...getDiffSettingsItems());
+  }
+
+  if (isPluginEnabled("notify")) {
+    const notifyItems = getNotifySettingsItems({ ...allConfig.notify });
+    // The notify package seeds delayMs as "30s" — strip the suffix so the
+    // number prompt can be edited in place (typed digits would otherwise
+    // append to "30s" and parseInt would discard the edit).
+    const delayItem = notifyItems.find((i) => i.id === "delayMs");
+    if (delayItem) {
+      delayItem.currentValue = String(allConfig.notify.delayMs / 1000);
+    }
+    items.push(...notifyItems);
+  }
+
+  if (isPluginEnabled("session-name")) {
+    items.push(...getSessionNameSettingsItems({ ...allConfig.sessionName }));
+  }
+
+  return items;
+}
+
 export async function openSettings(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
-  // Lazy-load diff (pulls in shiki) — only needed when /archimedes is opened
-  const { getDiffSettingsItems } = await import("@pi-archimedes/diff");
   const allConfig = loadAllConfig();
 
   const coreConfig: CoreConfig = { ...allConfig.core };
@@ -44,28 +81,7 @@ export async function openSettings(pi: ExtensionAPI, ctx: ExtensionContext): Pro
   const diffConfig = { ...allConfig.diff };
   const sessionNameConfig = { ...allConfig.sessionName };
 
-  // Build composed items from sub-packages
-  const coreItems = getCoreSettingsItems(coreConfig);
-  const footerItems = getFooterSettingsItems();
-  const diffItems = getDiffSettingsItems();
-  const notifyItems = getNotifySettingsItems(notifyConfig);
-  const sessionNameItems = getSessionNameSettingsItems(sessionNameConfig);
-
-  // The notify package seeds delayMs as "30s" — strip the suffix so the
-  // number prompt can be edited in place (typed digits would otherwise
-  // append to "30s" and parseInt would discard the edit).
-  const delayItem = notifyItems.find((i) => i.id === "delayMs");
-  if (delayItem) {
-    delayItem.currentValue = String(notifyConfig.delayMs / 1000);
-  }
-
-  const items: SettingItem[] = [
-    ...coreItems,
-    ...footerItems,
-    ...diffItems,
-    ...notifyItems,
-    ...sessionNameItems,
-  ];
+  const items = await buildSettingsItems(allConfig);
 
   ctx.ui.custom((_tui, theme, _keybindings, done) => {
     const settingsManager = createSettingsManager({
@@ -102,7 +118,6 @@ export async function openSettings(pi: ExtensionAPI, ctx: ExtensionContext): Pro
           }
 
           // ── Notify settings ──
-          case "enabled": notifyConfig.enabled = newValue === "On"; break;
           case "notifyOnAgentEnd": notifyConfig.notifyOnAgentEnd = newValue === "On"; break;
           case "notifyOnQuestion": notifyConfig.notifyOnQuestion = newValue === "On"; break;
           case "delayMs": {
@@ -112,7 +127,6 @@ export async function openSettings(pi: ExtensionAPI, ctx: ExtensionContext): Pro
           }
 
           // ── Session name settings ──
-          case "sessionNameEnabled": sessionNameConfig.enabled = newValue === "On"; break;
           case "sessionNameModel": sessionNameConfig.model = newValue === "(current model)" ? undefined : newValue; break;
         }
       },