@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/terminal/inject.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Terminal injection — Gap 2 of the Terminal Engine.
+ *
+ * Where the rest of the engine OPENS a surface (a tab / split running a
+ * command), injection types into an ALREADY-running surface. It's the primitive
+ * a native watchdog (RUSH-1415) needs to nudge a stalled agent with "continue"
+ * delivered into the exact terminal that agent lives in — the gap flagged in
+ * src/lib/session/provenance.ts:20:
+ *
+ *   > Actually delivering the keystrokes is Gap 2 (pty/tmux send-keys).
+ *
+ * It mirrors the engine's shape exactly: pure per-backend spec builders (like
+ * `tmuxTabArgv` / `itermTabScript`) produce a `LaunchSpec` (argv), and the same
+ * `runSpec` transport runs it — so injection inherits the engine's local/remote
+ * (`--host` over SSH) execution for free. A `LaunchSpec` never opens anything;
+ * building one is side-effect-free and unit-testable without a display.
+ *
+ * Backends (each addresses the EXACT split, not the frontmost surface):
+ *   - tmux  → `tmux send-keys -t <pane>` — the send-keys primitive addressed by
+ *             pane id + socket (the exact rail provenance.ts identifies).
+ *   - iterm (macOS) → AppleScript `tell session id "<uuid>" to write text` —
+ *             addresses the precise iTerm2 split by its session UUID WITHOUT
+ *             `activate`, so it never steals focus or types into the wrong split.
+ *             Uses the engine's `appleScriptStr` escaper; guarded by the iterm
+ *             backend's `isAvailable` (platform + app installed).
+ *   - vscodium (VSCodium / Cursor / VS Code) → the editor CLI's `--open-url`
+ *             into the swarmify `swarm-ext` extension's `/inject` verb, targeting
+ *             a live-terminals.json terminal by id. Focus-independent, exact
+ *             terminal, and (like the launch backend, src/lib/terminal/backends/
+ *             vscodium-agent.ts) works over `--host` SSH and on Linux.
+ *   - ghostty (macOS) → COARSE only: Ghostty has no scripting dictionary, so
+ *             there is no per-split addressing — this raises a window and types
+ *             via System Events keystrokes, stealing focus. The resolver refuses
+ *             to route here by default (see resolve.ts); it stays behind an
+ *             explicit opt-in.
+ *   - pty   → the `agents pty write` sidecar path (ptyRequest). Local-only —
+ *             the sidecar is not an engine transport surface.
+ *
+ * Ink-TUI Enter semantics: Claude's Ink TUI swallows an Enter fused to the text,
+ * so the default path delivers the text and the Enter as TWO SEPARATE writes
+ * (swarmify's `sendText(text,false)` then `sendText('\r',false)`). `combined`
+ * opts into one fused write for plain shells / REPLs.
+ */
+import { type HostResolver } from './transport.js';
+import { type LaunchSpec, type EngineContext } from './types.js';
+/**
+ * An already-running surface to type into. A superset of the engine's launch
+ * `Backend` — it adds `pty` (the sidecar), which the engine can't launch but can
+ * be injected into.
+ */
+export type InjectTarget = {
+    backend: 'tmux';
+    pane: string;
+    socket?: string;
+} | {
+    backend: 'iterm';
+    session?: string;
+}
+/**
+ * A VSCodium / Cursor / VS Code integrated terminal, addressed by the id the
+ * swarm-ext extension keys `live-terminals.json` on (the session UUID). `cli`
+ * is the editor CLI on PATH (`codium` / `cursor` / `code`); `scheme` is its
+ * URL scheme (`vscodium` / `cursor` / `vscode`) — the resolver fills both.
+ */
+ | {
+    backend: 'vscodium';
+    terminalId: string;
+    cli: string;
+    scheme: string;
+} | {
+    backend: 'ghostty';
+    window?: string;
+} | {
+    backend: 'pty';
+    id: string;
+};
+export type InjectBackend = InjectTarget['backend'];
+export interface InjectOptions {
+    /** Append Enter after the text. Default true. */
+    enter?: boolean;
+    /**
+     * Fuse the text and its Enter into a SINGLE write. Default false — the safe
+     * default sends the text, then the Enter, as two separate writes (Ink-TUI
+     * safe). Set true for plain shells / REPLs that want one atomic line.
+     */
+    combined?: boolean;
+    /** tmux socket override (defaults to `target.socket`, then tmux's default socket). */
+    socket?: string;
+    /** Remote host for the tmux / AppleScript backends (runs the spec over SSH). Local by default. */
+    host?: string;
+    /** Resolve a host alias to an ssh target (see the engine's transport). */
+    resolveHost?: HostResolver;
+    /** Ambient context for the availability check (defaults to the live process context). */
+    ctx?: EngineContext;
+    /** Don't execute — return the spec(s) that WOULD run. Lets the macOS paths be asserted on Linux. */
+    dryRun?: boolean;
+}
+export interface InjectResult {
+    ok: boolean;
+    backend: InjectBackend;
+    /** Discrete writes delivered: 2 for the Ink-safe text+Enter split, 1 when combined or enter=false. */
+    writes: number;
+    /** For the tmux / AppleScript backends (or any dryRun), the spec(s) that ran / would run. */
+    specs?: LaunchSpec[];
+    error?: string;
+}
+/**
+ * argv for `tmux send-keys` targeting a pane by id. Starts with `tmux` (like the
+ * engine's `tmuxTabArgv`) so the same transport runs it locally or over SSH. The
+ * socket, when set, is positioned before the subcommand (`-S` must lead). `-l`
+ * sends the keys literally; without it tmux interprets a key name like `Enter`.
+ *
+ * NOTE: distinct from `sendKeys()` in src/lib/tmux/session.ts — that one
+ * addresses by session *name* on the default socket (the `agents tmux` surface)
+ * and shells out directly; this one addresses by *pane id* + arbitrary socket and
+ * returns an SSH-capable `LaunchSpec` for the engine transport. Don't collapse them.
+ */
+export declare function tmuxSendKeysArgv(pane: string, keys: string, opts?: {
+    literal?: boolean;
+    socket?: string;
+}): string[];
+/** The one-or-two send-keys specs for a tmux injection (Ink-safe split by default). */
+export declare function tmuxInjectSpecs(target: Extract<InjectTarget, {
+    backend: 'tmux';
+}>, text: string, o: {
+    enter: boolean;
+    combined: boolean;
+    socket?: string;
+}): LaunchSpec[];
+/**
+ * AppleScript that types into a SPECIFIC iTerm2 split via `tell session id
+ * "<uuid>" to write text` — the exact split provenance's iterm rail identifies,
+ * addressed by its session UUID. Crucially there is NO `activate`: `write text`
+ * delivers to that session directly, so injection never brings iTerm forward or
+ * types into whatever split happens to be focused. Omitting `session` targets
+ * the current session (a direct-call convenience; the resolver always supplies
+ * one).
+ *
+ * Enter semantics — iTerm's `write text` appends a trailing newline, which fuses
+ * text+Enter into ONE write and Claude's Ink TUI swallows it. So the Ink-safe
+ * default (enter, not combined) suppresses that newline (`write text … newline
+ * no`) and sends the Return as a SEPARATE `write text` of a lone CR (`character
+ * id 13`) — two distinct pty writes, Enter seen on its own. `combined` opts into
+ * the single fused `write text` (auto-newline) for plain shells / REPLs.
+ *
+ * NOTE (macOS-only verification pending): the two-write CR path is the safe
+ * choice because it mirrors the tmux/pty Ink-safe split that IS verified here on
+ * Linux; whether a single `write text T` would also submit under Ink can only be
+ * confirmed on a Mac running iTerm (see the PR body).
+ */
+export declare function itermInjectScript(text: string, opts: {
+    session?: string;
+    enter: boolean;
+    combined?: boolean;
+}): string;
+/**
+ * AppleScript for Ghostty (no scripting dictionary): raise the target window via
+ * System Events, then keystroke the text and a separate Return. `window` matches
+ * a window whose title contains the string; omitted → the frontmost Ghostty window.
+ */
+export declare function ghosttyInjectScript(text: string, opts: {
+    window?: string;
+    enter: boolean;
+}): string;
+/** The osascript spec for a macOS injection. One invocation delivers the text + Return. */
+export declare function appleScriptInjectSpec(target: Extract<InjectTarget, {
+    backend: 'iterm' | 'ghostty';
+}>, text: string, enter: boolean, combined?: boolean): LaunchSpec;
+/**
+ * The `<scheme>://swarmify.swarm-ext/inject?p=<payload>` URL the extension
+ * handles to type into an ALREADY-open integrated terminal (the inject sibling
+ * of the launch backend's `/spawn`, src/lib/terminal/backends/vscodium-agent.ts).
+ *
+ * Payload is base64url-encoded JSON in a single `p` param — identical encoding
+ * to `spawnUri`, and for the same reason: VS Code percent-decodes `uri.query`
+ * once before the extension parses it, so a naive multi-param query would
+ * mis-split a text containing `&`/`=`; base64url (`[A-Za-z0-9_-]`) survives that
+ * decode untouched. `terminalId` is the id the extension keys live-terminals.json
+ * on (the session UUID); `enter` tells the extension to submit; `combined` asks
+ * it to fuse text+Enter into one write (default is the Ink-safe two-write split,
+ * mirroring the tmux/iterm paths — the extension owns that split on its side).
+ *
+ * DEPENDENCY: the `/inject` verb ships in the swarm-ext extension via PR #608's
+ * successor (PR #608 introduces `/spawn`; the inject verb + `write`/`enter`
+ * handling is its follow-up). Until that lands, this routes correctly on the CLI
+ * side but the extension will no-op the unknown verb. See the PR body.
+ */
+export declare function vscodiumInjectUri(scheme: string, terminalId: string, text: string, opts: {
+    enter: boolean;
+    combined: boolean;
+}): string;
+/** The editor-CLI spec for a VSCodium/Cursor/VS Code injection (one `--open-url` invocation). */
+export declare function vscodiumInjectSpec(target: Extract<InjectTarget, {
+    backend: 'vscodium';
+}>, text: string, opts: {
+    enter: boolean;
+    combined: boolean;
+}): LaunchSpec;
+/**
+ * Deliver `text` (+ Enter) into an existing terminal surface. Resolves the
+ * target's backend and routes to the matching primitive. Never throws — launch
+ * failures come back in the result, like the engine's `openSurface`.
+ */
+export declare function injectIntoTerminal(target: InjectTarget, text: string, opts?: InjectOptions): Promise<InjectResult>;

package/dist/lib/terminal/inject.js

@@ -0,0 +1,247 @@
+/**
+ * Terminal injection — Gap 2 of the Terminal Engine.
+ *
+ * Where the rest of the engine OPENS a surface (a tab / split running a
+ * command), injection types into an ALREADY-running surface. It's the primitive
+ * a native watchdog (RUSH-1415) needs to nudge a stalled agent with "continue"
+ * delivered into the exact terminal that agent lives in — the gap flagged in
+ * src/lib/session/provenance.ts:20:
+ *
+ *   > Actually delivering the keystrokes is Gap 2 (pty/tmux send-keys).
+ *
+ * It mirrors the engine's shape exactly: pure per-backend spec builders (like
+ * `tmuxTabArgv` / `itermTabScript`) produce a `LaunchSpec` (argv), and the same
+ * `runSpec` transport runs it — so injection inherits the engine's local/remote
+ * (`--host` over SSH) execution for free. A `LaunchSpec` never opens anything;
+ * building one is side-effect-free and unit-testable without a display.
+ *
+ * Backends (each addresses the EXACT split, not the frontmost surface):
+ *   - tmux  → `tmux send-keys -t <pane>` — the send-keys primitive addressed by
+ *             pane id + socket (the exact rail provenance.ts identifies).
+ *   - iterm (macOS) → AppleScript `tell session id "<uuid>" to write text` —
+ *             addresses the precise iTerm2 split by its session UUID WITHOUT
+ *             `activate`, so it never steals focus or types into the wrong split.
+ *             Uses the engine's `appleScriptStr` escaper; guarded by the iterm
+ *             backend's `isAvailable` (platform + app installed).
+ *   - vscodium (VSCodium / Cursor / VS Code) → the editor CLI's `--open-url`
+ *             into the swarmify `swarm-ext` extension's `/inject` verb, targeting
+ *             a live-terminals.json terminal by id. Focus-independent, exact
+ *             terminal, and (like the launch backend, src/lib/terminal/backends/
+ *             vscodium-agent.ts) works over `--host` SSH and on Linux.
+ *   - ghostty (macOS) → COARSE only: Ghostty has no scripting dictionary, so
+ *             there is no per-split addressing — this raises a window and types
+ *             via System Events keystrokes, stealing focus. The resolver refuses
+ *             to route here by default (see resolve.ts); it stays behind an
+ *             explicit opt-in.
+ *   - pty   → the `agents pty write` sidecar path (ptyRequest). Local-only —
+ *             the sidecar is not an engine transport surface.
+ *
+ * Ink-TUI Enter semantics: Claude's Ink TUI swallows an Enter fused to the text,
+ * so the default path delivers the text and the Enter as TWO SEPARATE writes
+ * (swarmify's `sendText(text,false)` then `sendText('\r',false)`). `combined`
+ * opts into one fused write for plain shells / REPLs.
+ */
+import { ptyRequest } from '../pty-client.js';
+import { appleScriptStr } from './quote.js';
+import { runSpec } from './transport.js';
+import { itermBackend, ghosttyBackend } from './backends/index.js';
+import { currentContext } from './types.js';
+/** Carriage return — what Enter delivers into a raw PTY/tmux byte stream. */
+const CR = '\r';
+// --- tmux -------------------------------------------------------------------
+/**
+ * argv for `tmux send-keys` targeting a pane by id. Starts with `tmux` (like the
+ * engine's `tmuxTabArgv`) so the same transport runs it locally or over SSH. The
+ * socket, when set, is positioned before the subcommand (`-S` must lead). `-l`
+ * sends the keys literally; without it tmux interprets a key name like `Enter`.
+ *
+ * NOTE: distinct from `sendKeys()` in src/lib/tmux/session.ts — that one
+ * addresses by session *name* on the default socket (the `agents tmux` surface)
+ * and shells out directly; this one addresses by *pane id* + arbitrary socket and
+ * returns an SSH-capable `LaunchSpec` for the engine transport. Don't collapse them.
+ */
+export function tmuxSendKeysArgv(pane, keys, opts = {}) {
+    const argv = ['tmux'];
+    if (opts.socket)
+        argv.push('-S', opts.socket);
+    argv.push('send-keys', '-t', pane);
+    if (opts.literal)
+        argv.push('-l');
+    argv.push(keys);
+    return argv;
+}
+/** The one-or-two send-keys specs for a tmux injection (Ink-safe split by default). */
+export function tmuxInjectSpecs(target, text, o) {
+    const socket = o.socket ?? target.socket;
+    if (o.enter && o.combined) {
+        return [{ argv: tmuxSendKeysArgv(target.pane, text + CR, { literal: true, socket }) }];
+    }
+    const specs = [{ argv: tmuxSendKeysArgv(target.pane, text, { literal: true, socket }) }];
+    // A separate Enter keypress — its own write, so the Ink TUI sees Enter alone.
+    if (o.enter)
+        specs.push({ argv: tmuxSendKeysArgv(target.pane, 'Enter', { socket }) });
+    return specs;
+}
+// --- macOS (iterm / ghostty) ------------------------------------------------
+/**
+ * AppleScript that types into a SPECIFIC iTerm2 split via `tell session id
+ * "<uuid>" to write text` — the exact split provenance's iterm rail identifies,
+ * addressed by its session UUID. Crucially there is NO `activate`: `write text`
+ * delivers to that session directly, so injection never brings iTerm forward or
+ * types into whatever split happens to be focused. Omitting `session` targets
+ * the current session (a direct-call convenience; the resolver always supplies
+ * one).
+ *
+ * Enter semantics — iTerm's `write text` appends a trailing newline, which fuses
+ * text+Enter into ONE write and Claude's Ink TUI swallows it. So the Ink-safe
+ * default (enter, not combined) suppresses that newline (`write text … newline
+ * no`) and sends the Return as a SEPARATE `write text` of a lone CR (`character
+ * id 13`) — two distinct pty writes, Enter seen on its own. `combined` opts into
+ * the single fused `write text` (auto-newline) for plain shells / REPLs.
+ *
+ * NOTE (macOS-only verification pending): the two-write CR path is the safe
+ * choice because it mirrors the tmux/pty Ink-safe split that IS verified here on
+ * Linux; whether a single `write text T` would also submit under Ink can only be
+ * confirmed on a Mac running iTerm (see the PR body).
+ */
+export function itermInjectScript(text, opts) {
+    // Two writes for the Ink-safe default; one fused write for combined / enter=false.
+    const body = opts.enter && opts.combined
+        ? [`write text ${appleScriptStr(text)}`]
+        : opts.enter
+            ? [`write text ${appleScriptStr(text)} newline no`, 'write text (character id 13) newline no']
+            : [`write text ${appleScriptStr(text)} newline no`];
+    const target = opts.session
+        ? `session id ${appleScriptStr(opts.session)}`
+        : 'current session of current window';
+    return [
+        'tell application "iTerm2"',
+        `  tell ${target}`,
+        ...body.map((l) => `    ${l}`),
+        '  end tell',
+        'end tell',
+    ].join('\n');
+}
+/**
+ * AppleScript for Ghostty (no scripting dictionary): raise the target window via
+ * System Events, then keystroke the text and a separate Return. `window` matches
+ * a window whose title contains the string; omitted → the frontmost Ghostty window.
+ */
+export function ghosttyInjectScript(text, opts) {
+    const lines = ['tell application "System Events"', '  tell process "ghostty"', '    set frontmost to true'];
+    if (opts.window) {
+        lines.push(`    perform action "AXRaise" of (first window whose title contains ${appleScriptStr(opts.window)})`);
+    }
+    lines.push('  end tell');
+    lines.push(`  keystroke ${appleScriptStr(text)}`);
+    if (opts.enter)
+        lines.push('  key code 36');
+    lines.push('end tell');
+    return lines.join('\n');
+}
+/** The osascript spec for a macOS injection. One invocation delivers the text + Return. */
+export function appleScriptInjectSpec(target, text, enter, combined = false) {
+    const script = target.backend === 'iterm'
+        ? itermInjectScript(text, { session: target.session, enter, combined })
+        : ghosttyInjectScript(text, { window: target.window, enter });
+    return { argv: ['osascript', '-e', script] };
+}
+// --- vscodium (VSCodium / Cursor / VS Code integrated terminal) -------------
+/** The swarmify extension identifier that owns the swarm-ext URI verbs (matches the launch backend). */
+const EXTENSION_AUTHORITY = 'swarmify.swarm-ext';
+/**
+ * The `<scheme>://swarmify.swarm-ext/inject?p=<payload>` URL the extension
+ * handles to type into an ALREADY-open integrated terminal (the inject sibling
+ * of the launch backend's `/spawn`, src/lib/terminal/backends/vscodium-agent.ts).
+ *
+ * Payload is base64url-encoded JSON in a single `p` param — identical encoding
+ * to `spawnUri`, and for the same reason: VS Code percent-decodes `uri.query`
+ * once before the extension parses it, so a naive multi-param query would
+ * mis-split a text containing `&`/`=`; base64url (`[A-Za-z0-9_-]`) survives that
+ * decode untouched. `terminalId` is the id the extension keys live-terminals.json
+ * on (the session UUID); `enter` tells the extension to submit; `combined` asks
+ * it to fuse text+Enter into one write (default is the Ink-safe two-write split,
+ * mirroring the tmux/iterm paths — the extension owns that split on its side).
+ *
+ * DEPENDENCY: the `/inject` verb ships in the swarm-ext extension via PR #608's
+ * successor (PR #608 introduces `/spawn`; the inject verb + `write`/`enter`
+ * handling is its follow-up). Until that lands, this routes correctly on the CLI
+ * side but the extension will no-op the unknown verb. See the PR body.
+ */
+export function vscodiumInjectUri(scheme, terminalId, text, opts) {
+    const payload = { terminalId, text, enter: opts.enter, combined: opts.combined };
+    const p = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+    return `${scheme}://${EXTENSION_AUTHORITY}/inject?p=${p}`;
+}
+/** The editor-CLI spec for a VSCodium/Cursor/VS Code injection (one `--open-url` invocation). */
+export function vscodiumInjectSpec(target, text, opts) {
+    return { argv: [target.cli, '--open-url', vscodiumInjectUri(target.scheme, target.terminalId, text, opts)] };
+}
+// --- pty --------------------------------------------------------------------
+async function injectPty(target, text, o) {
+    if (o.host && o.host !== 'local') {
+        return { ok: false, backend: 'pty', writes: 0, error: 'pty injection is local-only (the sidecar is not a remote surface)' };
+    }
+    // Same Ink-safe split as tmux: text write, then a separate CR write.
+    const writes = o.enter && o.combined ? [text + CR] : o.enter ? [text, CR] : [text];
+    if (o.dryRun)
+        return { ok: true, backend: 'pty', writes: writes.length };
+    try {
+        for (const input of writes) {
+            const res = await ptyRequest('write', target.id, { input });
+            if (!res.ok)
+                return { ok: false, backend: 'pty', writes: 0, error: res.error ?? 'pty write failed' };
+        }
+        return { ok: true, backend: 'pty', writes: writes.length };
+    }
+    catch (err) {
+        return { ok: false, backend: 'pty', writes: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+// --- public entry -----------------------------------------------------------
+/**
+ * Deliver `text` (+ Enter) into an existing terminal surface. Resolves the
+ * target's backend and routes to the matching primitive. Never throws — launch
+ * failures come back in the result, like the engine's `openSurface`.
+ */
+export async function injectIntoTerminal(target, text, opts = {}) {
+    const enter = opts.enter !== false;
+    const combined = opts.combined === true;
+    if (target.backend === 'pty') {
+        return injectPty(target, text, { enter, combined, host: opts.host, dryRun: opts.dryRun });
+    }
+    // tmux + AppleScript + editor-CLI backends all run through the engine transport.
+    const specs = target.backend === 'tmux'
+        ? tmuxInjectSpecs(target, text, { enter, combined, socket: opts.socket })
+        : target.backend === 'vscodium'
+            ? [vscodiumInjectSpec(target, text, { enter, combined })]
+            : [appleScriptInjectSpec(target, text, enter, combined)];
+    // Discrete writes delivered on the far side. tmux counts its send-keys calls.
+    // iterm/vscodium honor `combined` (text+Enter fused into one write). ghostty's
+    // coarse keystroke path ignores `combined` (it always emits keystroke + a
+    // separate Return), so its count tracks `enter` alone.
+    const writes = target.backend === 'tmux'
+        ? specs.length
+        : target.backend === 'ghostty'
+            ? enter ? 2 : 1
+            : enter && !combined ? 2 : 1;
+    if (opts.dryRun)
+        return { ok: true, backend: target.backend, writes, specs };
+    // AppleScript backends: guard on the backend's own availability, but only for a
+    // LOCAL run (a remote host is assumed to have the app — its ssh leg reports failure).
+    if (target.backend === 'iterm' || target.backend === 'ghostty') {
+        if (!opts.host || opts.host === 'local') {
+            const backend = target.backend === 'iterm' ? itermBackend : ghosttyBackend;
+            const ctx = opts.ctx ?? currentContext();
+            if (!backend.isAvailable(ctx)) {
+                return { ok: false, backend: target.backend, writes: 0, specs, error: `${backend.label} is not available here (platform ${ctx.platform})` };
+            }
+        }
+    }
+    for (const spec of specs) {
+        const res = await runSpec(spec, opts.host, opts.resolveHost);
+        if (!res.ok)
+            return { ok: false, backend: target.backend, writes: 0, specs, error: res.error };
+    }
+    return { ok: true, backend: target.backend, writes, specs };
+}

package/dist/lib/terminal/resolve.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Inject-target resolution — the safety choke point (RUSH-1415).
+ *
+ * The watchdog knows a session has stalled and wants to nudge it with "continue".
+ * `injectIntoTerminal` (inject.ts) can DELIVER into a target; this module decides
+ * the RIGHT target for a given sessionId — the exact split the agent lives in —
+ * and NEVER guesses. If it can't name a precise rail it returns `addressable:
+ * false` with a reason, and the watchdog skips rather than typing into the
+ * frontmost / wrong split.
+ *
+ * Resolution reads the agent's INHERITED ENV (via session provenance) plus the
+ * IDE's live-terminals registry (off disk) — no cooperation from the agent:
+ *
+ *   tmux  > iterm > vscodium > pty
+ *
+ * tmux wins whenever present: a `tmux send-keys -t <pane>` reaches the pane no
+ * matter which host app (iTerm / Ghostty / VS Code) is above it, so it's correct
+ * inside ANY of them. Absent tmux, the host-app rail: iTerm2's exact split by
+ * session UUID (env), or a VSCodium/Cursor/VS Code integrated terminal addressed
+ * by its live-terminals id. Ghostty has no per-split addressing (no scripting
+ * dictionary), so a Ghostty-hosted session with no tmux is honestly reported
+ * un-addressable — the coarse focus-stealing window path stays behind an explicit
+ * opt-in and is never chosen by default.
+ */
+import type { ActiveSession } from '../session/active.js';
+import type { InjectTarget } from './inject.js';
+/** A resolved rail, or an honest refusal. The watchdog acts only on `addressable: true`. */
+export type InjectRail = 'tmux' | 'iterm' | 'vscodium' | 'ghostty' | 'pty';
+export type InjectResolution = {
+    addressable: true;
+    rail: InjectRail;
+    target: InjectTarget;
+    note?: string;
+} | {
+    addressable: false;
+    reason: string;
+};
+export interface ResolveOptions {
+    /**
+     * Allow the COARSE Ghostty path (raise the frontmost/opt-in window and type via
+     * System Events keystrokes — steals focus, not split-precise). Off by default:
+     * a Ghostty session with no tmux resolves to un-addressable instead.
+     */
+    allowGhosttyFocus?: boolean;
+    /**
+     * A known `agents pty` sidecar id for this session, if the caller has one. No
+     * automatic sessionId -> pty mapping exists yet, so pty is only emitted when
+     * supplied here (the lowest-precedence rail).
+     */
+    ptyId?: string;
+}
+/**
+ * Resolve a target from an already-fetched ActiveSession. Pure — no I/O — so the
+ * precedence logic is unit-testable without the process table. This is where the
+ * tmux > iterm > vscodium > pty precedence and the Ghostty refusal live.
+ */
+export declare function resolveInjectTargetForSession(session: ActiveSession, opts?: ResolveOptions): InjectResolution;
+/**
+ * The single resolver the watchdog calls: sessionId -> a precise InjectTarget or
+ * an honest refusal. Fetches the active session (which carries provenance, host,
+ * and pid), then applies the pure precedence above. Returns `addressable: false`
+ * when the session isn't live / can't be found — never a guess.
+ */
+export declare function resolveInjectTarget(sessionId: string, opts?: ResolveOptions): Promise<InjectResolution>;

package/dist/lib/terminal/resolve.js

@@ -0,0 +1,90 @@
+import { getActiveSessions } from '../session/active.js';
+/** The editor CLIs that speak the swarm-ext URI protocol, keyed by the host detectHost() reports. */
+const IDE_INJECT_VARIANTS = {
+    codium: { cli: 'codium', scheme: 'vscodium' },
+    cursor: { cli: 'cursor', scheme: 'cursor' },
+    code: { cli: 'code', scheme: 'vscode' },
+};
+/**
+ * Resolve a target from an already-fetched ActiveSession. Pure — no I/O — so the
+ * precedence logic is unit-testable without the process table. This is where the
+ * tmux > iterm > vscodium > pty precedence and the Ghostty refusal live.
+ */
+export function resolveInjectTargetForSession(session, opts = {}) {
+    const prov = session.provenance;
+    // 1. tmux — correct inside any host app, so it takes precedence whenever the
+    //    env carries a pane. (provenance.reply already encodes tmux-over-iterm.)
+    if (prov?.mux?.kind === 'tmux' && prov.mux.pane) {
+        return {
+            addressable: true,
+            rail: 'tmux',
+            target: { backend: 'tmux', pane: prov.mux.pane, socket: prov.mux.socket },
+        };
+    }
+    // 2. iterm — the exact split by session UUID (env-derived, focus-safe).
+    if (prov?.reply?.rail === 'iterm') {
+        return {
+            addressable: true,
+            rail: 'iterm',
+            target: { backend: 'iterm', session: prov.reply.session },
+        };
+    }
+    // 3. vscodium — a VSCodium/Cursor/VS Code integrated terminal, addressed by the
+    //    id the extension keys live-terminals.json on (the session UUID). Only when
+    //    the session is IDE-hosted AND we know its id.
+    const variant = session.host ? IDE_INJECT_VARIANTS[session.host] : undefined;
+    if (variant) {
+        if (!session.sessionId) {
+            return { addressable: false, reason: `IDE terminal (${session.host}) has no session id to address` };
+        }
+        return {
+            addressable: true,
+            rail: 'vscodium',
+            target: { backend: 'vscodium', terminalId: session.sessionId, cli: variant.cli, scheme: variant.scheme },
+        };
+    }
+    // 4. pty — lowest precedence, only when the caller supplied a sidecar id.
+    if (opts.ptyId) {
+        return { addressable: true, rail: 'pty', target: { backend: 'pty', id: opts.ptyId } };
+    }
+    // 5. Ghostty — no per-split addressing exists. Refuse by default; the coarse,
+    //    focus-stealing window path is opt-in only.
+    if (session.host === 'ghostty') {
+        if (opts.allowGhosttyFocus) {
+            return {
+                addressable: true,
+                rail: 'ghostty',
+                target: { backend: 'ghostty' },
+                note: 'coarse Ghostty window path (opt-in): raises a window and types into the FOCUSED split — not split-precise',
+            };
+        }
+        return { addressable: false, reason: 'un-addressable (ghostty, no tmux): no per-split addressing; watchdog skips' };
+    }
+    return {
+        addressable: false,
+        reason: session.host
+            ? `no precise inject rail for host '${session.host}' (no tmux/iterm/IDE terminal detected)`
+            : 'no inject rail: session is not inside tmux, iTerm, or an IDE terminal',
+    };
+}
+/**
+ * The single resolver the watchdog calls: sessionId -> a precise InjectTarget or
+ * an honest refusal. Fetches the active session (which carries provenance, host,
+ * and pid), then applies the pure precedence above. Returns `addressable: false`
+ * when the session isn't live / can't be found — never a guess.
+ */
+export async function resolveInjectTarget(sessionId, opts = {}) {
+    if (!sessionId)
+        return { addressable: false, reason: 'no sessionId given' };
+    let sessions;
+    try {
+        sessions = await getActiveSessions();
+    }
+    catch (err) {
+        return { addressable: false, reason: `could not list active sessions: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const session = sessions.find((s) => s.sessionId === sessionId);
+    if (!session)
+        return { addressable: false, reason: `no live session found for id ${sessionId}` };
+    return resolveInjectTargetForSession(session, opts);
+}

package/dist/lib/terminal/types.d.ts

@@ -8,7 +8,7 @@
  * is attended and live. See docs/terminal-engine.md.
  */
 /** An interactive terminal backend the engine can drive. */
-export type Backend = 'iterm' | 'ghostty' | 'tmux';
+export type Backend = 'iterm' | 'ghostty' | 'tmux' | 'vscodium-agent';
 /** Which way a split pane grows. `right` = side-by-side; `down` = stacked. */
 export type SplitDirection = 'right' | 'down';
 /** Where a surface lands: a new tab, or a split of the current pane. */