@sentropic/h2a-runtime 0.92.0 → 0.93.0

package/dist/launch-layout.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Terminal-layout rendering for `remote restore` — split out of restore.ts so
+ * the F3 invariant is a MODULE-BOUNDARY property, not a review rule:
+ *
+ *   launchLayout decides every view/launch from the ONE `HostViewSnapshot`
+ *   it receives AS A PARAMETER. This module must NOT import any live host
+ *   reader (listNativeSessions, listLocalSessions*, nativeSession*, probe*):
+ *   you can't call what you don't have, so a divergence between plan time
+ *   and launch time can never be re-read here — and an error or divergence
+ *   NEVER becomes permission to launch (`live -> empty` yields attach or
+ *   refuse, never `h2a run` fabricating a second writer on a live
+ *   conversation). Only PURE name helpers may be imported from tmux.js.
+ */
+import { type LocalSession } from "./tmux.js";
+import type { LayoutTab, LayoutWindow } from "./restore.js";
+/**
+ * The ONE host inventory snapshot a restore plan runs on: BOTH inventories
+ * read once by the caller (restore.ts owns the readers), so the plan gate and
+ * the layout render see the SAME state. A failed inventory read is carried as
+ * `known: false` — an UNKNOWN view, never an empty one.
+ */
+export type HostViewSnapshot = {
+    readonly tmux: {
+        readonly known: true;
+        readonly sessions: ReadonlyArray<LocalSession>;
+    } | {
+        readonly known: false;
+        readonly reason?: string;
+    };
+    readonly native: {
+        readonly known: true;
+        /** RUNNING native sessions only, with the controller-visibility bit. */
+        readonly sessions: ReadonlyArray<{
+            readonly name: string;
+            readonly controlled: boolean | undefined;
+        }>;
+    } | {
+        readonly known: false;
+    };
+};
+/**
+ * Per-tab command for an ABSENT local session: create it via `remote run …
+ * --resume …` (which attaches by default). Live sessions are deliberately
+ * handled by `launchLayout`, which knows their exact tmux names and whether they
+ * have a client attached; it emits `tmux attach -t <exact-name>` and never
+ * relaunches them.
+ */
+export declare function tabCommand(tab: LayoutTab, liveSlugs?: ReadonlySet<string>, opts?: {
+    forceGateway?: "gateway" | "direct";
+    /** Exact existing tmux name — attach directly, never replace/relaunch it. */
+    attachSession?: string;
+}): string;
+/** Group collision candidates before restore emits bare-slug attach/resume commands. */
+export declare function ambiguousLiveSessionNames(sessions: readonly Pick<LocalSession, "name" | "slug">[]): Map<string, string[]>;
+/**
+ * Launch the layout in gnome-terminal: one window per group, one tab per session.
+ *
+ * Default behaviour: a live session with a tmux client is already visible and is
+ * skipped; a live session with zero clients is orphaned, so a terminal tab is
+ * opened directly onto that exact tmux session. An absent session is launched as
+ * before. `--reattach` explicitly opens another tab even for an already-visible
+ * session. This is deliberately a view decision, not a liveness decision.
+ *
+ * Every decision reads the `hostView` PARAMETER — the plan's one snapshot —
+ * never a live host (F3: this module has no reader to call).
+ */
+export declare function launchLayout(windows: LayoutWindow[], hostView: HostViewSnapshot, stderr?: NodeJS.WriteStream, opts?: {
+    reattach?: boolean;
+    forceGateway?: "gateway" | "direct";
+}): {
+    opened: number;
+    skippedLive: string[];
+};
+//# sourceMappingURL=launch-layout.d.ts.map

