@paradow/ledge 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# @paradow/ledge (WSL side)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Ledge daemon and CLI: follow and answer your WSL agent sessions (Claude Code, Codex, Cursor Agent) from the Ledge island on Windows. See the [repository README](https://github.com/Paradow-dev/ledge#readme) for the whole picture.
+
+## Install
+
+Node >= 22 is required.
+
+```sh
+npm i -g @paradow/ledge && ledge setup
+```
+
+## Update
+
+From the Ledge island: the card in the list updates the daemon, then the Windows app. By hand:
+
+```sh
+npm i -g @paradow/ledge@latest && systemctl --user restart ledge-daemon
+```
+
+A daemon started from a clone (see below) is not touched by the island's button.
+
+## Install for development
+
+Run from the repository root:
+
+```sh
+pnpm install
+pnpm --filter @paradow/ledge build
+chmod +x packages/ledge/dist/cli/index.js
+mkdir -p ~/.local/bin
+ln -sf "$PWD/packages/ledge/dist/cli/index.js" ~/.local/bin/ledge   # ~/.local/bin must be on the PATH Claude Code uses for hooks
+ledge setup
+```
+
+The daemon is spawned from the built CLI (`dist/cli/index.js`), so rebuild after changes (`pnpm --filter @paradow/ledge build`).
+
+## Use
+
+```sh
+ledge claude            # start Claude Code in a tracked tmux session (tab renamed to the bot)
+ledge claude --name max # pick the bot's name
+ledge status            # list bots and what they wait for
+ledge attach <id>       # put this terminal on a running session (what the overlay opens a tab with)
+ledge daemon            # run the daemon in the foreground (normally run by the systemd service)
+ledge uninstall         # undo ledge setup: hooks, service and the ~/.local/bin link (--purge: ~/.ledge too)
+```
+
+`ledge setup` installs `ledge-daemon.service` as a systemd user unit, starts it and enables linger, so the daemon runs from WSL boot and restarts after a crash. Rerun it after a node upgrade or a repository move: the unit is rewritten and the service restarted. Useful commands:
+
+```sh
+systemctl --user status ledge-daemon.service
+journalctl --user -u ledge-daemon.service -f
+systemctl --user restart ledge-daemon.service   # after pnpm --filter @paradow/ledge build
+systemctl --user disable --now ledge-daemon.service   # back to on-demand start by ledge claude
+```
+
+## Where things live
+
+```text
+~/.ledge/tmux.conf      dedicated tmux server config (status off, mouse on)
+~/.ledge/sessions.json  journal, reloaded when the daemon restarts
+~/.ledge/daemon.log     dropped hooks, failed injections, poll errors
+~/.ledge/chat.json      the day's chat conversation (date, session id)
+~/.ledge/chat/context/  files the chat reads (sessions.md, pane-*, reply-*, git-*)
+~/.ledge/daemon.pid     PID of the running daemon, removed when it stops cleanly
+~/.config/systemd/user/ledge-daemon.service   user unit written by `ledge setup`
+~/.ledge/exit-<id>      transient: the agent's exit code, written by the launcher's wrapper when the agent ends and read and deleted by `ledge claude`
+```
+
+## Ask Ledge (chat)
+
+The overlay's ask field sends a question to the daemon (`chat.ask`), which answers it with one headless, read-only run of the chosen harness (Settings › Default harness; Claude Code when omitted):
+
+```sh
+# Claude Code (default)
+claude -p --restricted --tools Read,Grep,Glob --permission-mode dontAsk --output-format stream-json --verbose --include-partial-messages --max-turns 16 --append-system-prompt <persona> --add-dir <each session folder> --session-id <id>   # --resume <id> for the next questions of the day
+
+# Codex
+codex exec --sandbox read-only --json --skip-git-repo-check --ignore-user-config -C <context> -c 'sandbox_permissions=["disk-full-read-access"]' -   # exec resume <id> … for the next questions
+
+# Cursor Agent
+cursor-agent -p --mode ask --output-format stream-json --stream-partial-output --sandbox enabled --trust --workspace <context> --add-dir <each session folder>   # --resume <id> for the next questions
+```
+
+The question goes on stdin, never in argv, and `LEDGE_CHAT=1` is set so Ledge's own hooks ignore the run. An inherited `ANTHROPIC_API_KEY` is dropped so Claude Code keeps its own login. `--restricted` ignores the user, project and local settings, so none of your hooks run and no setting can widen the tools. Only `Read`, `Grep` and `Glob` are allowed on Claude Code, and anything else is denied rather than asked. Codex runs in a read-only sandbox; Cursor Agent runs in ask mode.
+
+- `~/.ledge/chat/context/` is the folder the harness runs in, rewritten before each question: `sessions.md` (every session, its state and its file names), `pane-<id>.txt` (last terminal lines), `reply-<id>.md` (last reply), `git-<id>.txt` (status, log and diff stat). A source that fails or is empty is just left out. The folder is deleted when the turn ends.
+- `~/.ledge/chat.json` holds the day's conversation (its date, session id and which tool it belongs to); a new day, a `chat.reset`, or a change of harness starts a new conversation, and a question after a failed resume starts a new one too.
+- One question at a time; a turn that takes more than 180 s is stopped and the chat says it timed out (no retry). `chat.reset` is refused while a question is running.
+
+Session names and tab titles: Ledge sets `set-titles` in `~/.ledge/tmux.conf`. A tmux server that is already running re-reads `tmux.conf` only after it restarts, so `set-titles` applies to new tmux servers. The tab string is `${name} · ${topic ?? project}`; `session.rename` from the overlay updates it.
+
+## Tests
+
+```sh
+pnpm --filter @paradow/ledge test            # unit + tmux + end-to-end (needs tmux, no AI)
+pnpm --filter @paradow/ledge test state      # only the transition table
+```
+
+## Refreshing pane fixtures
+
+Run from `packages/ledge` (the output path is relative to it):
+
+```sh
+tmux -L ledge capture-pane -p -J -t ledge-<id> -S -30 > test/fixtures/panes/<name>.txt
+```

