@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/host/status.d.ts

@@ -0,0 +1,101 @@
+import { type ClaimUnavailableCause } from "../vendor/shared/durable-contract/codes.js";
+import type { HostStatusJson } from "../vendor/shared/durable-contract/cli-output.js";
+import { type LauncherKey } from "../vendor/shared/durable-contract/fixlines.js";
+import { type Launchctl } from "./launchd.js";
+import { type SeatPane } from "./tmux.js";
+import { type PsRow } from "./procs.js";
+import { type ExecutorRow } from "./owner.js";
+import { type GrantView } from "./grant.js";
+export declare const fingerprint: (secret: string) => string;
+export interface StatusDeps {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly home: string;
+    readonly uid: number;
+    readonly launchctl: Launchctl;
+    readonly panes: () => Promise<SeatPane[]>;
+    readonly ps: () => PsRow[];
+    readonly lsofPids: (file: string) => Promise<number[]>;
+    readonly lsofListenPort: (pid: number) => Promise<number | null>;
+    /** Absolute unix-socket names the process has open (its own listening seat socket among them). */
+    readonly lsofUnixPaths: (pid: number) => Promise<string[]>;
+    readonly alive: (pid: number) => boolean;
+    /** The executor row from exec_list (null when unknown or offline). */
+    readonly executorRow: (id: string) => Promise<ExecutorRow | null>;
+    readonly homeTag: string;
+    readonly cliVersion: string;
+    /** Wall clock for the grant window (defaults to Date.now). */
+    readonly now?: () => number;
+}
+export interface SeatRow {
+    session_id: string;
+    name: string | null;
+    epoch: number | null;
+    spawn_id: string;
+    pid: number | null;
+    state: string | null;
+    proxy_pid: number | null;
+    claude_pid: number | null;
+    proxy_port: number | null;
+    socket_path: string | null;
+    spec_path: string | null;
+    spec_sha256: string | null;
+    tmux_session: string;
+}
+export interface HostStatus {
+    instance: string;
+    installed: boolean;
+    loaded: boolean;
+    daemon: "running" | "idle" | "stopped";
+    daemon_pid: number | null;
+    lock_holder_pid: number | null;
+    lock_path: string;
+    enrolled: boolean;
+    executor_id: string | null;
+    executor_key_sha256: string | null;
+    nonce_sha256: string | null;
+    boot_id: string | null;
+    transcript_guard: "link" | "copy";
+    integrity: {
+        ok: boolean;
+        cause?: string;
+    };
+    risk_line_version: {
+        enrolled: number | null;
+        current: number;
+    };
+    /** The executor grant (C04-R18); null when the executor row is unknown (offline, not enrolled). */
+    grant: GrantView | null;
+    seats: SeatRow[];
+    sessions: {
+        id: string;
+        name: string | null;
+        state: string | null;
+        state_reason: string | null;
+        claim_unavailable: {
+            cause: ClaimUnavailableCause | null;
+            count: number;
+        } | null;
+    }[];
+    fixes: string[];
+    notes: string[];
+}
+/** The launcher's durable key (launcher.toml `durable = …`); default `ask`. */
+export declare function launcherDurableKey(home: string): LauncherKey;
+export declare function collectStatus(d: StatusDeps): Promise<HostStatus>;
+/**
+ * `host status --json`: exactly the S1 HOST_STATUS_JSON document (ruling 26), closed at every level.
+ * A seat row the schema cannot hold yet (no session state known, no launch spec on disk, no pane
+ * pid) is left out rather than printed with a guessed value; the human view still shows it.
+ */
+export declare function toHostStatusJson(s: HostStatus): HostStatusJson;
+export declare function renderStatusHuman(s: HostStatus): string[];
+/**
+ * Print a status. --json: the S1 document alone on stdout (one parseable object), and the notes
+ * and fix lines on stderr so a script still sees them. Human: everything on stdout.
+ */
+export declare function printStatus(s: HostStatus, json: boolean, out: (l: string) => void, err: (l: string) => void): void;
+export declare function lsofPids(file: string): Promise<number[]>;
+/** `lsof -F n` output to the absolute names it lists (unnamed peers such as `->0x…` are skipped). */
+export declare function parseLsofUnixPaths(out: string): string[];
+export declare function lsofUnixPaths(pid: number): Promise<string[]>;
+export declare function lsofListenPort(pid: number): Promise<number | null>;

