@berthdev/berth 0.0.0-stage → 0.2.1-rc.0

package/dist/src/present/attach.js

@@ -0,0 +1,31 @@
+import { appendFileSync } from 'node:fs';
+import { stamp } from '../registry/sessions.js';
+import { isIterm2, presentState } from './state.js';
+/** iTerm2 user variable naming the session a pane shows (spec §7.3). */
+export const PANE_VARIABLE = 'berthSession';
+export function setUserVar(name, value) {
+    return `\x1b]1337;SetUserVar=${name}=${Buffer.from(value).toString('base64')}\x07`;
+}
+/**
+ * A client attached to a session, or switched to one (tmux hooks
+ * client-attached / client-session-changed). For iTerm2 the pane is marked
+ * with the session's name and the session's origin becomes iterm2; every
+ * client is shown the session's current state.
+ */
+export function clientAttached(ctx, client) {
+    const live = ctx.tmux.listSessions().find((s) => s.name === client.session);
+    if (!live?.meta.agent)
+        return;
+    if (isIterm2(client.termtype)) {
+        try {
+            appendFileSync(client.tty, setUserVar(PANE_VARIABLE, client.session));
+        }
+        catch {
+            // The client went away; nothing to mark.
+        }
+        if (live.meta.origin !== 'iterm2')
+            stamp(ctx, client.session, { origin: 'iterm2' });
+    }
+    presentState(ctx.tmux, client.session, live.meta.state ?? '', { note: live.meta.note, clients: [{ tty: client.tty, termtype: client.termtype }] });
+}
+//# sourceMappingURL=attach.js.map

package/dist/src/present/attach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.js","sourceRoot":"","sources":["../../../src/present/attach.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEpD,wEAAwE;AACxE,MAAM,CAAC,MAAM,aAAa,GAAG,cAAc,CAAC;AAE5C,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAa;IACpD,OAAO,wBAAwB,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;AACrF,CAAC;AAQD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,MAAsB;IACjE,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5E,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK;QAAE,OAAO;IAC9B,IAAI,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,cAAc,CAAC,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QACxE,CAAC;QAAC,MAAM,CAAC;YACP,yCAAyC;QAC3C,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,QAAQ;YAAE,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;AACrJ,CAAC"}

package/dist/src/present/state.d.ts

@@ -0,0 +1,14 @@
+import type { Tmux } from '../tmux/client.js';
+export declare function isIterm2(termtype: string): boolean;
+export declare function sequencesFor(state: string, session: string, iterm2: boolean, note?: string): string;
+export interface Client {
+    tty: string;
+    termtype: string;
+}
+export declare function clientsOf(tmux: Tmux, session: string): Client[];
+export interface PresentOptions {
+    note?: string;
+    clients?: Client[];
+}
+/** Write the state to each attached terminal; failures are ignored (best effort). */
+export declare function presentState(tmux: Tmux, session: string, state: string, options?: PresentOptions): number;

package/dist/src/present/state.js