package/dist/cli/attach-YBGTDBQI.js

@@ -0,0 +1,53 @@
+import {
+  attachEnv
+} from "./chunk-Y44XZY6I.js";
+import {
+  realTmux
+} from "./chunk-7ICDC2LK.js";
+import "./chunk-OUIDBDIH.js";
+import "./chunk-6ZTCETRG.js";
+import {
+  connect
+} from "./chunk-W5XAZ5IS.js";
+import {
+  PROTOCOL_PORT
+} from "./chunk-6GMDFIGB.js";
+
+// src/cli/attach.ts
+import { spawn } from "child_process";
+var TMUX_SOCKET = "ledge";
+function attachInherit(args, env) {
+  return new Promise((resolve) => {
+    const child = spawn("tmux", args, { stdio: "inherit", env });
+    child.on("error", () => resolve(1));
+    child.on("exit", (c) => resolve(c ?? 1));
+  });
+}
+async function attach(id, opts = {}) {
+  if (!id) {
+    console.error("ledge attach: missing session id");
+    return 2;
+  }
+  const tmux = realTmux(opts.tmuxSocket ?? TMUX_SOCKET);
+  const tmuxName = `ledge-${id}`;
+  if (!await tmux.hasSession(tmuxName)) {
+    console.error(`ledge attach: no session ${id}`);
+    return 1;
+  }
+  let title = tmuxName;
+  try {
+    const c = await connect({ port: opts.port ?? PROTOCOL_PORT, timeoutMs: 800 });
+    const snap = await c.next("snapshot");
+    title = snap.sessions.find((s) => s.id === id)?.title ?? title;
+    await Promise.race([c.close(), new Promise((r) => setTimeout(r, 500))]);
+  } catch {
+  }
+  const write = opts.write ?? ((s) => {
+    if (process.stdout.isTTY) process.stdout.write(s);
+  });
+  write(`\x1B]0;${title}\x07`);
+  return (opts.attach ?? attachInherit)(tmux.attachArgs(tmuxName), attachEnv(process.env));
+}
+export {
+  attach
+};

