tmux-ide 2.1.4 → 2.6.0

package/packages/daemon/dist/lib/workspace-registry.js

@@ -0,0 +1,176 @@
+/**
+ * Workspace registry — runtime list of projects the daemon is serving.
+ *
+ * Replaces the legacy single-session TMUX_IDE_SESSION env coupling so a
+ * single daemon can host N concurrent projects (goal 12, T065).
+ *
+ * Persisted at ~/.tmux-ide/workspaces.json via atomic temp+rename. On
+ * `load()` the registry reconciles itself against `tmux list-sessions`
+ * output and drops entries whose session no longer exists.
+ *
+ * Distinct from project-registry.ts — that one is a long-lived
+ * "bookmark list" of projects the user knows about (probed metadata).
+ * This one tracks live workspaces and is reconciled with tmux on boot.
+ */
+import { EventEmitter } from "node:events";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { WorkspaceSchemaZ } from "@tmux-ide/contracts";
+const REGISTRY_DIR_ENV = "TMUX_IDE_REGISTRY_DIR";
+const RegistryFileSchemaZ = z.object({
+    version: z.literal(1),
+    workspaces: z.array(WorkspaceSchemaZ),
+});
+export class WorkspaceAlreadyExistsError extends Error {
+    code = "ALREADY_EXISTS";
+    constructor(name) {
+        super(`Workspace "${name}" already exists`);
+        this.name = "WorkspaceAlreadyExistsError";
+    }
+}
+export class WorkspaceNotFoundError extends Error {
+    code = "NOT_FOUND";
+    constructor(name) {
+        super(`Workspace "${name}" not found`);
+        this.name = "WorkspaceNotFoundError";
+    }
+}
+export class WorkspaceRegistry {
+    dir;
+    listSessions;
+    emitter = new EventEmitter();
+    workspaces = [];
+    loaded = false;
+    constructor(options = {}) {
+        this.dir = options.dir ?? process.env[REGISTRY_DIR_ENV] ?? join(homedir(), ".tmux-ide");
+        this.listSessions = options.listSessions ?? defaultListSessions;
+        this.emitter.setMaxListeners(0);
+    }
+    /**
+     * Load workspaces from disk and reconcile against live tmux sessions.
+     * Drops entries whose tmux session is gone (silently — they were
+     * persisted by a prior daemon invocation that may have crashed).
+     *
+     * Safe to call repeatedly; subsequent calls re-reconcile.
+     */
+    async load() {
+        const fromDisk = this.readDisk();
+        let live;
+        try {
+            live = new Set(this.listSessions());
+        }
+        catch {
+            // tmux is unavailable — keep all entries; reconcile when we can.
+            live = new Set(fromDisk.map((w) => w.sessionName));
+        }
+        const reconciled = fromDisk.filter((w) => live.has(w.sessionName));
+        this.workspaces = reconciled;
+        this.loaded = true;
+        if (reconciled.length !== fromDisk.length) {
+            this.writeDisk();
+        }
+    }
+    list() {
+        return [...this.workspaces];
+    }
+    get(name) {
+        return this.workspaces.find((w) => w.name === name) ?? null;
+    }
+    has(name) {
+        return this.workspaces.some((w) => w.name === name);
+    }
+    add(input) {
+        if (this.has(input.name)) {
+            throw new WorkspaceAlreadyExistsError(input.name);
+        }
+        const now = (input.now ?? (() => new Date()))();
+        const workspace = {
+            name: input.name,
+            sessionName: input.sessionName ?? input.name,
+            projectDir: input.projectDir,
+            ideConfigPath: input.ideConfigPath ?? null,
+            addedAt: now.toISOString(),
+        };
+        this.workspaces = [...this.workspaces, workspace];
+        this.writeDisk();
+        this.emitter.emit("workspace.added", workspace);
+        return workspace;
+    }
+    remove(name) {
+        if (!this.has(name)) {
+            throw new WorkspaceNotFoundError(name);
+        }
+        this.workspaces = this.workspaces.filter((w) => w.name !== name);
+        this.writeDisk();
+        this.emitter.emit("workspace.removed", name);
+    }
+    /** Subscribe to workspace.added | workspace.removed events. */
+    on(event, handler) {
+        this.emitter.on(event, handler);
+        return () => this.emitter.off(event, handler);
+    }
+    // ----------------- io -----------------
+    filePath() {
+        return join(this.dir, "workspaces.json");
+    }
+    readDisk() {
+        const path = this.filePath();
+        if (!existsSync(path))
+            return [];
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path, "utf-8"));
+        }
+        catch {
+            return [];
+        }
+        const result = RegistryFileSchemaZ.safeParse(parsed);
+        if (!result.success)
+            return [];
+        return result.data.workspaces;
+    }
+    writeDisk() {
+        const path = this.filePath();
+        mkdirSync(dirname(path), { recursive: true });
+        const file = { version: 1, workspaces: this.workspaces };
+        const tmp = `${path}.tmp`;
+        writeFileSync(tmp, JSON.stringify(file, null, 2) + "\n");
+        renameSync(tmp, path);
+    }
+    /** @internal Test-only: assert the registry is loaded. */
+    _isLoaded() {
+        return this.loaded;
+    }
+}
+// ---------------------------------------------------------------------------
+// Default singleton — the daemon process holds one registry; HTTP handlers
+// import it via getDefaultWorkspaceRegistry().
+// ---------------------------------------------------------------------------
+let _default = null;
+export function getDefaultWorkspaceRegistry() {
+    if (!_default)
+        _default = new WorkspaceRegistry();
+    return _default;
+}
+/** @internal Test hook: replace the singleton. */
+export function _setDefaultWorkspaceRegistryForTests(registry) {
+    _default = registry;
+}
+function defaultListSessions() {
+    // Lazy import keeps tmux-bridge optional for test environments that
+    // don't have tmux available; tests inject a stub instead.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { execFileSync } = require("node:child_process");
+    try {
+        const raw = execFileSync("tmux", ["list-sessions", "-F", "#{session_name}"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return raw.split("\n").filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}

package/packages/daemon/dist/lib/worktree.d.ts

@@ -0,0 +1,76 @@
+import { IdeError } from "./errors.ts";
+export type WorktreeErrorCode = "NOT_A_GIT_REPO" | "BRANCH_EXISTS" | "BRANCH_NOT_FOUND" | "ALREADY_CHECKED_OUT" | "WORKTREE_EXISTS" | "WORKTREE_DIRTY" | "WORKTREE_NOT_FOUND" | "GIT_FAILED";
+export declare class WorktreeError extends IdeError {
+    constructor(message: string, code: WorktreeErrorCode);
+}
+/**
+ * PURE — the tmux session name for a project's worktree on `branch`, e.g.
+ * `myapp@fix-auth`. Both sides are sanitized ({@link sanitizeForTmux}) so a
+ * dotted/colon'd branch (or project) stays a single inert session name; the
+ * `@` separator is preserved so the session reads as "project, this branch".
+ */
+export declare function worktreeSessionName(project: string, branch: string): string;
+/**
+ * PURE — the default base directory for a repo's worktrees: a SIBLING of the
+ * repo named `<repo-name>-worktrees`. Kept outside the repo so a worktree is
+ * never nested inside its own parent checkout (which git rejects and which
+ * would pollute the project tree).
+ */
+export declare function defaultWorktreeBaseDir(repoDir: string): string;
+/**
+ * PURE — the on-disk path for a worktree of `branch`. Defaults to
+ * `<repo>/../<repo-name>-worktrees/<branch>`; a non-empty `configuredDir` (the
+ * app-config `worktrees.dir` override) replaces the base, resolved relative to
+ * the repo when it isn't absolute. The branch is the final path segment (a
+ * slashed branch nests, which `git worktree add` creates).
+ */
+export declare function worktreePath(repoDir: string, branch: string, configuredDir?: string | null): string;
+/** A single record from `git worktree list --porcelain`. */
+export interface WorktreeEntry {
+    /** Absolute path of the worktree. */
+    path: string;
+    /** The checked-out commit sha, or null (bare repo). */
+    head: string | null;
+    /** Short branch name (no `refs/heads/`), or null when detached/bare. */
+    branch: string | null;
+    /** The bare repository entry. */
+    bare: boolean;
+    /** A detached-HEAD worktree (no branch). */
+    detached: boolean;
+}
+/**
+ * PURE — parse `git worktree list --porcelain`. Records are separated by blank
+ * lines; each has a `worktree <path>` line, then optional `HEAD <sha>`,
+ * `branch refs/heads/<name>`, `bare`, `detached` attribute lines. Unknown
+ * attribute lines are ignored. Malformed/empty input yields `[]`.
+ */
+export declare function parseWorktreeList(porcelain: string): WorktreeEntry[];
+/**
+ * PURE — map a failed `git` invocation's stderr to a typed
+ * {@link WorktreeError}. Recognizes the common worktree failures so the CLI can
+ * surface an actionable message instead of a raw git dump; anything unmatched
+ * falls back to `GIT_FAILED` carrying the trimmed stderr.
+ */
+export declare function mapWorktreeError(stderr: string, fallbackMessage: string): WorktreeError;
+/** Injectable git runner so io wrappers stay unit-testable. */
+export type GitRunner = (repoDir: string, args: string[]) => string;
+/** Swap the git runner (tests). Returns a restore fn. */
+export declare function _setGitRunnerForTests(fn: GitRunner): () => void;
+export interface CreateWorktreeOptions {
+    /** Create a NEW branch (git worktree add -b). Off → check out an existing branch. */
+    newBranch?: boolean;
+    /** Base ref for the new branch (default: current HEAD). Only used with newBranch. */
+    from?: string | null;
+}
+/**
+ * Add a git worktree for `branch` at `worktreeAbsPath` and return that path.
+ * With `newBranch`, creates the branch (optionally off `from`); otherwise
+ * checks out an existing branch. Failures throw a typed {@link WorktreeError}.
+ */
+export declare function createWorktree(repoDir: string, branch: string, worktreeAbsPath: string, options?: CreateWorktreeOptions): string;
+/** Remove a git worktree by path. `force` discards uncommitted changes. */
+export declare function removeWorktree(repoDir: string, worktreeAbsPath: string, options?: {
+    force?: boolean;
+}): void;
+/** List the repo's worktrees. Throws a typed {@link WorktreeError} on failure. */
+export declare function listWorktrees(repoDir: string): WorktreeEntry[];

package/packages/daemon/dist/lib/worktree.js

@@ -0,0 +1,207 @@
+/**
+ * Git worktree flow — one checkout per branch so parallel agents (or a fleet)
+ * each work on isolation. `tmux-ide worktree create <branch>` adds a git
+ * worktree in a SIBLING directory (never inside the repo) and opens a tmux
+ * session there; the CLI (`bin/cli.ts`, `worktree` case) wires the io.
+ *
+ * The pure helpers — {@link worktreeSessionName}, {@link worktreePath},
+ * {@link parseWorktreeList}, {@link mapWorktreeError} — carry no io so they're
+ * cheaply testable. The io wrappers ({@link createWorktree},
+ * {@link removeWorktree}, {@link listWorktrees}) shell out to `git` and map its
+ * stderr into a typed {@link WorktreeError} with an actionable message.
+ */
+import { execFileSync } from "node:child_process";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { IdeError } from "./errors.js";
+export class WorktreeError extends IdeError {
+    constructor(message, code) {
+        super(message, { code, exitCode: 1 });
+        this.name = "WorktreeError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+/**
+ * PURE — sanitize a component for a tmux session name. tmux treats `:` as a
+ * target separator and silently rewrites `.` to `_`, so we normalize both (plus
+ * whitespace) to `-` up front, keeping the name stable and predictable. `/` is
+ * left intact — tmux accepts it in session names (verified live on tmux 3.6).
+ */
+function sanitizeForTmux(part) {
+    // Slashes too: `feat/x` would parse as a path-ish target in tmux commands
+    // and can't appear in the status bar's `#[range=user|sw<name>]` mouse ranges.
+    return part.replace(/[.:/\s]+/g, "-");
+}
+/**
+ * PURE — the tmux session name for a project's worktree on `branch`, e.g.
+ * `myapp@fix-auth`. Both sides are sanitized ({@link sanitizeForTmux}) so a
+ * dotted/colon'd branch (or project) stays a single inert session name; the
+ * `@` separator is preserved so the session reads as "project, this branch".
+ */
+export function worktreeSessionName(project, branch) {
+    return `${sanitizeForTmux(project)}@${sanitizeForTmux(branch)}`;
+}
+/**
+ * PURE — the default base directory for a repo's worktrees: a SIBLING of the
+ * repo named `<repo-name>-worktrees`. Kept outside the repo so a worktree is
+ * never nested inside its own parent checkout (which git rejects and which
+ * would pollute the project tree).
+ */
+export function defaultWorktreeBaseDir(repoDir) {
+    const abs = resolve(repoDir);
+    return join(dirname(abs), `${basename(abs)}-worktrees`);
+}
+/**
+ * PURE — the on-disk path for a worktree of `branch`. Defaults to
+ * `<repo>/../<repo-name>-worktrees/<branch>`; a non-empty `configuredDir` (the
+ * app-config `worktrees.dir` override) replaces the base, resolved relative to
+ * the repo when it isn't absolute. The branch is the final path segment (a
+ * slashed branch nests, which `git worktree add` creates).
+ */
+export function worktreePath(repoDir, branch, configuredDir) {
+    const base = configuredDir && configuredDir.length > 0
+        ? isAbsolute(configuredDir)
+            ? configuredDir
+            : resolve(repoDir, configuredDir)
+        : defaultWorktreeBaseDir(repoDir);
+    return join(base, branch);
+}
+/**
+ * PURE — parse `git worktree list --porcelain`. Records are separated by blank
+ * lines; each has a `worktree <path>` line, then optional `HEAD <sha>`,
+ * `branch refs/heads/<name>`, `bare`, `detached` attribute lines. Unknown
+ * attribute lines are ignored. Malformed/empty input yields `[]`.
+ */
+export function parseWorktreeList(porcelain) {
+    const entries = [];
+    let current = null;
+    const flush = () => {
+        if (current)
+            entries.push(current);
+        current = null;
+    };
+    for (const rawLine of porcelain.split("\n")) {
+        const line = rawLine.replace(/\r$/, "");
+        if (line.length === 0) {
+            flush();
+            continue;
+        }
+        if (line.startsWith("worktree ")) {
+            flush();
+            current = {
+                path: line.slice("worktree ".length),
+                head: null,
+                branch: null,
+                bare: false,
+                detached: false,
+            };
+            continue;
+        }
+        if (!current)
+            continue;
+        if (line.startsWith("HEAD ")) {
+            current.head = line.slice("HEAD ".length);
+        }
+        else if (line.startsWith("branch ")) {
+            current.branch = line.slice("branch ".length).replace(/^refs\/heads\//, "");
+        }
+        else if (line === "bare") {
+            current.bare = true;
+        }
+        else if (line === "detached") {
+            current.detached = true;
+        }
+    }
+    flush();
+    return entries;
+}
+/**
+ * PURE — map a failed `git` invocation's stderr to a typed
+ * {@link WorktreeError}. Recognizes the common worktree failures so the CLI can
+ * surface an actionable message instead of a raw git dump; anything unmatched
+ * falls back to `GIT_FAILED` carrying the trimmed stderr.
+ */
+export function mapWorktreeError(stderr, fallbackMessage) {
+    const text = stderr.trim();
+    const lower = text.toLowerCase();
+    if (lower.includes("not a git repository")) {
+        return new WorktreeError("Not a git repository. Run `tmux-ide worktree` from inside a git repo.", "NOT_A_GIT_REPO");
+    }
+    if (lower.includes("already exists") && lower.includes("branch")) {
+        return new WorktreeError(`${text}\nUse \`tmux-ide worktree create <branch>\` without --from to check out the existing branch, or pick a new name.`, "BRANCH_EXISTS");
+    }
+    if (lower.includes("is already checked out") || lower.includes("already used by worktree")) {
+        return new WorktreeError(text, "ALREADY_CHECKED_OUT");
+    }
+    if (lower.includes("already exists")) {
+        return new WorktreeError(text, "WORKTREE_EXISTS");
+    }
+    if ((lower.includes("invalid reference") || lower.includes("not a valid ref")) &&
+        !lower.includes("already")) {
+        return new WorktreeError(text, "BRANCH_NOT_FOUND");
+    }
+    if (lower.includes("contains modified or untracked files") ||
+        lower.includes("use --force") ||
+        lower.includes("use 'remove -f'")) {
+        return new WorktreeError(`${text}\nRe-run with --force to discard those changes.`, "WORKTREE_DIRTY");
+    }
+    if (lower.includes("is not a working tree") || lower.includes("not a working tree")) {
+        return new WorktreeError(text, "WORKTREE_NOT_FOUND");
+    }
+    return new WorktreeError(text.length > 0 ? text : fallbackMessage, "GIT_FAILED");
+}
+let gitRunner = (repoDir, args) => execFileSync("git", args, {
+    cwd: repoDir,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+});
+/** Swap the git runner (tests). Returns a restore fn. */
+export function _setGitRunnerForTests(fn) {
+    const prev = gitRunner;
+    gitRunner = fn;
+    return () => {
+        gitRunner = prev;
+    };
+}
+function runGit(repoDir, args, fallbackMessage) {
+    try {
+        return gitRunner(repoDir, args);
+    }
+    catch (error) {
+        const stderr = error.stderr;
+        const text = stderr ? stderr.toString() : "";
+        throw mapWorktreeError(text, fallbackMessage);
+    }
+}
+/**
+ * Add a git worktree for `branch` at `worktreeAbsPath` and return that path.
+ * With `newBranch`, creates the branch (optionally off `from`); otherwise
+ * checks out an existing branch. Failures throw a typed {@link WorktreeError}.
+ */
+export function createWorktree(repoDir, branch, worktreeAbsPath, options = {}) {
+    const args = ["worktree", "add"];
+    if (options.newBranch) {
+        args.push("-b", branch, worktreeAbsPath);
+        if (options.from && options.from.length > 0)
+            args.push(options.from);
+    }
+    else {
+        args.push(worktreeAbsPath, branch);
+    }
+    runGit(repoDir, args, `Failed to create worktree for ${branch}`);
+    return worktreeAbsPath;
+}
+/** Remove a git worktree by path. `force` discards uncommitted changes. */
+export function removeWorktree(repoDir, worktreeAbsPath, options = {}) {
+    const args = ["worktree", "remove"];
+    if (options.force)
+        args.push("--force");
+    args.push(worktreeAbsPath);
+    runGit(repoDir, args, `Failed to remove worktree ${worktreeAbsPath}`);
+}
+/** List the repo's worktrees. Throws a typed {@link WorktreeError} on failure. */
+export function listWorktrees(repoDir) {
+    const out = runGit(repoDir, ["worktree", "list", "--porcelain"], "Failed to list worktrees");
+    return parseWorktreeList(out);
+}

package/packages/daemon/dist/lib/yaml-io.d.ts

@@ -0,0 +1,10 @@
+import type { IdeConfig } from "../types.ts";
+export declare function readConfig(dir: string): {
+    config: IdeConfig;
+    configPath: string;
+};
+export declare function writeConfig(dir: string, config: IdeConfig): string;
+export declare function getSessionName(dir: string): {
+    name: string;
+    source: "config" | "fallback";
+};

package/packages/daemon/dist/lib/yaml-io.js

@@ -0,0 +1,24 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve, basename } from "node:path";
+import yaml from "js-yaml";
+export function readConfig(dir) {
+    const configPath = resolve(dir, "ide.yml");
+    const raw = readFileSync(configPath, "utf-8");
+    const config = yaml.load(raw);
+    return { config, configPath };
+}
+export function writeConfig(dir, config) {
+    const configPath = resolve(dir, "ide.yml");
+    const out = yaml.dump(config, { lineWidth: -1, noRefs: true, quotingType: '"' });
+    writeFileSync(configPath, out);
+    return configPath;
+}
+export function getSessionName(dir) {
+    try {
+        const { config } = readConfig(dir);
+        return { name: config.name ?? basename(dir), source: config.name ? "config" : "fallback" };
+    }
+    catch {
+        return { name: basename(dir), source: "fallback" };
+    }
+}

package/packages/daemon/dist/ls.d.ts

@@ -0,0 +1,3 @@
+export declare function ls({ json }?: {
+    json?: boolean;
+}): Promise<void>;

package/packages/daemon/dist/ls.js

@@ -0,0 +1,35 @@
+import { execSync } from "node:child_process";
+export async function ls({ json } = {}) {
+    let raw;
+    try {
+        raw = execSync('tmux list-sessions -F "#{session_name}|#{session_created}|#{session_attached}"', { encoding: "utf-8" }).trim();
+    }
+    catch {
+        if (json) {
+            console.log(JSON.stringify({ sessions: [] }));
+        }
+        else {
+            console.log("No tmux sessions running.");
+        }
+        return;
+    }
+    const sessions = raw.split("\n").map((line) => {
+        const [name, created, attached] = line.split("|");
+        return {
+            name,
+            created: new Date(parseInt(created) * 1000).toISOString(),
+            attached: attached !== "0",
+        };
+    });
+    if (json) {
+        console.log(JSON.stringify({ sessions }, null, 2));
+        return;
+    }
+    // Table output
+    console.log("SESSION".padEnd(24) + "CREATED".padEnd(22) + "ATTACHED");
+    console.log("─".repeat(54));
+    for (const s of sessions) {
+        const date = new Date(s.created).toLocaleString();
+        console.log(s.name.padEnd(24) + date.padEnd(22) + (s.attached ? "yes" : "no"));
+    }
+}

package/packages/daemon/dist/restart.d.ts

@@ -0,0 +1,4 @@
+export declare function restart(targetDir: string | undefined, { json, attach }?: {
+    json?: boolean;
+    attach?: boolean;
+}): Promise<void>;

package/packages/daemon/dist/restart.js

@@ -0,0 +1,16 @@
+import { resolve } from "node:path";
+import { getSessionName } from "./lib/yaml-io.js";
+import { launch } from "./launch.js";
+import { killSession, stopSessionMonitor } from "@tmux-ide/tmux-bridge";
+export async function restart(targetDir, { json, attach } = {}) {
+    const dir = resolve(targetDir ?? ".");
+    const { name: session } = getSessionName(dir);
+    // Stop the session monitor first — this triggers orchestrator graceful
+    // shutdown (release tasks, save state) before we kill the tmux session.
+    stopSessionMonitor(session);
+    const result = killSession(session);
+    if (result.stopped) {
+        console.log(`Stopped session "${session}"`);
+    }
+    await launch(dir, { json, attach });
+}

package/packages/daemon/dist/restore.d.ts

@@ -0,0 +1,86 @@
+import { type FleetSnapshot, type PaneSnapshot, type SessionSnapshot } from "./tui/chrome/snapshot.ts";
+/**
+ * One restore action per snapshot session:
+ *  - `skip`    — a live session already owns the name; never clobber it.
+ *  - `launch`  — the session maps to a registry project WITH an ide.yml; the
+ *                config is the source of truth, so relaunch it instead of a raw
+ *                rebuild.
+ *  - `rebuild` — raw reconstruction from the snapshot (windows/panes/layout).
+ */
+export type RestoreAction = {
+    kind: "skip";
+    session: string;
+} | {
+    kind: "launch";
+    session: string;
+    dir: string;
+} | {
+    kind: "rebuild";
+    session: SessionSnapshot;
+};
+export interface RestorePlan {
+    actions: RestoreAction[];
+    /** Total panes across `rebuild` actions (what restore directly creates). */
+    paneCount: number;
+}
+/**
+ * PURE — decide what to do with each snapshot session.
+ *
+ * Sessions are processed in snapshot order. A name that's already live is
+ * skipped. Otherwise, when `ideProjects` maps the name to a directory (a
+ * registry project whose dir has an ide.yml), we prefer relaunching from that
+ * config; failing that, we raw-rebuild from the recorded windows/panes.
+ */
+export declare function buildRestorePlan(snapshot: FleetSnapshot, liveSessionNames: Iterable<string>, ideProjects?: Map<string, string>): RestorePlan;
+/**
+ * PURE — the command to relaunch a pane so its agent conversation is revived,
+ * or `null` for "no resume — leave it a plain shell (or replay `command`)".
+ *
+ * Decision table (only fires when `resumeAgents` is on):
+ *  - claude + a recorded `@agent_session_id` → `claude --resume <id>`. The id is
+ *    a uuid, but we don't trust the snapshot: unless it matches
+ *    {@link SAFE_SESSION_ID} (`[A-Za-z0-9-]`) we bail to `null` rather than risk
+ *    feeding shell metacharacters into send-keys.
+ *  - claude with NO session id → `null`. `claude --continue` would be too
+ *    magical here (it resumes the most-recent conversation in the cwd, which may
+ *    belong to a different pane); a fresh shell is the safe, predictable default.
+ *  - any other agent → `null`. No native resume story yet.
+ *  - `resumeAgents` off → always `null`.
+ */
+export declare function paneResumeCommand(pane: PaneSnapshot, opts: {
+    resumeAgents: boolean;
+}): string | null;
+/** PURE — how many of a session's panes would resume under `resumeAgents`. */
+export declare function countResumableAgents(session: SessionSnapshot, resumeAgents: boolean): number;
+/** Restore behaviour toggles (minimal, pre-M14). */
+export interface RestorePrefs {
+    resumeAgents: boolean;
+}
+/** Default: don't resume agents unless asked (flag or config). */
+export declare const DEFAULT_RESTORE_PREFS: RestorePrefs;
+/**
+ * PURE — read `{ restore: { resumeAgents } }` out of a parsed config, falling
+ * back to {@link DEFAULT_RESTORE_PREFS} for anything missing or mistyped.
+ * Delegates to the shared {@link parseAppConfig} so restore parsing can't drift
+ * from the rest of the config.
+ */
+export declare function restorePrefs(parsedConfig: unknown): RestorePrefs;
+/** Absolute path to the shared config (honors `TMUX_IDE_CONFIG`). */
+export declare function restoreConfigPath(): string;
+/** io — resolve restore prefs from the shared app config; missing/invalid → defaults. */
+export declare function readRestorePrefs(): RestorePrefs;
+export interface RestoreOptions {
+    json?: boolean;
+    dryRun?: boolean;
+    runCommands?: boolean;
+    /** Relaunch resumable agent panes (`--resume-agents`); ORed with config default. */
+    resumeAgents?: boolean;
+}
+/**
+ * Rebuild the fleet from the last snapshot. Missing snapshot → friendly exit 1.
+ * `dryRun` prints the plan without touching tmux; `runCommands` opts into
+ * replaying recorded pane commands (off by default for safety); `resumeAgents`
+ * (flag ORed with the `~/.tmux-ide/config.json` default) revives agent
+ * conversations via `claude --resume <id>`.
+ */
+export declare function restore({ json, dryRun, runCommands, resumeAgents, }?: RestoreOptions): Promise<void>;