package/dist/host/status.js

@@ -0,0 +1,307 @@
+/**
+ * `mnemom agent host status [--json]` (C12-R23, R24, R31, R36, R39; C04). Every per-seat field
+ * is read at call time from its own probe: tmux (seat rows and tags), ps (claude and proxy
+ * pids), lsof (proxy port, lock holder), stat (socket), sha256 (launch spec). The daemon's
+ * runtime file adds only what the OS cannot tell (unavailable cause and count, integrity, idle).
+ * Only fingerprints of the nonce and key are printed.
+ */
+import { SESSION_STATES } from "../vendor/shared/durable-contract/states.js";
+import { CLAIM_UNAVAILABLE_CAUSES, } from "../vendor/shared/durable-contract/codes.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { renderFixLine, RISK_LINE_TEXT, FIX_LINES, } from "../vendor/shared/durable-contract/fixlines.js";
+import { CLAIM_UNAVAILABLE_SURFACE_N, RISK_LINE_VERSION, } from "../vendor/shared/durable-contract/constants.js";
+import { resolveInstance, hostPaths } from "./instance.js";
+import { durableOnInConfig, IDLE_TEXT, IDLE_FIX } from "./gate.js";
+import { readExecutorState } from "./state.js";
+import { readRuntime } from "./runtime.js";
+import { printJob } from "./launchd.js";
+import { seatPids } from "./procs.js";
+import { grantStatus, GRANT_EXPIRED_LINE } from "./grant.js";
+export const fingerprint = (secret) => createHash("sha256").update(secret).digest("hex").slice(0, 12);
+const sha256File = (p) => {
+    try {
+        return createHash("sha256").update(fs.readFileSync(p)).digest("hex");
+    }
+    catch {
+        return null;
+    }
+};
+/** The launcher's durable key (launcher.toml `durable = …`); default `ask`. */
+export function launcherDurableKey(home) {
+    try {
+        const t = fs.readFileSync(path.join(home, ".mnemom", "launcher.toml"), "utf8");
+        const m = /^\s*durable\s*=\s*"?(off|ask|always)"?\s*$/m.exec(t);
+        return m?.[1] ?? "ask";
+    }
+    catch {
+        return "ask";
+    }
+}
+export async function collectStatus(d) {
+    const instance = resolveInstance(d.env);
+    const paths = hostPaths(d.home, instance);
+    const installed = fs.existsSync(paths.plistFile);
+    const job = await printJob(d.launchctl, d.uid, instance.label);
+    const rt = readRuntime(paths.runtimeFile);
+    const holders = fs.existsSync(paths.lockFile) ? await d.lsofPids(paths.lockFile) : [];
+    const lockHolder = holders.length ? holders[0] : null;
+    const daemonPid = job.pid ?? (rt && d.alive(rt.pid) && lockHolder === rt.pid ? rt.pid : null);
+    const gateOn = durableOnInConfig(paths.configFile);
+    const st = readExecutorState(paths.stateFile);
+    const state = st.kind === "ok" ? st.state : null;
+    const fixes = [];
+    const notes = [];
+    let daemon = daemonPid ? "running" : "stopped";
+    if (daemonPid && !gateOn)
+        daemon = "idle";
+    if (daemon === "idle")
+        fixes.push(IDLE_FIX);
+    if (!installed)
+        fixes.push(FIX_LINES.daemon_not_running.body);
+    if (rt && rt.integrity && rt.integrity.ok === false && daemonPid)
+        fixes.push(FIX_LINES.integrity.body.replace("<cli_version>", d.cliVersion));
+    let enrolledRl = null;
+    let grant = null;
+    if (state) {
+        const row = await d.executorRow(state.executor_id).catch(() => null);
+        if (row) {
+            const g = grantStatus(row.grantExpiresAt, (d.now ?? Date.now)());
+            if (g.state === "warning") {
+                grant = { state: "warning", days: g.days };
+                fixes.push(g.line);
+            }
+            else if (g.state === "expired") {
+                grant = { state: "expired" };
+                fixes.push(GRANT_EXPIRED_LINE);
+            }
+            else
+                grant = { state: "ok" };
+            enrolledRl = row.riskLineVersion;
+            if (row.riskLineVersion !== null && row.riskLineVersion < RISK_LINE_VERSION) {
+                notes.push(RISK_LINE_TEXT);
+                notes.push(`risk line updated since enrollment (enrolled under v${row.riskLineVersion}, current v${RISK_LINE_VERSION})`);
+            }
+        }
+    }
+    const byId = new Map((rt?.sessions ?? []).map((s) => [s.id, s]));
+    const rtSeats = new Map((rt?.seats ?? []).map((s) => [s.spawn_id, s]));
+    const rows = d.ps();
+    const seats = [];
+    for (const p of await d.panes()) {
+        if (p.home !== d.homeTag || !p.sid)
+            continue;
+        const pids = p.panePid && !p.dead ? seatPids(rows, p.panePid) : { claude: null, proxy: null };
+        // The seat socket is C3's to name; status reads it off the proxy (lsof) and confirms it by stat.
+        const socketPath = pids.proxy ? firstSocket(await d.lsofUnixPaths(pids.proxy)) : null;
+        // seat.ts writes the launch spec per session (specs/<session id>.json); an adopted seat has no
+        // spec_path in the runtime file, so fall back to that same name.
+        const spec = rtSeats.get(p.spawn)?.spec_path ?? path.join(paths.specDir, `${p.sid}.json`);
+        const specSha = sha256File(spec);
+        seats.push({
+            session_id: p.sid,
+            name: byId.get(p.sid)?.name ?? null,
+            epoch: p.epoch,
+            spawn_id: p.spawn,
+            pid: p.panePid,
+            state: byId.get(p.sid)?.state ?? null,
+            proxy_pid: pids.proxy,
+            claude_pid: pids.claude,
+            proxy_port: pids.proxy ? await d.lsofListenPort(pids.proxy) : null,
+            socket_path: socketPath,
+            spec_path: specSha ? spec : null,
+            spec_sha256: specSha,
+            tmux_session: p.session,
+        });
+    }
+    const launcherKey = launcherDurableKey(d.home);
+    const sessions = (rt?.sessions ?? []).map((s) => {
+        const u = rt?.unavailable?.[s.id] ?? null;
+        if (u && u.cause === "guard" && u.count > CLAIM_UNAVAILABLE_SURFACE_N && s.name) {
+            fixes.push(renderFixLine("guard", { launcherKey, nameHeld: true, params: { name: s.name } }));
+        }
+        return {
+            id: s.id,
+            name: s.name,
+            state: s.state,
+            state_reason: s.state_reason,
+            claim_unavailable: u ? { cause: u.cause, count: u.count } : null,
+        };
+    });
+    return {
+        instance: instance.label,
+        installed,
+        loaded: job.loaded,
+        daemon,
+        daemon_pid: daemonPid,
+        lock_holder_pid: lockHolder,
+        lock_path: paths.lockFile,
+        enrolled: state !== null,
+        executor_id: state?.executor_id ?? null,
+        executor_key_sha256: state ? fingerprint(state.executor_key) : null,
+        nonce_sha256: state && state.nonce ? fingerprint(state.nonce) : null,
+        boot_id: state?.boot_id ?? null,
+        transcript_guard: rt?.transcript_guard ?? "link",
+        integrity: rt?.integrity
+            ? rt.integrity.ok
+                ? { ok: true }
+                : { ok: false, cause: rt.integrity.cause }
+            : { ok: true },
+        risk_line_version: { enrolled: enrolledRl, current: RISK_LINE_VERSION },
+        grant,
+        seats,
+        sessions,
+        fixes,
+        notes,
+    };
+}
+const isUuid = (v) => typeof v === "string" &&
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v);
+/**
+ * `host status --json`: exactly the S1 HOST_STATUS_JSON document (ruling 26), closed at every level.
+ * A seat row the schema cannot hold yet (no session state known, no launch spec on disk, no pane
+ * pid) is left out rather than printed with a guessed value; the human view still shows it.
+ */
+export function toHostStatusJson(s) {
+    const seats = [];
+    for (const r of s.seats) {
+        if (!isUuid(r.session_id) || !isUuid(r.spawn_id) || r.epoch === null || r.pid === null)
+            continue;
+        if (r.state === null || !SESSION_STATES.includes(r.state))
+            continue;
+        if (r.spec_path === null || r.spec_sha256 === null)
+            continue;
+        seats.push({
+            session_id: r.session_id,
+            epoch: r.epoch,
+            spawn_id: r.spawn_id,
+            state: r.state,
+            pid: r.pid,
+            proxy_pid: r.proxy_pid,
+            claude_pid: r.claude_pid,
+            // ruling 26.1: a port is reported only with the proxy process it belongs to
+            proxy_port: r.proxy_pid === null ? null : r.proxy_port,
+            socket_path: r.socket_path,
+            spec_path: r.spec_path,
+            spec_sha256: r.spec_sha256,
+        });
+    }
+    const sessions = [];
+    for (const x of s.sessions) {
+        if (!isUuid(x.id))
+            continue;
+        const u = x.claim_unavailable;
+        const known = u !== null &&
+            u.cause !== null &&
+            CLAIM_UNAVAILABLE_CAUSES.includes(u.cause) &&
+            u.count >= 1;
+        sessions.push({
+            session_id: x.id,
+            claim_unavailable: known
+                ? { cause: u.cause, consecutive: u.count }
+                : null,
+        });
+    }
+    return {
+        installed: s.installed,
+        loaded: s.loaded,
+        instance: s.instance,
+        daemon_pid: s.daemon_pid,
+        lock_holder_pid: s.lock_holder_pid,
+        lock_path: s.lock_path,
+        transcript_guard: s.transcript_guard,
+        nonce_fingerprint: s.nonce_sha256,
+        key_fingerprint: s.executor_key_sha256,
+        seats,
+        sessions,
+    };
+}
+export function renderStatusHuman(s) {
+    const out = [];
+    out.push(`instance: ${s.instance}`);
+    out.push(`installed: ${s.installed ? "yes" : "no"}${s.loaded ? " (loaded)" : ""}`);
+    out.push(s.daemon === "idle"
+        ? IDLE_TEXT
+        : `daemon: ${s.daemon}${s.daemon_pid ? ` (pid ${s.daemon_pid})` : ""}`);
+    out.push(`lock: ${s.lock_path}${s.lock_holder_pid ? ` (held by ${s.lock_holder_pid})` : ""}`);
+    out.push(s.enrolled
+        ? `executor: ${s.executor_id} (key ${s.executor_key_sha256}, nonce ${s.nonce_sha256})`
+        : "executor: not enrolled");
+    out.push(`transcript guard: ${s.transcript_guard}`);
+    for (const r of s.seats) {
+        out.push(`seat ${r.name ?? r.session_id} epoch ${r.epoch ?? "?"} spawn ${r.spawn_id.slice(0, 8)} pane ${r.pid ?? "-"} claude ${r.claude_pid ?? "-"} proxy ${r.proxy_pid ?? "-"}${r.proxy_port ? `:${r.proxy_port}` : ""} ${r.state ?? ""}`.trimEnd());
+    }
+    for (const x of s.sessions) {
+        if (x.claim_unavailable)
+            out.push(`session ${x.name ?? x.id}: claim unavailable (${x.claim_unavailable.cause ?? "cause not given"}) x${x.claim_unavailable.count}`);
+    }
+    for (const n of s.notes)
+        out.push(n);
+    for (const f of s.fixes)
+        out.push(f);
+    return out;
+}
+/**
+ * Print a status. --json: the S1 document alone on stdout (one parseable object), and the notes
+ * and fix lines on stderr so a script still sees them. Human: everything on stdout.
+ */
+export function printStatus(s, json, out, err) {
+    if (!json) {
+        for (const l of renderStatusHuman(s))
+            out(l);
+        return;
+    }
+    out(JSON.stringify(toHostStatusJson(s), null, 2));
+    for (const n of s.notes)
+        err(n);
+    for (const f of s.fixes)
+        err(f);
+}
+// ---- real probes ------------------------------------------------------------------------------
+const run = (file, args) => new Promise((resolve) => {
+    execFile(file, args, { env: { PATH: "/usr/bin:/bin:/usr/sbin:/sbin" }, timeout: 15000 }, (_e, stdout) => resolve(String(stdout ?? "")));
+});
+export async function lsofPids(file) {
+    const out = await run("/usr/sbin/lsof", ["-F", "p", file]);
+    return out
+        .split("\n")
+        .filter((l) => /^p\d+$/.test(l))
+        .map((l) => Number(l.slice(1)));
+}
+function firstSocket(paths) {
+    for (const p of paths) {
+        try {
+            if (fs.lstatSync(p).isSocket())
+                return p;
+        }
+        catch {
+            /* gone or not a path */
+        }
+    }
+    return null;
+}
+/** `lsof -F n` output to the absolute names it lists (unnamed peers such as `->0x…` are skipped). */
+export function parseLsofUnixPaths(out) {
+    return out
+        .split("\n")
+        .filter((l) => l.startsWith("n/"))
+        .map((l) => l.slice(1));
+}
+export async function lsofUnixPaths(pid) {
+    return parseLsofUnixPaths(await run("/usr/sbin/lsof", ["-nP", "-a", "-p", String(pid), "-U", "-Fn"]));
+}
+export async function lsofListenPort(pid) {
+    const out = await run("/usr/sbin/lsof", [
+        "-nP",
+        "-a",
+        "-p",
+        String(pid),
+        "-iTCP",
+        "-sTCP:LISTEN",
+        "-Fn",
+    ]);
+    const m = /^n[^\n]*:(\d+)$/m.exec(out);
+    return m ? Number(m[1]) : null;
+}