@@ -0,0 +1,63 @@
+import { appendFileSync } from 'node:fs';
+/**
+ * Show a session's agent state on every terminal attached to it (spec §6, §7.4).
+ *
+ * Sequences are written straight to each client's tty, past tmux, so the
+ * outer terminal sees them. Which ones depends on the terminal, read from
+ * tmux's client_termtype:
+ * - iTerm2: its tab status sequence (OSC 21337) — a dot and a subtitle;
+ * - others (VS Code's xterm.js among them): OSC 9;4 progress, which VS Code
+ *   shows through `${progress}`, and an OSC 2 title.
+ */
+const GLYPH = { working: '●', waiting: '◐', done: '✓' };
+const PROGRESS = { working: '3', waiting: '4', done: '0' };
+const ITERM_COLOUR = { working: '#4f8fe6', waiting: '#ebaa28', done: '#50b464' };
+const ITERM_TEXT = { working: 'working', waiting: 'waiting for you', done: 'done' };
+const OSC = '\x1b]';
+const ST = '\x07';
+export function isIterm2(termtype) {
+    return /^iTerm2\b/i.test(termtype);
+}
+/** iTerm2's tab status may not contain the sequence separators. */
+function statusText(text) {
+    return text.replace(/[;\x07\x1b]/g, ' ').trim().slice(0, 80);
+}
+export function sequencesFor(state, session, iterm2, note = '') {
+    if (iterm2) {
+        const colour = ITERM_COLOUR[state];
+        if (!colour)
+            return `${OSC}21337;indicator=;status=${ST}`;
+        const text = statusText(state === 'waiting' && note ? note : ITERM_TEXT[state]);
+        return `${OSC}21337;indicator=${colour};status=${text};status-color=${colour}${ST}`;
+    }
+    const glyph = GLYPH[state];
+    return `${OSC}9;4;${PROGRESS[state] ?? '0'};0${ST}${OSC}2;${glyph ? `${glyph} ` : ''}${session}${ST}`;
+}
+export function clientsOf(tmux, session) {
+    const result = tmux.run(['list-clients', '-t', `=${session}`, '-F', '#{client_tty}\t#{client_termtype}'], true);
+    if (!result.ok)
+        return [];
+    return result.stdout
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => {
+        const [tty, termtype = ''] = line.split('\t');
+        return { tty, termtype };
+    });
+}
+/** Write the state to each attached terminal; failures are ignored (best effort). */
+export function presentState(tmux, session, state, options = {}) {
+    const clients = options.clients ?? clientsOf(tmux, session);
+    let written = 0;
+    for (const client of clients) {
+        try {
+            appendFileSync(client.tty, sequencesFor(state, session, isIterm2(client.termtype), options.note ?? ''));
+            written++;
+        }
+        catch {
+            // A client that went away or a tty we cannot write is not an error.
+        }
+    }
+    return written;
+}
+//# sourceMappingURL=state.js.map

package/dist/src/present/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/present/state.ts"],"names":[],"mappings":"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"}

package/dist/src/registry/doctor.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from '../context.js';
+export interface Finding {
+    session?: string;
+    problem: string;
+}
+/** Drift and gaps worth a user's attention; empty when all is well. */
+export declare function doctor(ctx: Context, env?: NodeJS.ProcessEnv): Finding[];

package/dist/src/registry/doctor.js