package/dist/launch-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-layout.d.ts","sourceRoot":"","sources":["../src/launch-layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,EAA6B,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,IAAI,EACT;QAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;KAAE,GACxE;QAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,QAAQ,CAAC,MAAM,EACX;QACE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;QACrB,wEAAwE;QACxE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;YAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YACtB,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,SAAS,CAAC;SAC1C,CAAC,CAAC;KACJ,GACD;QAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC;CAC/B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,SAAS,EACd,SAAS,GAAE,WAAW,CAAC,MAAM,CAAa,EAC1C,IAAI,GAAE;IACJ,YAAY,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;CACnB,GACL,MAAM,CAgDR;AAED,wFAAwF;AACxF,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,SAAS,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,GACvD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAUvB;AA4BD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EAAE,EACvB,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,GAAE,MAAM,CAAC,WAA4B,EAC3C,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;CAAO,GACrE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,CAgQ3C"}

package/dist/launch-layout.js

@@ -0,0 +1,324 @@
+/**
+ * Terminal-layout rendering for `remote restore` — split out of restore.ts so
+ * the F3 invariant is a MODULE-BOUNDARY property, not a review rule:
+ *
+ *   launchLayout decides every view/launch from the ONE `HostViewSnapshot`
+ *   it receives AS A PARAMETER. This module must NOT import any live host
+ *   reader (listNativeSessions, listLocalSessions*, nativeSession*, probe*):
+ *   you can't call what you don't have, so a divergence between plan time
+ *   and launch time can never be re-read here — and an error or divergence
+ *   NEVER becomes permission to launch (`live -> empty` yields attach or
+ *   refuse, never `h2a run` fabricating a second writer on a live
+ *   conversation). Only PURE name helpers may be imported from tmux.js.
+ */
+import { spawn } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { localSessionName, slugify } from "./tmux.js";
+/**
+ * Per-tab command for an ABSENT local session: create it via `remote run …
+ * --resume …` (which attaches by default). Live sessions are deliberately
+ * handled by `launchLayout`, which knows their exact tmux names and whether they
+ * have a client attached; it emits `tmux attach -t <exact-name>` and never
+ * relaunches them.
+ */
+export function tabCommand(tab, liveSlugs = new Set(), opts = {}) {
+    const q = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+    if (tab.remoteId) {
+        // SCW: attach straight into the Pod's tmux (live, copy-friendly).
+        return `h2a attach ${q(tab.remoteId)} --exec`;
+    }
+    const slug = slugify(tab.label);
+    if (tab.attachLive) {
+        // §4.1 attach-live: a live managed row whose conversation id is
+        // unresolved re-enters by EXACT managed name only. No resume id exists,
+        // so no run/replace command may ever be rendered for it.
+        return `h2a attach ${q(tab.managedName ?? localSessionName(slug))}`;
+    }
+    // Effective gateway posture: an explicit `restore --gw/--no-gw` OVERRIDES the
+    // per-instance pin; otherwise honour the pinned gatewayMode (absent = default).
+    const posture = opts.forceGateway ?? tab.gatewayMode;
+    const gwFlag = posture === "gateway" ? " --gw" : posture === "direct" ? " --no-gw" : "";
+    // Persisted-host pin — the gatewayMode pattern applied to the terminal
+    // host: a NON-LIVE session is re-created on the host its registry record
+    // names, never on the current default. A recorded native session survives
+    // the fleet-wide H2A_SESSION_HOST=tmux valve via the env pin (any other
+    // value selects native — resolveSessionHostKind), where it fails closed if
+    // the native host is unavailable rather than silently re-routing; a
+    // recorded tmux session survives the native default via --tmux. Tabs
+    // without a recorded host (scan fallback) keep following the default.
+    const nativePin = tab.hostKind === "local-native" ? "H2A_SESSION_HOST=native " : "";
+    const tmuxPin = tab.hostKind === "local-tmux" ? " --tmux" : "";
+    const runCmd = (extra) => `${nativePin}h2a run ${q(tab.tool ?? "shell")} ${q(tab.cwd)} ` +
+        (tab.sid ? `--resume ${q(tab.sid)} ` : "") +
+        `--name ${q(tab.label)}${gwFlag}${tmuxPin}${extra}`;
+    if (opts.attachSession) {
+        // `h2a attach` resolves the exact managed name and honors the session's
+        // RECORDED host (tmux attach for tmux sessions, the native bridge for
+        // native-PTY sessions) — a raw `tmux attach -t` here would strand every
+        // native session behind a "no such session" error.
+        return `h2a attach ${q(opts.attachSession)}`;
+    }
+    if (liveSlugs.has(slug)) {
+        // Compatibility for direct callers that only know a unique slug.  Restore
+        // itself always supplies the exact name above, avoiding prefix collisions.
+        // Crucially, a gateway override never turns a live session into --replace:
+        // restore must preserve its process and conversation.
+        return `h2a attach ${q(slug)}`;
+    }
+    return runCmd("");
+}
+/** Group collision candidates before restore emits bare-slug attach/resume commands. */
+export function ambiguousLiveSessionNames(sessions) {
+    const namesBySlug = new Map();
+    for (const session of sessions) {
+        const names = namesBySlug.get(session.slug) ?? [];
+        names.push(session.name);
+        namesBySlug.set(session.slug, names);
+    }
+    return new Map([...namesBySlug].filter(([, names]) => names.length > 1));
+}
+// gnome-terminal applies ONE trailing `-- command` to EVERY tab of an
+// invocation (you cannot give each tab its own `--`). So all tabs run the same
+// dispatcher; each claims (under flock) the first map line matching its $PWD
+// and runs that tab's command — exactly how ~/bin/resume-dev-sessions worked.
+const DISPATCHER = `map="$1"
+lock="$map.lock"
+exec 9>"$lock"; flock 9
+line=$(awk -F'\\t' -v c="$PWD" '$1==c{print;exit}' "$map")
+if [ -n "$line" ]; then
+  awk -F'\\t' -v c="$PWD" 'BEGIN{d=0} d==0 && $1==c {d=1; next} {print}' "$map" > "$map.tmp" && mv "$map.tmp" "$map"
+fi
+flock -u 9
+cmd=$(printf '%s' "$line" | cut -f2-)
+if [ -n "$cmd" ]; then eval "$cmd"; else echo "[h2a] rien a reprendre pour $PWD" >&2; fi
+exec bash -l`;
+let mapCounter = 0;
+function runDir() {
+    const base = process.env.XDG_RUNTIME_DIR
+        ? join(process.env.XDG_RUNTIME_DIR, "sentropic-remote")
+        : join(homedir(), ".config", "sentropic", "remote-cli", "run");
+    mkdirSync(base, { recursive: true });
+    return base;
+}
+/**
+ * Launch the layout in gnome-terminal: one window per group, one tab per session.
+ *
+ * Default behaviour: a live session with a tmux client is already visible and is
+ * skipped; a live session with zero clients is orphaned, so a terminal tab is
+ * opened directly onto that exact tmux session. An absent session is launched as
+ * before. `--reattach` explicitly opens another tab even for an already-visible
+ * session. This is deliberately a view decision, not a liveness decision.
+ *
+ * Every decision reads the `hostView` PARAMETER — the plan's one snapshot —
+ * never a live host (F3: this module has no reader to call).
+ */
+export function launchLayout(windows, hostView, stderr = process.stderr, opts = {}) {
+    const tmuxKnown = hostView.tmux.known;
+    const tmuxReason = hostView.tmux.known ? undefined : hostView.tmux.reason;
+    const tmuxSessions = hostView.tmux.known
+        ? hostView.tmux.sessions
+        : [];
+    // Native view by EXACT session name, carrying the controller-visibility
+    // bit. A failed inventory read is an UNKNOWN view (undefined map) — never
+    // "no sessions": launching a replacement onto an unprovable host state
+    // could create a second writer, so unknown fails closed below.
+    const nativeSessionsByName = hostView.native.known
+        ? new Map(hostView.native.sessions.map((session) => [
+            session.name,
+            { controlled: session.controlled },
+        ]))
+        : undefined;
+    // Slug-union view for LEGACY tabs without a recorded host (scan fallback)
+    // ONLY — a tab that carries its persisted hostKind + exact managed name is
+    // rendered from that identity and never chooses a host from a merged slug
+    // list. A CONTROLLED native session counts as attached (already visible).
+    const nativeLive = nativeSessionsByName !== undefined
+        ? [...nativeSessionsByName.entries()]
+            .filter(([name]) => name.startsWith("h2a-") && !name.endsWith(".h2a"))
+            .map(([name, view]) => ({
+            name,
+            slug: name.slice("h2a-".length),
+            attached: view.controlled === true,
+        }))
+        : [];
+    const liveSessions = [
+        ...tmuxSessions,
+        ...nativeLive.filter((native) => !tmuxSessions.some((s) => s.name === native.name)),
+    ];
+    const ambiguousLiveNames = ambiguousLiveSessionNames(liveSessions);
+    const skippedLive = [];
+    let opened = 0;
+    // A gateway override can configure a NEW process but must never replace a live
+    // one. `--reattach` is the sole opt-in that duplicates an already-visible tab.
+    const includeAttached = opts.reattach === true;
+    const tabOpts = opts.forceGateway ? { forceGateway: opts.forceGateway } : {};
+    if (!tmuxKnown) {
+        // We cannot reliably tell "attached" from "orphaned".  Prefer a harmless
+        // duplicate/failing attach over `h2a run` possibly racing a live tmux
+        // session; a restore command must never reclaim a view by killing its work.
+        stderr.write(`[h2a] tmux view state unavailable${tmuxReason ? ` (${tmuxReason})` : ""}; ` +
+            "opening attach tabs rather than relaunching local sessions\n");
+    }
+    for (const win of windows) {
+        // Remote (k8s) tabs are always included — we can't probe pod health here.
+        // Local tabs carry their finalized command because a live orphan must attach
+        // to its exact tmux name, while an absent session must be launched.
+        const activeTabs = [];
+        for (const t of win.tabs) {
+            if (t.remoteId) {
+                activeTabs.push({ tab: t, command: tabCommand(t) });
+                continue;
+            }
+            const slug = slugify(t.label);
+            // --- Tabs WITH a recorded host: exact-identity, single-host render. ---
+            // The host decision was made by the plan (persisted kind + exact
+            // managed name); this block only renders the view for THAT host.
+            if (t.hostKind === "local-native") {
+                const exact = t.managedName ?? `h2a-${slug}`;
+                if (nativeSessionsByName === undefined) {
+                    stderr.write(`[h2a] restore: native host state UNKNOWN — "${t.label}" neither relaunched nor attached (fail closed)\n`);
+                    continue;
+                }
+                const view = nativeSessionsByName.get(exact);
+                if (view !== undefined) {
+                    if (view.controlled === true) {
+                        // running && controlled → already visible. Even --reattach must
+                        // not open a competing controller (single-controller model).
+                        skippedLive.push(t.label);
+                        if (includeAttached) {
+                            stderr.write(`[h2a] restore: "${t.label}" is already controlled in a terminal; not opening a second controller\n`);
+                        }
+                        continue;
+                    }
+                    if (view.controlled === undefined) {
+                        // running && view unknown (host predates the visibility bit):
+                        // preserve the process, report, never relaunch.
+                        stderr.write(`[h2a] restore: controller visibility UNKNOWN for running native session "${t.label}"; attach manually: h2a attach ${exact}\n`);
+                        continue;
+                    }
+                    // running && !controlled → exactly one exact-name attach.
+                    activeTabs.push({
+                        tab: t,
+                        command: tabCommand(t, new Set([slug]), { attachSession: exact }),
+                    });
+                    continue;
+                }
+                // Dead/absent on a KNOWN native view.
+                if (t.attachLive) {
+                    stderr.write(`[h2a] restore: "${t.label}" was live at plan time but is gone; no resolved conversation exists to relaunch it\n`);
+                    continue;
+                }
+                activeTabs.push({ tab: t, command: tabCommand(t, new Set(), tabOpts) });
+                continue;
+            }
+            if (t.hostKind === "local-tmux") {
+                const exact = t.managedName ?? `h2a-${slug}`;
+                if (!tmuxKnown) {
+                    // Conservative: a harmless exact attach, never a relaunch race.
+                    activeTabs.push({
+                        tab: t,
+                        command: tabCommand(t, new Set([slug]), { attachSession: exact }),
+                    });
+                    continue;
+                }
+                const liveTmux = tmuxSessions.find((session) => session.name === exact);
+                if (liveTmux) {
+                    // DRAIN view: the live legacy process is attach-only — dispatched
+                    // to its persisted host via `h2a attach`; never replaced, and no
+                    // tmux session is ever created here.
+                    if (!includeAttached && liveTmux.attached) {
+                        skippedLive.push(t.label);
+                        continue;
+                    }
+                    activeTabs.push({
+                        tab: t,
+                        command: tabCommand(t, new Set([slug]), { attachSession: exact }),
+                    });
+                    continue;
+                }
+                if (t.attachLive) {
+                    stderr.write(`[h2a] restore: "${t.label}" was live at plan time but is gone; no resolved conversation exists to relaunch it\n`);
+                    continue;
+                }
+                // Dead recorded tmux row: re-created on its recorded host via the
+                // --tmux pin (tabCommand). Which host a dead tmux session should be
+                // relaunched on is a REOPENED policy question — this keeps the #199
+                // behavior as-is.
+                activeTabs.push({ tab: t, command: tabCommand(t, new Set(), tabOpts) });
+                continue;
+            }
+            // --- Legacy tabs without a recorded host: slug-union view (scan). ---
+            if (!tmuxKnown) {
+                activeTabs.push({
+                    tab: t,
+                    command: tabCommand(t, new Set([slug]), { attachSession: `h2a-${slug}` }),
+                });
+                continue;
+            }
+            const names = ambiguousLiveNames.get(slug);
+            if (names) {
+                skippedLive.push(t.label);
+                stderr.write(`[h2a] restore skipped "${t.label}": local tmux slug is ambiguous (${names.sort().join(", ")}); ` +
+                    `attach explicitly with h2a attach ${names.sort()[0]} or h2a attach ${names.sort()[1]}\n`);
+                continue;
+            }
+            const liveSession = liveSessions.find((session) => session.slug === slug);
+            if (liveSession && !includeAttached && liveSession.attached) {
+                skippedLive.push(t.label);
+                continue;
+            }
+            if (!liveSession && nativeSessionsByName === undefined) {
+                // The tab would LAUNCH — but the native host state is unknown, so a
+                // homonymous live native session cannot be ruled out. Fail closed.
+                stderr.write(`[h2a] restore: native host state UNKNOWN — "${t.label}" not launched (fail closed)\n`);
+                continue;
+            }
+            activeTabs.push({
+                tab: t,
+                command: liveSession
+                    ? tabCommand(t, new Set([slug]), { attachSession: liveSession.name })
+                    : tabCommand(t, new Set(), tabOpts),
+            });
+        }
+        if (activeTabs.length === 0) {
+            // All sessions in this window are already active — no tab needed.
+            continue;
+        }
+        // Map keyed by per-tab working directory -> the tab's command. Tabs sharing
+        // a cwd (several sessions of one project) each claim a distinct line FIFO.
+        const slug = win.title.replace(/[^a-zA-Z0-9]+/g, "-");
+        const mapPath = join(runDir(), `restore-${process.pid}-${slug}-${mapCounter++}.map`);
+        const body = activeTabs
+            .map(({ tab, command }) => `${tab.cwd}\t${command}`)
+            .join("\n") + "\n";
+        writeFileSync(mapPath, body, "utf8");
+        const args = [];
+        activeTabs.forEach(({ tab }, i) => {
+            args.push(i === 0 ? "--window" : "--tab", `--working-directory=${tab.cwd}`, `--title=${tab.label}`);
+        });
+        // ONE shared dispatcher command for all tabs of this window.
+        args.push("--", "bash", "-lc", DISPATCHER, "remote-restore", mapPath);
+        stderr.write(`[h2a] fenêtre "${win.title}" (${activeTabs.length} onglet(s))\n`);
+        // Surface gnome-terminal errors (e.g. "Failed to get screen…") instead of
+        // silently claiming the window opened.
+        const { GNOME_TERMINAL_SCREEN: _drop, ...childEnv } = process.env;
+        const child = spawn("gnome-terminal", args, {
+            stdio: ["ignore", "ignore", "pipe"],
+            detached: true,
+            env: childEnv,
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr.write(`[h2a] gnome-terminal: ${chunk.toString().trim()}\n`);
+        });
+        child.unref();
+        opened += activeTabs.length;
+    }
+    if (skippedLive.length > 0) {
+        stderr.write(`[h2a] ${skippedLive.length} session(s) déjà visibles ignorées` +
+            ` (--reattach pour les rouvrir quand même): ${skippedLive.join(", ")}\n`);
+    }
+    return { opened, skippedLive };
+}
+//# sourceMappingURL=launch-layout.js.map

