@pinet/slack-bridge 0.2.2 → 0.2.6

package/dist/broker/hibernation-runtime-adapters.js

@@ -0,0 +1,473 @@
+// Real hibernation runtime adapters: the live `HibernationProcessController` and
+// `HibernationTmuxController` the broker injects into `HibernationOrchestrator`.
+//
+// Design (proven feasible on disposable tmux/pi workers):
+//   • A broker-managed worker runs `pi` as the foreground process of a tmux pane
+//     whose session was launched with `remain-on-exit on`. The pane's `pane_pid`
+//     IS the Pi runtime pid; its session `.jsonl` path is recorded in the runtime
+//     spec's `sessionResumeRef` (`session:<path>`).
+//   • Hibernate = stop the Pi pid (TERM then bounded KILL). Because the pane has
+//     `remain-on-exit on`, the tmux session survives (operator-attachable) and is
+//     NEVER destroyed here; the pane transitions to `pane_dead=1`.
+//   • Wake = respawn a launcher into the recorded pane ONLY when that exact pane
+//     is present and explicitly dead, exporting the single-use wake fence and
+//     resuming the exact session via `pi --session <path>`. The woken Pi
+//     re-registers under the SAME stable id and presents the fence for atomic
+//     generation acceptance.
+//
+// PID-reuse / signal safety (independent-review P1): a numeric pid is NEVER
+// signalled on its own. Every TERM/KILL/liveness action is bound to a process
+// GENERATION and re-verified immediately before each signal. A generation is the
+// tuple (pane-authoritative `pane_pid`, `pane_dead=0`, and the OS process START
+// TIME from `ps -o lstart=`). If the pane no longer hosts that exact live
+// generation — the process exited, the pane died, or the pid was reused by a
+// process with a different start time — the action is abandoned as "already gone"
+// rather than risking a signal to an unrelated process. Start time is used (not
+// the command line) because the wake launcher `exec`s Pi over its own shell: that
+// preserves the pid AND the start time but REWRITES the command line, so a
+// command-line token would spuriously drift across the exec while start time stays
+// stable and correctly pins the process instance.
+//
+// Honest limits (independent-review P2 hardening): `ps -o lstart=` is only
+// second-resolution and the verify→signal step is not atomic, so a residual TOCTOU
+// window remains — a same-user process that reused the pid WITHIN the same wall
+// second could compare equal. No higher-resolution start token is portably
+// available via `ps` across macOS/Linux, so this is strong defense-in-depth that
+// makes cross-second reuse safe, NOT an absolute guarantee; the same-second window
+// is an accepted, documented residual rather than a claimed "never".
+//
+// The wake attempt's generation travels INSIDE the `RuntimeAttemptHandle` the
+// controller returns (see {@link LaunchedAttemptHandle}); the orchestrator
+// round-trips that handle opaquely and hands it back to the attempt-scoped
+// stop/liveness probes. There is therefore NO shared mutable registry between the
+// two controllers to mis-compose — the generation binding is carried by the
+// handle itself, so independent construction of the two controllers (as the live
+// wiring does) is inherently correct and a failed/timed-out wake is always
+// cleanable by the exact process it launched.
+//
+// All process/tmux/ps/git interaction is funnelled through an injectable
+// `CommandRunner` + signal/liveness hooks so the security- and correctness-
+// critical control flow is unit-testable without spawning real processes.
+import { execFile } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { buildResumeLauncherScript, buildWakeFenceEnv, deriveVcsIdentity, parseRssBytesFromPs, resumePathFromSessionRef, } from "./hibernation-runtime-helpers.js";
+/** Real `CommandRunner` over `child_process.execFile` that never throws on a
+ * non-zero exit — it resolves the captured exit code so callers branch on it. */
+export function createExecFileRunner() {
+    return {
+        run(file, args) {
+            return new Promise((resolve) => {
+                execFile(file, args, { encoding: "utf8", maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+                    const rawCode = error?.code;
+                    const code = typeof rawCode === "number" ? rawCode : error ? 1 : 0;
+                    resolve({ stdout: stdout ?? "", stderr: stderr ?? "", code });
+                });
+            });
+        },
+    };
+}
+/**
+ * Boundary read of the launch generation carried by a handle. The handle arrives
+ * typed as the public broker-core shape; if it was minted by our
+ * `respawnRuntime` it carries a well-formed {@link AttemptGeneration}, otherwise
+ * the field is absent and we return null (probes then fail closed).
+ */
+function launchedGenerationOf(handle) {
+    return handle.generation ?? null;
+}
+function tmuxSocketArgs(socket) {
+    return socket ? ["-S", socket] : [];
+}
+// agent-standards-ignore prefer-inline-single-use-helper: centralizes default
+// resolution for the ResolvedProcessDeps bundle shared by the controller and the
+// module-level generation-termination helper.
+function resolveProcessDeps(deps) {
+    return {
+        runner: deps.runner ?? createExecFileRunner(),
+        sessionByteSize: deps.sessionByteSize ??
+            ((p) => {
+                try {
+                    return fs.statSync(p).size;
+                }
+                catch {
+                    return null;
+                }
+            }),
+        processAlive: deps.processAlive ??
+            ((pid) => {
+                try {
+                    process.kill(pid, 0);
+                    return true;
+                }
+                catch (error) {
+                    // EPERM means the process exists but we may not signal it — still "alive".
+                    return error.code === "EPERM";
+                }
+            }),
+        sendSignal: deps.sendSignal ?? ((pid, signal) => process.kill(pid, signal)),
+        now: deps.now ?? (() => Date.now()),
+        sleep: deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+        pendingInboxCount: deps.pendingInboxCount ?? (() => 0),
+        stopGraceMs: deps.stopGraceMs ?? 5_000,
+        pollMs: deps.pollMs ?? 100,
+    };
+}
+async function paneField(runner, addr, field) {
+    const result = await runner.run("tmux", [
+        ...tmuxSocketArgs(addr.tmuxSocket),
+        "display-message",
+        "-p",
+        "-t",
+        addr.tmuxTarget,
+        `#{${field}}`,
+    ]);
+    if (result.code !== 0)
+        return null;
+    const value = result.stdout.trim();
+    return value.length > 0 ? value : null;
+}
+async function panePid(runner, addr) {
+    const raw = await paneField(runner, addr, "pane_pid");
+    const pid = raw ? Number.parseInt(raw, 10) : Number.NaN;
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+async function rssBytesOf(runner, pid) {
+    const result = await runner.run("ps", ["-o", "rss=", "-p", String(pid)]);
+    if (result.code !== 0)
+        return null;
+    return parseRssBytesFromPs(result.stdout);
+}
+/**
+ * The OS generation token for a pid: its process START TIME (`ps -o lstart=`),
+ * normalized. Two processes sharing a pid but not this start time are DIFFERENT
+ * process instances (cross-second reuse), so this pins the generation against the
+ * common pid-reuse case. The command line is deliberately NOT included: the wake
+ * launcher `exec`s Pi over its shell, rewriting the command line while preserving
+ * the pid and start time, so a command token would drift spuriously across that
+ * exec. Returns null when the pid is gone (no ps row). See the "Honest limits"
+ * header note re: the residual same-second window.
+ */
+async function readGenerationToken(runner, pid) {
+    const started = await runner.run("ps", ["-o", "lstart=", "-p", String(pid)]);
+    if (started.code !== 0)
+        return null;
+    const startedAt = started.stdout.trim().replace(/\s+/g, " ");
+    return startedAt.length > 0 ? startedAt : null;
+}
+/**
+ * Read the pane's current process generation: its foreground pid, whether the
+ * pane is dead (only an explicit `pane_dead=0` is live; null/"1" ⇒ dead/gone),
+ * and the pid's generation token. `generationToken` is null when the pane has no
+ * live pid.
+ */
+async function readPaneGeneration(runner, addr) {
+    const pid = await panePid(runner, addr);
+    const deadRaw = await paneField(runner, addr, "pane_dead");
+    const dead = deadRaw !== "0";
+    const generationToken = pid != null ? await readGenerationToken(runner, pid) : null;
+    return { pid, dead, generationToken };
+}
+/**
+ * True only if the pane provably still hosts the EXACT expected live generation:
+ * the pane's foreground pid equals the expected pid, the pane is not dead, the
+ * pid is a live process, and its current generation token matches the expected
+ * one (defeating pid reuse). Any drift ⇒ false (the expected process is gone /
+ * not ours), so a signal is never sent to a reused or replaced pid.
+ */
+async function paneHostsGeneration(runner, addr, expected, processAlive) {
+    const current = await readPaneGeneration(runner, addr);
+    return (current.pid === expected.pid &&
+        !current.dead &&
+        current.generationToken != null &&
+        current.generationToken === expected.generationToken &&
+        processAlive(expected.pid));
+}
+/**
+ * TERM then bounded KILL a process addressed by its pane + generation. The pane
+ * is re-verified to still host the exact expected live generation immediately
+ * before EVERY signal; the moment it no longer does (exit, pane death, or pid
+ * reuse with a different generation token) the process is treated as confirmed
+ * gone and no further signal is sent. Shared by pre-hibernation stop and
+ * failed-wake attempt cleanup. Resolves whether the generation is confirmed gone.
+ */
+async function terminateGeneration(addr, expected, deps) {
+    const stillOurs = () => paneHostsGeneration(deps.runner, addr, expected, deps.processAlive);
+    if (!(await stillOurs()))
+        return true;
+    try {
+        deps.sendSignal(expected.pid, "SIGTERM");
+    }
+    catch {
+        // Raced to exit between the verification and the signal.
+        return !(await stillOurs());
+    }
+    const deadline = deps.now() + deps.stopGraceMs;
+    while (deps.now() < deadline) {
+        await deps.sleep(deps.pollMs);
+        if (!(await stillOurs()))
+            return true;
+    }
+    if (!(await stillOurs()))
+        return true;
+    try {
+        deps.sendSignal(expected.pid, "SIGKILL");
+    }
+    catch {
+        // Raced to exit during escalation.
+    }
+    await deps.sleep(deps.pollMs);
+    return !(await stillOurs());
+}
+export function createHibernationProcessController(deps = {}) {
+    const d = resolveProcessDeps(deps);
+    async function runtimeAlive(spec) {
+        const addr = { tmuxSocket: spec.tmuxSocket, tmuxTarget: spec.tmuxTarget };
+        const current = await readPaneGeneration(d.runner, addr);
+        const alive = current.pid != null &&
+            !current.dead &&
+            current.generationToken != null &&
+            d.processAlive(current.pid);
+        return {
+            alive,
+            generation: alive && current.pid != null && current.generationToken != null
+                ? { pid: current.pid, generationToken: current.generationToken }
+                : null,
+        };
+    }
+    return {
+        async requestCheckpoint(spec) {
+            // Contract (narrowed, evidence-backed): a `hibernateSafe` result asserts
+            // the RESUMABILITY PRECONDITION — the recorded pane still hosts a live
+            // process generation (pane-authoritative pid, `pane_dead=0`, live pid with
+            // a readable generation token) AND the session `.jsonl` exists and is
+            // NON-EMPTY on disk. It does NOT perform a cooperative in-flight flush/ack
+            // handshake with Pi (which would require Pi-side support and is future
+            // work); the orchestrator additionally refuses to hibernate while any inbox
+            // work is pending/arriving, so a mid-turn runtime is not silently discarded.
+            const { alive, generation } = await runtimeAlive(spec);
+            const rssBytes = generation != null ? await rssBytesOf(d.runner, generation.pid) : null;
+            const pendingInboxCount = d.pendingInboxCount(spec.agentId);
+            const base = { sessionResumeRef: spec.sessionResumeRef, pendingInboxCount, rssBytes };
+            if (!alive) {
+                return { hibernateSafe: false, reason: "runtime_not_alive", ...base };
+            }
+            const resumePath = resumePathFromSessionRef(spec.sessionResumeRef);
+            const sessionBytes = resumePath != null ? d.sessionByteSize(resumePath) : null;
+            if (sessionBytes == null) {
+                return { hibernateSafe: false, reason: "session_unresumable", ...base };
+            }
+            if (sessionBytes <= 0) {
+                return { hibernateSafe: false, reason: "session_empty", ...base };
+            }
+            return { hibernateSafe: true, reason: null, ...base };
+        },
+        async stopRuntime(spec) {
+            const addr = { tmuxSocket: spec.tmuxSocket, tmuxTarget: spec.tmuxTarget };
+            // Capture the live generation to stop BEFORE any mutation; if the pane is
+            // already dead / has no live generation there is nothing to stop.
+            const current = await readPaneGeneration(d.runner, addr);
+            if (current.pid == null || current.dead || current.generationToken == null) {
+                return { stopped: true, rssBytes: null };
+            }
+            if (!d.processAlive(current.pid))
+                return { stopped: true, rssBytes: null };
+            const generation = {
+                pid: current.pid,
+                generationToken: current.generationToken,
+            };
+            const rssBytes = await rssBytesOf(d.runner, generation.pid);
+            // Ensure the pane survives the Pi exit BEFORE stopping it, so hibernation
+            // requires no change to the worker spawn path. With remain-on-exit on,
+            // killing the pane's foreground Pi leaves the tmux session intact and
+            // operator-attachable, and a wake can respawn into the (now dead) pane.
+            await d.runner.run("tmux", [
+                ...tmuxSocketArgs(spec.tmuxSocket),
+                "set-option",
+                "-t",
+                spec.tmuxSession,
+                "remain-on-exit",
+                "on",
+            ]);
+            const stopped = await terminateGeneration(addr, generation, d);
+            return { stopped, rssBytes };
+        },
+        async isRuntimeAlive(spec) {
+            return (await runtimeAlive(spec)).alive;
+        },
+        async stopLaunchedAttempt(handle) {
+            // Bind to the generation THIS attempt carried in its handle. A handle with
+            // no generation is unprovable, so fail closed rather than risk relaunching
+            // over a live runtime.
+            const generation = launchedGenerationOf(handle);
+            if (!generation)
+                return { stopped: false };
+            const addr = {
+                tmuxSocket: generation.tmuxSocket,
+                tmuxTarget: generation.tmuxTarget,
+            };
+            return { stopped: await terminateGeneration(addr, generation, d) };
+        },
+        async isLaunchedAttemptAlive(handle) {
+            // Unprovable (no carried generation) ⇒ treat as still alive so cleanup
+            // never assumes a phantom exit.
+            const generation = launchedGenerationOf(handle);
+            if (!generation)
+                return true;
+            const addr = {
+                tmuxSocket: generation.tmuxSocket,
+                tmuxTarget: generation.tmuxTarget,
+            };
+            return paneHostsGeneration(d.runner, addr, generation, d.processAlive);
+        },
+    };
+}
+export function createHibernationTmuxController(deps) {
+    const runner = deps.runner ?? createExecFileRunner();
+    const writeFile = deps.writeFile ?? ((filePath, content, mode) => fs.writeFileSync(filePath, content, { mode }));
+    const unlink = deps.unlink ??
+        ((filePath) => {
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch {
+                // Best effort: already gone (e.g. the launcher self-deleted).
+            }
+        });
+    const readEnv = deps.readEnv ?? ((key) => process.env[key]);
+    const buildNickname = deps.buildNickname ??
+        ((ctx) => `Woken ${ctx.spec.launchSource || "worker"} ${ctx.reservationNonce.slice(0, 8)}`);
+    // Private, owner-only launcher dir (0700), created lazily so constructing the
+    // controller has no filesystem side effect and tests can inject an explicit dir.
+    let launcherDir = deps.launcherDir;
+    const resolveLauncherDir = () => {
+        if (launcherDir)
+            return launcherDir;
+        launcherDir = fs.mkdtempSync(path.join(os.tmpdir(), "pinet-wake-"));
+        return launcherDir;
+    };
+    return {
+        async isSessionAttachable(spec) {
+            const result = await runner.run("tmux", [
+                ...tmuxSocketArgs(spec.tmuxSocket),
+                "has-session",
+                "-t",
+                spec.tmuxSession,
+            ]);
+            return result.code === 0;
+        },
+        async respawnRuntime(ctx) {
+            if (ctx.spec.runtimeKind !== "tmux") {
+                throw new Error("hibernation unsupported on this runtime");
+            }
+            const spec = ctx.spec;
+            const resumePath = resumePathFromSessionRef(spec.sessionResumeRef);
+            // Unresumable spec ⇒ no session to bring back; fail closed (no handle).
+            if (!resumePath)
+                return { launched: false, handle: null };
+            const addr = { tmuxSocket: spec.tmuxSocket, tmuxTarget: spec.tmuxTarget };
+            // Destructive-wake guard (independent-review P1): only respawn when the
+            // EXACT recorded pane is present AND explicitly dead. A missing pane cannot
+            // be woken; a LIVE pane must never be clobbered (drift / manual recovery /
+            // ambiguous state), so we neither force-kill it with `respawn-pane -k` nor
+            // proceed. `respawn-pane` (no `-k`) additionally refuses a non-dead pane at
+            // the tmux layer, giving defence in depth.
+            const sessionPresent = (await runner.run("tmux", [
+                ...tmuxSocketArgs(spec.tmuxSocket),
+                "has-session",
+                "-t",
+                spec.tmuxSession,
+            ])).code === 0;
+            if (!sessionPresent)
+                return { launched: false, handle: null };
+            const deadRaw = await paneField(runner, addr, "pane_dead");
+            if (deadRaw !== "1")
+                return { launched: false, handle: null };
+            const inheritedEnv = {};
+            for (const key of deps.inheritedEnvKeys)
+                inheritedEnv[key] = readEnv(key);
+            const pinetEnv = {
+                ...deps.baseLaunchEnv,
+                ...buildWakeFenceEnv({
+                    wakeLeaseId: ctx.wakeLeaseId,
+                    fenceToken: ctx.fenceToken,
+                    reservedGeneration: ctx.reservedGeneration,
+                    reservationNonce: ctx.reservationNonce,
+                    correlationId: ctx.correlationId,
+                }),
+            };
+            const script = buildResumeLauncherScript({
+                repoPath: spec.cwd || spec.repoRoot,
+                sessionPath: resumePath,
+                extensionEntryPath: deps.extensionEntryPath,
+                inheritedEnv,
+                pinetEnv,
+                nickname: buildNickname(ctx),
+            });
+            const launcherPath = path.join(resolveLauncherDir(), `pinet-wake-${ctx.reservationNonce}.sh`);
+            let launched = false;
+            try {
+                writeFile(launcherPath, script, 0o700);
+                // No `-k`: only a dead pane is respawned (guarded above); a live pane is
+                // never force-killed.
+                const result = await runner.run("tmux", [
+                    ...tmuxSocketArgs(spec.tmuxSocket),
+                    "respawn-pane",
+                    "-t",
+                    spec.tmuxTarget,
+                    launcherPath,
+                ]);
+                if (result.code !== 0)
+                    return { launched: false, handle: null };
+                launched = true;
+                // Bind the launched attempt to its exact process generation and carry it
+                // INSIDE the handle, so retry cleanup can prove THIS process (not a reused
+                // pid) is gone with no shared registry. If the pid/token cannot be
+                // captured, the handle carries no generation and the attempt-scoped probes
+                // fail closed (orchestrator quarantines as ambiguous).
+                const pid = await panePid(runner, addr);
+                const generationToken = pid != null ? await readGenerationToken(runner, pid) : null;
+                const base = {
+                    reservationNonce: ctx.reservationNonce,
+                    tmuxTarget: spec.tmuxTarget,
+                    pid,
+                };
+                if (pid != null && generationToken != null) {
+                    const handle = {
+                        ...base,
+                        generation: {
+                            pid,
+                            generationToken,
+                            tmuxSocket: spec.tmuxSocket,
+                            tmuxTarget: spec.tmuxTarget,
+                        },
+                    };
+                    return { launched: true, handle };
+                }
+                return { launched: true, handle: base };
+            }
+            finally {
+                // Guaranteed cleanup of the secret-bearing launcher: on the happy path
+                // the script self-deletes (`rm -f "$0"` before exec), so unlinking here
+                // could race the pane shell's open — only remove the orphan on the
+                // FAILURE path (where the launcher never exec'd).
+                if (!launched)
+                    unlink(launcherPath);
+            }
+        },
+    };
+}
+/**
+ * Resolve the canonical git-remote-derived `owner/repo` VCS identity for a repo
+ * root at spawn time. This is the ONLY identity the repo allowlist authorizes
+ * against — derived from the runtime's actual `origin` remote, never from the
+ * filesystem directory name. Returns null when no remote is resolvable (the
+ * fail-closed authorization gate then refuses).
+ */
+export async function resolveVcsIdentity(repoRoot, runner = createExecFileRunner()) {
+    const result = await runner.run("git", ["-C", repoRoot, "remote", "get-url", "origin"]);
+    if (result.code !== 0)
+        return null;
+    return deriveVcsIdentity(result.stdout.trim());
+}

package/dist/broker/hibernation-runtime-helpers.d.ts

@@ -0,0 +1,146 @@
+import type { AgentRuntimeSpecInput } from "@pinet/broker-core/types";
+/** Single-quote a value for safe embedding in a POSIX shell launcher script. */
+export declare function shellQuote(value: string): string;
+/**
+ * Derive a canonical `owner/repo` VCS identity from a git remote URL. Supports
+ * scp-style (`git@github.com:owner/repo.git`), URL (`https://host/owner/repo`,
+ * `ssh://git@host/owner/repo`, `git://host/owner/repo`), and bare `owner/repo`
+ * forms. Returns null when no `owner/repo` can be derived.
+ *
+ * This is the ONLY identity the repo allowlist authorizes against, and it is
+ * derived from the runtime's actual git REMOTE — never from filesystem directory
+ * names — so distinct roots that merely share their final path segments (or a
+ * worktree vs. its clone) never collapse onto, or diverge from, one authorization
+ * identity.
+ */
+export declare function deriveVcsIdentity(remoteUrl: string | null | undefined): string | null;
+/**
+ * Parse resident set size (bytes) from `ps -o rss= -p <pid>` output. macOS/Linux
+ * `ps` reports RSS in kibibytes; returns null when no numeric value is present
+ * (e.g. the process already exited).
+ */
+export declare function parseRssBytesFromPs(psOutput: string | null | undefined): number | null;
+/**
+ * Build the broker-resolvable, redaction-safe session resume reference for a
+ * worker from its stable id. A worker's stable id embeds the absolute path to
+ * its Pi session `.jsonl` (`<host>:session:<path>`); the resume ref is stored as
+ * `session:<path>` so `redactRuntimeSpec` digests it to `session:#<fingerprint>`
+ * on every operator/JSON surface while the broker can still recover the path to
+ * respawn `pi --session <path>`. Returns null for stable ids without a session
+ * path (e.g. `cwd:`/`leaf:` kinds), which are not resumable.
+ */
+export declare function sessionResumeRefFromStableId(stableId: string | null | undefined): string | null;
+/** Recover the absolute session `.jsonl` path from a `session:<path>` resume ref. */
+export declare function resumePathFromSessionRef(sessionResumeRef: string | null | undefined): string | null;
+/** The broker-issued wake fence a respawned runtime must echo back to register. */
+export interface WakeFence {
+    wakeLeaseId: string;
+    fenceToken: number;
+    reservedGeneration: number;
+    reservationNonce: string;
+}
+export interface WakeFenceEnvInput extends WakeFence {
+    correlationId: string;
+}
+/**
+ * Environment variables the respawn launcher exports so the woken runtime can
+ * present its single-use wake fence on registration. Ordinary (non-wake) spawns
+ * never set these, so ordinary registration stays fence-free and backward
+ * compatible.
+ */
+export declare function buildWakeFenceEnv(input: WakeFenceEnvInput): Record<string, string>;
+/**
+ * Parse a wake fence from a woken worker's environment (the boundary between the
+ * respawn launcher and the follower's register RPC). Returns null unless ALL
+ * required fields are present and well-formed — the numeric fence token and
+ * reserved generation must be canonical positive decimal safe integers — so a
+ * partial/garbled environment fails closed to an ordinary (fence-free)
+ * registration rather than a malformed fenced one.
+ */
+export declare function parseWakeFenceEnv(env: Record<string, string | undefined>): WakeFence | null;
+/**
+ * The broker-KNOWN, spawn-authored facts that compose a durable runtime spec.
+ *
+ * Every operational field here (the tmux socket/session/target the broker will
+ * later kill and respawn into, the repo/cwd it runs `ps`/`kill`/`git` against)
+ * MUST come from the broker's own spawn record — NEVER from worker-reported
+ * registration metadata. A worker that could name another worker's tmux pane
+ * would otherwise get the broker to checkpoint/kill/respawn THAT pane on its
+ * behalf. The only field the worker's identity contributes is its stable id
+ * (which embeds its own session path); authorization uses solely the
+ * broker-derived {@link vcsIdentity}.
+ */
+interface SpawnAuthoredRuntimeFactsBase {
+    agentId: string;
+    stableId: string;
+    brokerOwnerId: string;
+    cwd: string;
+    repoRoot: string;
+    worktreePath: string;
+    extensionEntryPath: string;
+    /** Environment variable NAMES (never values) the launcher exports. */
+    envAllowlist: string[];
+    configFingerprint: string;
+    expectedUser: string;
+    launchSource: string;
+    /** Broker-derived from the runtime's git remote — the ONLY authz identity. */
+    vcsIdentity: string | null;
+}
+export type SpawnAuthoredRuntimeFacts = SpawnAuthoredRuntimeFactsBase & ({
+    /** Optional only for compatibility with existing tmux-authored callers. */
+    runtimeKind?: "tmux";
+    tmuxSocket: string;
+    tmuxSession: string;
+    tmuxTarget: string;
+} | {
+    runtimeKind: "herdr";
+    herdrSession: string;
+    herdrConfigDir: string;
+    herdrPaneId: string;
+    herdrShellPid: number;
+});
+/**
+ * Compose a durable {@link AgentRuntimeSpecInput} from broker-known spawn facts.
+ *
+ * Fails closed (returns null) when the identity is not a resumable Pi session
+ * (`sessionResumeRef` cannot be derived) or any operational locator the broker
+ * must act on (tmux socket/session/target, repo root) is missing — a spec that
+ * could not be safely hibernated/woken is never recorded. `expectedHost` is
+ * taken from the stable id's host prefix; `argv` mirrors the resume launch
+ * (`pi -e <entry> --session <path>`) for provenance; the resume path itself is
+ * only ever recovered from the redaction-safe `sessionResumeRef`.
+ */
+export declare function buildRuntimeSpecInput(facts: SpawnAuthoredRuntimeFacts): AgentRuntimeSpecInput | null;
+export interface ResumeLauncherInput {
+    repoPath: string;
+    /** Absolute path to the Pi session `.jsonl` to resume. */
+    sessionPath: string;
+    extensionEntryPath: string;
+    /** Inherited env keys to re-export if present in the broker environment. */
+    inheritedEnv: Record<string, string | undefined>;
+    /** PINET_* launch env plus the wake-fence env for this attempt. */
+    pinetEnv: Record<string, string>;
+    nickname: string;
+}
+/**
+ * Build the launcher script a wake attempt runs via `tmux respawn-pane` to bring
+ * back the fenced runtime. It re-establishes the repo cwd and launch environment,
+ * exports the wake fence, and resumes the exact session with `pi --session
+ * <path>` (no startup prompt — the session already carries the worker's context;
+ * injecting a prompt would append a spurious user turn). The woken Pi therefore
+ * re-registers under the SAME stable id (same session path) and presents the
+ * fence for atomic generation acceptance.
+ *
+ * The script is secret-bearing (it exports mesh/Slack credential VALUES), so it
+ * removes its own file (`rm -f -- "$0"`) as its FIRST executable action — before
+ * `cd` and before exporting ANY secret. Under `set -euo pipefail` a later failure
+ * (e.g. a missing/unmounted repo making `cd` exit) therefore cannot leave a
+ * secret-bearing file behind, closing the “tmux accepted launch, launcher began,
+ * pre-delete setup failed” retention window. The launcher fd stays open across the
+ * unlink (POSIX keeps the inode until the fd closes), so `exec pi` still runs from
+ * the now-unnamed inode even though the secrets are exported after the unlink. The
+ * broker separately unlinks on the failure path (where the script never ran) and
+ * materializes launchers only in a private, owner-only directory.
+ */
+export declare function buildResumeLauncherScript(input: ResumeLauncherInput): string;
+export {};