jeo-code 0.6.4 → 0.6.5

package/src/commands/launch/input.ts

@@ -0,0 +1,330 @@
+export interface InFlightAbortHarness {
+  controller: AbortController;
+  handleSigint(): void;
+  handleData(chunk: string | Uint8Array): void;
+  dispose(): void;
+}
+
+interface AbortHarnessOptions {
+  controller?: AbortController;
+  captureEsc?: boolean;
+  stdin?: {
+    isTTY?: boolean;
+    isRaw?: boolean;
+    setRawMode?(raw: boolean): void;
+    resume?(): void;
+    on(event: "data", listener: (chunk: string | Uint8Array) => void): unknown;
+    off(event: "data", listener: (chunk: string | Uint8Array) => void): unknown;
+  };
+  onAbortNotice?: (message: string) => void;
+  onHardExit?: () => void;
+  /** Invoked when stray escape-sequence noise (wheel scroll etc.) arrives mid-turn. */
+  onNoise?: () => void;
+  /** Invoked when Ctrl+O (\u000f) is pressed mid-turn — the detail-view binding.
+   *  Without this hook the byte would be swallowed into the buffered input queue,
+   *  which is why Ctrl+O historically "did nothing" while the TUI owned stdin. */
+  onDetailKey?: () => void;
+  /** Invoked when an arrow / PageUp / PageDown key arrives mid-turn — scrolls the
+   *  open Ctrl+O detail panel. dir -1 = up/back, +1 = down/forward; page = full jump. */
+  onScrollKey?: (dir: -1 | 1, page: boolean) => void;
+  /** Invoked with printable keyboard input received while the live turn owns stdin. */
+  onBufferedInput?: (chunk: string) => void;
+  /** True while the input queue is inside a bracketed paste (mid-paste chunks
+   *  carry no marker and must keep routing to the queue, not the noise path). */
+  pasteActive?: () => boolean;
+}
+
+/** Bracketed-paste markers (DECSET 2004): terminals wrap pasted text in these so
+ *  an app can treat the paste as DATA instead of keystrokes — the prompt_toolkit
+ *  paste contract. jeo enables the mode for the REPL TTY so a multi-line paste
+ *  arrives atomically and executes one command per line, in order. */
+export const PASTE_START = "\u001b[200~";
+export const PASTE_END = "\u001b[201~";
+
+/** True when a stdin chunk is ONLY backspace bytes (DEL 0x7f or BS 0x08) — i.e. a
+ *  standalone Backspace keystroke with nothing else. A backspace on an EMPTY input
+ *  line is a no-op edit, but some Bun readline builds turn it into a spurious `close`
+ *  event, which the REPL would treat as a hard exit ("Backspace quits jeo"). The
+ *  input filter swallows these when the line buffer is already empty so the byte never
+ *  reaches readline and the close can't fire. */
+export function isStandaloneBackspace(chunk: string): boolean {
+  return chunk.length > 0 && /^[\x7f\b]+$/.test(chunk);
+}
+
+/**
+ * macOS / fixterms combo-key normalization for the boxed prompt's line editor.
+ *
+ * Bun's readline acts on Ctrl+arrow (CSI `1;5D`/`1;5C` → word jump), Home/End, and the
+ * Emacs control bytes (Ctrl+A/E/W/U/K, Meta+b/f/d, Meta+DEL) — but it does NOT act on
+ * the modifier-flagged cursor keys macOS users reach for most: Option+Left/Right (word
+ * jump, CSI `1;3D`/`1;3C`) and Cmd+Left/Right (line start/end, CSI `1;9D`/`1;9C`) are
+ * inert. Rather than racing readline for cursor state in a keypress handler, we rewrite
+ * each inert combo to the canonical control byte readline DOES act on, BEFORE it reaches
+ * readline. readline stays the single owner of `rl.line`/`rl.cursor`; the box just reads
+ * and repaints. Replacement targets are empirically verified against Bun's readline.
+ *
+ * Modifier digit in `CSI 1;<m><dir>`: 3=Alt/Option, 5=Ctrl (already handled), 9=Cmd/Super.
+ * Both the CSI form and the ESC-prefixed alt-as-meta form (`ESC ESC [ D`) are covered. */
+export const CURSOR_COMBO_REWRITES: ReadonlyArray<readonly [string, string]> = [
+  ["\u001b[1;3D", "\u001bb"],     // Option+Left   → word left
+  ["\u001b[1;3C", "\u001bf"],     // Option+Right  → word right
+  ["\u001b\u001b[D", "\u001bb"],  // Option+Left   (ESC-prefixed alt-as-meta)
+  ["\u001b\u001b[C", "\u001bf"],  // Option+Right  (ESC-prefixed alt-as-meta)
+  ["\u001b[1;9D", "\u0001"],      // Cmd+Left      → line start (Ctrl+A)
+  ["\u001b[1;9C", "\u0005"],      // Cmd+Right     → line end   (Ctrl+E)
+  ["\u001b[127;3u", "\u0017"],    // Option+Backspace (kitty CSI-u) → delete word left (Ctrl+W)
+  ["\u001b[127;9u", "\u0015"],    // Cmd+Backspace    (kitty CSI-u) → delete to line start (Ctrl+U)
+  ["\u001b[3;3~", "\u001bd"],     // Option+Delete (forward) → delete word right (Meta+d)
+];
+
+/** First combo-key rewrite whose source sequence begins at `data[i]`, else undefined. */
+export function matchCursorCombo(data: string, i: number): readonly [string, string] | undefined {
+  for (const pair of CURSOR_COMBO_REWRITES) if (data.startsWith(pair[0], i)) return pair;
+  return undefined;
+}
+
+/** Apply combo-key rewrites across a plain (non-paste) input segment. Shares
+ *  `matchCursorCombo` with the live input filter, so the filter and this exported
+ *  helper can never diverge. */
+export function rewriteCursorCombos(plain: string): string {
+  let out = "";
+  let i = 0;
+  while (i < plain.length) {
+    const combo = matchCursorCombo(plain, i);
+    if (combo) { out += combo[1]; i += combo[0].length; continue; }
+    out += plain[i];
+    i += 1;
+  }
+  return out;
+}
+
+export interface PromptInputQueue {
+  pendingLines: string[];
+  partial: string;
+  /** Complete lines that arrived inside a bracketed PASTE: intentional batch
+   *  commands, served one per prompt in order. Never folded into the typed-line
+   *  prefill (that contract is for keystrokes typed during a live turn). */
+  pastedLines: string[];
+  /** True while a bracketed paste spans chunks (between \x1b[200~ and \x1b[201~). */
+  inPaste: boolean;
+}
+
+/** Typed (non-paste) keystrokes: printable chars build the partial, Enter promotes
+ *  it to pendingLines, backspace edits — ESC/ctrl noise segments are rejected. */
+function feedTypedSegment(state: PromptInputQueue, segment: string): boolean {
+  if (!segment || segment.includes("\u001b") || segment.includes("\u0003")) return false;
+  let accepted = false;
+  const normalized = segment.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  for (const ch of Array.from(normalized)) {
+    if (ch === "\n") {
+      if (state.partial.length > 0) accepted = true;
+      state.pendingLines.push(state.partial);
+      state.partial = "";
+    } else if (ch === "\u007f" || ch === "\b") {
+      const chars = Array.from(state.partial);
+      chars.pop();
+      state.partial = chars.join("");
+      accepted = true;
+    } else if (ch === "\t" || ch >= " ") {
+      state.partial += ch;
+      accepted = true;
+    }
+  }
+  return accepted;
+}
+
+/** Pasted body: pure DATA — newlines split commands into pastedLines, the trailing
+ *  partial stays editable, and control bytes (incl. any stray ESC from copied ANSI
+ *  text) are dropped instead of being interpreted as keystrokes. */
+function feedPasteBody(state: PromptInputQueue, body: string): boolean {
+  if (!body) return false;
+  let accepted = false;
+  const normalized = body.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  for (const ch of Array.from(normalized)) {
+    if (ch === "\n") {
+      state.pastedLines.push(state.partial);
+      state.partial = "";
+      accepted = true;
+    } else if (ch === "\t" || ch >= " ") {
+      state.partial += ch;
+      accepted = true;
+    }
+  }
+  return accepted;
+}
+
+export function queuePromptInputChunk(state: PromptInputQueue, chunk: string): boolean {
+  if (!chunk) return false;
+  let accepted = false;
+  let rest = chunk;
+  while (rest.length > 0) {
+    if (state.inPaste) {
+      const end = rest.indexOf(PASTE_END);
+      const body = end === -1 ? rest : rest.slice(0, end);
+      if (end !== -1) state.inPaste = false;
+      rest = end === -1 ? "" : rest.slice(end + PASTE_END.length);
+      if (feedPasteBody(state, body)) accepted = true;
+    } else {
+      const start = rest.indexOf(PASTE_START);
+      const plain = start === -1 ? rest : rest.slice(0, start);
+      if (start !== -1) state.inPaste = true;
+      rest = start === -1 ? "" : rest.slice(start + PASTE_START.length);
+      if (feedTypedSegment(state, plain)) accepted = true;
+    }
+  }
+  return accepted;
+}
+
+/** Live-turn prompt capture: printable input edits the SAME next-prompt line the
+ * idle footer will show after the turn finishes. Enter does NOT promote a hidden
+ * queue entry; it merely marks the current line as ready, so the existing input
+ * box stays the single source of truth and the user presses Enter once more at
+ * the real prompt to run it. */
+function feedLivePromptSegment(state: PromptInputQueue, segment: string): boolean {
+  if (!segment || segment.includes("\u001b") || segment.includes("\u0003")) return false;
+  let accepted = false;
+  const normalized = segment.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  for (const ch of Array.from(normalized)) {
+    if (ch === "\n") {
+      accepted = true;
+    } else if (ch === "\u007f" || ch === "\b") {
+      const chars = Array.from(state.partial);
+      chars.pop();
+      state.partial = chars.join("");
+      accepted = true;
+    } else if (ch === "\t" || ch >= " ") {
+      state.partial += ch;
+      accepted = true;
+    }
+  }
+  return accepted;
+}
+
+function feedLivePromptPasteBody(state: PromptInputQueue, body: string): boolean {
+  if (!body) return false;
+  const normalized = body.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const flattened = normalized.split("\n").map(part => part.trim()).filter(Boolean).join(" ");
+  if (!flattened) return false;
+  state.partial = state.partial ? `${state.partial} ${flattened}` : flattened;
+  return true;
+}
+
+export function captureLivePromptInputChunk(state: PromptInputQueue, chunk: string): boolean {
+  if (!chunk) return false;
+  let accepted = false;
+  let rest = chunk;
+  while (rest.length > 0) {
+    if (state.inPaste) {
+      const end = rest.indexOf(PASTE_END);
+      const body = end === -1 ? rest : rest.slice(0, end);
+      if (end !== -1) state.inPaste = false;
+      rest = end === -1 ? "" : rest.slice(end + PASTE_END.length);
+      if (feedLivePromptPasteBody(state, body)) accepted = true;
+    } else {
+      const start = rest.indexOf(PASTE_START);
+      const plain = start === -1 ? rest : rest.slice(0, start);
+      if (start !== -1) state.inPaste = true;
+      rest = start === -1 ? "" : rest.slice(start + PASTE_START.length);
+      if (feedLivePromptSegment(state, plain)) accepted = true;
+    }
+  }
+  return accepted;
+}
+
+/**
+ * TTY "new input first" contract: fold any queued FULL lines (stray
+ * Enter-terminated buffer noise, or older persisted queues) into the editable
+ * prompt prefill instead of leaving them to auto-execute as the next prompt.
+ * Without this, stale queued lines ran BEFORE the user's fresh input — jeo
+ * appeared to "continue the previous work first". Returns the number of lines
+ * folded. Pure over the queue object — piped/non-TTY callers must NOT use this
+ * (scripted stdin relies on in-order line execution).
+ */
+export function restoreQueuedLinesToPrefill(state: PromptInputQueue): number {
+  const lines = state.pendingLines.splice(0, state.pendingLines.length).map(l => l.trim()).filter(Boolean);
+  if (lines.length === 0) return 0;
+  const restored = lines.join(" ");
+  state.partial = state.partial ? `${restored} ${state.partial}`.trim() : restored;
+  return lines.length;
+}
+
+export function createInFlightAbortHarness(opts: AbortHarnessOptions = {}): InFlightAbortHarness {
+  const controller = opts.controller ?? new AbortController();
+  const stdin = opts.stdin ?? process.stdin;
+  const captureEsc = opts.captureEsc === true && !!stdin.isTTY;
+  const wasRaw = !!stdin.isRaw;
+  let rawChanged = false;
+
+  const abortNow = (message: string) => {
+    if (controller.signal.aborted) return false;
+    opts.onAbortNotice?.(message);
+    controller.abort();
+    return true;
+  };
+
+  const handleSigint = () => {
+    if (!controller.signal.aborted) controller.abort();
+    opts.onHardExit?.();
+  };
+
+  const handleData = (chunk: string | Uint8Array) => {
+    if (!captureEsc || controller.signal.aborted) return;
+    const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    if (text.includes(PASTE_START) || opts.pasteActive?.()) {
+      opts.onBufferedInput?.(text);
+      return;
+    }
+    if (text === "\u000f") {
+      opts.onDetailKey?.();
+      return;
+    }
+    if (text === "\u001b[A") { opts.onScrollKey?.(-1, false); return; }
+    if (text === "\u001b[B") { opts.onScrollKey?.(1, false); return; }
+    if (text === "\u001b[5~") { opts.onScrollKey?.(-1, true); return; }
+    if (text === "\u001b[6~") { opts.onScrollKey?.(1, true); return; }
+    const escAt = text.indexOf("\u001b");
+    const sigintAt = text.indexOf("\u0003");
+    const controlAt =
+      escAt === -1 ? sigintAt :
+      sigintAt === -1 ? escAt :
+      Math.min(escAt, sigintAt);
+    if (controlAt >= 0) {
+      const printablePrefix = text.slice(0, controlAt);
+      if (printablePrefix) opts.onBufferedInput?.(printablePrefix);
+      if (text[controlAt] === "\u0003") {
+        handleSigint();
+        return;
+      }
+      if (text === "\u001b") {
+        abortNow("ESC pressed — cancelling current run…");
+        return;
+      }
+      opts.onNoise?.();
+      return;
+    }
+    opts.onBufferedInput?.(text);
+  };
+
+  process.on("SIGINT", handleSigint);
+  if (captureEsc) {
+    stdin.on("data", handleData);
+    if (stdin.setRawMode && !wasRaw) {
+      stdin.setRawMode(true);
+      rawChanged = true;
+    }
+    stdin.resume?.();
+  }
+
+  return {
+    controller,
+    handleSigint,
+    handleData,
+    dispose() {
+      process.removeListener("SIGINT", handleSigint);
+      if (captureEsc) {
+        stdin.off("data", handleData);
+        if (rawChanged) stdin.setRawMode?.(false);
+      }
+    },
+  };
+}

