@osdlc/agent-seat 0.0.0-stage → 0.7.1

package/dist/harness.js

@@ -0,0 +1,610 @@
+/**
+ * The harness axis — pure argv-building + naming for whichever coding-agent
+ * CLI a host opens a session in.
+ *
+ * `Harness` is independent of `HostName` (`contract.ts`): every host composes
+ * `harnessArgv` to run whichever harness the caller asked for.
+ *
+ * Not `@osdlc/agent-call`'s planner: that plans HEADLESS calls (`claude -p`,
+ * `codex exec`) whose output a program reads. A session is the opposite — a
+ * person sits in it — so the argv is the bare CLI with the first message,
+ * plus the Claude-only flags in {@link claudeSessionArgv}.
+ *
+ * This module also carries harness-specific machinery: codex's own on-disk
+ * session-index lookup (`codexSessionsDir` et al. — harness-specific, not
+ * host-specific, so it belongs on this axis), `wrapperSession`, the one body
+ * every wrapper host's `session()` shares ("build argv, run it, best-effort
+ * resolve a session id"), and `harnessNativeSend`, a per-harness
+ * message-injection mechanism independent of any host (`contract.ts`'s
+ * `Host.send` is the host-level counterpart).
+ */
+import { closeSync, openSync, readdirSync, readSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { z } from 'zod';
+import { claudePluginArgv, claudeResumeFlag, modelArgs, } from '@osdlc/agent-call';
+import { harnessId } from '@osdlc/detect-harness';
+import { ran, resolveRunner } from '@osdlc/command-seam';
+import { isRecord, parseJsonOrNull, realResolve, sleepSync, strOrNull, which } from "./util.js";
+// `contract.ts` imports only types from this file (`Harness` for
+// `SessionRequest.harness`), so the value imported back here makes no runtime cycle.
+import { hostCanWait, } from "./contract.js";
+/** A tool id: a lowercase letter, then lowercase letters, digits and hyphens. */
+const HARNESS_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+ * The schema a harness field validates against. A tool id, not a closed list,
+ * since a caller may run a tool of its own.
+ */
+export const HarnessSchema = z
+    .string()
+    .regex(HARNESS_ID_PATTERN, 'must be a tool id: lowercase letters, digits and hyphens');
+/**
+ * `value` (what a host reports running in a pane) as a built-in harness id, or null when
+ * it names none. An alias or binary name maps to its id (`cursor-agent` → `cursor`), by
+ * `harnessId` from `@osdlc/detect-harness`.
+ */
+export function harnessOrNull(value) {
+    return typeof value === 'string' ? (harnessId(value) ?? null) : null;
+}
+/** `<bin> <model flags> <injected> -- <prompt>`: the shape of every CLI whose positional is the first message. */
+const guarded = (p) => [
+    p.bin,
+    ...p.model,
+    ...p.injected,
+    '--',
+    p.prompt,
+];
+/**
+ * The interactive argv builders, keyed by tool id: the bare CLI with `prompt`
+ * as its first message, guarded behind a `--` end-of-options marker, so a
+ * prompt starting with `-` (or naming a subcommand) is never read as one.
+ * A tool missing here has no interactive launch (antigravity, a declared tool).
+ *
+ *   - `claude`: its CLI parser (commander.js) treats `--` as the end of
+ *     options. Its session flags ({@link claudeSessionArgv}) sit before the guard.
+ *   - `codex`: its CLI parser (clap) honours `--`; without it a prompt starting
+ *     with `-` is parsed as a flag, and one naming a subcommand (`login`) runs
+ *     that subcommand. Checked against a live codex.
+ *   - `cursor`: taken from Cursor's published CLI docs, not a live run; guarded
+ *     the same way, since any argv-parsing CLI has the same ambiguity.
+ *   - `pi`: `pi --help` documents `pi [options] [--] [@files...] [messages...]`,
+ *     and a live run with `--` opened the session on the prompt.
+ *   - `opencode`: its bare positional is the PROJECT directory, so the first
+ *     message goes in `--prompt=<message>` (bound with `=` so a message starting
+ *     with `-` is not read as a flag), per `opencode --help`.
+ */
+const INTERACTIVE_ARGV = {
+    claude: (p) => [p.bin, ...p.model, ...claudeSessionArgv(p.claude), ...p.injected, '--', p.prompt],
+    codex: guarded,
+    cursor: guarded,
+    pi: guarded,
+    opencode: (p) => [p.bin, ...p.model, ...p.injected, `--prompt=${p.prompt}`],
+};
+/** Whether an interactive argv can be built for `tool`. */
+export function hasInteractiveArgv(tool) {
+    return Object.hasOwn(INTERACTIVE_ARGV, tool);
+}
+/**
+ * The argv that opens `harness`, run as `binary` (a name on PATH or an
+ * absolute path), interactively with `prompt` as its first message
+ * ({@link INTERACTIVE_ARGV}). A resolved `choice` adds its launch mode,
+ * model and effort flags (`modelArgs`, `@osdlc/agent-call`) before the `--` guard; a
+ * tool with no model or effort flags wired throws on a choice rather than
+ * dropping it. Throws for a tool with no interactive launch.
+ *
+ * `injected` is the argv a per-launch observation adds (pi's
+ * `--session-id` and `-e <extension>`); it sits before the prompt.
+ */
+export function harnessArgv(harness, binary, prompt, claude = {}, choice = {}, injected = []) {
+    const build = Object.hasOwn(INTERACTIVE_ARGV, harness) ? INTERACTIVE_ARGV[harness] : undefined;
+    if (build === undefined)
+        throw new Error(`'${harness}' has no interactive launch`);
+    return build({
+        bin: binary,
+        prompt,
+        model: modelArgs(harness, choice),
+        claude,
+        injected,
+    });
+}
+/** Session flags only `claude` takes; a caller can store them to resume with the same flags. */
+export const ClaudeSessionFlagsSchema = z.object({
+    /** Text for `claude --append-system-prompt`. */
+    appendSystemPrompt: z.string().optional(),
+    /** Session-only plugins (`claude --plugin-dir` / `--settings`). */
+    plugins: z.object({
+        dirs: z.array(z.string()),
+        disable: z.array(z.string()),
+    }).optional(),
+    /**
+     * The shell command Claude's hooks run (`<caller> hook --harness claude ...`);
+     * set, it adds the hook settings of {@link claudeHookSettings} to every launch and
+     * resume, since `--settings` is not persisted with the session.
+     */
+    hookCommand: z.string().optional(),
+});
+/**
+ * The Claude Code hook events the caller listens to. Everything is async except
+ * `SessionEnd`, which has to finish its write before Claude exits (its budget
+ * is the hook's own `timeout`). `PreToolUse` is matched to `AskUserQuestion`
+ * alone: the question is what puts the agent in `waiting_for_input` there, and
+ * a hook on every tool call would cost a process each. `PermissionRequest` and
+ * `StopFailure` mark a tool-permission prompt and a turn that ended on an API error.
+ */
+export const CLAUDE_HOOK_EVENTS = {
+    SessionStart: { async: true },
+    UserPromptSubmit: { async: true },
+    PreToolUse: { async: true, matcher: 'AskUserQuestion' },
+    PermissionRequest: { async: true },
+    PostToolUse: { async: true },
+    PostToolUseFailure: { async: true },
+    Stop: { async: true },
+    StopFailure: { async: true },
+    SubagentStart: { async: true },
+    SubagentStop: { async: true },
+    Notification: { async: true },
+    PreCompact: { async: true },
+    PostModelSwitch: { async: true },
+    SessionEnd: { async: false },
+};
+/** Seconds `SessionEnd`'s hook may run; Claude's default budget for it is 1.5s. */
+const SESSION_END_HOOK_TIMEOUT_S = 10;
+/** The `hooks` settings object that runs `command` for every {@link CLAUDE_HOOK_EVENTS} event. */
+export function claudeHookSettings(command) {
+    const hooks = {};
+    for (const [name, spec] of Object.entries(CLAUDE_HOOK_EVENTS)) {
+        hooks[name] = [
+            {
+                ...(spec.matcher === undefined ? {} : { matcher: spec.matcher }),
+                hooks: [
+                    spec.async
+                        ? { type: 'command', command, async: true }
+                        : { type: 'command', command, timeout: SESSION_END_HOOK_TIMEOUT_S },
+                ],
+            },
+        ];
+    }
+    return { hooks };
+}
+/**
+ * The plugin argv with the hook settings merged into its `--settings` value, or
+ * a `--settings` of their own when the plugins brought none: Claude is handed
+ * one `--settings`, never two that could shadow each other.
+ */
+function withHookSettings(pluginArgv, command) {
+    if (command === undefined)
+        return pluginArgv;
+    const hooks = claudeHookSettings(command);
+    const at = pluginArgv.indexOf('--settings');
+    if (at === -1)
+        return [...pluginArgv, '--settings', JSON.stringify(hooks)];
+    const existing = JSON.parse(pluginArgv[at + 1]);
+    const merged = [...pluginArgv];
+    // The plugin settings are only `enabledPlugins`, so the spread cannot lose a
+    // user key; if they ever carry `hooks`, ours replace them.
+    merged[at + 1] = JSON.stringify({ ...existing, ...hooks });
+    return merged;
+}
+/** The argv for {@link ClaudeLaunchFlags}, shared by the launches and {@link claudeResumeArgv}. */
+export function claudeSessionArgv(flags) {
+    const pluginArgv = flags.plugins === undefined ? [] : claudePluginArgv(flags.plugins);
+    return [
+        ...(flags.harnessSessionId === undefined ? [] : ['--session-id', flags.harnessSessionId]),
+        ...withHookSettings(pluginArgv, flags.hookCommand),
+        ...(flags.appendSystemPrompt === undefined
+            ? []
+            : ['--append-system-prompt', flags.appendSystemPrompt]),
+    ];
+}
+/**
+ * `claude --resume=<id>` plus the launch's session flags, so a resumed session
+ * keeps its plugins and prompt pin. Does not validate `id`; `claudeResumeFlag`
+ * (`@osdlc/agent-call`) binds it with `=`.
+ */
+export function claudeResumeArgv(id, flags = {}) {
+    return [claudeResumeFlag(id), ...claudeSessionArgv(flags)];
+}
+/**
+ * Whether `harness`'s CLI, `binary` (a name on PATH or an absolute path), is
+ * on PATH. A synchronous lookup that spawns nothing. Only a PATH hit counts: an
+ * installed app bundle (Cursor.app) gives a session nothing to run.
+ */
+export function harnessAvailable(_harness, binary) {
+    return which(binary) !== null;
+}
+/**
+ * `codex queue --thread <id> --message <text>` — the FLAGS are verified (`codex queue --help`-shaped syntax), but
+ * whether this actually reaches a session that is CURRENTLY OPEN in a live
+ * TUI, versus only queuing for a future `codex resume`, is
+ * unresolved — no bundled source to check, no live test run. Through
+ * the command seam, `opts.runner` injectable so a test never shells out for
+ * real (`cwd: process.cwd()` — `queue` addresses by `--thread <id>`, not by
+ * working directory, so any real directory does). `ack` is always
+ * false regardless of exit code: a clean exit only proves the daemon
+ * ACCEPTED the queue request, never that a live session consumed it — the
+ * same honesty `hosts/tmux.ts`'s `send` applies for a different reason (no
+ * confirmation mechanism at all, versus this one's confirmed-but-unresolved
+ * mechanism).
+ */
+function codexNativeSend(sessionId, text, opts) {
+    const runner = resolveRunner('codex', opts.runner);
+    const res = runner.run(['queue', '--thread', sessionId, '--message', text], {
+        cwd: process.cwd(),
+        timeoutMs: 30_000,
+    });
+    return { accepted: ran(res), ack: false };
+}
+/**
+ * Per-harness native message injection, independent of any host — a caller's
+ * "native send" step (`docs/planning/research/orca.md`'s "Recommended
+ * shape" section), distinct from `Host.send` (`contract.ts`'s `SendRequest`):
+ * this reaches the harness's OWN process/daemon directly, never through
+ * whichever terminal happens to host it. Only `codex` gets a real entry here
+ * — every other harness is simply ABSENT from this map, meaning "no known
+ * native-send mechanism," not "not implemented yet": `claude` has no way to
+ * inject into a running session at all (it has its own separate `--bg`/`attach` background-session mechanism
+ * instead, unrelated to sending into an interactive one); `cursor`'s
+ * published docs describe no such surface; `pi`'s only send-like channel,
+ * `--mode rpc`, requires the dispatcher to have spawned and held that
+ * process's own stdin from the very start — not a way to reach an already-running independent `pi` TUI process, and
+ * building that headless-RPC surface is out of scope here besides.
+ *
+ * Deciding when to PREFER native-send over host `send` is left to the caller;
+ * `harnessNativeSend` just needs to exist and be callable.
+ */
+const NATIVE_SEND = {
+    codex: codexNativeSend,
+};
+/** `NATIVE_SEND[harness]`, called if present; `null` — not a thrown error — when the harness has no known native-send mechanism at all (see the map's own doc for which). */
+export function harnessNativeSend(harness, sessionId, text, opts = {}) {
+    const fn = Object.hasOwn(NATIVE_SEND, harness) ? NATIVE_SEND[harness] : undefined;
+    return fn === undefined ? null : fn(sessionId, text, opts);
+}
+/** `~/.codex/sessions` (or under an injected `codexHome`, for tests). */
+export function codexSessionsDir(codexHome) {
+    return join(codexHome ?? join(homedir(), '.codex'), 'sessions');
+}
+/**
+ * Recursively finds every `rollout-*.jsonl` file under `dir`. Missing/
+ * unreadable dirs yield `[]`. Exported so a caller that needs the transcript
+ * path can reuse this walk; {@link findCodexSessionId} returns only the id.
+ */
+export function walkRolloutFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...walkRolloutFiles(full));
+        }
+        else if (entry.isFile() && /^rollout-.*\.jsonl$/.test(entry.name)) {
+            files.push(full);
+        }
+    }
+    return files;
+}
+/** The `cwd`/session-id pair recorded in a rollout file's first (`session_meta`) line, or null if unparsable. */
+export function parseRolloutMeta(firstLine) {
+    const parsed = parseJsonOrNull(firstLine.trim());
+    const payload = isRecord(parsed) ? parsed['payload'] : null;
+    if (!isRecord(payload))
+        return null;
+    const cwd = strOrNull(payload['cwd']);
+    const sessionId = strOrNull(payload['session_id']) ?? strOrNull(payload['id']);
+    return cwd === null || sessionId === null ? null : { cwd, sessionId };
+}
+/**
+ * How far before the launch instant a rollout's creation may fall and still
+ * count as this launch's: the file name has one-second resolution, and file
+ * timestamps come from a coarser clock than `Date.now()`, so a file created
+ * just after the launch can read a little before it.
+ */
+export const ROLLOUT_CREATED_MARGIN_MS = 2_000;
+const ROLLOUT_NAME_TIME = /^rollout-(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})-/;
+/**
+ * How far a rollout's name time can sit from its real creation instant: codex
+ * stamps the name from its own local clock, and two UTC offsets differ by at
+ * most 26 hours (UTC-12 to UTC+14).
+ */
+const ROLLOUT_NAME_ZONE_SLACK_MS = 26 * 3_600_000;
+/**
+ * The instant in a rollout file name, `rollout-<YYYY-MM-DDTHH-MM-SS>-<uuid>.jsonl`,
+ * or null when the name has none. Read as LOCAL time: codex stamps the name
+ * (and the `yyyy/mm/dd` buckets) from its local clock, so this is exact only
+ * when codex ran in the same time zone as this process.
+ */
+export function rolloutNameTimeMs(path) {
+    const m = ROLLOUT_NAME_TIME.exec(basename(path));
+    if (m === null)
+        return null;
+    const fields = m.slice(1);
+    const [y = 0, mo = 0, d = 0, h = 0, mi = 0, s = 0] = fields.map(Number);
+    const date = new Date(y, mo - 1, d, h, mi, s);
+    const pad = (n, width = 2) => String(n).padStart(width, '0');
+    const back = [
+        pad(date.getFullYear(), 4),
+        pad(date.getMonth() + 1),
+        pad(date.getDate()),
+        pad(date.getHours()),
+        pad(date.getMinutes()),
+        pad(date.getSeconds()),
+    ];
+    // `Date` rolls an out-of-range field over (month 13, hour 25); such a name has no instant.
+    return back.join('-') === fields.join('-') ? date.getTime() : null;
+}
+/**
+ * When a rollout file was created: its birthtime when the file system records
+ * one (a birthtime of 0 means it does not), else the time in its name, else its
+ * mtime. The name is read in this process's time zone ({@link rolloutNameTimeMs}),
+ * so it is off by the zone difference when codex ran elsewhere; a name time
+ * later than the file's last write (beyond the margin) cannot be right and
+ * falls through to the mtime.
+ */
+export function rolloutCreatedMs(path, stats) {
+    if (stats.birthtimeMs > 0)
+        return stats.birthtimeMs;
+    const named = rolloutNameTimeMs(path);
+    return named !== null && named <= stats.mtimeMs + ROLLOUT_CREATED_MARGIN_MS
+        ? named
+        : stats.mtimeMs;
+}
+/** Whether two paths name the same place once symlinks are resolved. */
+function samePlace(a, b) {
+    return a === b || realResolve(a) === realResolve(b);
+}
+/**
+ * The session id of the newest candidate (by creation instant) created no more
+ * than {@link ROLLOUT_CREATED_MARGIN_MS} before `sinceMs` whose rollout `cwd`
+ * names the same directory as `opts.cwd` (compared as real paths, so a cwd
+ * reached through a symlink matches), or null when none qualifies. Takes
+ * canned candidates, so a test needs no rollout files.
+ */
+export function newestRolloutSessionIdSince(candidates, opts) {
+    const cutoff = opts.sinceMs - ROLLOUT_CREATED_MARGIN_MS;
+    let best = null;
+    for (const c of candidates) {
+        if (c.createdMs < cutoff)
+            continue;
+        const meta = parseRolloutMeta(c.firstLine);
+        if (meta === null || !samePlace(meta.cwd, opts.cwd))
+            continue;
+        if (best === null || c.createdMs > best.createdMs)
+            best = { sessionId: meta.sessionId, createdMs: c.createdMs };
+    }
+    return best?.sessionId ?? null;
+}
+/** The first line of the file at `path` (without its `\n`), read no further than it. */
+function readFirstLine(path) {
+    const fd = openSync(path, 'r');
+    try {
+        let buf = Buffer.alloc(4096);
+        let len = 0;
+        for (;;) {
+            const n = readSync(fd, buf, len, buf.length - len, len);
+            const end = buf.indexOf(0x0a, len);
+            len += n;
+            if (end !== -1 && end < len)
+                return buf.toString('utf-8', 0, end);
+            if (n === 0)
+                return buf.toString('utf-8', 0, len);
+            if (len === buf.length)
+                buf = Buffer.concat([buf, Buffer.alloc(buf.length)]);
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * The `yyyy/mm/dd` folders under `sessionsDir` a rollout created between
+ * `fromMs` and `toMs` can sit in. codex names a folder by its own local date,
+ * which can differ from this process's by up to {@link ROLLOUT_NAME_ZONE_SLACK_MS},
+ * so the range is widened by that much on each side (one or two days).
+ */
+export function rolloutDayDirs(sessionsDir, fromMs, toMs) {
+    const from = new Date(fromMs - ROLLOUT_NAME_ZONE_SLACK_MS);
+    const to = new Date(toMs + ROLLOUT_NAME_ZONE_SLACK_MS);
+    const last = new Date(to.getFullYear(), to.getMonth(), to.getDate()).getTime();
+    const pad = (n) => String(n).padStart(2, '0');
+    const dirs = [];
+    for (let day = new Date(from.getFullYear(), from.getMonth(), from.getDate()); day.getTime() <= last; day = new Date(day.getFullYear(), day.getMonth(), day.getDate() + 1)) {
+        dirs.push(join(sessionsDir, String(day.getFullYear()), pad(day.getMonth() + 1), pad(day.getDate())));
+    }
+    return dirs;
+}
+/**
+ * The codex session started in `cwd` at or after `sinceMs`
+ * ({@link newestRolloutSessionIdSince}), or null.
+ *
+ * Reads codex's own on-disk session index. `~/.codex/session_index.jsonl` is
+ * NOT used: it only records threads that were given a name. Instead this scans
+ * the rollout files, `~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-*.jsonl`, in
+ * the date folders from the launch through now ({@link rolloutDayDirs}), for
+ * the session created at or after the launch whose first line, a
+ * `session_meta` record
+ * (`{"type":"session_meta","payload":{"session_id":"<uuid>","cwd":"<path>",…}}`),
+ * names `cwd`. The cwds are compared as real paths: codex records its
+ * process's directory with symlinks resolved.
+ *
+ * Selection is by the rollout's creation instant ({@link rolloutCreatedMs}),
+ * not its mtime: another codex session in the same cwd keeps appending to its
+ * own rollout, so its mtime would pass a launch-time cutoff. This is still
+ * best-effort: two codex sessions launched from the same cwd within a couple of
+ * seconds of each other (or one launched in that cwd while a waiting host holds
+ * ours) can be mistaken for each other. No local signal tells them apart.
+ *
+ * With `waitMs`, keeps looking that long for a rollout file codex has not
+ * written yet; a file ruled out once (created too early, or another cwd) is not
+ * read again. `listFiles` and `codexHome` are injectable so a test needs no
+ * real `~/.codex/`.
+ */
+export function findCodexSessionId(sinceMs, cwd, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const listFiles = opts.listFiles ??
+        (() => rolloutDayDirs(codexSessionsDir(opts.codexHome), sinceMs, now()).flatMap(walkRolloutFiles));
+    const cutoff = sinceMs - ROLLOUT_CREATED_MARGIN_MS;
+    const realCwd = realResolve(cwd);
+    const ruledOut = new Set();
+    const look = () => {
+        const candidates = [];
+        for (const path of listFiles()) {
+            if (ruledOut.has(path))
+                continue;
+            // The name time can be off by a time-zone difference (`rolloutCreatedMs`), so
+            // only a name earlier than that rules the file out unread.
+            const named = rolloutNameTimeMs(path);
+            if (named !== null && named < cutoff - ROLLOUT_NAME_ZONE_SLACK_MS) {
+                ruledOut.add(path);
+                continue;
+            }
+            try {
+                const createdMs = rolloutCreatedMs(path, statSync(path));
+                if (createdMs < cutoff) {
+                    ruledOut.add(path);
+                    continue;
+                }
+                const firstLine = readFirstLine(path);
+                // A first line not yet complete parses as null and is read again on the next look.
+                const meta = parseRolloutMeta(firstLine);
+                if (meta !== null && !samePlace(meta.cwd, realCwd))
+                    ruledOut.add(path);
+                else
+                    candidates.push({ firstLine, createdMs });
+            }
+            catch {
+                // Raced away (deleted) or unreadable — skip, not fatal.
+            }
+        }
+        return newestRolloutSessionIdSince(candidates, { sinceMs, cwd: realCwd });
+    };
+    return pollFor(look, opts);
+}
+/** `look()` until it gives a value or `opts.waitMs` runs out; null then. */
+function pollFor(look, opts) {
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? sleepSync;
+    const pollMs = opts.pollMs ?? 250;
+    const deadline = now() + (opts.waitMs ?? 0);
+    for (;;) {
+        const found = look();
+        if (found !== null)
+            return found;
+        const left = deadline - now();
+        if (left <= 0)
+            return null;
+        sleep(Math.min(pollMs, left));
+    }
+}
+/**
+ * Only `codex` has a resolver. `claude` needs none: a caller presets the
+ * session id with `claude --session-id` (`ClaudeLaunchFlags.harnessSessionId`)
+ * and so knows it already. `cursor` has no local session index or rollout file
+ * to look an id up in.
+ */
+const SESSION_ID_RESOLVERS = {
+    codex: findCodexSessionId,
+};
+/** How long {@link wrapperSession} waits for the agent to record its session after a host returned early. */
+export const SESSION_ID_WAIT_MS = 3_000;
+/**
+ * `argv` carrying `env`, so the vars reach the process whatever terminal runs it.
+ * POSIX: prefixed with `env [-u K ...] [K=V ...]`. win32 has no `env`, so the
+ * argv becomes a `powershell -Command` that sets (`$env:K='V'`) or clears
+ * (`Remove-Item Env:K`) each variable and then runs the original command.
+ *
+ * Windows limits (not run on Windows): `powershell` is Windows PowerShell 5.1,
+ * which passes an argument containing `"` to a native program without escaping
+ * it (the program sees it split, or with the quotes gone) and drops an empty
+ * argument; and `-Command` turns the program's exit code into 0 or 1. Every
+ * word of the command is single-quoted, even one that needs no quoting: Windows
+ * PowerShell 5.1 drops a bare `--` (the guard `harnessArgv` puts before the
+ * prompt) and splits a bare `-name.value`, which a quoted word avoids.
+ */
+export function withEnv(argv, env, platform = process.platform) {
+    const entries = Object.entries(env ?? {});
+    if (entries.length === 0)
+        return argv;
+    if (platform === 'win32') {
+        for (const [k] of entries) {
+            // The name goes into a PowerShell command unquoted (set branch), so it must be a plain identifier.
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k))
+                throw new Error(`invalid environment variable name: ${k}`);
+        }
+        const sets = entries.map(([k, v]) => v === undefined
+            ? `Remove-Item -ErrorAction SilentlyContinue ${powershellLiteral(`Env:${k}`)}`
+            : `$env:${k} = ${powershellLiteral(v)}`);
+        return [
+            'powershell',
+            '-NoProfile',
+            '-Command',
+            `${sets.join('; ')}; & ${argv.map(powershellLiteral).join(' ')}`,
+        ];
+    }
+    const unset = [];
+    const pairs = [];
+    for (const [k, v] of entries) {
+        if (v === undefined)
+            unset.push('-u', k);
+        else
+            pairs.push(`${k}=${v}`);
+    }
+    return ['env', ...unset, ...pairs, ...argv];
+}
+/** `word` as a single-quoted PowerShell literal, each single quote (typographic ones too) doubled. */
+function powershellLiteral(word) {
+    return `'${word.replace(/['‘’‚‛]/g, (q) => q + q)}'`;
+}
+/**
+ * The shared body of every wrapper host's `session()`: build `harnessArgv`
+ * under `req.env`, run it, best-effort resolve a session id.
+ *
+ * Most hosts return as soon as the pane exists, before the agent has recorded
+ * its session, so after a clean launch the lookup keeps trying for
+ * `opts.waitMs` (default {@link SESSION_ID_WAIT_MS}). With `opts.hostWaited`
+ * (the host held the launch until the agent exited) it looks once.
+ *
+ * @param terminal The calling host's own `terminal()`, which opens its
+ *   terminal or workspace.
+ */
+export function wrapperSession(terminal, req, opts = {}) {
+    const sinceMs = (opts.now ?? Date.now)();
+    const argv = [
+        ...(req.wrap ?? []),
+        ...harnessArgv(req.harness, req.binary, req.prompt, req, req, req.injectedArgv),
+    ];
+    const exitCode = terminal({
+        cwd: req.cwd,
+        argv: withEnv(argv, req.env),
+        title: req.title,
+        sessionId: req.sessionId,
+        ...(req.wait !== undefined ? { wait: req.wait } : {}),
+    });
+    const resolver = Object.hasOwn(SESSION_ID_RESOLVERS, req.harness)
+        ? SESSION_ID_RESOLVERS[req.harness]
+        : undefined;
+    if (resolver === undefined)
+        return { exitCode, harnessSessionId: null };
+    // A failed launch started no agent, and a held one has written its file: look once.
+    const waitMs = exitCode !== 0 || opts.hostWaited === true ? 0 : (opts.waitMs ?? SESSION_ID_WAIT_MS);
+    return { exitCode, harnessSessionId: resolver(sinceMs, req.cwd, { ...opts, waitMs }) };
+}
+/**
+ * The `session` part of a host whose `terminal` part opens the harness: assign
+ * it as `session: sessionViaTerminal`. `this` is the host the part is called on,
+ * so the host's own `terminal` runs; a host that has none throws rather than
+ * start nothing. A host honouring `req.wait` returns only once the agent
+ * exited, so the session-id lookup does not wait.
+ */
+export function sessionViaTerminal(req) {
+    const terminal = this.terminal;
+    if (terminal === undefined)
+        throw new Error('host has no terminal part to open a session with');
+    const hostWaited = req.wait !== undefined && this.name !== undefined && hostCanWait(this.name);
+    return wrapperSession((r) => terminal.call(this, r), req, { hostWaited });
+}

package/dist/hosts/cmux.d.ts

@@ -0,0 +1,67 @@
+/**
+ * cmux: a new workspace on `cwd` whose first terminal runs a command, plus
+ * send/find/focus/capture. Research: `docs/planning/research/cmux.md`
+ * (cmux 0.64.17).
+ *
+ * `workspace create` is the canonical spelling; `new-workspace` is the legacy
+ * alias and prints a deprecation notice on every call.
+ *
+ * cmux cannot bind a pane to a caller session id: `workspace create` has no
+ * tag the list commands read back (the shapes are docs-only), so every part
+ * resolves by `cwd` and ignores `sessionId`. `close` therefore acts only when
+ * exactly one workspace is at the cwd.
+ *
+ * Socket access: send/focus/capture and the workspace-list half of `find` use
+ * the cmux control socket, which by default (`automation.socketControlMode`
+ * "cmuxOnly") rejects callers not started inside cmux ("Access denied - only
+ * processes started inside cmux can connect"; observed). Published docs
+ * (the cmux.json schema and `cmux --help` "Socket Auth"): set
+ * `automation.socketControlMode` in ~/.config/cmux/cmux.json to `automation`,
+ * `allowAll` or `password`; in password mode export `CMUX_SOCKET_PASSWORD` (or
+ * pass `--password`). When denied these parts report "not accepted / false /
+ * null" without throwing; `find` still answers from the hook store.
+ */
+import { type CommandRunner } from '@osdlc/command-seam';
+import { type CommandRequest, type FoundSession, type Host } from '../contract.ts';
+/** Argv for `cmux workspace create` — pure, so a test can pin it. */
+export declare function cmuxCreateArgv(req: CommandRequest): string[];
+/** Argv for `cmux sessions list` (hook store, no socket). `--cwd` is a text filter, so results are re-filtered exactly. */
+export declare function cmuxSessionsArgv(cwd: string): string[];
+/** Argv for `cmux --json workspace list` (needs the socket). */
+export declare function cmuxWorkspaceListArgv(): string[];
+/**
+ * `cmux send` types the text (its `\n`, `\r` and `\t` escape sequences are
+ * interpreted as keys, so `send` refuses text containing them,
+ * {@link cmuxTextIsUnsafe}); a separate `send-key enter` submits.
+ */
+export declare function cmuxSendArgv(handle: string, text: string): string[];
+export declare function cmuxSendEnterArgv(handle: string): string[];
+export declare function cmuxFocusArgv(handle: string): string[];
+/** `cmux workspace close <workspace>` (per `cmux workspace --help`); closes the whole workspace. */
+export declare function cmuxCloseArgv(handle: string): string[];
+export declare function cmuxReadScreenArgv(handle: string): string[];
+/**
+ * Whether `text` would be typed as a key press rather than as text: a real
+ * newline, or a backslash-n / -r / -t sequence, which `cmux send` turns into
+ * Enter or Tab. cmux's `set-buffer` / `paste-buffer` exist, but whether a
+ * paste is bracketed is not observable without the control socket, so such text
+ * is refused rather than risking a partial prompt being submitted.
+ */
+export declare function cmuxTextIsUnsafe(text: string): boolean;
+/**
+ * Parses `cmux sessions list --json`: `{sessions: [{agent, cwd, workspace_id,
+ * surface_id, ...}]}`. DOCS-ONLY field names (the store was empty when
+ * observed; only the envelope was seen). Records are saved hook state, so a
+ * match can be stale; a failed send then falls through to the next route.
+ */
+export declare function parseCmuxSessions(stdout: string, cwd: string): FoundSession[];
+/** Parses `cmux --json workspace list`: an array (or `{workspaces}`) of `{ref|id, cwd|current_directory}`. DOCS-ONLY shape. */
+export declare function parseCmuxWorkspaces(stdout: string, cwd: string): FoundSession[];
+/**
+ * The cmux host: drives the cmux app through the `cmux` binary, which must be on PATH.
+ * darwin only. Keeps no state of its own; every part resolves by `cwd`.
+ */
+export declare function makeCmuxHost(opts: {
+    runner?: CommandRunner | undefined;
+    available?: (() => boolean) | undefined;
+}): Host;