@@ -0,0 +1,31 @@
+import { existsSync } from 'node:fs';
+import { getAdapter } from '../agents/registry.js';
+import { hooksInstalled } from '../agents/hooks.js';
+import { list } from './sessions.js';
+/** Drift and gaps worth a user's attention; empty when all is well. */
+export function doctor(ctx, env = process.env) {
+    const findings = [];
+    const agentsInUse = new Set();
+    for (const row of list(ctx)) {
+        if (!row.managed)
+            continue;
+        agentsInUse.add(row.agent);
+        const adapter = getAdapter(row.agent);
+        if (!adapter) {
+            findings.push({ session: row.name, problem: `unknown agent ${row.agent}` });
+            continue;
+        }
+        if (!existsSync(row.cwd))
+            findings.push({ session: row.name, problem: `working directory missing: ${row.cwd}` });
+        if (adapter.resume && !row.conversation)
+            findings.push({ session: row.name, problem: 'conversation not bound; restore will start fresh' });
+    }
+    for (const agent of agentsInUse) {
+        const adapter = getAdapter(agent);
+        if (adapter?.hookTarget && !hooksInstalled(agent, env)) {
+            findings.push({ problem: `hooks for ${adapter.displayName} not installed (berth hooks install ${agent})` });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/src/registry/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/registry/doctor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAOrC,uEAAuE;AACvE,MAAM,UAAU,MAAM,CAAC,GAAY,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG;IACpD,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;IACtC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,IAAI,CAAC,GAAG,CAAC,OAAO;YAAE,SAAS;QAC3B,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC5E,SAAS;QACX,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,8BAA8B,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACjH,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,kDAAkD,EAAE,CAAC,CAAC;IAC7I,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,OAAO,EAAE,UAAU,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;YACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,aAAa,OAAO,CAAC,WAAW,uCAAuC,KAAK,GAAG,EAAE,CAAC,CAAC;QAC9G,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/src/registry/sessions.d.ts

@@ -0,0 +1,47 @@
+import type { Context } from '../context.js';
+/** One row of `berth ls` (implementation §2.2). */
+export interface SessionRow {
+    name: string;
+    managed: boolean;
+    agent: string;
+    cwd: string;
+    conversation: string;
+    origin: string;
+    state: string;
+    note: string;
+    attachedClients: number;
+    live: boolean;
+}
+export declare const ORIGINS: readonly ["vscode", "iterm2", "none"];
+export declare function list(ctx: Context): SessionRow[];
+export declare function sanitizeName(raw: string): string;
+/** Default name from the cwd's basename; suffix -2, -3, … on collision with any live session. */
+export declare function uniqueName(ctx: Context, base: string): string;
+export declare function checkOrigin(origin: string): string;
+export interface NewOptions {
+    agent: string;
+    cwd: string;
+    name?: string;
+    origin?: string;
+    extraArgs?: string[];
+}
+export declare function create(ctx: Context, options: NewOptions): string;
+export declare function requireLive(ctx: Context, name: string): void;
+/**
+ * Make a live session managed. Its directory is the one it records, else the
+ * active pane's current directory (a launcher may have changed into the
+ * project), else the session's start directory.
+ */
+export declare function adopt(ctx: Context, name: string, agent: string, origin?: string): void;
+export declare function stamp(ctx: Context, name: string, values: Record<string, string>): void;
+/** Note that marks a waiting state raised by a terminal bell rather than a hook. */
+export declare const BELL_NOTE = "bell";
+/**
+ * A terminal bell from a managed session (tmux alert-bell). Agents without
+ * Berth hooks get state `waiting`, so every agent can ask for attention; for
+ * agents whose hooks are installed the hooks are more precise and the bell
+ * is ignored. Returns whether the state changed.
+ */
+export declare function bellRang(ctx: Context, name: string, env?: NodeJS.ProcessEnv): boolean;
+/** Seeing a session answers its bell: clear a bell-raised waiting state. */
+export declare function clearBell(ctx: Context, name: string): void;

package/dist/src/registry/sessions.js

@@ -0,0 +1,138 @@
+import { basename } from 'node:path';
+import { BerthError, ExitCode } from '../errors.js';
+import { launchCommand, requireAdapter } from '../agents/commands.js';
+import { hooksInstalled } from '../agents/hooks.js';
+import { getAdapter } from '../agents/registry.js';
+import { snapshotQuietly } from '../snapshot/take.js';
+import { presentState } from '../present/state.js';
+export const ORIGINS = ['vscode', 'iterm2', 'none'];
+export function list(ctx) {
+    const live = ctx.tmux.listSessions();
+    const rows = live.map((s) => ({
+        name: s.name,
+        managed: Boolean(s.meta.agent),
+        agent: s.meta.agent ?? '',
+        cwd: s.meta.cwd ?? s.path,
+        conversation: s.meta.conversation ?? '',
+        origin: s.meta.origin ?? (s.meta.agent ? 'none' : ''),
+        state: s.meta.state ?? '',
+        note: s.meta.note ?? '',
+        attachedClients: s.attachedClients,
+        live: true,
+    }));
+    const liveNames = new Set(live.map((s) => s.name));
+    for (const s of ctx.store.newest()?.sessions ?? []) {
+        if (liveNames.has(s.name))
+            continue;
+        rows.push({ ...s, managed: true, state: '', note: '', attachedClients: 0, live: false });
+    }
+    return rows;
+}
+export function sanitizeName(raw) {
+    const cleaned = raw.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+    return cleaned || 'session';
+}
+/** Default name from the cwd's basename; suffix -2, -3, … on collision with any live session. */
+export function uniqueName(ctx, base) {
+    const taken = new Set(ctx.tmux.listSessions().map((s) => s.name));
+    const name = sanitizeName(base);
+    if (!taken.has(name))
+        return name;
+    for (let n = 2;; n++)
+        if (!taken.has(`${name}-${n}`))
+            return `${name}-${n}`;
+}
+export function checkOrigin(origin) {
+    if (!ORIGINS.includes(origin)) {
+        throw new BerthError(`origin must be one of ${ORIGINS.join(', ')}`, ExitCode.usage);
+    }
+    return origin;
+}
+export function create(ctx, options) {
+    const adapter = requireAdapter(options.agent);
+    const name = options.name ? sanitizeName(options.name) : uniqueName(ctx, basename(options.cwd));
+    if (ctx.tmux.hasSession(name))
+        throw new BerthError(`session already exists: ${name}`, ExitCode.usage);
+    const command = launchCommand({ adapter, name, cwd: options.cwd, extraArgs: options.extraArgs, overrides: ctx.config.agents });
+    ctx.tmux.newSession(name, options.cwd, command);
+    ctx.tmux.setMeta(name, {
+        agent: adapter.id,
+        cwd: options.cwd,
+        argv: command,
+        origin: checkOrigin(options.origin ?? 'none'),
+    });
+    ctx.tmux.setTitle(name);
+    snapshotQuietly(ctx);
+    return name;
+}
+export function requireLive(ctx, name) {
+    if (!ctx.tmux.hasSession(name))
+        throw new BerthError(`no such session: ${name}`, ExitCode.notFound);
+}
+/**
+ * Make a live session managed. Its directory is the one it records, else the
+ * active pane's current directory (a launcher may have changed into the
+ * project), else the session's start directory.
+ */
+export function adopt(ctx, name, agent, origin) {
+    requireLive(ctx, name);
+    const adapter = requireAdapter(agent);
+    const live = ctx.tmux.listSessions().find((s) => s.name === name);
+    ctx.tmux.setMeta(name, {
+        agent: adapter.id,
+        cwd: live?.meta.cwd ?? ctx.tmux.paneCurrentPath(name) ?? live?.path ?? '',
+        argv: live?.meta.argv ?? adapter.launch.replace(/\{\w+\}/g, '').trim(),
+        origin: checkOrigin(origin ?? live?.meta.origin ?? 'none'),
+    });
+    ctx.tmux.setTitle(name);
+    snapshotQuietly(ctx);
+}
+const STAMPABLE = new Set(['agent', 'cwd', 'argv', 'conversation', 'origin', 'state', 'note']);
+export function stamp(ctx, name, values) {
+    requireLive(ctx, name);
+    const meta = {};
+    for (const [key, value] of Object.entries(values)) {
+        if (!STAMPABLE.has(key))
+            throw new BerthError(`cannot stamp ${key}`, ExitCode.usage);
+        if (key === 'origin')
+            checkOrigin(value);
+        if (key === 'agent')
+            requireAdapter(value);
+        meta[key] = value;
+    }
+    ctx.tmux.setMeta(name, meta);
+    // A state change shows on attached terminals whoever reports it (spec §6, §7).
+    if (meta.state !== undefined) {
+        const note = meta.note ?? ctx.tmux.listSessions().find((s) => s.name === name)?.meta.note;
+        presentState(ctx.tmux, name, meta.state, { note });
+    }
+    // What a restore needs changed: record it now, not at the next session event.
+    if (['agent', 'cwd', 'argv', 'conversation', 'origin'].some((k) => k in meta))
+        snapshotQuietly(ctx);
+}
+/** Note that marks a waiting state raised by a terminal bell rather than a hook. */
+export const BELL_NOTE = 'bell';
+/**
+ * A terminal bell from a managed session (tmux alert-bell). Agents without
+ * Berth hooks get state `waiting`, so every agent can ask for attention; for
+ * agents whose hooks are installed the hooks are more precise and the bell
+ * is ignored. Returns whether the state changed.
+ */
+export function bellRang(ctx, name, env = process.env) {
+    const live = ctx.tmux.listSessions().find((s) => s.name === name);
+    const agent = live?.meta.agent;
+    if (!agent)
+        return false;
+    const adapter = getAdapter(agent);
+    if (adapter?.hookTarget && hooksInstalled(agent, env))
+        return false;
+    stamp(ctx, name, { state: 'waiting', note: BELL_NOTE });
+    return true;
+}
+/** Seeing a session answers its bell: clear a bell-raised waiting state. */
+export function clearBell(ctx, name) {
+    const live = ctx.tmux.listSessions().find((s) => s.name === name);
+    if (live?.meta.state === 'waiting' && live.meta.note === BELL_NOTE)
+        stamp(ctx, name, { state: '', note: '' });
+}
+//# sourceMappingURL=sessions.js.map

package/dist/src/registry/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../../src/registry/sessions.ts"],"names":[],"mappings":"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"}

package/dist/src/restore/ensure.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from '../context.js';
+import type { StoredSnapshot } from '../snapshot/store.js';
+export type RestoreOutcome = 'resumed' | 'launched' | 'shell' | 'skipped-live' | 'skipped-missing-cwd';
+export interface RestoreResult {
+    name: string;
+    outcome: RestoreOutcome;
+    detail?: string;
+}
+export interface RestoreOptions {
+    origin?: string;
+    session?: string;
+    /** How long to wait for another restore to finish; editors pass a short one so they never freeze. */
+    lockTimeoutMs?: number;
+}
+/** Rebuild missing managed sessions from a snapshot; live ones are left alone. */
+export declare function restoreFrom(ctx: Context, snapshot: StoredSnapshot | undefined, options?: RestoreOptions): RestoreResult[];
+export declare function ensure(ctx: Context, options?: RestoreOptions): RestoreResult[];

package/dist/src/restore/ensure.js

@@ -0,0 +1,57 @@
+import { existsSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { launchCommand, resumeCommand, requireAdapter } from '../agents/commands.js';
+import { shellSplit } from '../shell.js';
+import { withLock } from './lock.js';
+function onPath(binary, env = process.env) {
+    if (!binary)
+        return true;
+    if (binary.includes('/'))
+        return existsSync(binary);
+    return (env.PATH ?? '').split(delimiter).some((dir) => dir && existsSync(join(dir, binary)));
+}
+function selected(s, options) {
+    if (options.session && s.name !== options.session)
+        return false;
+    if (options.origin && options.origin !== 'all' && s.origin !== options.origin)
+        return false;
+    return true;
+}
+function rebuild(ctx, s) {
+    if (!existsSync(s.cwd))
+        return { name: s.name, outcome: 'skipped-missing-cwd', detail: s.cwd };
+    const adapter = requireAdapter(s.agent);
+    const input = { adapter, name: s.name, cwd: s.cwd, overrides: ctx.config.agents };
+    const resumed = s.conversation
+        ? resumeCommand({ ...input, conversation: s.conversation, originalArgv: s.argv })
+        : undefined;
+    let command = resumed ?? launchCommand({ ...input, extraArgs: [] });
+    let outcome = resumed ? 'resumed' : 'launched';
+    const [binary] = command ? shellSplit(command) : [''];
+    if (!onPath(binary ?? '')) {
+        command = '';
+        outcome = 'shell';
+    }
+    ctx.tmux.newSession(s.name, s.cwd, command);
+    ctx.tmux.setMeta(s.name, {
+        agent: s.agent,
+        cwd: s.cwd,
+        argv: s.argv,
+        conversation: s.conversation || undefined,
+        origin: s.origin,
+    });
+    ctx.tmux.setTitle(s.name);
+    return { name: s.name, outcome, detail: outcome === 'shell' ? `${binary} not found` : undefined };
+}
+/** Rebuild missing managed sessions from a snapshot; live ones are left alone. */
+export function restoreFrom(ctx, snapshot, options = {}) {
+    if (!snapshot)
+        return [];
+    return withLock(ctx.config.stateDir, () => snapshot.sessions
+        .filter((s) => selected(s, options))
+        .map((s) => (ctx.tmux.hasSession(s.name) ? { name: s.name, outcome: 'skipped-live' } : rebuild(ctx, s))), options.lockTimeoutMs);
+}
+export function ensure(ctx, options = {}) {
+    return restoreFrom(ctx, ctx.store.newest(), options);
+}
+//# sourceMappingURL=ensure.js.map

package/dist/src/restore/ensure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure.js","sourceRoot":"","sources":["../../../src/restore/ensure.ts"],"names":[],"mappings":"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"}

package/dist/src/restore/lock.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Directory lock (implementation §2.4): created atomically, holds the owner
+ * PID. An abandoned lock is taken over by renaming it away first, so two
+ * waiters cannot both remove it and both proceed. Others wait up to `timeoutMs`.
+ */
+export declare function withLock<T>(stateDir: string, fn: () => T, timeoutMs?: number): T;

package/dist/src/restore/lock.js

@@ -0,0 +1,74 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { BerthError } from '../errors.js';
+/** A lock directory with no PID yet is its owner's first moment; older than this, the owner died there. */
+const PIDLESS_GRACE_MS = 10_000;
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Whether the lock at `dir` belongs to nobody any more. */
+function abandoned(dir) {
+    try {
+        const owner = Number(readFileSync(join(dir, 'pid'), 'utf8'));
+        return Number.isInteger(owner) && owner > 0 && !alive(owner);
+    }
+    catch {
+        try {
+            return Date.now() - statSync(dir).mtimeMs > PIDLESS_GRACE_MS;
+        }
+        catch {
+            return false; // released meanwhile
+        }
+    }
+}
+/**
+ * Directory lock (implementation §2.4): created atomically, holds the owner
+ * PID. An abandoned lock is taken over by renaming it away first, so two
+ * waiters cannot both remove it and both proceed. Others wait up to `timeoutMs`.
+ */
+export function withLock(stateDir, fn, timeoutMs = 30_000) {
+    mkdirSync(stateDir, { recursive: true });
+    const dir = join(stateDir, 'ensure.lock');
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            mkdirSync(dir);
+            writeFileSync(join(dir, 'pid'), String(process.pid));
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            if (abandoned(dir)) {
+                const stale = `${dir}.stale-${process.pid}-${Date.now()}`;
+                try {
+                    renameSync(dir, stale);
+                    rmSync(stale, { recursive: true, force: true });
+                }
+                catch {
+                    // Another waiter took it over first; try again.
+                }
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new BerthError(`another restore is running (${dir})`);
+            sleep(100);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/src/restore/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../../src/restore/lock.ts"],"names":[],"mappings":"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"}

package/dist/src/shell.d.ts

@@ -0,0 +1,6 @@
+/** Minimal POSIX shell word handling for launch commands. */
+export declare function shellQuote(word: string): string;
+/** Split a command line into words: honours single quotes, double quotes and backslashes. */
+export declare function shellSplit(line: string): string[];
+/** Fill `{key}` placeholders; values are shell-quoted, `{args}` is inserted as already-quoted words. */
+export declare function renderTemplate(template: string, values: Record<string, string>): string;

package/dist/src/shell.js

@@ -0,0 +1,68 @@
+/** Minimal POSIX shell word handling for launch commands. */
+// No '=': zsh expands a word starting with '=' to a command path.
+const SAFE = /^[A-Za-z0-9_@%+:,./-]+$/;
+export function shellQuote(word) {
+    if (word === '')
+        return "''";
+    if (SAFE.test(word))
+        return word;
+    return `'${word.replace(/'/g, `'\\''`)}'`;
+}
+/** Split a command line into words: honours single quotes, double quotes and backslashes. */
+export function shellSplit(line) {
+    const words = [];
+    let current = '';
+    let inWord = false;
+    let quote = null;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quote === "'") {
+            if (ch === "'")
+                quote = null;
+            else
+                current += ch;
+        }
+        else if (quote === '"') {
+            if (ch === '"')
+                quote = null;
+            else if (ch === '\\' && i + 1 < line.length && '"\\$`'.includes(line[i + 1]))
+                current += line[++i];
+            else
+                current += ch;
+        }
+        else if (ch === "'" || ch === '"') {
+            quote = ch;
+            inWord = true;
+        }
+        else if (ch === '\\' && i + 1 < line.length) {
+            current += line[++i];
+            inWord = true;
+        }
+        else if (/\s/.test(ch)) {
+            if (inWord)
+                words.push(current);
+            current = '';
+            inWord = false;
+        }
+        else {
+            current += ch;
+            inWord = true;
+        }
+    }
+    if (quote)
+        throw new Error(`unterminated quote in: ${line}`);
+    if (inWord)
+        words.push(current);
+    return words;
+}
+/** Fill `{key}` placeholders; values are shell-quoted, `{args}` is inserted as already-quoted words. */
+export function renderTemplate(template, values) {
+    return template
+        .replace(/\{(\w+)\}/g, (match, key) => {
+        if (!(key in values))
+            return match;
+        return key === 'args' ? values[key] : shellQuote(values[key]);
+    })
+        .replace(/\s+$/, '');
+}
+//# sourceMappingURL=shell.js.map

package/dist/src/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/shell.ts"],"names":[],"mappings":"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"}