package/src/commands/launch/stream.ts

@@ -0,0 +1,102 @@
+import chalk from "chalk";
+import { type AgentLoopEvents } from "../../agent/engine";
+import { type TaskSubEvent } from "../../agent/task-tool";
+import { categoryBadge } from "../../tui/components/category-index";
+import { summarizeForgeInvocation } from "../../tui/components/forge";
+import { formatDuration, formatUsage } from "../../tui/components/duration";
+import { LaunchTui } from "../../tui/app";
+
+const GATED_OUTPUT_METHODS = new Set(["write", "cursorTo", "moveCursor", "clearLine", "clearScreenDown", "_write", "_writev"]);
+export function gatedStdout(real: NodeJS.WriteStream, gated: () => boolean): NodeJS.WriteStream {
+  return new Proxy(real, {
+    get(target, prop, _receiver) {
+      if (typeof prop === "string" && GATED_OUTPUT_METHODS.has(prop)) {
+        return (...args: any[]) => {
+          if (gated()) {
+            const cb = args[args.length - 1]; // honor readline's write callback so it never stalls
+            if (typeof cb === "function") cb();
+            return true;
+          }
+          return (target as any)[prop](...args);
+        };
+      }
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  }) as unknown as NodeJS.WriteStream;
+}
+
+function firstOutputLine(output: string | undefined): string {
+  if (!output) return "";
+  const line = String(output)
+    .split("\n")
+    .map(l => l.trim())
+    .find(l => l.length > 0);
+  return line ? line.replace(/\s+/g, " ").slice(0, 140) : "";
+}
+
+function streamResultSuffix(tool: string, ok: boolean, output: string | undefined): string {
+  const summary = firstOutputLine(output);
+  if (!summary) return "";
+  if (!ok || tool === "task") return ` — ${summary}`;
+  return "";
+}
+
+export function formatTaskSubEvent(e: TaskSubEvent): string {
+  const role = e.role || "subagent";
+  const roleLabel = e.index && e.total ? `${role.toUpperCase()}[${e.index}/${e.total}]` : role.toUpperCase();
+  const tokTag = e.tokens ? ` (${e.tokens.input + e.tokens.output} tok)` : "";
+  const detail = firstOutputLine(e.detail);
+  const summary = e.summary ? ` — ${e.summary}` : "";
+  const badge = categoryBadge("subagent");
+  if (e.kind === "start") return `${badge} ${chalk.magenta(`▸ ${roleLabel}`)} · ${detail}`.slice(0, 240);
+  if (e.kind === "step") return `  ${badge} ${chalk.cyan(`├─ ${roleLabel}`)} · ${detail || "working"}`;
+  if (e.kind === "tool") return `  ${badge} ${e.success === false ? chalk.red("├─") : chalk.green("├─")} ${roleLabel} ${e.success === false ? chalk.red("✗") : chalk.green("✓")} ${detail || "tool"}${summary}`;
+  if (e.kind === "error") return `  ${badge} ${chalk.red("├─")} ${roleLabel} ${chalk.red("✗")} ${detail || "error"}`;
+  return `${badge} ${e.success === false ? chalk.red("└─") : chalk.green("└─")} ${roleLabel} done${tokTag}${e.success === false ? " (incomplete)" : ""}${detail ? `: ${detail}` : ""}`;
+}
+
+export function logTaskSubEvent(e: TaskSubEvent, log: (line: string) => void = (s: string) => console.log(s)): void {
+  log(formatTaskSubEvent(e));
+}
+
+export function createStreamEvents(
+  _maxSteps: number,
+  log: (line: string) => void = (s: string) => console.log(s),
+  now: () => number = Date.now,
+): AgentLoopEvents {
+  let pending = "";
+  let latestUsage: { inputTokens: number; outputTokens: number } | undefined;
+  const startTime = now();
+
+  return {
+    onStep: () => {},
+    onAssistant: (_raw: string, invocation: { tool?: string; arguments?: unknown } | null) => {
+      const tool = typeof invocation?.tool === "string" ? invocation.tool.trim() : "";
+      if (!tool || tool === "done") return;
+      pending = summarizeForgeInvocation(tool, invocation?.arguments).title;
+      const elapsedMs = now() - startTime;
+      let suffix = "";
+      if (elapsedMs >= 1000) suffix += ` · ${formatDuration(elapsedMs)}`;
+      if (latestUsage) suffix += ` · ${formatUsage(latestUsage)}`;
+      log(`${categoryBadge("progress")} ${pending}${suffix ? chalk.dim(suffix) : ""}`);
+    },
+    onToolResult: (tool: string, ok: boolean, output?: string) => {
+      const label = pending || tool;
+      const mark = ok ? chalk.green("✓") : chalk.red("✗");
+      log(`  ${categoryBadge(ok ? "done" : "error")} ${mark} ${label}${streamResultSuffix(tool, ok, output)}`);
+      pending = "";
+    },
+    onNotice: (msg: string) => log(`  ${categoryBadge("progress")} ${chalk.yellow(msg)}`),
+    onBudget: (_limit: number, reason: string) => {
+      log(`  ${categoryBadge("progress")} ${chalk.yellow(reason)}`);
+    },
+    onUsage: (usage: { inputTokens: number; outputTokens: number }) => {
+      latestUsage = usage;
+    },
+  };
+}
+
+export function shouldUseOneShotTui(noTui: boolean): boolean {
+  return LaunchTui.usable(noTui);
+}

package/src/commands/launch/tmux.ts

@@ -0,0 +1,227 @@
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { type LaunchFlags } from "./flags";
+
+function hashString(input: string): string {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36).padStart(6, "0").slice(0, 6);
+}
+
+function tmuxSafeNamePart(input: string, max = 32): string {
+  const safe = input.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "") || "value";
+  if (safe.length <= max) return safe;
+  return `${safe.slice(0, Math.max(1, max - 7))}-${hashString(input)}`;
+}
+
+function tmuxRuntimeSuffix(flags: LaunchFlags): string {
+  const parts: string[] = [];
+  if (flags.provider) parts.push(`provider-${flags.provider}`);
+  if (flags.model) parts.push(`model-${tmuxSafeNamePart(flags.model)}`);
+  else if (flags.modelRole) parts.push(flags.modelRole);
+  if (flags.thinking) parts.push(`think-${flags.thinking}`);
+  // Only an EXPLICIT --max-steps cap names the session; the dynamic default (0) adds nothing.
+  if (flags.maxSteps > 0) parts.push(`steps-${flags.maxSteps}`);
+  if (parts.length === 0) return "";
+  const joined = parts.join("-");
+  const suffix = joined.length <= 72 ? joined : `${joined.slice(0, 65)}-${hashString(joined)}`;
+  return `-${suffix}`;
+}
+
+/**
+ * Base tmux session name for `jeo --tmux`. Keyed on the working DIRECTORY (not just the
+ * git branch) so two different projects/worktrees on the same branch (e.g. `main`)
+ * never share a base. {@link uniqueTmuxSessionName} then makes each concurrent invocation
+ * fully independent, so a second `jeo --tmux` never attaches to (and mirrors) the first.
+ */
+export function tmuxSessionName(cwd: string, branch: string, flags: LaunchFlags): string {
+  const dirTag = `${tmuxSafeNamePart(path.basename(cwd) || "root", 16)}-${hashString(cwd)}`;
+  const base = branch ? `jeo-${branch}-${dirTag}` : `jeo-${dirTag}`;
+  return base + tmuxRuntimeSuffix(flags);
+}
+
+/**
+ * Count uncommitted git entries for the `⑂ <branch> ?N` footer dirty flag (gjc parity).
+ * One `git status --porcelain` spawn per CALL; callers invoke it once per turn start, not
+ * per render. Returns undefined when not a repo / git absent / clean.
+ */
+export function gitDirtyCount(cwd: string): number | undefined {
+  try {
+    const res = Bun.spawnSync(["git", "status", "--porcelain"], { cwd, stdout: "pipe", stderr: "ignore" });
+    if (res.exitCode !== 0) return undefined;
+    const n = res.stdout.toString().split("\n").filter(l => l.trim().length > 0).length;
+    return n || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Allocate + create an INDEPENDENT tmux session from a base name. Each separate,
+ * concurrent `jeo --tmux` invocation gets its OWN session instead of attaching to (and
+ * mirroring) one another process already created: try `base`, then `base-2`, `base-3`, …
+ * The create itself is the guard, so this is race-safe — two processes starting at the
+ * same instant can't both win `base`. `tryCreate` must attempt to create the named session
+ * and return `"ok"` (created — it's ours), `"taken"` (name already live / lost the race →
+ * try the next suffix), or `"error:<msg>"` (a real failure → abort). Sessions die with
+ * their jeo process, so a sequential re-run reuses the clean base; only live overlap is
+ * suffixed.
+ */
+export type TmuxCreateResult = "ok" | "taken" | `error:${string}`;
+export function allocateTmuxSession(
+  base: string,
+  tryCreate: (name: string) => TmuxCreateResult,
+): { name: string } | { error: string } {
+  for (let n = 1; n <= 1000; n++) {
+    const candidate = n === 1 ? base : `${base}-${n}`;
+    const result = tryCreate(candidate);
+    if (result === "ok") return { name: candidate };
+    if (result === "taken") continue;
+    return { error: result.slice("error:".length) };
+  }
+  return { error: `could not allocate a free tmux session name for ${base} (1000 already live?)` };
+}
+export function shellQuote(arg: string): string {
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+
+
+
+
+/**
+ * True when `jeo --tmux` runs INSIDE an existing tmux session and should enable
+ * session-scoped mouse mode for the CURRENT session: no jeo-owned session is created
+ * on this path, so without `mouse on` tmux ignores the wheel entirely and the
+ * mid-turn scrollback (ledger lines flushed above the live frame) is unreachable.
+ * Skipped for jeo-spawned sessions (JEO_TMUX_LAUNCHED=1 — the creator already set
+ * it) and when JEO_TMUX_MOUSE=0 opts out.
+ */
+export function shouldEnableCurrentTmuxMouse(env: Record<string, string | undefined>): boolean {
+  return !!env.TMUX
+    && (env.JEO_TMUX_LAUNCHED ?? env.JEO_TMUX_LAUNCHED) !== "1"
+    && (env.JEO_TMUX_MOUSE ?? env.JEO_TMUX_MOUSE) !== "0";
+}
+
+/**
+ * The runnable command for the INNER `jeo launch` a `--tmux` session executes.
+ * Pure — testable. Three runtime shapes:
+ *  - compiled standalone binary: `argv[1]` is a Bun VIRTUAL path (`/$bunfs/…`)
+ *    that does not exist on disk; the binary itself (`execPath`) is the
+ *    entrypoint. Passing the virtual path made the inner command crash on
+ *    spawn, so `tmux new-session` died instantly and the follow-up attach
+ *    failed with "can't find session".
+ *  - source run (`bun src/cli.ts`): re-run the script through the runtime.
+ *  - anything else (a shim/binary path on disk): run it directly.
+ */
+export function tmuxLaunchCommand(argv1: string | undefined, execPath: string, cwd: string): string[] {
+  const entrypoint = argv1 ?? "";
+  if (entrypoint === "" || entrypoint.startsWith("/$bunfs/") || entrypoint.startsWith("B:\\~BUN\\")) {
+    return [execPath];
+  }
+  const resolved = path.isAbsolute(entrypoint) ? entrypoint : path.resolve(cwd, entrypoint);
+  if (/\.(ts|js|mjs)$/.test(entrypoint)) return [execPath, resolved];
+  return [resolved];
+}
+
+/** One tmux configuration step applied to a jeo-owned session after creation. */
+export interface TmuxProfileCommand {
+  description: string;
+  args: string[];
+}
+
+/**
+ * gjc-parity tmux profile for jeo-OWNED sessions (mirrors gjc's
+ * `buildGjcTmuxProfileCommands`). Applied right after `new-session`, before attach:
+ *  - `mouse on` (session-scoped): wheel-up enters copy-mode over the REAL pane
+ *    history — this is what makes the mid-turn scrollback (ledger lines flushed
+ *    above the inline live frame) reachable with the mouse wheel. Wheel-down at
+ *    the bottom drops back out. `JEO_TMUX_MOUSE=0` opts out.
+ *  - ownership/identity markers (`@jeo-profile`, `@jeo-branch`, `@jeo-project`):
+ *    lets tooling tell jeo-owned sessions apart from user sessions (gjc parity
+ *    with `@gjc-*`). Never applied to foreign sessions.
+ *  - `set-clipboard on` + a readable copy-mode `mode-style`: text selected while
+ *    wheel-scrolled back is visibly highlighted and lands on the system clipboard
+ *    (OSC52). `JEO_TMUX_PROFILE=0` opts out of these cosmetic extras while keeping
+ *    mouse + markers.
+ */
+export function tmuxProfileCommands(
+  target: string,
+  env: Record<string, string | undefined>,
+  meta: { branch?: string; project?: string } = {},
+): TmuxProfileCommand[] {
+  const t = `=${target}:`;
+  const commands: TmuxProfileCommand[] = [];
+  if ((env.JEO_TMUX_MOUSE ?? env.JEO_TMUX_MOUSE) !== "0") {
+    commands.push({
+      description: "enable tmux mouse scrolling (wheel-up → copy-mode over real history)",
+      args: ["set-option", "-t", t, "mouse", "on"],
+    });
+  }
+  commands.push({
+    description: "mark jeo tmux ownership",
+    args: ["set-option", "-t", t, "@jeo-profile", "1"],
+  });
+  if (meta.branch) {
+    commands.push({
+      description: "record jeo branch identity",
+      args: ["set-option", "-t", t, "@jeo-branch", meta.branch],
+    });
+  }
+  if (meta.project) {
+    commands.push({
+      description: "record jeo project identity",
+      args: ["set-option", "-t", t, "@jeo-project", meta.project],
+    });
+  }
+  if ((env.JEO_TMUX_PROFILE ?? env.JEO_TMUX_PROFILE) !== "0") {
+    commands.push(
+      {
+        description: "enable tmux clipboard integration",
+        args: ["set-option", "-t", t, "set-clipboard", "on"],
+      },
+      {
+        description: "make copy-mode selection readable",
+        args: ["set-window-option", "-t", t, "mode-style", "fg=colour231,bg=colour60"],
+      },
+    );
+  }
+  return commands;
+}
+
+/**
+ * Resolve a git worktree path (gjc `--worktree <path>` parity). If the path
+ * already exists it is reused as-is; otherwise a new worktree is created on a
+ * branch derived from the path basename. Returns the absolute worktree path.
+ */
+export function resolveWorktree(cwd: string, wt: string): string {
+  const abs = path.isAbsolute(wt) ? wt : path.resolve(cwd, wt);
+  if (fs.existsSync(abs)) return abs;
+  if (!Bun.which("git")) {
+    console.error("error: --worktree requires git on PATH");
+    process.exit(1);
+  }
+  const branch = (path.basename(abs).replace(/[^a-zA-Z0-9_-]/g, "-") || "jeo-wt");
+  const withBranch = Bun.spawnSync(["git", "worktree", "add", "-b", branch, abs], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (withBranch.exitCode !== 0) {
+    // Branch may already exist; retry attaching the existing branch.
+    const plain = Bun.spawnSync(["git", "worktree", "add", abs], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (plain.exitCode !== 0) {
+      console.error(
+        `error: failed to create git worktree at ${abs}: ${withBranch.stderr.toString().trim()}`,
+      );
+      process.exit(1);
+    }
+  }
+  return abs;
+}

package/src/commands/launch/workflow.ts

@@ -0,0 +1,26 @@
+import { runDeepInterviewEngine, type DeepInterviewEngineOptions } from "../deep-interview";
+import { runRalplanEngine, type RalplanEngineOptions } from "../ralplan";
+import { runTeamEngine, type TeamEngineOptions } from "../team";
+import { runUltragoalEngine, type UltragoalEngineOptions } from "../ultragoal";
+
+/** The bundled workflow skills that run through a dedicated engine (deep-interview /
+ *  ralplan / team / ultragoal), not the ordinary agent loop. Single source of truth —
+ *  the menu listing, the dispatch guards, and the engine switch all read from here. */
+export const WORKFLOW_NAMES = ["deep-interview", "ralplan", "team", "ultragoal"] as const;
+
+/** True when a skill name is one of the bundled workflow engines. */
+export function isWorkflowSkill(name: string): boolean {
+  return (WORKFLOW_NAMES as readonly string[]).includes(name);
+}
+
+/** Dispatch a bundled workflow by name to its engine. Keeps the name→engine mapping in
+ *  ONE place so the one-shot and interactive skill runners can't drift apart. */
+export function runWorkflowEngine(
+  name: string,
+  opts: DeepInterviewEngineOptions & RalplanEngineOptions & TeamEngineOptions & UltragoalEngineOptions,
+): Promise<{ ok: boolean; reason?: string }> {
+  if (name === "deep-interview") return runDeepInterviewEngine(opts);
+  if (name === "ralplan") return runRalplanEngine(opts);
+  if (name === "team") return runTeamEngine(opts);
+  return runUltragoalEngine(opts);
+}