package/dist/launch-layout.js.map

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

package/dist/native-host.d.ts

@@ -0,0 +1,146 @@
+import { type PromptDeliveryDeps } from "./prompt-delivery.js";
+import { type SessionClass } from "./session-class.js";
+export type SessionHostKind = "native" | "local-tmux";
+/**
+ * Which host runs a NEW session's terminal. The native PTY host is the
+ * default; `--tmux` (per command) or H2A_SESSION_HOST=tmux (fleet-wide safety
+ * valve) selects tmux. Existing sessions are NEVER re-routed here — verbs that
+ * act on a recorded session honor its registry kind instead.
+ */
+export declare function resolveSessionHostKind(opts: {
+    readonly tmux?: boolean;
+}, env?: Readonly<Record<string, string | undefined>>): SessionHostKind;
+/** Companion native session that hosts the h2a MCP sidecar for `name`. */
+export declare function nativeSidecarName(name: string): string;
+export type NativeSessionState = {
+    readonly id: string;
+    readonly pid: number;
+    readonly status: "running" | "stopping" | "exited";
+    readonly exit: {
+        readonly exitCode: number;
+        readonly signal?: number;
+    } | null;
+    /**
+     * Controller-visibility bit (never the controller's identity): true when an
+     * exclusive input controller is attached. OPTIONAL because an older running
+     * host does not report it — consumers must treat absence as an UNKNOWN view
+     * and fail closed (report, don't relaunch), never as "uncontrolled".
+     */
+    readonly controlled?: boolean;
+};
+export type NativeStartResult = {
+    readonly name: string;
+    readonly slug: string;
+    readonly pid: number;
+};
+/** node-pty loadable + containment binaries present. Pure preflight. */
+export declare function nativeHostAvailable(): {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Spawn-or-adopt the per-user host; returns its identity. */
+export declare function ensureNativeHost(): {
+    hostPid: number;
+    socketPath: string;
+};
+export declare function listNativeSessions(): ReadonlyArray<NativeSessionState>;
+/**
+ * 3-state session probe (F2). The lie this type removes: a failed `state` op
+ * used to flatten into `undefined`/`alive=false` — indistinguishable from a
+ * PROVEN dead/absent session, which let destructive acts read an op failure
+ * as a death certificate. The states:
+ *  - "found": a reachable host answered with the session's state;
+ *  - "absent": POSITIVE proof of absence — a reachable host does not know
+ *    the session, or no host is listening at all (a PTY cannot outlive its
+ *    host process, the same provable-death rule as a missing tmux server);
+ *  - "unknown": the op failed (spawn error, timeout, protocol failure) —
+ *    NEVER proof of death; destructive callers must fail closed on it.
+ * The classification happens IN-BAND in the `probe` op (op.ts), where the
+ * error codes live — never by parsing a generic failure on this side.
+ */
+export type NativeStateProbe = {
+    readonly state: "found";
+    readonly session: NativeSessionState;
+} | {
+    readonly state: "absent";
+} | {
+    readonly state: "unknown";
+    readonly reason: string;
+};
+export declare function nativeSessionState(name: string): NativeStateProbe;
+/**
+ * 3-state liveness (F2): `true` / `false` are POSITIVE verdicts; "unknown"
+ * is a probe failure that destructive paths must refuse on. Never throws.
+ */
+export declare function nativeSessionLiveness(name: string): true | false | "unknown";
+export declare function nativeSessionPid(name: string): number | undefined;
+export type NativeLaunchMetadata = {
+    readonly label?: string;
+    readonly resumeId?: string;
+    readonly sessionClass?: SessionClass;
+    readonly terminateOnAgentExit?: boolean;
+    readonly refuseExisting?: boolean;
+};
+/**
+ * startLocalSession twin. Runs the SAME bash wrapper contract as the tmux
+ * path (LOCAL_WRAPPER drop-to-shell / STRUCTURED_LOCAL_WRAPPER exec-only), so
+ * agent exit semantics are identical across hosts.
+ */
+export declare function startNativeSession(profile: string, command: string, cwd: string, args?: ReadonlyArray<string>, label?: string, metadata?: NativeLaunchMetadata): NativeStartResult;
+/** sendKeysLiteral twin: raw keystrokes, no interpretation. */
+export declare function nativeSendKeysLiteral(name: string, text: string): boolean;
+/** paste-buffer -p twin: the text lands as ONE bracketed block. */
+export declare function nativePasteBlock(name: string, text: string): boolean;
+/** The Enter that submits a composed block. */
+export declare function nativeSendEnter(name: string): boolean;
+/**
+ * capturePane twin. IMPORTANT semantic difference: tmux returns the RENDERED
+ * screen; this returns the ANSI-stripped tail of the output stream. For probe
+ * matching (prompt echo, modal text) the stream tail carries the same visible
+ * text — full-screen-repaint TUIs re-emit their frame into the tail.
+ */
+export declare function nativeCapture(name: string, bytes?: number): string | undefined;
+/** kill-session twin: SIGTERM with SIGKILL escalation inside the op. */
+export declare function killNativeSession(name: string): boolean;
+/**
+ * Kill a session AND its h2a sidecar companion (the tmux twin gets this for
+ * free because the sidecar is a window inside the killed session).
+ */
+export declare function killNativeSessionTree(name: string): boolean;
+/**
+ * startHeadlessSession twin: run-once agent under HEADLESS_WRAPPER, writing
+ * result.json + output.log, session ends when the wrapper finishes. The
+ * prompt rides a 0600 file consumed and unlinked by the wrapper — identical
+ * contract to the tmux path.
+ */
+export declare function startNativeHeadlessSession(profile: string, command: string, cwd: string, args: ReadonlyArray<string>, resultJson: string, outputLog: string, label: string, promptInput?: string, refuseExisting?: boolean, sessionClass?: SessionClass): NativeStartResult & {
+    promptFile?: string;
+};
+/**
+ * startH2aWindow twin: the h2a MCP sidecar runs in a COMPANION native session
+ * (`<name>.h2a`) instead of a tmux window. Lifecycle: killNativeSessionTree
+ * stops it with its main session.
+ */
+export declare function startNativeH2aSidecar(name: string, cwd: string, h2aCommand: string, options?: {
+    verified?: boolean;
+}): boolean;
+/**
+ * Foreground interactive attach on the CURRENT terminal (tmux attach twin).
+ * Blocks until the session exits or the user detaches with Ctrl-\.
+ */
+export declare function attachNativeSession(name: string): number;
+/** clearPaneComposer twin: C-u wipes the composer line (best-effort). */
+export declare function nativeClearComposer(name: string): boolean;
+/** paneTreeCpuMs twin, keyed by session name instead of tmux pane. */
+export declare function nativeTreeCpuMs(name: string): number | undefined;
+/** paneWorkerPid twin: the pid actually doing the work under the wrapper. */
+export declare function nativeWorkerPid(name: string): number | undefined;
+/**
+ * PromptDeliveryDeps for a native session — deliverInitialPrompt() runs the
+ * SAME measured protocol as on tmux; only the transport differs. The "pane"
+ * key given to deliverInitialPrompt must be the session NAME.
+ */
+export declare function nativePromptDeliveryDeps(sleep: (ms: number) => void): PromptDeliveryDeps;
+//# sourceMappingURL=native-host.d.ts.map

package/dist/native-host.d.ts.map

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