package/dist/host/tmux.d.ts

@@ -0,0 +1,56 @@
+export declare const TAG_SID = "@mnemom_sid";
+export declare const TAG_EPOCH = "@mnemom_epoch";
+export declare const TAG_SPAWN = "@mnemom_spawn";
+export declare const TAG_HOME = "@mnemom_home";
+/** A seat's tmux session name: the session id and its spawn's first 8 characters. */
+export declare function seatTmuxSession(sessionId: string, spawnId: string): string;
+export interface TmuxResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type TmuxRunner = (args: readonly string[]) => Promise<TmuxResult>;
+/** tmux's own environment: only what it needs to find its socket; no credential can ride along. */
+export declare function tmuxEnv(env: Readonly<Record<string, string | undefined>>): Record<string, string>;
+export declare function tmuxRunner(socket: string, env: Readonly<Record<string, string | undefined>>): TmuxRunner;
+export interface SeatPane {
+    readonly session: string;
+    readonly paneId: string;
+    readonly panePid: number | null;
+    readonly dead: boolean;
+    readonly deadStatus: number | null;
+    readonly sid: string;
+    readonly epoch: number | null;
+    readonly spawn: string;
+    readonly home: string;
+}
+export declare function parsePanes(stdout: string): SeatPane[];
+export declare class Tmux {
+    private readonly run;
+    constructor(run: TmuxRunner);
+    /** Start (or reuse) the server with the host's global options. */
+    ensureServer(): Promise<void>;
+    /** Every pane on this socket with its tags ([] when there is no server). */
+    panes(): Promise<SeatPane[]>;
+    /** A detached session running `command`, tagged in the same tmux command. Returns the pane pid. */
+    newSeat(opts: {
+        name: string;
+        cwd: string;
+        command: string;
+        env: Readonly<Record<string, string>>;
+        tags: {
+            sid: string;
+            epoch: number;
+            spawn: string;
+            home: string;
+        };
+    }): Promise<{
+        panePid: number;
+        paneId: string;
+    }>;
+    /** The visible text of a session's pane, or null when the session is gone. */
+    capturePane(name: string): Promise<string | null>;
+    /** Type `text` literally into a session's pane, then press Enter. */
+    sendLine(name: string, text: string): Promise<void>;
+    killSession(name: string): Promise<void>;
+}

