@humwick/runner 0.0.0-stage → 0.130.1

package/src/adapters/claude-tmux.ts

@@ -0,0 +1,548 @@
+import { relayEnv } from "@humwick/sdk/env";
+import { envPipeSource, prepareEnvPipe, providerSecretEnvKeys } from "@humwick/sdk/child-env";
+import { PROVIDER_SCRATCH_ENV_KEYS } from "@humwick/sdk/provider-scratch";
+// Claude tmux transport plumbing (extracted from ./claude for the file-size
+// ratchet, #300/#291): session/socket naming, pane capture, input-ready gating,
+// paste/submit injection, launcher-script materialization, and env-key selection.
+// The adapter (./claude) keeps the lifecycle decisions; this module owns the
+// mechanical tmux interactions they ride on. Public symbols are re-exported from
+// ./claude so existing import paths (including claude.test.ts) keep resolving.
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { sanitizeFsName } from "@humwick/sdk/fs-name";
+import { shellEscape as shellQuote } from "@humwick/sdk/shell-utils";
+import { TMUX_SESSION_OWNER_OPTION, managedTmuxSocketName, renderTmuxSessionTarget, tmuxCommand, tmuxHasSession } from "@humwick/sdk/tmux-utils";
+import { claudeClearCommitted, claudeConversationAnchor, claudePaneIsBusy, claudePaneLooksReady } from "./claude-status-detectors";
+import { ClaudeSubmitFence, ClaudeSubmitTranscriptProbe, claudeSubmitRecoveryConfirmed, submitClaudePromptConfirmed } from "./claude-submit-confirmation";
+import type { ClaudePromptHookExpectation, ClaudePromptHookLedger } from "./claude-prompt-hook";
+import type { ProviderInputObserver } from "../adapter";
+import { logger } from "../logger";
+import { claudeClearSessionVerdict, type ClaudeClearSessionReading } from "./claude-session-probe";
+import { tmuxOwnerIdFromEnv } from "../config";
+import { spawnSyncBounded } from "../bounded-spawn-sync";
+import { launcherGatePathForSession, launcherScriptPathForSession, readOneShotExitCode } from "../session-scratch";
+import { captureTmuxPaneAsync, captureTmuxVisiblePaneAsync, loadTmuxBufferFromStdin, runTmuxInput, tmuxSessionPresence, type TmuxReadOpts, type TmuxSessionPresence } from "./tmux-offload";
+
+export const CLAUDE_TMUX_SUBMIT_DELAY_MS = 250;
+export const CLAUDE_TMUX_SUBMIT_KEY = "C-m";
+export const CLAUDE_TMUX_READY_TIMEOUT_MS = 10_000;
+export const CLAUDE_MAX_INLINE_PROMPT_BYTES = 96 * 1024;
+const TMUX_SOCKET_PATH_SAFE_BYTES = 100;
+const promptSubmitFence = new ClaudeSubmitFence();
+const promptSubmitSessionKey = (session: string, socket?: string) => `${socket ?? "default"}:${session}`;
+
+// Claude normally accepts its first user turn as a positional argument. Linux limits one
+// argv element well below a useful large task brief, and tmux paste is not a submission
+// guarantee during onboarding. A transient headless Claude can instead consume the exact
+// assignment from stdin in `-p` mode, preserving its user-message role.
+export function seedClaudeInitialPrompt(args: string[], prompt: string, options: { headless: boolean; lifecycle?: string; scratchDir?: string }): { stdinFile: string; exitCodeFile: string; stdinContents: string } | undefined {
+  if (new TextEncoder().encode(prompt).byteLength <= CLAUDE_MAX_INLINE_PROMPT_BYTES) {
+    args.push(prompt);
+    return undefined;
+  }
+  if (!options.headless || options.lifecycle !== "transient") {
+    throw new Error("oversized Claude initial prompt requires a transient headless launch; refusing a racy or role-changing fallback");
+  }
+  if (!options.scratchDir) throw new Error("oversized Claude initial prompt requires AGENT_RELAY_SCRATCH_DIR");
+  const promptFile = join(options.scratchDir, "claude-initial-assignment.md");
+  const exitCodeFile = join(options.scratchDir, "claude-initial-exit-code");
+  args.push("-p", "--input-format", "text");
+  return { stdinFile: promptFile, exitCodeFile, stdinContents: prompt };
+}
+
+/** A missing sentinel means the one-shot process was killed before its shell could report success. */
+export async function claudeOneShotExitStatus(exitCodeFile?: string): Promise<"offline" | "error"> {
+  if (!exitCodeFile) return "offline";
+  return (await readOneShotExitCode(exitCodeFile)) === "0" ? "offline" : "error";
+}
+
+export function tmuxSessionName(prefix: string, instanceId: string, label?: string): string {
+  if (label) return `${prefix}-${sanitizeFsName(label, { replacement: "-", collapse: false, lowercase: true })}`;
+  return `${prefix}-${instanceId.slice(0, 8)}`;
+}
+
+// tmux silently rewrites `.` and `:` in new session names to `_` (a colon also
+// separates the session/window/pane portions of a target). All later `-t` lookups
+// must use the rendered name or `has-session` misses the session tmux just created.
+// Delegates to the shared SDK renderer so the runner and orchestrator (which must match
+// the rendered name when resolving a shutdown target, #1746 RC-1) can never diverge.
+export function tmuxSessionTargetName(sessionName: string): string {
+  return renderTmuxSessionTarget(sessionName);
+}
+
+export function tmuxSocketName(sessionName: string): string {
+  // `tmux -L` puts this value at <TMUX_TMPDIR>/tmux-<uid>/<socket>. Unix
+  // socket paths are limited to roughly 104-108 bytes, so a display-oriented
+  // session name must never flow into the path unbounded. Hash the complete
+  // session identity (including the orchestrator's agent/spawn suffix) into a
+  // fixed-size token; the readable session name remains unchanged in tmux/UI.
+  const socketName = managedTmuxSocketName(sessionName);
+  assertTmuxSocketPathFits(socketName);
+  return socketName;
+}
+
+// Pre-#1353 socket selector, used only for one-way cleanup when a runner first
+// starts after upgrading. Do not assert its path length: an overlong legacy
+// name is exactly what the new fixed-size selector is designed to escape.
+export function legacyTmuxSocketName(sessionName: string): string {
+  return sanitizeFsName(`agent-relay-${sessionName}`, { replacement: "-", collapse: false, lowercase: true });
+}
+
+export function createOrReuseTmuxSession(sessionName: string, socketName: string, tmuxArgs: string[]): boolean {
+  const targetSessionName = tmuxSessionTargetName(sessionName);
+  spawnSyncBounded(tmuxCommand(socketName, "kill-session", "-t", targetSessionName), {
+    stdin: "ignore", stdout: "ignore", stderr: "ignore",
+  });
+  // Upgrade cleanup: a pre-#1353 runner used the readable session name as its
+  // selector. Best-effort removal prevents a legacy pane surviving beside its
+  // replacement; an overlong legacy selector can fail here harmlessly.
+  spawnSyncBounded(tmuxCommand(legacyTmuxSocketName(sessionName), "kill-session", "-t", targetSessionName), {
+    stdin: "ignore", stdout: "ignore", stderr: "ignore",
+  });
+  const result = spawnSyncBounded(tmuxCommand(socketName, ...tmuxArgs), {
+    stdin: "ignore", stdout: "pipe", stderr: "pipe",
+  });
+  const stderr = result.stderr.toString().trim();
+  // A restart can race a still-live predecessor. Reuse the uniquely named,
+  // confirmed session rather than failing the healthy agent on "duplicate".
+  const reusable = tmuxSessionCreationFailureIsReusable(stderr, targetSessionName, socketName);
+  if (result.exitCode !== 0 && !reusable) {
+    throw new Error(`tmux session creation failed: ${stderr || (result.signalCode ? `signal ${result.signalCode}` : `exit code ${result.exitCode}`)}`);
+  }
+  if (result.exitCode === 0) promptSubmitFence.clear(promptSubmitSessionKey(targetSessionName, socketName));
+  // #1514 — stamp the owning orchestrator's state-home id (passed to this runner via
+  // env) onto the session so the orchestrator's wedged-session reaper reaps ONLY the
+  // sessions it positively owns, never a co-tenant orchestrator's on the same host.
+  setTmuxSessionOwner(targetSessionName, tmuxOwnerIdFromEnv(), socketName);
+  return result.exitCode === 0;
+}
+
+export async function createTmuxSessionWithEnv(sessionName: string, socketName: string, args: string[], script: string, spawnEnv: Record<string, string>, providerEnv: Record<string, string>, gateFifo?: string, provider = "claude"): Promise<void> {
+  const keys = tmuxEnvKeys(spawnEnv, providerEnv, provider);
+  const env = Object.fromEntries(keys.filter((key) => relayEnv(spawnEnv, key) !== undefined).map((key) => [key, relayEnv(spawnEnv, key)!]));
+  const pipe = await prepareEnvPipe(script, env);
+  try {
+    if (createOrReuseTmuxSession(sessionName, socketName, args)) await pipe.sent();
+  } catch (error) {
+    await runTmuxInput("tmux-launch-cleanup", tmuxCommand(socketName, "kill-session", "-t", tmuxSessionTargetName(sessionName))).catch(() => {});
+    if (gateFifo) await releaseLauncherGate(gateFifo);
+    throw error;
+  } finally { await pipe.cleanup(); }
+}
+
+export function tmuxSessionCreationFailureIsReusable(
+  stderr: string,
+  sessionName: string,
+  socketName: string,
+  hasSession: (session: string, socket?: string) => boolean = tmuxHasSession,
+): boolean {
+  return /duplicate session/i.test(stderr)
+    && hasSession(tmuxSessionTargetName(sessionName), socketName);
+}
+
+// #1514 — stamp the owning orchestrator's state-home id onto the tmux session as a
+// user-option. The orchestrator's wedged-session reaper reads it back and reaps ONLY
+// sessions whose owner id matches its own, so it can never reap a session belonging
+// to a different orchestrator that happens to share the UID + tmux prefix on this
+// host. Best-effort: a failure just leaves the session untagged, which the reaper
+// treats as "not positively owned" and skips (fail-safe).
+export function setTmuxSessionOwner(sessionName: string, ownerId: string | undefined, socketName?: string): void {
+  if (!ownerId) return;
+  spawnSyncBounded(tmuxCommand(socketName, "set-option", "-t", sessionName, TMUX_SESSION_OWNER_OPTION, ownerId), {
+    stdin: "ignore", stdout: "ignore", stderr: "ignore",
+  });
+}
+
+export function tmuxSocketPath(socketName: string, socketDir = defaultTmuxSocketDir()): string {
+  return join(socketDir, socketName);
+}
+
+export function assertTmuxSocketPathFits(socketName: string, socketDir = defaultTmuxSocketDir()): void {
+  const path = tmuxSocketPath(socketName, socketDir);
+  const bytes = Buffer.byteLength(path);
+  if (bytes <= TMUX_SOCKET_PATH_SAFE_BYTES) return;
+  throw new Error(`tmux socket directory is too long (socket path is ${bytes} bytes; must be <= ${TMUX_SOCKET_PATH_SAFE_BYTES}); shorten TMUX_TMPDIR`);
+}
+
+// A single failed `has-session` can be transient (and historically was at the
+// Unix socket path boundary). Call after an initial miss and only declare the
+// session gone if a delayed confirmation misses too.
+export async function confirmTmuxSessionGone(
+  sessionName: string,
+  socketName?: string,
+  delayMs = 250,
+  // #1838 row 12 — off the event loop via the tri-state `tmuxSessionPresence` (#1838 review
+  // HIGH-2). Death is confirmed ONLY when BOTH the immediate and the delayed read are the
+  // positive `absent` (tmux exited 1); a `present` OR an `unreadable` (timeout/abort on a
+  // wedged-but-live server) at either point means NOT gone, so a slow read can never be
+  // mistaken for a dead session. Unit tests inject their own presence override.
+  presence: (session: string, socket?: string) => TmuxSessionPresence | Promise<TmuxSessionPresence> = tmuxSessionPresence,
+): Promise<boolean> {
+  if ((await presence(sessionName, socketName)) !== "absent") return false;
+  await Bun.sleep(delayMs);
+  return (await presence(sessionName, socketName)) === "absent";
+}
+
+function defaultTmuxSocketDir(): string {
+  const base = process.env.TMUX_TMPDIR || "/tmp";
+  const uid = typeof process.getuid === "function" ? process.getuid() : "user";
+  return join(base, `tmux-${uid}`);
+}
+
+export function captureTmuxPane(sessionName: string, socketName?: string): string {
+  const result = spawnSyncBounded(tmuxCommand(socketName, "capture-pane", "-p", "-t", sessionName, "-S", "-80"), {
+    stdin: "ignore", stdout: "pipe", stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    throw new Error(`tmux capture-pane failed: ${stderr || (result.signalCode ? `signal ${result.signalCode}` : `exit code ${result.exitCode}`)}`);
+  }
+  return result.stdout.toString();
+}
+
+// #1514's exit-dialog confirmation used to live here as
+// `confirmClaudeExitDialogIfPresent(sessionName, socketName)` — an Enter writer that
+// any caller holding a session name could invoke. #1647 removed it: taking a session
+// name meant nothing in the type system stopped a pane detector from calling it, and
+// the production kill was exactly that Enter answering an "Exit anyway" modal on a
+// live pane. It now lives in ./claude-exit, where both it and the `/exit` writer take
+// an unforgeable one-shot ClaudeExitGrant instead.
+
+// #1838 review BLOCKER + round-3 MED — this readiness poller runs on the hot delivery path
+// (every deliver / deliverInitialPrompt / monitor self-resume settle) and used to call the
+// SYNCHRONOUS tmuxHasSession + captureTmuxPane every 200ms; a single wedged tmux call froze the
+// whole runner event loop for the full 10s deadline. Both reads now go OFF the loop and use the
+// tri-state presence (only a positive `absent` ends the wait with the session-exited error; an
+// `unreadable`/transient read just retries).
+//
+// Round-3 MED: the deadline is now ACTUALLY absolute. Checking Date.now() only BETWEEN calls was
+// not enough — each subprocess still got the runner's ~10s default deadline + kill grace, so a
+// waitForClaudeInputReady(...,500) could hold the serialized provider-input ticket ~12s. An
+// AbortController fires at the outer deadline AND the REMAINING budget is threaded into each read
+// as its own timeout, so no single read can outlive the caller's deadline (bar the irreducible
+// SIGKILL grace).
+export async function waitForClaudeInputReady(sessionName: string, timeoutMs = CLAUDE_TMUX_READY_TIMEOUT_MS, socketName?: string): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  const controller = new AbortController();
+  const abortTimer = setTimeout(() => controller.abort(), timeoutMs);
+  abortTimer.unref?.();
+  try {
+    for (;;) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      const readOpts: TmuxReadOpts = { signal: controller.signal, timeoutMs: remaining };
+      const presence = await tmuxSessionPresence(sessionName, socketName, readOpts);
+      if (presence === "absent") throw new Error("tmux session exited before Claude became ready");
+      if (presence === "present") {
+        try {
+          if (claudePaneLooksReady(await captureTmuxVisiblePaneAsync(sessionName, socketName, readOpts))) return;
+        } catch { /* transient/aborted capture — retry until the deadline rather than fail delivery */ }
+      }
+      await Bun.sleep(Math.min(200, Math.max(0, deadline - Date.now())));
+    }
+    throw new Error(`Claude input was not ready within ${timeoutMs}ms`);
+  } finally {
+    clearTimeout(abortTimer);
+  }
+}
+
+export const CLAUDE_CLEAR_COMMIT_POLL_MS = 200;
+
+/** #2850 — consecutive idle+ready polls (~1s) a vacuous clear needs when the probe can't attest. */
+export const CLAUDE_VACUOUS_CLEAR_READY_POLLS = 5;
+
+/**
+ * #2261 — the capture scope the clear-commit barrier reads, pinned as a named export so the
+ * invariant is assertable. It MUST be the visible-screen capture: `/clear` repaints only the
+ * visible screen (no `ESC[3J`), so a scrollback capture keeps returning the wiped conversation —
+ * and with it the anchor — for the entire timeout, making a committed clear unconfirmable.
+ */
+export const CLAUDE_CLEAR_COMMIT_CAPTURE = captureTmuxVisiblePaneAsync;
+
+// Injectable seams so the polling loop (which otherwise only talks to a live tmux server) is
+// unit-testable — same pattern as confirmTmuxSessionGone's `hasSession` override.
+export interface ClaudeClearCommitDeps {
+  capture?: (sessionName: string, socketName?: string, opts?: TmuxReadOpts) => string | Promise<string>;
+  presence?: (sessionName: string, socketName?: string, opts?: TmuxReadOpts) => TmuxSessionPresence | Promise<TmuxSessionPresence>;
+  sleep?: (ms: number) => Promise<unknown>;
+  /** #2261 — the probe reading taken immediately BEFORE the `/clear` submit (null = unavailable). */
+  preClearSession?: ClaudeClearSessionReading | null;
+  /** #2261 — re-read it each poll, pid-pinned by the caller. Absent → anchor-only (legacy). */
+  readSession?: () => Promise<ClaudeClearSessionReading | null>;
+  /** #2849 — true only when `preClearPane` is a successful capture (not the "" fallback
+   * left by a throw). Lets a provably-empty pre-clear pane confirm via idle+ready. */
+  preClearCaptured?: boolean;
+}
+
+// #1588 — CLEAR-AWARE settle barrier for the self-resume clear+inject coupling. Unlike
+// waitForClaudeInputReady (which returns on the first persistent-footer match — present BOTH
+// before and after `/clear`, the F2 race), this requires POSITIVE evidence the `/clear` actually
+// committed: it snapshots a distinctive pre-clear conversation anchor and only reports success
+// once the pane is idle, input-ready, AND that anchor is gone (the loaded conversation was wiped).
+// Returns a BOOLEAN rather than throwing: `true` = clear positively confirmed committed; `false` =
+// timed out / session vanished / capture failed / no anchor derivable (uncertain). The caller MUST
+// treat `false` as "not confirmed" and report continuationDelivered:false so the #1023 backstop
+// re-injects — never as a wipe. A settle timeout is therefore surfaced, not swallowed.
+export async function waitForClaudeClearCommitted(
+  sessionName: string,
+  preClearPane: string,
+  timeoutMs = CLAUDE_TMUX_READY_TIMEOUT_MS,
+  socketName?: string,
+  deps: ClaudeClearCommitDeps = {},
+): Promise<boolean> {
+  // #1838 review — same off-loop + tri-state + ABSOLUTE-deadline treatment as
+  // waitForClaudeInputReady (this poller also ran sync captureTmuxPane on the clear path, and had
+  // the same between-calls-only deadline, round-3 MED). A positive `absent` returns false (clear
+  // not confirmed → the #1023 backstop re-injects, the safe outcome); an `unreadable` read or a
+  // transient capture failure retries until the deadline instead of blocking or giving up early.
+  // #2261 — the VISIBLE screen, never the `-S -80` scrollback window: `/clear` repaints only the
+  // visible screen, so a scrollback capture keeps returning the wiped conversation (and with it the
+  // anchor) for the whole timeout. That single mismatch made a committed clear unconfirmable on any
+  // pane with history — proven live: the clear-inject at 22:15:10.185Z minted its new Claude
+  // session 112ms later (new transcript file), yet the barrier polled the full 10s and returned
+  // false. `preClearPane` must be a visible-screen capture too, so the anchor is a line the clear
+  // can actually repaint away.
+  const capture = deps.capture ?? CLAUDE_CLEAR_COMMIT_CAPTURE;
+  const presence = deps.presence ?? tmuxSessionPresence;
+  const sleep = deps.sleep ?? Bun.sleep;
+  const anchor = claudeConversationAnchor(preClearPane);
+  const { preClearSession, readSession } = deps;
+  // #2849 — a positively-captured pane with no anchor held no conversation, so the
+  // clear is vacuous. A failed capture ("") also yields no anchor but must stay
+  // fail-closed (preClearCaptured false). Confirmation still needs the settle below.
+  const preClearEmpty = deps.preClearCaptured === true && anchor === undefined;
+  // #2849r1/#2850 — with no probe verdict a ready pane may predate the commit (#1588),
+  // so a vacuous clear needs a CLAUDE_VACUOUS_CLEAR_READY_POLLS streak. A failed capture,
+  // a busy/non-ready pane or an `unchanged` probe reading resets it.
+  let readyStreak = 0;
+  // #2261 — the new session is minted ~112ms BEFORE the TUI finishes repainting (measured on the
+  // live repro), and inside that window an un-cleared pane still reads non-busy + input-ready. So
+  // a rotation only counts once it has been observed on TWO CONSECUTIVE polls, which lands the
+  // confirmation after the repaint rather than inside the #1588 injection window. One poll
+  // interval (200ms) out of a 10s budget.
+  let rotationSeen = false;
+  const deadline = Date.now() + timeoutMs;
+  const controller = new AbortController();
+  const abortTimer = setTimeout(() => controller.abort(), timeoutMs);
+  abortTimer.unref?.();
+  try {
+    for (;;) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      const readOpts: TmuxReadOpts = { signal: controller.signal, timeoutMs: remaining };
+      if ((await presence(sessionName, socketName, readOpts)) === "absent") return false;
+      let pane: string;
+      try {
+        pane = await capture(sessionName, socketName, readOpts);
+      } catch {
+        readyStreak = 0;
+        // #1838 round-4 MED — clamp the poll sleep to the remaining budget so a wait started
+        // with < CLAUDE_CLEAR_COMMIT_POLL_MS left can't overshoot the absolute deadline.
+        await sleep(Math.min(CLAUDE_CLEAR_COMMIT_POLL_MS, Math.max(0, deadline - Date.now())));
+        continue;
+      }
+      // A throw/absent reading yields the `unknown` verdict, so the poll falls back to the anchor
+      // test (and, failing that, to the backstop) exactly as it did before the probe existed.
+      const verdict = claudeClearSessionVerdict(preClearSession, readSession ? await readSession().catch(() => null) : null);
+      const settled = verdict === "rotated" && !rotationSeen ? "unknown" : verdict;
+      rotationSeen = verdict === "rotated";
+      readyStreak = verdict !== "unchanged" && !claudePaneIsBusy(pane) && claudePaneLooksReady(pane) ? readyStreak + 1 : 0;
+      const settledReady = readyStreak >= CLAUDE_VACUOUS_CLEAR_READY_POLLS;
+      if (claudeClearCommitted(anchor, pane, { session: settled, preClearEmpty, settledReady })) return true;
+      // #1838 round-4 MED — same clamp on the steady-state poll.
+      await sleep(Math.min(CLAUDE_CLEAR_COMMIT_POLL_MS, Math.max(0, deadline - Date.now())));
+    }
+    return false;
+  } finally {
+    clearTimeout(abortTimer);
+  }
+}
+
+// #1838 row 16 — the provider input transport (up to 50 spawns per delivered payload).
+// Wave 2a moves every tmux subprocess here OFF the event loop via the offload runner, and the
+// payload rides on STDIN (`load-buffer -`) rather than in argv.
+//
+// The old `set-buffer -b <name> <text>` put the whole delivered message in argv — an
+// ARG_MAX exposure: a large enough message (Claude briefs are routinely multi-KB and can be
+// far larger) overflows the platform's argument limit and the spawn fails outright. tmux
+// `load-buffer` reading from stdin has no such bound, so the buffer load is unconditionally
+// safe now. Every step is side-effecting (it mutates a buffer or types into the pane) and
+// at-most-once — see tmux-offload.ts's header for why a re-run could never double-send.
+//
+// User prompts opt into visible-composer confirmation. Context commands retain their own
+// command-specific commit barriers; the tmux transport still sends those once.
+async function deleteTmuxBuffer(bufferName: string, socketName?: string): Promise<void> {
+  // Best-effort: a failed delete must never fail (or mask) the delivery outcome. #1838 review
+  // LOW — always runs, so a buffer loaded-but-not-cleaned (e.g. a paste timeout) can't leak.
+  await runTmuxInput("tmux-delete-buffer", tmuxCommand(socketName, "delete-buffer", "-b", bufferName)).catch(() => {});
+}
+
+/** Claude user prompts need one bracketed paste with LF intact; slash commands stay literal. */
+export function claudePasteBufferCommand(sessionName: string, bufferName: string, socketName?: string, confirmSubmit = false): string[] {
+  return tmuxCommand(socketName, "paste-buffer", ...(confirmSubmit ? ["-p", "-r"] : []), "-b", bufferName, "-t", sessionName);
+}
+
+/** One event-driven recovery probe; no polling loop runs while the provider is blocked. */
+export async function confirmClaudeSubmitRecovery(sessionName: string, socketName?: string, turnStarted = false): Promise<boolean> {
+  return promptSubmitFence.recover(promptSubmitSessionKey(sessionName, socketName), turnStarted);
+}
+
+export function releaseClaudeSubmitFence(sessionName: string, socketName?: string): void {
+  promptSubmitFence.clear(promptSubmitSessionKey(sessionName, socketName));
+}
+
+export async function submitTextToTmux(sessionName: string, text: string, socketName?: string, options: { confirmSubmit?: boolean; transcriptPath?: string; resolveTranscriptPath?: () => Promise<string | undefined>; promptHooks?: ClaudePromptHookLedger; imagePaths?: readonly string[]; inputObserver?: ProviderInputObserver } = {}): Promise<void> {
+  const bufferName = `agent-relay-${crypto.randomUUID()}`;
+  const paste = async () => {
+    try {
+      // Load via stdin so large prompts never hit the platform argv limit.
+      await loadTmuxBufferFromStdin(bufferName, text, socketName);
+      // tmux otherwise converts every LF to CR, which can submit each paragraph
+      // of a dashboard prompt as a separate turn. Claude requests bracketed paste;
+      // preserve LF and wrap user prompts so its editor receives one paste event.
+      await runTmuxInput("tmux-paste-buffer", claudePasteBufferCommand(sessionName, bufferName, socketName, options.confirmSubmit));
+    } finally {
+      await deleteTmuxBuffer(bufferName, socketName);
+    }
+  };
+  if (options.confirmSubmit) {
+    // Hook mode only on evidence: a stamped hook has reached the runner from this Claude.
+    const hooks = options.promptHooks?.hookPathVerified ? options.promptHooks : undefined;
+    if (options.promptHooks && !hooks) logger.warn("claude", `no stamped hook seen yet; confirming the submit by the composer (${sessionName})`);
+    // The composer (plus the transcript) confirms hookless submits and recovers any failed one.
+    const transcript = (options.transcriptPath || options.resolveTranscriptPath)
+      ? new ClaudeSubmitTranscriptProbe(options.resolveTranscriptPath ?? (async () => options.transcriptPath)) : undefined;
+    await transcript?.start(options.transcriptPath);
+    let expectation: ClaudePromptHookExpectation | undefined;
+    let offeredAt: number | undefined;
+    const confirmConsumption = async () => {
+      const consumed = expectation?.accepted() || (offeredAt !== undefined && await transcript?.confirms(text, offeredAt, options.imagePaths));
+      if (consumed) options.inputObserver?.consumed();
+      return consumed === true;
+    };
+    const startedAt = Date.now();
+    await promptSubmitFence.run(promptSubmitSessionKey(sessionName, socketName), async (markPasteStarted) => {
+      expectation = hooks?.expect(text, options.imagePaths);
+      let entered = false;
+      const mode = await submitClaudePromptConfirmed({
+        ...(expectation ? { hook: expectation } : {}),
+        paste: async () => { markPasteStarted(); await paste(); },
+        readPane: (timeoutMs) => captureTmuxVisiblePaneAsync(sessionName, socketName, { timeoutMs, styled: true }),
+        sendEnter: async () => {
+          if (!entered) { offeredAt = Date.now(); options.inputObserver?.offered(offeredAt, Boolean(hooks || transcript)); }
+          entered = true;
+          await runTmuxInput("tmux-send-keys-submit", tmuxCommand(socketName, "send-keys", "-t", sessionName, CLAUDE_TMUX_SUBMIT_KEY));
+        },
+        cancelCopyMode: async () => {
+          await runTmuxInput("tmux-cancel-copy-mode", tmuxCommand(socketName, "send-keys", "-t", sessionName, "-X", "cancel")).catch(() => {});
+        },
+        delayBeforeFirstEnterMs: CLAUDE_TMUX_SUBMIT_DELAY_MS,
+        onRetry: (attempt) => logger.warn("claude", `Claude input still in composer after Enter; retrying submit key ${attempt}/3 (${sessionName})`),
+      }).catch((error) => {
+        if (hooks && entered && !expectation!.accepted()) {
+          hooks.hookPathLost();
+          logger.warn("claude", `no UserPromptSubmit hook after Enter; hook path unverified until the next stamped hook (${sessionName})`);
+        }
+        throw error;
+      });
+      await confirmConsumption();
+      expectation?.release();
+      logger.info("claude", `Claude prompt submit confirmed via ${mode} in ${Date.now() - startedAt}ms (${sessionName})`);
+    }, async (turnStarted) => await confirmConsumption() || claudeSubmitRecoveryConfirmed({
+      readPane: (timeoutMs) => captureTmuxVisiblePaneAsync(sessionName, socketName, { timeoutMs, styled: true }),
+      ...(transcript ? { readNewUserPrompts: () => transcript.poll() } : {}),
+      paneShowsTurnStarted: claudePaneIsBusy,
+    }, turnStarted));
+    return;
+  }
+  // Submit the pasted input with a SINGLE send-keys C-m: one send, throw-on-failure, no retry —
+  // delivery-acknowledgment semantics identical to main (see the header note + #1844).
+  await paste();
+  await Bun.sleep(CLAUDE_TMUX_SUBMIT_DELAY_MS);
+  options.inputObserver?.offered(Date.now(), false);
+  await runTmuxInput("tmux-send-keys-submit", tmuxCommand(socketName, "send-keys", "-t", sessionName, CLAUDE_TMUX_SUBMIT_KEY));
+}
+
+// The script keeps the provider command out of tmux argv. Environment values
+// arrive through a private FIFO; only the recovery identity is written here.
+// `gateFifo`, when given, is read from (blocking) before the real command execs
+// (#1317): the caller creates the FIFO before the tmux session exists, attaches
+// `pipe-pane` once the pane is up, then writes to the FIFO to release the gate.
+// That guarantees no provider output can be produced before pipe-pane is capturing
+// it — a process that dies in milliseconds previously produced a 0-byte log because
+// pipe-pane was attached in a separate call *after* the session (and its command)
+// had already started. If the FIFO doesn't exist (e.g. mkfifo unavailable), the
+// redirection fails, bash prints a warning and continues straight to `exec` — same
+// racy-but-working behavior as before this fix, not a hard failure.
+export function writeLauncherScript(sessionName: string, env: Record<string, string>, shellCmd: string, gateFifo?: string, stdinFile?: string, exitCodeFile?: string, unsetKeys: string[] = []): string {
+  const scriptPath = launcherScriptPathForSession(sessionName);
+  const launcherDir = dirname(scriptPath); mkdirSync(launcherDir, { recursive: true, mode: 0o700 }); chmodSync(launcherDir, 0o700);
+  const exports = Object.entries(env)
+    .filter(([key]) => key === "AGENT_RELAY_ID")
+    .map(([key, value]) => `export ${shellEnvKey(key)}=${shellQuote(value)}`)
+    .join("\n");
+  // #2513 — exports only ADD to the tmux server's inherited environment; a key that must
+  // not reach the pane (an ambient credential a second-subscription launch must shed)
+  // needs an explicit unset, absence from `env` is not enough.
+  const unsets = unsetKeys.map((key) => `unset ${shellEnvKey(key)}`).join("\n");
+  const gate = gateFifo ? `read -r _ < ${shellQuote(gateFifo)} || true\n` : "";
+  const stdin = stdinFile ? `exec < ${shellQuote(stdinFile)}\n` : "";
+  const command = exitCodeFile ? `${shellCmd}\nexit_code=$?\nprintf '%s' "$exit_code" > ${shellQuote(exitCodeFile)}\nexit "$exit_code"` : `exec ${shellCmd}`;
+  writeFileSync(scriptPath, `#!/usr/bin/env bash\n${exports ? `${exports}\n` : ""}${Object.keys(env).length ? `${envPipeSource()}\n` : ""}${unsets ? `${unsets}\n` : ""}rm -f -- "$0"\n${gate}${stdin}${command}\n`, { mode: 0o700 });
+  return scriptPath;
+}
+
+// Create the gate FIFO before the tmux session starts. Best-effort: if `mkfifo`
+// is unavailable, the launcher script's `read < fifo` simply fails-and-continues
+// (see writeLauncherScript), so callers don't need to branch on this return value.
+export function createLauncherGate(gateFifo: string): void {
+  try { rmSync(gateFifo, { force: true }); } catch {}
+  spawnSyncBounded(["mkfifo", "-m", "600", gateFifo], { stdin: "ignore", stdout: "ignore", stderr: "ignore" });
+}
+
+// Release a launcher gate created by `createLauncherGate`, unblocking the
+// launcher script's `read`. Opening a FIFO for writing blocks until a reader is
+// present, so this runs the write in a short-lived subprocess with a timeout
+// guard: if nothing ever reads the FIFO (session/launcher failed to start), we
+// give up rather than hang the caller forever.
+export async function releaseLauncherGate(gateFifo: string, timeoutMs = 5_000): Promise<void> {
+  try {
+    const proc = Bun.spawn(["sh", "-c", `printf x > ${shellQuote(gateFifo)}`], {
+      stdin: "ignore", stdout: "ignore", stderr: "ignore",
+    });
+    const timedOut = await Promise.race([
+      proc.exited.then(() => false),
+      Bun.sleep(timeoutMs).then(() => true),
+    ]);
+    if (timedOut) {
+      try { proc.kill(); } catch {}
+    }
+  } catch {
+    // best-effort — a stuck launcher gate is no worse than the pre-#1317 race.
+  } finally {
+    try { rmSync(gateFifo, { force: true }); } catch {}
+  }
+}
+
+function shellEnvKey(key: string): string {
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) return key;
+  throw new Error(`invalid environment variable name for Claude launcher: ${key}`);
+}
+
+export function tmuxEnvKeys(env: Record<string, string>, providerEnv: Record<string, string>, provider = "claude"): string[] {
+  // #1222 — PATH is always carried through, not just AGENT_RELAY_/CLAUDE_ vars, so the
+  // launcher script's exported session PATH (built by buildSpawnArgs) reaches
+  // the tmux pane instead of whatever ambient PATH the tmux server happened to inherit.
+  // #3084 — likewise the agent's private TMPDIR/TMP/TEMP: without them the pane got the tmux
+  // server's host-shared TMPDIR while only CLAUDE_CODE_TMPDIR was per-agent.
+  const keys = new Set<string>(["PATH", ...PROVIDER_SCRATCH_ENV_KEYS, ...providerSecretEnvKeys(provider)]);
+  for (const key of Object.keys(env)) {
+    if ((key.startsWith("AGENT_RELAY_") || key.startsWith("HUMWICK_")) || key.startsWith("CLAUDE_")) {
+      keys.add(key);
+    }
+  }
+  for (const key of Object.keys(providerEnv)) {
+    keys.add(key);
+  }
+  return [...keys].sort();
+}