package/dist/cli/chunk-6GMDFIGB.js

@@ -0,0 +1,306 @@
+// ../protocol/src/messages.ts
+import { z as z4 } from "zod";
+
+// ../protocol/src/session.ts
+import { z } from "zod";
+var ToolSchema = z.enum(["claude", "codex", "cursor"]);
+var SessionStateSchema = z.enum(["starting", "working", "waiting_input", "waiting_permission", "idle", "exited", "error"]);
+var PendingSchema = z.object({
+  kind: z.enum(["question", "permission", "plan", "diff"]),
+  text: z.string(),
+  tool: z.string().optional(),
+  options: z.array(z.string()).optional(),
+  source: z.enum(["hook", "pane"]),
+  /** Set when the request comes from a helper (subagent): it is routed through its parent. */
+  helperId: z.string().optional(),
+  /** For a helper-routed request: the state the parent returns to once it is answered (main thread may stop meanwhile). */
+  parentState: SessionStateSchema.optional()
+});
+var ReplySchema = z.object({
+  text: z.string(),
+  at: z.string().datetime()
+});
+var HelperSchema = z.object({
+  id: z.string(),
+  kind: z.string(),
+  task: z.string(),
+  state: SessionStateSchema
+});
+var TopicSourceSchema = z.enum(["user", "pane", "prompt"]);
+var SessionSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  tool: ToolSchema,
+  cwd: z.string(),
+  project: z.string(),
+  title: z.string(),
+  /** One line saying what the session is about (spec 2026-10-11 §3). */
+  topic: z.string().optional(),
+  topicSource: TopicSourceSchema.optional(),
+  /** The repository (its main worktree's folder name and absolute path), the checked-out branch, and whether `cwd` is a linked worktree (§4). */
+  repo: z.string().optional(),
+  repoPath: z.string().optional(),
+  branch: z.string().optional(),
+  worktree: z.boolean().optional(),
+  tmuxSession: z.string().nullable(),
+  state: SessionStateSchema,
+  pending: PendingSchema.optional(),
+  helpers: z.array(HelperSchema).default([]),
+  lastReply: ReplySchema.optional(),
+  startedAt: z.string().datetime(),
+  lastActivityAt: z.string().datetime(),
+  lastHookAt: z.string().datetime().optional(),
+  exitCode: z.number().int().nullable().optional(),
+  exitedAt: z.string().datetime().optional(),
+  lastError: z.string().optional(),
+  source: z.enum(["launcher", "hook_only"])
+});
+
+// ../protocol/src/chat.ts
+import { z as z2 } from "zod";
+var ChatStepSchema = z2.object({
+  kind: z2.enum(["sessions", "pane", "reply", "git", "repo"]),
+  id: z2.string().optional(),
+  name: z2.string().optional(),
+  path: z2.string().optional()
+});
+var ChatTurnSchema = z2.object({
+  qid: z2.string().min(1),
+  question: z2.string(),
+  askedAt: z2.string().datetime(),
+  steps: z2.array(ChatStepSchema),
+  answer: z2.string().optional(),
+  answeredAt: z2.string().datetime().optional(),
+  error: z2.string().optional()
+});
+
+// ../protocol/src/documents.ts
+import { z as z3 } from "zod";
+var DOCUMENT_MAX_BYTES = 1048576;
+var path = z3.string().min(1).max(4096);
+var requestId = z3.string().min(1);
+var DocumentReadSchema = z3.object({
+  type: z3.literal("document.read"),
+  requestId,
+  path,
+  sessionId: z3.string().min(1).optional(),
+  basePath: path.optional()
+});
+var DocumentContentSchema = z3.object({
+  type: z3.literal("document.content"),
+  requestId,
+  path,
+  text: z3.string(),
+  bytes: z3.number().int().nonnegative(),
+  modifiedAt: z3.string().datetime()
+});
+var DocumentErrorCodeSchema = z3.enum([
+  "not_found",
+  "not_file",
+  "unsupported_path",
+  "unsupported_type",
+  "permission_denied",
+  "too_large",
+  "invalid_utf8",
+  "ambiguous_path",
+  "session_missing",
+  "read_failed"
+]);
+var DocumentErrorSchema = z3.object({
+  type: z3.literal("document.error"),
+  requestId,
+  path,
+  code: DocumentErrorCodeSchema
+});
+
+// ../protocol/src/messages.ts
+var PROTOCOL_PORT = 47831;
+var SessionEventSchema = z4.object({
+  name: z4.enum(["SessionStart", "UserPromptSubmit", "PreToolUse", "PermissionRequest", "Notification", "Stop", "SessionEnd", "PaneChanged", "PaneGone", "PanePrompt", "PaneIdle", "InjectFailed", "Decided", "PostToolUse", "PostToolUseFailure", "StopFailure", "SubagentStart", "SubagentStop", "PaneTitle", "Renamed"]),
+  at: z4.string().datetime(),
+  source: z4.enum(["hook", "pane", "daemon"]),
+  tool: z4.string().optional(),
+  text: z4.string().optional(),
+  options: z4.array(z4.string()).optional(),
+  kind: z4.enum(["question", "permission", "plan", "diff"]).optional(),
+  exitCode: z4.number().int().nullable().optional(),
+  helperId: z4.string().optional(),
+  /** The helper's description, once known (Claude Code: its `.meta.json`, written after SubagentStart). */
+  task: z4.string().optional(),
+  /** PostToolUseFailure: the user interrupted the turn (Esc); Claude then waits for input with no Stop. */
+  interrupt: z4.boolean().optional()
+});
+var RecentSchema = z4.object({ cwd: z4.string().min(1), project: z4.string().min(1), lastAt: z4.string().datetime() });
+var SEMVER = /^\d+\.\d+\.\d+$/;
+var DaemonInfoSchema = z4.object({ version: z4.string(), install: z4.enum(["npm", "git", "unknown"]), systemd: z4.boolean(), manual: z4.string().optional() });
+var UpdateFailureSchema = z4.enum(["git-install", "no-systemd", "sessions-at-risk", "npm-failed", "busy"]);
+var ServerMessageSchema = z4.discriminatedUnion("type", [
+  DocumentContentSchema,
+  DocumentErrorSchema,
+  /** `recents`: the folders of past sessions, most recent first. `launcher`: the command that runs `ledge` inside WSL
+   *  (`[node, cli]`), so the overlay can attach a terminal to a session with `<launcher> attach <id>`. `daemon`: absent
+   *  from daemons older than the auto-update. */
+  z4.object({ type: z4.literal("snapshot"), sessions: z4.array(SessionSchema), recents: z4.array(RecentSchema).optional(), launcher: z4.array(z4.string()).optional(), daemon: DaemonInfoSchema.optional() }),
+  z4.object({ type: z4.literal("session.updated"), session: SessionSchema }),
+  z4.object({ type: z4.literal("session.removed"), id: z4.string() }),
+  z4.object({ type: z4.literal("session.preview"), id: z4.string(), lines: z4.array(z4.string()) }),
+  /** Answer to the requester of a `session.launch`: the session exists (its `session.updated` is broadcast as usual). */
+  z4.object({ type: z4.literal("session.launched"), id: z4.string() }),
+  z4.object({ type: z4.literal("recents"), recents: z4.array(RecentSchema) }),
+  /** Answer to the requester of a `folder.list` or `folder.create`: `path` resolved (`~` expanded), `parent` null at the
+   *  root, `entries` its subfolders by name (hidden ones left out). A failure keeps the asked path and says why in `error`,
+   *  never in an `error` message, which the launch form reads as a failed launch. */
+  z4.object({ type: z4.literal("folder.listing"), path: z4.string(), parent: z4.string().nullable(), entries: z4.array(z4.string()), error: z4.string().optional() }),
+  /** The chat (spec 2026-10-11 §5): what Ledge reads, its words as they come, the final text, or why it stopped; the day's turns after each snapshot. */
+  z4.object({ type: z4.literal("chat.step"), qid: z4.string(), step: ChatStepSchema }),
+  z4.object({ type: z4.literal("chat.delta"), qid: z4.string(), text: z4.string() }),
+  z4.object({ type: z4.literal("chat.done"), qid: z4.string(), text: z4.string(), at: z4.string().datetime() }),
+  z4.object({ type: z4.literal("chat.error"), qid: z4.string(), message: z4.string() }),
+  z4.object({ type: z4.literal("chat.history"), turns: z4.array(ChatTurnSchema) }),
+  /** The daemon updating itself: npm is running, then the service restarts (the socket closes right after). */
+  z4.object({ type: z4.literal("update.progress"), version: z4.string(), step: z4.enum(["installing", "restarting"]) }),
+  /** Nothing was changed. `detail`: the useful end of npm's output; `command`: what the person can run instead. */
+  z4.object({ type: z4.literal("update.failed"), version: z4.string(), reason: UpdateFailureSchema, detail: z4.string().optional(), command: z4.string().optional() }),
+  z4.object({ type: z4.literal("error"), message: z4.string(), id: z4.string().optional() })
+]);
+var ClientMessageSchema = z4.discriminatedUnion("type", [
+  DocumentReadSchema,
+  /** The overlay starts a session: `cwd` is a WSL path (`~` allowed), `name` a preferred bot name (the daemon picks a
+   *  free one otherwise), `prompt` the agent's first instruction, `continue` resumes the folder's last conversation. */
+  z4.object({ type: z4.literal("session.launch"), tool: ToolSchema, cwd: z4.string().min(1), name: z4.string().optional(), prompt: z4.string().optional(), continue: z4.boolean().optional() }),
+  /** The launch form's folder browser: list a folder's subfolders (home when no `path`), or make `name` inside `parent`
+   *  and list it. Both are answered with a `folder.listing`. */
+  z4.object({ type: z4.literal("folder.list"), path: z4.string().optional() }),
+  z4.object({ type: z4.literal("folder.create"), parent: z4.string().min(1), name: z4.string().min(1) }),
+  z4.object({ type: z4.literal("session.reply"), id: z4.string(), text: z4.string().min(1) }),
+  z4.object({ type: z4.literal("session.decide"), id: z4.string(), decision: z4.enum(["accept", "deny"]) }),
+  z4.object({ type: z4.literal("session.focus"), id: z4.string() }),
+  z4.object({ type: z4.literal("session.kill"), id: z4.string() }),
+  z4.object({ type: z4.literal("session.interrupt"), id: z4.string() }),
+  /** Removes a finished (exited) or read-only (hook_only) session from the list; refused for a live launcher session. */
+  z4.object({ type: z4.literal("session.dismiss"), id: z4.string() }),
+  /** The user names the session's topic from the overlay (500 characters at most, the hook's prompt cap); an empty topic hands back to the automatic sources. */
+  z4.object({ type: z4.literal("session.rename"), id: z4.string(), topic: z4.string().max(500) }),
+  z4.object({ type: z4.literal("session.register"), session: SessionSchema }),
+  /** `agent` and `cwd` describe the session when the daemon does not know it yet (a hook from an agent started without ledge). */
+  z4.object({ type: z4.literal("session.event"), id: z4.string(), event: SessionEventSchema, agent: ToolSchema.optional(), cwd: z4.string().optional() }),
+  z4.object({ type: z4.literal("session.unregister"), id: z4.string(), exitCode: z4.number().int().nullable() }),
+  z4.object({ type: z4.literal("snapshot.request") }),
+  z4.object({ type: z4.literal("chat.ask"), qid: z4.string().min(1), text: z4.string().min(1), tool: ToolSchema.optional() }),
+  z4.object({ type: z4.literal("chat.cancel"), qid: z4.string().min(1) }),
+  /** Starts a new conversation with Ledge: the day's turns are cleared and the next question opens a new harness session. */
+  z4.object({ type: z4.literal("chat.reset") }),
+  /** Installs `@paradow/ledge@version` and restarts the service (spec 2026-10-12 auto-update §6). */
+  z4.object({ type: z4.literal("update.daemon"), version: z4.string().regex(SEMVER) })
+]);
+function parseClientMessage(raw) {
+  return ClientMessageSchema.parse(raw);
+}
+function parseServerMessage(raw) {
+  return ServerMessageSchema.parse(raw);
+}
+
+// ../protocol/src/names.ts
+var NAMES = [
+  "Otto",
+  "Pim",
+  "Nova",
+  "Bix",
+  "Lu",
+  "Max",
+  "Ida",
+  "Rex",
+  "Zoe",
+  "Kit",
+  "Ari",
+  "Bo",
+  "Cal",
+  "Dee",
+  "Eli",
+  "Fay",
+  "Gus",
+  "Hal",
+  "Ivy",
+  "Jax",
+  "Kai",
+  "Lio",
+  "Mo",
+  "Nia",
+  "Oz",
+  "Pax",
+  "Quin",
+  "Rae",
+  "Sol",
+  "Tad",
+  "Uma",
+  "Vic",
+  "Wyn",
+  "Xen",
+  "Yan",
+  "Zia",
+  "Abe",
+  "Bea",
+  "Cy",
+  "Dot",
+  "Eva",
+  "Fin",
+  "Gil",
+  "Hen",
+  "Iro",
+  "Jo",
+  "Kip",
+  "Lex",
+  "Mia",
+  "Ned",
+  "Ola",
+  "Pat",
+  "Rio",
+  "Sam",
+  "Tia",
+  "Ulf",
+  "Val",
+  "Wes",
+  "Yui",
+  "Zed",
+  "Ash",
+  "Bry",
+  "Cleo",
+  "Dax"
+];
+var cap = (s) => s.charAt(0).toUpperCase() + s.slice(1).toLowerCase();
+function pickName(taken, preferred) {
+  const used = new Set(taken);
+  const free = (n) => !used.has(n);
+  const wanted = preferred?.trim();
+  if (wanted) {
+    const base = cap(wanted);
+    if (free(base)) return base;
+    for (let i = 2; ; i++) if (free(`${base}-${i}`)) return `${base}-${i}`;
+  }
+  const first = NAMES.find(free);
+  if (first) return first;
+  for (let i = 2; ; i++) if (free(`${NAMES[0]}-${i}`)) return `${NAMES[0]}-${i}`;
+}
+
+// ../protocol/src/topic.ts
+var TOPIC_MAX = 80;
+function cleanTopic(text) {
+  const line = text.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0) ?? "";
+  const flat = line.replace(/\s+/g, " ");
+  return flat.length > TOPIC_MAX ? `${flat.slice(0, TOPIC_MAX - 1).trimEnd()}\u2026` : flat;
+}
+function sessionTitle(s) {
+  return `${s.name} \xB7 ${s.topic || s.project}`;
+}
+
+export {
+  DOCUMENT_MAX_BYTES,
+  SessionSchema,
+  PROTOCOL_PORT,
+  RecentSchema,
+  parseClientMessage,
+  parseServerMessage,
+  pickName,
+  cleanTopic,
+  sessionTitle
+};

