tmux-ide 2.7.0 → 2.8.0

package/packages/daemon/dist/doctor.js

@@ -1,11 +1,13 @@
 import { execSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { accessSync, constants, existsSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getCurrentVersion, getUpdateStatus } from "./lib/update-check.js";
 import { installedSkillVersion } from "./lib/skill-sync.js";
 import { discoverAgents, presentAgents } from "./lib/agent-discovery.js";
 import { findCompiledTui, isBunAvailable } from "./tui/compiled.js";
+import { claudeSettingsPath } from "./tui/integrations/claude.js";
+import { readNotificationPrefs, resolveNativeMacosNotifierPath } from "./tui/chrome/notify.js";
 /**
  * PURE — the "agent integrations" doctor rows, one per DISCOVERED agent (absent
  * agents produce nothing — no noise). All rows are optional (informational, they
@@ -19,12 +21,18 @@ export function agentIntegrationRows(agents) {
     return presentAgents(agents).map((agent) => {
         const label = `agent: ${agent.id}`;
         if (agent.integration) {
+            // What installing actually buys, honestly per mechanism: claude's hooks
+            // give ground-truth status (and record resume ids); opencode's plugin
+            // records resume ids only.
+            const benefit = agent.capture === "hooks"
+                ? "for ground-truth status"
+                : "to record session ids for restore --resume-agents";
             return agent.installed
                 ? { label, pass: true, detail: "integration installed ✓", optional: true }
                 : {
                     label,
                     pass: false,
-                    detail: `found on PATH — run \`tmux-ide integration install ${agent.id}\` for ground-truth status`,
+                    detail: `found on PATH — run \`tmux-ide integration install ${agent.id}\` ${benefit}`,
                     optional: true,
                 };
         }
@@ -36,6 +44,52 @@ export function agentIntegrationRows(agents) {
         };
     });
 }
+/**
+ * PURE — the "Claude hooks target writable" row from observed facts. Both
+ * `integration install claude` and the npm postinstall write the settings
+ * file; surface a permissions problem BEFORE an install fails halfway.
+ * Optional: a machine without Claude Code shouldn't fail doctor over this.
+ */
+export function hooksTargetRow(facts) {
+    const label = "Claude hooks target writable";
+    if (facts.writable) {
+        return {
+            label,
+            pass: true,
+            detail: facts.fileExists ? facts.settingsPath : `${facts.settingsPath} (will be created)`,
+            optional: true,
+        };
+    }
+    return {
+        label,
+        pass: false,
+        detail: `cannot write ${facts.settingsPath} — fix its permissions (chown/chmod), or point TMUX_IDE_CLAUDE_SETTINGS at a writable path`,
+        optional: true,
+    };
+}
+/**
+ * PURE — native notifier health, shown only when macOS notifications are ON.
+ * Release packages always include the helper; absence means an incomplete or
+ * old installation, which can still fall back to the unbranded AppleScript path.
+ * Optional — informational, never fails doctor.
+ */
+export function notifierRow(present) {
+    const label = "native macOS notifications";
+    if (present) {
+        return {
+            label,
+            pass: true,
+            detail: "bundled — branded banners and click-to-jump are ready",
+            optional: true,
+        };
+    }
+    return {
+        label,
+        pass: false,
+        detail: "native helper missing — reinstall tmux-ide; unbranded AppleScript banners remain available",
+        optional: true,
+    };
+}
 function check(label, fn, { optional = false } = {}) {
     try {
         const result = fn();
@@ -48,7 +102,12 @@ function check(label, fn, { optional = false } = {}) {
 export async function doctor({ json, } = {}) {
     const checks = [];
     checks.push(check("tmux installed", () => {
-        execSync("which tmux", { stdio: "ignore" });
+        try {
+            execSync("which tmux", { stdio: "ignore" });
+        }
+        catch {
+            throw new Error("not found on PATH — install it (macOS: `brew install tmux`; Debian/Ubuntu: `sudo apt install tmux`)");
+        }
         return "found";
     }));
     checks.push(check("tmux version ≥ 3.0", () => {
@@ -103,18 +162,45 @@ export async function doctor({ json, } = {}) {
         }
         return "enabled";
     }, { optional: true }));
-    checks.push(check("tailscale CLI", () => {
-        const version = execSync("tailscale version", { encoding: "utf-8" }).trim().split("\n")[0];
-        return version;
-    }, { optional: true }));
-    checks.push(check("ngrok CLI", () => {
-        const version = execSync("ngrok version", { encoding: "utf-8" }).trim();
-        return version;
-    }, { optional: true }));
-    checks.push(check("cloudflared CLI", () => {
-        const version = execSync("cloudflared --version", { encoding: "utf-8" }).trim();
-        return version;
-    }, { optional: true }));
+    // Optional tunnel CLIs: probe quietly (a missing binary must not leak
+    // "command not found" stderr into doctor's own output) and fail with a
+    // plain hint rather than execSync's raw error.
+    const tunnelCli = (label, cmd) => check(label, () => {
+        try {
+            return execSync(cmd, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] })
+                .trim()
+                .split("\n")[0];
+        }
+        catch {
+            throw new Error("not found (optional — used for remote access tunnels)");
+        }
+    }, { optional: true });
+    checks.push(tunnelCli("tailscale CLI", "tailscale version"));
+    checks.push(tunnelCli("ngrok CLI", "ngrok version"));
+    checks.push(tunnelCli("cloudflared CLI", "cloudflared --version"));
+    checks.push((() => {
+        // Claude hooks target: the settings file `integration install claude`
+        // (and the npm postinstall) will write. Writability of the file itself
+        // when it exists, else of its nearest existing ancestor directory.
+        const settingsPath = claudeSettingsPath();
+        const fileExists = existsSync(settingsPath);
+        let probe = fileExists ? settingsPath : dirname(settingsPath);
+        while (!existsSync(probe)) {
+            const parent = dirname(probe);
+            if (parent === probe)
+                break;
+            probe = parent;
+        }
+        let writable = false;
+        try {
+            accessSync(probe, constants.W_OK);
+            writable = true;
+        }
+        catch {
+            // leave writable=false — the row explains the fix
+        }
+        return hooksTargetRow({ settingsPath, fileExists, writable });
+    })());
     checks.push(check("tmux-ide up to date", () => {
         const current = getCurrentVersion();
         const { latest, updateAvailable } = getUpdateStatus({ currentVersion: current });
@@ -137,6 +223,10 @@ export async function doctor({ json, } = {}) {
         }
         return `in sync (v${installed})`;
     }, { optional: true }));
+    // Native branded sender: only when the macOS channel is actually on.
+    if (process.platform === "darwin" && readNotificationPrefs().macos) {
+        checks.push(notifierRow(resolveNativeMacosNotifierPath() !== null));
+    }
     // Agent integrations: one row per agent discovered on PATH (absent → no row).
     checks.push(...agentIntegrationRows(discoverAgents()));
     const allPass = checks.every((c) => c.pass || c.optional);

package/packages/daemon/dist/lib/agent-discovery.d.ts

@@ -1,3 +1,16 @@
+/**
+ * How a kind's `@agent_session_id` (the `restore --resume-agents` key) gets
+ * captured:
+ *  - `"hooks"`  — the agent's own lifecycle hooks stamp it (claude; needs
+ *    `integration install`).
+ *  - `"plugin"` — an in-process plugin stamps it (opencode; needs
+ *    `integration install`).
+ *  - `"probe"`  — the chrome updater discovers it from the agent's own on-disk
+ *    session state (codex, cursor; automatic, nothing to install).
+ *  - `null`     — no defensible capture surface (see
+ *    {@link ../tui/detect/session-id.ts} for the per-kind evidence).
+ */
+export type CaptureMechanism = "hooks" | "plugin" | "probe" | null;
 /** A coding agent tmux-ide knows how to detect. */
 export interface KnownAgent {
     /** Stable id — also the `tmux-ide integration <install|status> <id>` selector. */
@@ -6,11 +19,14 @@ export interface KnownAgent {
     bin: string;
     /** True → tmux-ide ships a lifecycle-integration installer for this agent. */
     integration: boolean;
+    /** How this kind's session id is captured for `restore --resume-agents`. */
+    capture: CaptureMechanism;
 }
 /**
  * The agents tmux-ide recognizes. `integration: true` means we HAVE an installer
- * (a real lifecycle hook → ground-truth pane state); the rest are detected via
- * screen-manifest scraping only, with no lifecycle hook yet.
+ * (claude's lifecycle hooks, opencode's plugin); the rest are detected via
+ * screen-manifest scraping only. `capture` records each kind's session-id
+ * story ({@link CaptureMechanism}).
  */
 export declare const KNOWN_AGENTS: readonly KnownAgent[];
 /** One probed agent: its registry facts plus what the PATH/integration probe found. */
@@ -27,6 +43,15 @@ export interface DiscoveredAgent {
      * integrate (there's nothing to install) and for any agent absent from PATH.
      */
     installed: boolean;
+    /** How this kind's session id is captured (copied from the registry). */
+    capture: CaptureMechanism;
+    /**
+     * Whether session-id capture is LIVE for this kind on this machine:
+     * `"probe"` capture is automatic whenever the binary is present; hook/plugin
+     * capture requires the integration to be installed; `null` capture is never
+     * active.
+     */
+    captureActive: boolean;
 }
 /** Resolve a binary to its absolute path, or null. Must never throw. */
 export type WhichRunner = (bin: string) => string | null;

package/packages/daemon/dist/lib/agent-discovery.js

@@ -17,17 +17,21 @@
  */
 import { execFileSync } from "node:child_process";
 import { claudeIntegrationStatus } from "../tui/integrations/claude.js";
+import { opencodeIntegrationStatus } from "../tui/integrations/opencode.js";
 /**
  * The agents tmux-ide recognizes. `integration: true` means we HAVE an installer
- * (a real lifecycle hook → ground-truth pane state); the rest are detected via
- * screen-manifest scraping only, with no lifecycle hook yet.
+ * (claude's lifecycle hooks, opencode's plugin); the rest are detected via
+ * screen-manifest scraping only. `capture` records each kind's session-id
+ * story ({@link CaptureMechanism}).
  */
 export const KNOWN_AGENTS = [
-    { id: "claude", bin: "claude", integration: true },
-    { id: "codex", bin: "codex", integration: false },
-    { id: "opencode", bin: "opencode", integration: false },
-    { id: "gemini", bin: "gemini", integration: false },
-    { id: "aider", bin: "aider", integration: false },
+    { id: "claude", bin: "claude", integration: true, capture: "hooks" },
+    { id: "codex", bin: "codex", integration: false, capture: "probe" },
+    { id: "opencode", bin: "opencode", integration: true, capture: "plugin" },
+    { id: "gemini", bin: "gemini", integration: false, capture: null },
+    { id: "aider", bin: "aider", integration: false, capture: null },
+    { id: "cursor", bin: "cursor-agent", integration: false, capture: "probe" },
+    { id: "copilot", bin: "copilot", integration: false, capture: null },
 ];
 /**
  * Default which-runner: `which <bin>`, hard-capped at 2s, swallowing every
@@ -51,15 +55,17 @@ const defaultWhich = (bin) => {
     }
 };
 /**
- * Default integration probe: only `claude` has an installer, so only it can be
- * "installed". Reads the real Claude settings; any failure degrades to false so
- * discovery never throws.
+ * Default integration probe: claude's hooks and opencode's plugin are the two
+ * shipped installers. Reads the real settings/plugin file; any failure degrades
+ * to false so discovery never throws.
  */
 const defaultIntegrationProbe = (agentId) => {
-    if (agentId !== "claude")
-        return false;
     try {
-        return claudeIntegrationStatus().installed;
+        if (agentId === "claude")
+            return claudeIntegrationStatus().installed;
+        if (agentId === "opencode")
+            return opencodeIntegrationStatus().installed;
+        return false;
     }
     catch {
         return false;
@@ -76,7 +82,16 @@ export function discoverAgents(which = defaultWhich, isInstalled = defaultIntegr
         const path = which(agent.bin);
         const present = path !== null;
         const installed = present && agent.integration ? isInstalled(agent.id) : false;
-        return { id: agent.id, bin: agent.bin, integration: agent.integration, path, installed };
+        const captureActive = agent.capture === "probe" ? present : agent.capture !== null ? installed : false;
+        return {
+            id: agent.id,
+            bin: agent.bin,
+            integration: agent.integration,
+            path,
+            installed,
+            capture: agent.capture,
+            captureActive,
+        };
     });
 }
 /** The subset of discovered agents actually present on PATH (path resolved). */

package/packages/daemon/dist/lib/app-config.d.ts

@@ -60,10 +60,29 @@ export interface AppUpdater {
     /** Write a disaster-recovery snapshot every N ticks (default 15). */
     snapshotEvery: number;
 }
+/** The sound channel's states: ping sound on blocked only, on every ping, or never. */
+export type NotificationSound = "blocked" | "all" | "none";
 /** Notification channel toggles. */
 export interface AppNotifications {
     toast: boolean;
     macos: boolean;
+    /**
+     * Terminal-native banners (M25.2): an OSC 9 (kitty: OSC 99) escape written to
+     * each eligible attached client's tty, so terminals that surface them (iTerm2,
+     * Ghostty, WezTerm, kitty) show a native notification even over ssh. Default
+     * true — terminals without support ignore the sequence entirely.
+     */
+    terminal: boolean;
+    /**
+     * Seconds the OS-LEVEL channels (banner / terminal escape / sound / BEL) wait
+     * before firing, re-verifying the pane is STILL in the notified state — a
+     * blocked→working flap inside the window fires nothing. 0 fires immediately.
+     * The in-app toast never waits. Tick-native: the delay rounds up to the
+     * updater's next tick at or after `delaySeconds`.
+     */
+    delaySeconds: number;
+    /** Sound channel (M25.2) — `afplay`/`paplay` + a BEL to eligible client ttys. */
+    sound: NotificationSound;
 }
 /** Restore behaviour toggles. */
 export interface AppRestore {
@@ -72,6 +91,14 @@ export interface AppRestore {
 /** Update-check toggles (consumed later by the update-flow card). */
 export interface AppUpdates {
     check: boolean;
+    /**
+     * Whether the daily update check ALSO refreshes the remote agent-detection
+     * manifest pack into `~/.tmux-ide/agent-detection/pack/` (M25.4). Default
+     * FALSE — auto-installing detection rules is opt-in; `tmux-ide update
+     * --manifests` always works explicitly. Requires `check: true` (the refresh
+     * rides the same daily throttle — no timer of its own).
+     */
+    manifests: boolean;
 }
 /** First-run welcome toggles. */
 export interface AppWelcome {
@@ -92,6 +119,55 @@ export interface AppIntegrations {
      */
     offer: boolean;
 }
+/** The unified-app front-door decision (M22.6). */
+export interface AppApp {
+    /**
+     * Whether bare `tmux-ide` (no ide.yml here, no `--team`) launches the unified
+     * app (`tmux-ide app`) instead of the classic team cockpit. Default false —
+     * the flip is opt-in until the default-entry decision is made. `tmux-ide team`
+     * (the explicit cockpit) and a project's `ide.yml` auto-launch are unaffected.
+     */
+    frontDoor: boolean;
+    /**
+     * Whether `tmux-ide app` runs HOSTED by default (M23.2): the app lives in an
+     * internal `_tmux-ide-app` tmux session and the invoking terminal attaches to
+     * it, so the cockpit survives the terminal and reattaches from anywhere (^q
+     * detaches instead of quitting). Default false — the same behavior as the
+     * explicit `--detachable` flag; `--detachable`/`--hosted` still force it on a
+     * single run.
+     */
+    detachable: boolean;
+    /**
+     * When a plain left drag on an app-mouse pane SELECTS locally instead of
+     * forwarding to the pane's app (M24.2). "agents" (default): panes our own
+     * detection matches to a fleet agent entry select; other app-mouse panes
+     * (vim/htop) forward. "always": every app-mouse pane selects on drag.
+     * "never": every app-mouse pane forwards (the pre-M24.2 behavior). A genuine
+     * click (press+release in one cell) is still forwarded on select-default
+     * panes; shift inverts a pane's default; the right-click pane menu overrides
+     * per pane for the session.
+     */
+    dragSelect: "agents" | "always" | "never";
+    /**
+     * Where a Terminal-surface "New agent" spawn starts (M24.1): `"pane"`
+     * (default) inherits the FOCUSED pane's current working directory —
+     * `#{pane_current_path}`, so the agent lands where you are — while
+     * `"session"` keeps the session/project directory. Home/sidebar spawns
+     * always use the session/project dir (no focused pane exists there).
+     */
+    newAgentCwd: NewAgentCwd;
+    /**
+     * Whether the unified app enables the kitty keyboard protocol on its host
+     * terminal (M24.4). On (default), kitty-capable terminals deliver ⌘-modified
+     * keys — ⌘K opens the command palette — and disambiguated escapes; the app
+     * re-encodes every key for the mirrored panes either way, and terminals
+     * without the protocol ignore the request entirely. Off restores the legacy
+     * key encoding for hosts where the protocol misbehaves.
+     */
+    kittyKeys: boolean;
+}
+/** The two Terminal-spawn cwd policies (see {@link AppApp.newAgentCwd}). */
+export type NewAgentCwd = "pane" | "session";
 /** Worktree flow config (`tmux-ide worktree`). */
 export interface AppWorktrees {
     /**
@@ -112,6 +188,7 @@ export interface AppConfig {
     welcome: AppWelcome;
     integrations: AppIntegrations;
     worktrees: AppWorktrees;
+    app: AppApp;
 }
 /** The built-in config — every field's fallback. */
 export declare const DEFAULT_APP_CONFIG: AppConfig;
@@ -145,3 +222,32 @@ export declare function loadAppConfig(): AppConfig;
 export declare function getAppConfig(): AppConfig;
 /** Drop the cache so the next {@link getAppConfig} re-reads. Test-only. */
 export declare function _resetForTests(): void;
+/**
+ * io — the RAW parsed config file as the user wrote it (`{}` when missing or
+ * malformed). Writers merge over THIS, not over {@link parseAppConfig}'s output:
+ * round-tripping through the parser would materialize every default into the
+ * hand-editable file and silently DROP fields the typed shape doesn't model yet
+ * (e.g. the notification polish fields `notifications.enabled` /
+ * `notifications.quietHours` that {@link ../tui/chrome/notify.ts} reads raw).
+ */
+export declare function loadRawAppConfig(): Record<string, unknown>;
+/** A partial config write: plain objects merge recursively, scalars/arrays
+ *  replace, and an explicit `undefined` DELETES the key (how "reset to
+ *  defaults" removes a block so the parser's defaults take over). */
+export type AppConfigPatch = {
+    [key: string]: unknown;
+};
+/**
+ * PURE — merge `patch` into `raw` without touching either input. Objects merge
+ * key-by-key (recursively), anything else replaces, and a key whose patch value
+ * is `undefined` is REMOVED from the result. Unknown user fields survive — the
+ * merge only visits keys the patch names.
+ */
+export declare function mergeConfigPatch(raw: Record<string, unknown>, patch: AppConfigPatch): Record<string, unknown>;
+/**
+ * io — apply a patch to the config file ATOMICALLY (temp + rename, the same
+ * discipline as the editor save): read raw → {@link mergeConfigPatch} → write.
+ * Busts the {@link getAppConfig} process cache and returns the new parsed
+ * config. Honors `TMUX_IDE_CONFIG`, so tests never touch the real file.
+ */
+export declare function updateAppConfig(patch: AppConfigPatch): AppConfig;

package/packages/daemon/dist/lib/app-config.js

@@ -20,9 +20,9 @@
  * per-concern readers ({@link ../tui/chrome/notify.ts}, {@link ../restore.ts})
  * now delegate here.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 // ---------------------------------------------------------------------------
 // Defaults
 // ---------------------------------------------------------------------------
@@ -50,12 +50,19 @@ export const DEFAULT_APP_CONFIG = {
         glyphs: { active: "●", inactive: "○" },
     },
     updater: { tickMs: 2000, snapshotEvery: 15 },
-    notifications: { toast: true, macos: false },
+    notifications: { toast: true, macos: false, terminal: true, delaySeconds: 2, sound: "blocked" },
     restore: { resumeAgents: false },
-    updates: { check: true },
+    updates: { check: true, manifests: false },
     welcome: { show: true },
     integrations: { offer: true },
     worktrees: { dir: "" },
+    app: {
+        frontDoor: false,
+        detachable: false,
+        dragSelect: "agents",
+        newAgentCwd: "pane",
+        kittyKeys: true,
+    },
 };
 /** The default theme tokens — the fallback threaded into the pure builders. */
 export const DEFAULT_THEME = DEFAULT_APP_CONFIG.theme;
@@ -82,6 +89,16 @@ function pickBool(value, fallback) {
 function pickPosInt(value, fallback) {
     return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
 }
+/** A non-negative integer (0 allowed — e.g. "no delay"), else the default. */
+function pickNonNegInt(value, fallback) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : fallback;
+}
+/** One of the allowed literals, else the default. */
+function pickChoice(value, allowed, fallback) {
+    return typeof value === "string" && allowed.includes(value)
+        ? value
+        : fallback;
+}
 /**
  * PURE — merge an unknown (typically parsed JSON) over {@link DEFAULT_APP_CONFIG}.
  * Every block/leaf is validated independently: a missing or mistyped field falls
@@ -103,6 +120,7 @@ export function parseAppConfig(input) {
     const welcome = asObject(root.welcome);
     const integrations = asObject(root.integrations);
     const worktrees = asObject(root.worktrees);
+    const app = asObject(root.app);
     return {
         keys: {
             popup: pickString(keys.popup, D.keys.popup),
@@ -139,12 +157,25 @@ export function parseAppConfig(input) {
         notifications: {
             toast: pickBool(notifications.toast, D.notifications.toast),
             macos: pickBool(notifications.macos, D.notifications.macos),
+            terminal: pickBool(notifications.terminal, D.notifications.terminal),
+            delaySeconds: pickNonNegInt(notifications.delaySeconds, D.notifications.delaySeconds),
+            sound: pickChoice(notifications.sound, ["blocked", "all", "none"], D.notifications.sound),
         },
         restore: { resumeAgents: pickBool(restore.resumeAgents, D.restore.resumeAgents) },
-        updates: { check: pickBool(updates.check, D.updates.check) },
+        updates: {
+            check: pickBool(updates.check, D.updates.check),
+            manifests: pickBool(updates.manifests, D.updates.manifests),
+        },
         welcome: { show: pickBool(welcome.show, D.welcome.show) },
         integrations: { offer: pickBool(integrations.offer, D.integrations.offer) },
         worktrees: { dir: pickString(worktrees.dir, D.worktrees.dir) },
+        app: {
+            frontDoor: pickBool(app.frontDoor, D.app.frontDoor),
+            detachable: pickBool(app.detachable, D.app.detachable),
+            dragSelect: pickChoice(app.dragSelect, ["agents", "always", "never"], D.app.dragSelect),
+            newAgentCwd: pickChoice(app.newAgentCwd, ["pane", "session"], D.app.newAgentCwd),
+            kittyKeys: pickBool(app.kittyKeys, D.app.kittyKeys),
+        },
     };
 }
 // ---------------------------------------------------------------------------
@@ -189,3 +220,71 @@ export function getAppConfig() {
 export function _resetForTests() {
     cached = null;
 }
+// ---------------------------------------------------------------------------
+// Writes (M22.4 — the settings surface persists through here)
+// ---------------------------------------------------------------------------
+/**
+ * io — the RAW parsed config file as the user wrote it (`{}` when missing or
+ * malformed). Writers merge over THIS, not over {@link parseAppConfig}'s output:
+ * round-tripping through the parser would materialize every default into the
+ * hand-editable file and silently DROP fields the typed shape doesn't model yet
+ * (e.g. the notification polish fields `notifications.enabled` /
+ * `notifications.quietHours` that {@link ../tui/chrome/notify.ts} reads raw).
+ */
+export function loadRawAppConfig() {
+    const path = appConfigPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function isPlainObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * PURE — merge `patch` into `raw` without touching either input. Objects merge
+ * key-by-key (recursively), anything else replaces, and a key whose patch value
+ * is `undefined` is REMOVED from the result. Unknown user fields survive — the
+ * merge only visits keys the patch names.
+ */
+export function mergeConfigPatch(raw, patch) {
+    const out = { ...raw };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined) {
+            delete out[key];
+        }
+        else if (isPlainObject(value) && isPlainObject(out[key])) {
+            out[key] = mergeConfigPatch(out[key], value);
+        }
+        else if (isPlainObject(value)) {
+            out[key] = mergeConfigPatch({}, value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * io — apply a patch to the config file ATOMICALLY (temp + rename, the same
+ * discipline as the editor save): read raw → {@link mergeConfigPatch} → write.
+ * Busts the {@link getAppConfig} process cache and returns the new parsed
+ * config. Honors `TMUX_IDE_CONFIG`, so tests never touch the real file.
+ */
+export function updateAppConfig(patch) {
+    const path = appConfigPath();
+    const merged = mergeConfigPatch(loadRawAppConfig(), patch);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf-8");
+    renameSync(tmp, path);
+    cached = null;
+    return parseAppConfig(merged);
+}

package/packages/daemon/dist/lib/manifest-pack.d.ts

@@ -0,0 +1,79 @@
+import type { AgentManifest } from "../tui/detect/manifest.ts";
+/** The pack-format version this build understands. */
+export declare const MANIFEST_PACK_SCHEMA = 1;
+/** The release asset name a pack is published under. */
+export declare const MANIFEST_PACK_ASSET = "agent-manifests.json";
+/** Env override for the pack URL (tests/dev; may be `file://` or loopback http). */
+export declare const MANIFEST_PACK_URL_ENV = "TMUX_IDE_MANIFEST_PACK_URL";
+/** A fetched/validated manifest pack. */
+export interface ManifestPack {
+    schema: number;
+    /** Pack version — informational (surfaced in logs), any non-empty string. */
+    pack: string;
+    manifests: AgentManifest[];
+}
+/**
+ * PURE — the default pack URL for a version:
+ * `https://github.com/<repo>/releases/download/v<version>/agent-manifests.json`
+ * (the same asset-URL construction as the TUI binary download).
+ */
+export declare function manifestPackUrl(version?: string): string;
+/**
+ * PURE — is `url` an acceptable pack source? `https:` always; `file:` and
+ * LOOPBACK `http:` (127.0.0.1 / localhost / [::1]) only so tests and local
+ * fixtures can drive the flow. Any other scheme/host is rejected.
+ */
+export declare function isAllowedPackUrl(url: string): boolean;
+/**
+ * PURE — validate an untrusted pack document. Returns the typed pack or a
+ * human-readable reason. Every manifest entry must pass the SAME structural
+ * validation user override files do ({@link validateManifestShape}) — one bad
+ * entry rejects the whole pack (a partial install would be harder to reason
+ * about than a loud failure). Never throws.
+ */
+export declare function validateManifestPack(value: unknown): {
+    ok: true;
+    pack: ManifestPack;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The installed pack's directory: `<agent-detection>/pack/`. */
+export declare function packDir(): string;
+/** The installed pack's path: `<agent-detection>/pack/manifest-pack.json`. */
+export declare function packPath(): string;
+/**
+ * io — fetch and validate a pack. `file://` URLs are read from disk (Node's
+ * fetch does not speak file:); everything else goes through fetch with a
+ * timeout. THROWS with an actionable message on a disallowed URL, a failed
+ * fetch, malformed JSON, or a schema-invalid pack — the caller decides whether
+ * that is loud (CLI) or swallowed (the background refresh).
+ */
+export declare function fetchManifestPack(url: string, timeoutMs?: number): Promise<ManifestPack>;
+/**
+ * io — write a validated pack into place atomically (temp-in-same-dir →
+ * rename, so a crash never leaves a half-written pack the loader would then
+ * warn about every run). Returns the installed path.
+ */
+export declare function installManifestPack(pack: ManifestPack, dest?: string): string;
+/**
+ * io — the `tmux-ide update --manifests` flow: resolve the URL (env override →
+ * the release-asset default), fetch, validate, install. Throws loudly on any
+ * failure (the CLI surfaces it); returns what was installed for reporting.
+ */
+export declare function updateManifestPack(opts?: {
+    url?: string;
+    log?: (msg: string) => void;
+}): Promise<{
+    path: string;
+    packVersion: string;
+    count: number;
+}>;
+/**
+ * io — the GATED background refresh the daily update check invokes (see
+ * `runUpdateCheck` in {@link ./update-check.ts}). Opt-in via
+ * `updates.manifests: true` (default false); NEVER throws — a failed refresh
+ * just keeps the previous pack, exactly like a failed version check keeps the
+ * previous `latest`.
+ */
+export declare function maybeRefreshManifestPack(): Promise<void>;