tmux-ide 2.7.0 → 2.9.0-beta.5

package/packages/daemon/dist/lib/__tests__/fixtures/workspace-state-writer.js

@@ -0,0 +1,58 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { createProjectRuntimeRepository } from "../../project-runtime-repository.js";
+import { captureWorkspaceObservation, createWorkspaceLayout } from "../../workspace-state.js";
+import { loadWorkspaceState, workspaceCheckoutKey, writeWorkspaceStateWithRetry, } from "../../workspace-state-repository.js";
+const [home, projectRoot, layoutId, readyPath, goPath] = process.argv.slice(2);
+if (!home || !projectRoot || !layoutId || !readyPath || !goPath) {
+    throw new Error("home, projectRoot, layoutId, readyPath, and goPath are required");
+}
+const repository = createProjectRuntimeRepository({
+    inputDir: projectRoot,
+    projectRoot,
+    identityKey: `git-${"c".repeat(64)}`,
+    identitySource: "git-common-dir",
+    identityAnchor: "/shared/.git",
+    config: { kind: "none", path: null, explicit: false },
+    workspaceConfigPath: null,
+    legacyConfigPath: null,
+    hasLegacyConfigAtInput: false,
+}, { home });
+const loaded = loadWorkspaceState(repository);
+const checkoutKey = workspaceCheckoutKey(projectRoot);
+let next = captureWorkspaceObservation(loaded.state, {
+    checkoutKey,
+    projectRoot,
+    observedAt: "2026-07-20T12:00:00.000Z",
+    sessionName: null,
+    windowIndex: null,
+    windowName: null,
+    panes: [],
+    focusedPaneId: null,
+    workbench: {
+        canvasPanel: "home",
+        dock: { activeTab: "files", mode: "open", preferredHeight: null, focusZone: "canvas" },
+    },
+});
+next = createWorkspaceLayout(next, {
+    id: layoutId,
+    name: layoutId,
+    checkoutKey,
+    now: "2026-07-20T12:00:00.000Z",
+});
+writeFileSync(readyPath, "ready\n", "utf8");
+while (!existsSync(goPath))
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+const result = writeWorkspaceStateWithRetry({
+    repository,
+    revision: loaded.revision,
+    next,
+    touchedLayoutIds: new Set([layoutId]),
+    checkoutIntents: new Map([
+        [checkoutKey, new Set(["live", "workbench", "focus", "active-layout"])],
+    ]),
+    lock: { timeoutMs: 5_000 },
+});
+if (!result.saved) {
+    process.stderr.write(`${JSON.stringify(result.diagnostics)}\n`);
+    process.exitCode = 1;
+}

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/agent-kind.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve a configured launch command to the stable agent id stamped on the
+ * pane. Only executable-like argv tokens are considered so paths such as
+ * `~/.claude/notes.md` cannot accidentally turn a regular editor into an
+ * agent. Runtime process-tree detection remains the fallback for wrappers.
+ */
+export declare function agentHintForCommand(command: string | null | undefined): string | null;

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

@@ -0,0 +1,24 @@
+import { KNOWN_AGENTS } from "./agent-discovery.js";
+/**
+ * Resolve a configured launch command to the stable agent id stamped on the
+ * pane. Only executable-like argv tokens are considered so paths such as
+ * `~/.claude/notes.md` cannot accidentally turn a regular editor into an
+ * agent. Runtime process-tree detection remains the fallback for wrappers.
+ */
+export function agentHintForCommand(command) {
+    if (!command)
+        return null;
+    const parts = command.trim().split(/\s+/u).filter(Boolean);
+    const candidates = parts
+        .slice(0, 2)
+        .filter((part) => !part.startsWith("-"))
+        .map((part) => {
+        const segments = part.split("/");
+        return segments[segments.length - 1]?.toLowerCase() ?? "";
+    });
+    for (const agent of KNOWN_AGENTS) {
+        if (candidates.includes(agent.bin.toLowerCase()))
+            return agent.id;
+    }
+    return null;
+}

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

@@ -1,4 +1,6 @@
 import type { AgentStatus } from "../tui/detect/classify.ts";