package/dist/cli/chunk-6ZTCETRG.js

@@ -0,0 +1,38 @@
+// src/paths.ts
+import { homedir } from "os";
+import { join } from "path";
+import { mkdir, writeFile, readFile } from "fs/promises";
+var TITLE_LINES = `set -g set-titles on
+set -g set-titles-string "#{@ledge_title}"
+`;
+var TMUX_CONF = `set -g status off
+set -g mouse on
+set -g default-terminal "tmux-256color"
+set -sg escape-time 10
+set -g history-limit 20000
+set -g remain-on-exit off
+${TITLE_LINES}`;
+function ledgeDir() {
+  return process.env.LEDGE_HOME ?? join(homedir(), ".ledge");
+}
+function paths() {
+  const dir = ledgeDir();
+  return { dir, tmuxConf: join(dir, "tmux.conf"), journal: join(dir, "sessions.json"), log: join(dir, "daemon.log"), pid: join(dir, "daemon.pid") };
+}
+async function ensureLedgeDir() {
+  const p = paths();
+  await mkdir(p.dir, { recursive: true });
+  let conf = null;
+  try {
+    conf = await readFile(p.tmuxConf, "utf8");
+  } catch {
+  }
+  if (conf === null) await writeFile(p.tmuxConf, TMUX_CONF);
+  else if (!conf.includes("set-titles")) await writeFile(p.tmuxConf, `${conf.trimEnd()}
+${TITLE_LINES}`);
+}
+
+export {
+  paths,
+  ensureLedgeDir
+};