package/dist/host/tmux.js

@@ -0,0 +1,182 @@
+/**
+ * The host's own tmux server (C12-R04, R10, R12, R22, R35). Every call names the instance socket
+ * (-L); the daemon never touches the default server or any other socket. The server is started
+ * from a scrubbed environment with update-environment empty, so neither the daemon's own env nor
+ * an owner's later attach leaks into seats. Seats are tagged at session scope with
+ * @mnemom_sid / @mnemom_epoch / @mnemom_spawn / @mnemom_home in the same tmux command that creates
+ * them; remain-on-exit keeps a dead pane so its exit status can be read (liveness itself is judged
+ * by pid, never by pane existence, R19 M23).
+ */
+import { execFile } from "node:child_process";
+export const TAG_SID = "@mnemom_sid";
+export const TAG_EPOCH = "@mnemom_epoch";
+export const TAG_SPAWN = "@mnemom_spawn";
+export const TAG_HOME = "@mnemom_home";
+/** A seat's tmux session name: the session id and its spawn's first 8 characters. */
+export function seatTmuxSession(sessionId, spawnId) {
+    return `mnm-${sessionId}-${spawnId.slice(0, 8)}`;
+}
+/** tmux's own environment: only what it needs to find its socket; no credential can ride along. */
+export function tmuxEnv(env) {
+    const out = {
+        PATH: env.PATH || "/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin:/usr/local/bin",
+    };
+    for (const k of ["HOME", "TMUX_TMPDIR", "LANG", "USER", "LOGNAME"]) {
+        const v = env[k];
+        if (v)
+            out[k] = v;
+    }
+    return out;
+}
+export function tmuxRunner(socket, env) {
+    const e = tmuxEnv(env);
+    return (args) => new Promise((resolve) => {
+        execFile("tmux", ["-L", socket, ...args], { env: e, timeout: 15000, maxBuffer: 8 * 1024 * 1024 }, (err, stdout, stderr) => {
+            const code = err
+                ? typeof err.code === "number"
+                    ? err.code
+                    : 1
+                : 0;
+            resolve({ code, stdout: String(stdout), stderr: String(stderr) });
+        });
+    });
+}
+const FMT = [
+    "#{session_name}",
+    "#{pane_id}",
+    "#{pane_pid}",
+    "#{pane_dead}",
+    "#{pane_dead_status}",
+    `#{${TAG_SID}}`,
+    `#{${TAG_EPOCH}}`,
+    `#{${TAG_SPAWN}}`,
+    `#{${TAG_HOME}}`,
+].join("\t");
+export function parsePanes(stdout) {
+    const out = [];
+    for (const line of stdout.split("\n")) {
+        if (!line.trim())
+            continue;
+        const [session = "", paneId = "", pid = "", dead = "", status = "", sid = "", epoch = "", spawn = "", home = "",] = line.split("\t");
+        out.push({
+            session,
+            paneId,
+            panePid: /^\d+$/.test(pid) ? Number(pid) : null,
+            dead: dead === "1",
+            deadStatus: /^\d+$/.test(status) ? Number(status) : null,
+            sid,
+            epoch: /^\d+$/.test(epoch) ? Number(epoch) : null,
+            spawn,
+            home,
+        });
+    }
+    return out;
+}
+export class Tmux {
+    run;
+    constructor(run) {
+        this.run = run;
+    }
+    /** Start (or reuse) the server with the host's global options. */
+    async ensureServer() {
+        const r = await this.run([
+            "start-server",
+            ";",
+            "set-option",
+            "-g",
+            "exit-empty",
+            "off",
+            ";",
+            "set-option",
+            "-g",
+            "update-environment",
+            "",
+            ";",
+            "set-option",
+            "-g",
+            "remain-on-exit",
+            "on",
+            ";",
+            "set-option",
+            "-g",
+            "default-shell",
+            "/bin/sh",
+        ]);
+        if (r.code !== 0)
+            throw new Error(`tmux start-server failed: ${r.stderr.trim()}`);
+    }
+    /** Every pane on this socket with its tags ([] when there is no server). */
+    async panes() {
+        const r = await this.run(["list-panes", "-a", "-F", FMT]);
+        if (r.code !== 0)
+            return [];
+        return parsePanes(r.stdout);
+    }
+    /** A detached session running `command`, tagged in the same tmux command. Returns the pane pid. */
+    async newSeat(opts) {
+        const envArgs = Object.entries(opts.env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+        const t = opts.name;
+        const r = await this.run([
+            "new-session",
+            "-d",
+            "-s",
+            t,
+            "-c",
+            opts.cwd,
+            "-x",
+            "200",
+            "-y",
+            "50",
+            ...envArgs,
+            "-P",
+            "-F",
+            "#{pane_pid}\t#{pane_id}",
+            opts.command,
+            ";",
+            "set-option",
+            "-t",
+            t,
+            TAG_SID,
+            opts.tags.sid,
+            ";",
+            "set-option",
+            "-t",
+            t,
+            TAG_EPOCH,
+            String(opts.tags.epoch),
+            ";",
+            "set-option",
+            "-t",
+            t,
+            TAG_SPAWN,
+            opts.tags.spawn,
+            ";",
+            "set-option",
+            "-t",
+            t,
+            TAG_HOME,
+            opts.tags.home,
+        ]);
+        const m = /^(\d+)\t(%\d+)/m.exec(r.stdout);
+        if (r.code !== 0 || !m)
+            throw new Error(`tmux new-session failed: ${r.stderr.trim() || r.stdout.trim()}`);
+        return { panePid: Number(m[1]), paneId: m[2] };
+    }
+    /** The visible text of a session's pane, or null when the session is gone. */
+    async capturePane(name) {
+        const r = await this.run(["capture-pane", "-p", "-t", `=${name}:`]);
+        return r.code === 0 ? r.stdout : null;
+    }
+    /** Type `text` literally into a session's pane, then press Enter. */
+    async sendLine(name, text) {
+        const r = await this.run(["send-keys", "-t", `=${name}:`, "-l", text]);
+        if (r.code !== 0)
+            throw new Error(`tmux send-keys failed: ${r.stderr.trim()}`);
+        const e = await this.run(["send-keys", "-t", `=${name}:`, "Enter"]);
+        if (e.code !== 0)
+            throw new Error(`tmux send-keys failed: ${e.stderr.trim()}`);
+    }
+    async killSession(name) {
+        await this.run(["kill-session", "-t", `=${name}`]);
+    }
+}

package/dist/host/transcript.d.ts

@@ -0,0 +1,30 @@
+export type GuardMode = "link" | "copy";
+export declare function ccProjectsDir(env: Readonly<Record<string, string | undefined>>, home?: string): string;
+/** Claude Code's project folder name for a cwd: every non-alphanumeric character becomes '-'. */
+export declare const projectSlug: (cwd: string) => string;
+export declare function expectedTranscriptPath(projectsDir: string, cwd: string, ccSessionId: string): string;
+/** The transcript as it is on disk now: the cwd's project folder first, then any project folder. */
+export declare function findTranscript(projectsDir: string, cwd: string | null, ccSessionId: string): string | null;
+export interface GuardResult {
+    readonly mode: GuardMode | null;
+    readonly guardPath: string;
+}
+/** Create or refresh the guard for one session. Returns the mode now held (null when there is nothing to guard). */
+export declare function refreshGuard(home: string, sessionId: string, original: string | null): GuardResult;
+export type TranscriptCheck = {
+    kind: "present";
+    path: string;
+} | {
+    kind: "restored";
+    path: string;
+} | {
+    kind: "lost";
+};
+/**
+ * Before a `--resume`: the original exists, or it is restored from the guard (a new hard link,
+ * or a copy across volumes), or both are missing (transcript_lost).
+ */
+export declare function ensureTranscript(home: string, sessionId: string, projectsDir: string, cwd: string | null, ccSessionId: string, lastKnown: string | null): TranscriptCheck;
+export declare function removeGuard(home: string, sessionId: string): void;
+/** Session ids that have a guard file. */
+export declare function guardedSessionIds(home: string): string[];