+import type { ThemeModeSetting } from "./theme-mode.ts";
+import { LEGACY_THEME_OVERRIDE_PROVENANCE, type LegacyThemeOverrideProvenance } from "./legacy-theme-compat.ts";
 /**
  * Root-table key binds (tmux key names) for the per-widget PANEL popups —
  * every widget is a floating app dialog one keystroke away, esc to close (the
@@ -42,6 +44,8 @@ export interface AppThemeGlyphs {
  * reads as one system.
  */
 export interface AppTheme {
+    /** Explicit palette mode or terminal-following mode. Default keeps legacy dark visuals. */
+    mode: ThemeModeSetting;
     /** Primary/brand accent (default `colour75`). */
     accent: string;
     /** Muted/secondary foreground for dim text (default `colour240`). */
@@ -52,6 +56,8 @@ export interface AppTheme {
     status: AppThemeStatus;
     /** The filled/hollow state glyphs. */
     glyphs: AppThemeGlyphs;
+    /** Internal, non-serializing record of legacy leaves genuinely present in the raw config. */
+    [LEGACY_THEME_OVERRIDE_PROVENANCE]?: LegacyThemeOverrideProvenance;
 }
 /** Chrome updater cadence. */
 export interface AppUpdater {
@@ -60,10 +66,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 +97,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 +125,54 @@ export interface AppIntegrations {
      */
     offer: boolean;
 }
+/** The unified-app front-door decision (M22.6). */
+export interface AppApp {
+    /**
+     * Whether bare `tmux-ide` (no workspace config here, no `--team`) launches
+     * the unified visual tmux app. Default true: a project file is an optional
+     * declarative preset, never the admission ticket to managing live tmux.
+     */
+    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 +193,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 +227,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,10 @@
  * 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";
+import { LEGACY_THEME_OVERRIDE_PROVENANCE, legacyThemeOverrideProvenance, } from "./legacy-theme-compat.js";
 // ---------------------------------------------------------------------------
 // Defaults
 // ---------------------------------------------------------------------------
@@ -37,6 +38,7 @@ export const DEFAULT_APP_CONFIG = {
         panels: { explorer: "M-e", changes: "M-g", config: "M-," },
     },
     theme: {
+        mode: "dark",
         accent: "colour75",
         muted: "colour240",
         fg: "colour250",
@@ -48,14 +50,22 @@ export const DEFAULT_APP_CONFIG = {
             unknown: "colour244",
         },
         glyphs: { active: "●", inactive: "○" },
+        [LEGACY_THEME_OVERRIDE_PROVENANCE]: legacyThemeOverrideProvenance(),
     },
     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: true,
+        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 +92,37 @@ 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;
+}
+function isExplicitString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function appThemeOverrideProvenance(theme, status, glyphs) {
+    const explicit = new Set();
+    if (isExplicitString(theme.accent))
+        explicit.add("accent");
+    if (isExplicitString(theme.muted))
+        explicit.add("muted");
+    if (isExplicitString(theme.fg))
+        explicit.add("fg");
+    for (const id of ["blocked", "working", "done", "idle", "unknown"]) {
+        if (isExplicitString(status[id]))
+            explicit.add(`status.${id}`);
+    }
+    for (const id of ["active", "inactive"]) {
+        if (isExplicitString(glyphs[id]))
+            explicit.add(`glyphs.${id}`);
+    }
+    return legacyThemeOverrideProvenance(explicit);
+}
 /**
  * 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 +144,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),
@@ -117,6 +159,7 @@ export function parseAppConfig(input) {
             },
         },
         theme: {
+            mode: pickChoice(theme.mode, ["dark", "light", "system"], D.theme.mode),
             accent: pickString(theme.accent, D.theme.accent),
             muted: pickString(theme.muted, D.theme.muted),
             fg: pickString(theme.fg, D.theme.fg),
@@ -131,6 +174,7 @@ export function parseAppConfig(input) {
                 active: pickString(glyphs.active, D.theme.glyphs.active),
                 inactive: pickString(glyphs.inactive, D.theme.glyphs.inactive),
             },
+            [LEGACY_THEME_OVERRIDE_PROVENANCE]: appThemeOverrideProvenance(theme, status, glyphs),
         },
         updater: {
             tickMs: pickPosInt(updater.tickMs, D.updater.tickMs),
@@ -139,12 +183,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 +246,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/app-window-kernel.d.ts

@@ -0,0 +1,64 @@
+import { type AppWindowDocumentV1, type AppWindowRect } from "@tmux-ide/contracts";
+export declare const APP_WINDOW_FLOAT_MIN_WIDTH = 20;
+export declare const APP_WINDOW_FLOAT_MIN_HEIGHT = 6;
+export type AppWindowKernelErrorCode = "WINDOW_NOT_FOUND" | "STACK_NOT_FOUND" | "WINDOW_NOT_IN_STACK" | "INVALID_PLACEMENT" | "LAYOUT_NOT_FOUND" | "INVALID_INPUT" | "TIMESTAMP_REGRESSION";
+export declare class AppWindowKernelError extends Error {
+    readonly code: AppWindowKernelErrorCode;
+    readonly path: string;
+    constructor(code: AppWindowKernelErrorCode, path: string, message: string);
+}
+export type AppWindowCommand = {
+    type: "window.focus";
+    windowId: string | null;
+} | {
+    type: "window.float";
+    windowId: string;
+    rect?: AppWindowRect;
+} | {
+    type: "window.dock";
+    windowId: string;
+    stackId?: string;
+    index?: number;
+} | {
+    type: "window.move";
+    windowId: string;
+    x: number;
+    y: number;
+} | {
+    type: "window.resize";
+    windowId: string;
+    width: number;
+    height: number;
+} | {
+    type: "stack.activate";
+    stackId: string;
+    windowId: string;
+} | {
+    type: "stack.reorder";
+    stackId: string;
+    windowId: string;
+    index: number;
+} | {
+    type: "layout.save";
+    layoutId: string;
+    name: string;
+    description?: string | null;
+} | {
+    type: "layout.restore";
+    layoutId: string;
+} | {
+    type: "layout.rename";
+    layoutId: string;
+    name: string;
+} | {
+    type: "layout.delete";
+    layoutId: string;
+};
+export declare function applyAppWindowCommand(document: AppWindowDocumentV1, command: AppWindowCommand, timestamp: string): AppWindowDocumentV1;
+/**
+ * True when reapplying a semantic command would only repeat an outcome already
+ * visible in the durable document. This is used after a CAS retry so commands
+ * such as delete/dock do not fail merely because another writer completed the
+ * same intent first.
+ */
+export declare function isAppWindowCommandSatisfied(document: AppWindowDocumentV1, command: AppWindowCommand): boolean;