package/dist/cli/chunk-7ICDC2LK.js

@@ -0,0 +1,88 @@
+import {
+  log
+} from "./chunk-OUIDBDIH.js";
+import {
+  paths
+} from "./chunk-6ZTCETRG.js";
+
+// src/tmux.ts
+import { execFile } from "child_process";
+import { existsSync } from "fs";
+import { join } from "path";
+function runFile(file, args, env, opts) {
+  return new Promise((resolve) => {
+    execFile(file, args, { maxBuffer: 4 * 1024 * 1024, env, ...opts?.timeoutMs ? { timeout: opts.timeoutMs, killSignal: "SIGTERM" } : {} }, (err, stdout, stderr) => {
+      const code = err && opts?.timeoutMs && err.killed ? 124 : err && typeof err.code === "number" ? err.code : err ? 1 : 0;
+      resolve({ code, stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}
+var run = (args, env) => runFile("tmux", args, env);
+function systemdAvailable(env = process.env, exists = existsSync) {
+  return !!env.XDG_RUNTIME_DIR && exists(join(env.XDG_RUNTIME_DIR, "systemd", "private"));
+}
+function newSessionCommand(tmuxArgs, scoped, unit) {
+  if (!scoped) return { file: "tmux", args: tmuxArgs };
+  return { file: "systemd-run", args: ["--user", "--scope", "--quiet", "--collect", `--unit=${unit}`, "--", "tmux", ...tmuxArgs] };
+}
+function realTmux(socket = "ledge", opts = {}) {
+  const scope = opts.scope ?? (async () => systemdAvailable());
+  const base = () => ["-L", socket, "-f", paths().tmuxConf];
+  const t = (args, env) => run([...base(), ...args], env);
+  return {
+    async newSession({ name, cwd, env, command }) {
+      const envArgs = Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+      const clientEnv = env.PATH === void 0 ? void 0 : { ...process.env, PATH: env.PATH };
+      const args = [...base(), "new-session", "-d", "-s", name, "-c", cwd, "-x", "200", "-y", "50", ...envArgs, "--", ...command];
+      const serverUp = (await t(["list-sessions"])).code === 0;
+      const scoped = !serverUp && await scope();
+      const { file, args: argv } = newSessionCommand(args, scoped, `ledge-tmux-${Date.now()}`);
+      let r = await runFile(file, argv, clientEnv);
+      if (r.code !== 0 && scoped) {
+        log(`tmux: scoped start failed (${r.stderr.trim()}), starting unscoped`);
+        r = await runFile("tmux", args, clientEnv);
+      }
+      if (r.code !== 0) throw new Error(`tmux new-session failed: ${r.stderr.trim()}`);
+    },
+    async sendText(name, text) {
+      if (/[\r\n]/.test(text)) throw new Error("sendText: text must not contain newlines; flatten it first");
+      const arg = text.endsWith(";") ? `${text.slice(0, -1)}\\;` : text;
+      const r = await t(["send-keys", "-t", `=${name}:`, "-l", "--", arg]);
+      if (r.code !== 0) throw new Error(`tmux send-keys failed: ${r.stderr.trim()}`);
+    },
+    async sendKeys(name, keys) {
+      const r = await t(["send-keys", "-t", `=${name}:`, ...keys]);
+      if (r.code !== 0) throw new Error(`tmux send-keys failed: ${r.stderr.trim()}`);
+    },
+    async capture(name, lines) {
+      const r = await t(["capture-pane", "-p", "-J", "-t", `=${name}:`, "-S", String(-lines)]);
+      if (r.code !== 0) return null;
+      return r.stdout.replace(/\s+$/g, "").split("\n").slice(-lines).join("\n");
+    },
+    async hasSession(name) {
+      return (await t(["has-session", "-t", `=${name}`])).code === 0;
+    },
+    async listSessions() {
+      const r = await t(["list-sessions", "-F", "#{session_name}"]);
+      if (r.code === 0) return r.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+      if (/no server running|error connecting to/i.test(r.stderr)) return [];
+      throw new Error(`tmux list-sessions failed: ${r.stderr.trim()}`);
+    },
+    async setOption(name, option, value) {
+      const r = await t(["set-option", "-t", `=${name}:`, option, value]);
+      if (r.code !== 0) throw new Error(`tmux set-option failed: ${r.stderr.trim()}`);
+    },
+    async killSession(name) {
+      await t(["kill-session", "-t", `=${name}`]);
+    },
+    attachArgs(name) {
+      return [...base(), "attach-session", "-t", `=${name}`];
+    }
+  };
+}
+
+export {
+  runFile,
+  run,
+  realTmux
+};

package/dist/cli/chunk-OUIDBDIH.js

@@ -0,0 +1,59 @@
+import {
+  paths
+} from "./chunk-6ZTCETRG.js";
+import {
+  pickName
+} from "./chunk-6GMDFIGB.js";
+
+// src/log.ts
+import { appendFileSync } from "fs";
+function log(line) {
+  try {
+    appendFileSync(paths().log, `${(/* @__PURE__ */ new Date()).toISOString()} | ${line}
+`);
+  } catch {
+  }
+}
+
+// src/spawn.ts
+import { basename, join } from "path";
+import { randomBytes } from "crypto";
+var AGENT_BIN = { claude: "claude", codex: "codex", cursor: "cursor-agent" };
+var CODEX_ENV_VAR = "LEDGE_CODEX_SESSION";
+var CODEX_HOOK_VAR = "LEDGE_CODEX_HOOK_SESSION";
+function agentIdArgs(tool, id) {
+  return tool === "codex" ? ["-c", `shell_environment_policy.set.${CODEX_HOOK_VAR}="${id}"`] : [];
+}
+function exitFile(id) {
+  return join(paths().dir, `exit-${id}`);
+}
+function agentEnv(base, extra) {
+  const env = {};
+  for (const [k, v] of Object.entries(base)) if (v !== void 0 && k !== "TMUX" && !k.startsWith("TMUX_")) env[k] = v;
+  return { ...env, ...extra };
+}
+async function spawnSession(opts) {
+  const now = opts.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const takenIds = new Set(opts.taken.ids);
+  let id;
+  do
+    id = randomBytes(2).toString("hex");
+  while (takenIds.has(id));
+  const name = pickName(opts.taken.names, opts.name);
+  const project = basename(opts.cwd) || opts.cwd;
+  const tmuxSession = `ledge-${id}`;
+  const agent = opts.command ?? [AGENT_BIN[opts.tool], ...agentIdArgs(opts.tool, id), ...opts.args];
+  const command = opts.recordExit ? ["sh", "-c", '"$@"; echo $? > "$0"', exitFile(id), ...agent] : agent;
+  await opts.tmux.newSession({ name: tmuxSession, cwd: opts.cwd, env: agentEnv(opts.env ?? process.env, { LEDGE_SESSION: id, LEDGE_NAME: name, ...opts.tool === "codex" ? { [CODEX_ENV_VAR]: id } : {} }), command });
+  const at = now();
+  return { id, name, tool: opts.tool, cwd: opts.cwd, project, title: `${name} \xB7 ${project}`, tmuxSession, state: "starting", helpers: [], startedAt: at, lastActivityAt: at, source: "launcher" };
+}
+
+export {
+  log,
+  CODEX_ENV_VAR,
+  CODEX_HOOK_VAR,
+  exitFile,
+  agentEnv,
+  spawnSession
+};

package/dist/cli/chunk-QYQIJW5G.js

@@ -0,0 +1,6 @@
+// src/version.ts
+var LEDGE_VERSION = true ? "0.3.0" : "0.0.0-dev";
+
+export {
+  LEDGE_VERSION
+};