@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/terminal/inject.js

@@ -1,88 +1,16 @@
-/**
- * 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
- * (`--device` 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 `--device` 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.
- *
- * 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 { appleScriptStr } from './quote.js';
 import { runSpec } from './transport.js';
 import { itermBackend, ghosttyBackend } from './backends/index.js';
 import { currentContext } from './types.js';
-/**
- * Whether a successful transport on this backend CONFIRMS delivery to the agent.
- * Everything but vscodium self-confirms (see InjectResult.confirmed); vscodium's
- * `--open-url` is fire-and-forget until the swarm-ext extension acks the verb.
- */
 function backendConfirmsDelivery(backend) {
     return backend !== 'vscodium';
 }
-/** Carriage return — what Enter delivers into a raw PTY/tmux byte stream. */
 const CR = '\r';
-/**
- * Bracketed-paste framing (DEC mode 2004) — the pty contract for "insert this
- * verbatim, do not submit". A readline/Ink composer that sees the start marker
- * buffers every byte up to the end marker, so an embedded newline lands as a
- * literal newline in the draft instead of submitting the partial line.
- */
 export const BRACKETED_PASTE_START = '\u001b[200~';
 export const BRACKETED_PASTE_END = '\u001b[201~';
-/**
- * Only tmux can carry the framing: `send-keys -l` writes the marker bytes
- * straight to the pty. ghostty simulates keystrokes, vscodium hands a JSON
- * payload to the extension, and iTerm's AppleScript `write text` cannot encode
- * a raw ESC byte — so a paste request on those is refused rather than
- * half-delivered as one submit per line.
- */
 export function backendCarriesPaste(backend) {
     return backend === 'tmux';
 }
-// --- 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)
@@ -93,42 +21,17 @@ export function tmuxSendKeysArgv(pane, keys, opts = {}) {
     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
@@ -145,11 +48,6 @@ export function itermInjectScript(text, opts) {
         '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) {
@@ -162,55 +60,24 @@ export function ghosttyInjectScript(text, opts) {
     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)] };
 }
-// --- 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;
-    // Fail loud at the rail boundary: a backend that cannot carry the markers must
-    // not silently deliver the raw text, which submits once per embedded newline.
     if (opts.paste === true && !backendCarriesPaste(target.backend)) {
         return {
             ok: false, confirmed: false, backend: target.backend, writes: 0, started: 0, specs: [],
@@ -218,16 +85,11 @@ export async function injectIntoTerminal(target, text, opts = {}) {
         };
     }
     const payload = opts.paste === true ? `${BRACKETED_PASTE_START}${text}${BRACKETED_PASTE_END}` : text;
-    // tmux + AppleScript + editor-CLI backends all run through the engine transport.
     const specs = target.backend === 'tmux'
         ? tmuxInjectSpecs(target, payload, { enter, combined, socket: opts.socket })
         : target.backend === 'vscodium'
             ? [vscodiumInjectSpec(target, payload, { enter, combined })]
             : [appleScriptInjectSpec(target, payload, 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'
@@ -236,8 +98,6 @@ export async function injectIntoTerminal(target, text, opts = {}) {
     const confirmed = backendConfirmsDelivery(target.backend);
     if (opts.dryRun)
         return { ok: true, confirmed, backend: target.backend, writes, started: 0, 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;
@@ -251,9 +111,6 @@ export async function injectIntoTerminal(target, text, opts = {}) {
     let sent = 0;
     let started = 0;
     for (const spec of specs) {
-        // Never START a spec the budget can no longer cover. Racing the caller's
-        // promise instead let a write begin AFTER the operator had already been told
-        // the answer timed out.
         const remaining = endMs === undefined ? undefined : endMs - Date.now();
         if (remaining !== undefined && remaining <= 0) {
             return {
@@ -264,9 +121,6 @@ export async function injectIntoTerminal(target, text, opts = {}) {
         started += 1;
         const res = await runSpec(spec, opts.host, opts.resolveHost, remaining);
         if (!res.ok) {
-            // `writes` counts specs that COMPLETED; `started` counts specs that began.
-            // The failing spec may have written bytes before dying, so the caller must
-            // branch on `started`, not on `writes`.
             return { ok: false, confirmed: false, backend: target.backend, writes: sent, started, specs, error: res.error };
         }
         sent += 1;

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

@@ -1,11 +1,3 @@
-/**
- * Layout policy — how a batch of surfaces is arranged.
- *
- * `two-per-tab` (default) packs sessions two-up: session 1 opens a new tab,
- * session 2 splits it (right), session 3 opens a new tab, and so on — so each
- * tab holds a left+right pair. `tabs` gives every session its own tab.
- */
 import type { Layout } from './types.js';
 export type Packing = 'two-per-tab' | 'tabs';
-/** Assign a layout to each index in a batch of `count` surfaces. */
 export declare function planLayouts(count: number, packing?: Packing): Layout[];

package/dist/lib/terminal/policy.js

@@ -1,4 +1,3 @@
-/** Assign a layout to each index in a batch of `count` surfaces. */
 export function planLayouts(count, packing = 'two-per-tab') {
     const out = [];
     for (let i = 0; i < count; i++) {

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

@@ -1,89 +1,23 @@
-/**
- * Which terminal to launch a NEW surface into, for callers that aren't in one.
- *
- * `detectCurrentBackend` answers this from `$TMUX` / `$TERM_PROGRAM`, which is
- * correct for a command the user typed in a terminal — and useless to a GUI
- * caller. The menu-bar helper is launched by launchd with no terminal in its
- * ancestry, so it used to hardcode AppleScript against Terminal.app and opened
- * every "New Session" there no matter what the user actually works in.
- *
- * The signal it was missing is already on disk: `agents sessions --active`
- * attributes every live session to its host app (`ActiveSession.host`, resolved
- * by walking the process table in session/active.ts). So the terminal the user
- * demonstrably runs agents in is the terminal a new session should open in —
- * that's what this module resolves, and it is the reason the menu bar now opens
- * Ghostty for a Ghostty user and iTerm for an iTerm user.
- *
- * Resolution order (each step is skipped when it names nothing DRIVABLE here):
- *   1. the terminal this process is running in   -> 'current-terminal'
- *   2. the host app of the most recent live session -> 'active-session'
- *   3. the first available backend (Terminal.app is the every-Mac floor) -> 'available'
- */
 import type { Backend, EngineContext } from './types.js';
-/**
- * `ActiveSession.host` -> the backend that can open a new surface in it.
- *
- * Deliberately partial. A host is listed ONLY when the engine can really drive
- * it, because a wrong mapping opens the wrong app and looks like success:
- *   - `code` / `cursor` / `windsurf` are absent even though the engine has an
- *     editor backend — the registered `vscodium-agent` is bound to the VSCodium
- *     variant (backends/vscodium-agent.ts: `EDITOR_VARIANTS[0]`), so mapping
- *     Cursor to it would open VSCodium instead of Cursor.
- *   - `warp` / `kitty` / `wezterm` / `alacritty` / `hyper` / `screen` are absent
- *     because no backend drives them yet.
- * An unmapped host isn't an error — resolution simply moves to the next session,
- * and ultimately to the available-backend floor.
- */
 export declare const SESSION_HOST_BACKENDS: Readonly<Record<string, Backend>>;
-/** The subset of an ActiveSession this resolver reads. */
 export interface SessionHostSample {
     host?: string;
-    /**
-     * For a tmux-hosted session: the app its attached tmux client is in
-     * (`ActiveSession.viewingIn.app`). This is load-bearing, not a nicety —
-     * `agents run` wraps interactive runs in tmux, so a session the user started
-     * in Ghostty is attributed `host: 'tmux'` and the terminal it is actually
-     * displayed in is only knowable through the attached client. Takes precedence
-     * over `host`, which for these sessions names the multiplexer, not a terminal.
-     */
     viewingApp?: string;
     lastActivityMs?: number;
     startedAtMs?: number;
 }
-/** Where the chosen backend came from — reported so a caller can say why. */
 export type BackendSource = 'forced' | 'current-terminal' | 'active-session' | 'available';
 export interface LaunchBackendChoice {
     backend: Backend;
     source: BackendSource;
-    /** The `ActiveSession.host` that selected it, when source is 'active-session'. */
     host?: string;
 }
-/**
- * Injection seam so the PRECEDENCE is testable without the machine's installed
- * apps. `isAvailable` for iterm/ghostty/terminal probes `/Applications`, so a
- * test that just passes `platform: 'darwin'` silently depends on the host having
- * those apps — it passes on a dev Mac and fails on a Linux CI runner. Same shape
- * as `ViewingInDeps` in session/viewing-in.ts.
- */
 export interface BackendResolveDeps {
-    /** Defaults to the real backend availability probe. */
     isAvailable?: (backend: Backend, ctx: EngineContext) => boolean;
 }
-/**
- * The backend for the terminal the user's most recent live session runs in, or
- * null when no live session names a host this engine can drive. Pure — the
- * caller supplies the sessions, so the precedence is unit-testable without a
- * process table.
- */
 export declare function backendFromSessions(sessions: SessionHostSample[], ctx: EngineContext, deps?: BackendResolveDeps): {
     backend: Backend;
     host: string;
 } | null;
-/**
- * Resolve the terminal to open a new surface in. Pure. Returns null when this
- * machine has no drivable terminal at all (Linux with no tmux, an SSH session),
- * which callers must handle — never a guess that silently goes nowhere.
- */
 export declare function resolveLaunchBackend(ctx: EngineContext, sessions?: SessionHostSample[], deps?: BackendResolveDeps): LaunchBackendChoice | null;
-/** One line explaining a choice, for the `agents run --terminal` preamble. */
 export declare function describeBackendChoice(choice: LaunchBackendChoice): string;

package/dist/lib/terminal/preferred.js

@@ -1,18 +1,4 @@
 import { BACKENDS, detectCurrentBackend } from './backends/index.js';
-/**
- * `ActiveSession.host` -> the backend that can open a new surface in it.
- *
- * Deliberately partial. A host is listed ONLY when the engine can really drive
- * it, because a wrong mapping opens the wrong app and looks like success:
- *   - `code` / `cursor` / `windsurf` are absent even though the engine has an
- *     editor backend — the registered `vscodium-agent` is bound to the VSCodium
- *     variant (backends/vscodium-agent.ts: `EDITOR_VARIANTS[0]`), so mapping
- *     Cursor to it would open VSCodium instead of Cursor.
- *   - `warp` / `kitty` / `wezterm` / `alacritty` / `hyper` / `screen` are absent
- *     because no backend drives them yet.
- * An unmapped host isn't an error — resolution simply moves to the next session,
- * and ultimately to the available-backend floor.
- */
 export const SESSION_HOST_BACKENDS = Object.freeze({
     iterm: 'iterm',
     ghostty: 'ghostty',
@@ -20,28 +6,18 @@ export const SESSION_HOST_BACKENDS = Object.freeze({
     tmux: 'tmux',
     codium: 'vscodium-agent',
 });
-/** Most recent first. Falls back to start time, then to the given order. */
 function byRecency(a, b) {
     const at = a.lastActivityMs ?? a.startedAtMs ?? 0;
     const bt = b.lastActivityMs ?? b.startedAtMs ?? 0;
     return bt - at;
 }
 const realIsAvailable = (backend, ctx) => BACKENDS[backend].isAvailable(ctx);
-/**
- * The backend for the terminal the user's most recent live session runs in, or
- * null when no live session names a host this engine can drive. Pure — the
- * caller supplies the sessions, so the precedence is unit-testable without a
- * process table.
- */
 export function backendFromSessions(sessions, ctx, deps = {}) {
     const isAvailable = deps.isAvailable ?? realIsAvailable;
     for (const s of [...sessions].sort(byRecency)) {
-        // The app an attached tmux client is in beats the multiplexer name.
         const host = s.viewingApp ?? s.host;
         if (!host)
             continue;
-        // hasOwn, not a bare index: the host is data, and `SESSION_HOST_BACKENDS['constructor']`
-        // would otherwise hand back a prototype member that BACKENDS cannot key on.
         if (!Object.hasOwn(SESSION_HOST_BACKENDS, host))
             continue;
         const backend = SESSION_HOST_BACKENDS[host];
@@ -53,11 +29,6 @@ export function backendFromSessions(sessions, ctx, deps = {}) {
     }
     return null;
 }
-/**
- * Resolve the terminal to open a new surface in. Pure. Returns null when this
- * machine has no drivable terminal at all (Linux with no tmux, an SSH session),
- * which callers must handle — never a guess that silently goes nowhere.
- */
 export function resolveLaunchBackend(ctx, sessions = [], deps = {}) {
     const isAvailable = deps.isAvailable ?? realIsAvailable;
     const current = detectCurrentBackend(ctx);
@@ -71,7 +42,6 @@ export function resolveLaunchBackend(ctx, sessions = [], deps = {}) {
     const first = Object.keys(BACKENDS).find((b) => isAvailable(b, ctx));
     return first ? { backend: first, source: 'available' } : null;
 }
-/** One line explaining a choice, for the `agents run --terminal` preamble. */
 export function describeBackendChoice(choice) {
     const label = BACKENDS[choice.backend].label;
     switch (choice.source) {

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

@@ -1,11 +1,3 @@
-/**
- * Quoting helpers for building launch commands.
- *
- * `shellQuote` is the single canonical POSIX single-quoter, re-exported from the
- * SSH transport so the local and remote legs quote identically. `appleScriptStr`
- * is the AppleScript string-literal escaper used by the iTerm/Ghostty backends.
- */
 import { shellQuote } from '../ssh-exec.js';
 export { shellQuote };
-/** AppleScript double-quoted string literal (escape backslash, then quote). */
 export declare function appleScriptStr(s: string): string;

package/dist/lib/terminal/quote.js

@@ -1,13 +1,5 @@
-/**
- * Quoting helpers for building launch commands.
- *
- * `shellQuote` is the single canonical POSIX single-quoter, re-exported from the
- * SSH transport so the local and remote legs quote identically. `appleScriptStr`
- * is the AppleScript string-literal escaper used by the iTerm/Ghostty backends.
- */
 import { shellQuote } from '../ssh-exec.js';
 export { shellQuote };
-/** AppleScript double-quoted string literal (escape backslash, then quote). */
 export function appleScriptStr(s) {
     return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }

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

@@ -1,30 +1,5 @@
-/**
- * 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
- *
- * 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';
 export type InjectResolution = {
     addressable: true;
@@ -37,29 +12,8 @@ export type InjectResolution = {
     hint?: 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;
 }
-/**
- * Human-facing recovery hint for a session the resolver judged un-addressable.
- * Tells the user both how to continue THIS session and how to make FUTURE runs
- * addressable, so the failure is not silent and the fix is actionable.
- */
 export declare function addressabilityRecoveryHint(session: ActiveSession, fallbackId?: string): 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 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

@@ -1,23 +1,12 @@
 import { getActiveSessions } from '../session/active.js';
 import { machineId } from '../machine-id.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' },
 };
-/**
- * Human-facing recovery hint for a session the resolver judged un-addressable.
- * Tells the user both how to continue THIS session and how to make FUTURE runs
- * addressable, so the failure is not silent and the fix is actionable.
- */
 export function addressabilityRecoveryHint(session, fallbackId) {
     const sid = session.sessionId;
-    // Branch on the live sessionId (an IDE terminal that has not registered one
-    // yet is a distinct message), but render the resume command with the real id
-    // when the caller can supply it — e.g. `focus` has meta.id even though the
-    // live row's sessionId is falsy, so without this the hint printed a useless
-    // `agents sessions resume <id>` placeholder in exactly that case (PHNX-3070).
     const resumeId = sid ?? fallbackId;
     const shortId = resumeId ? resumeId.slice(0, 8) : '<id>';
     const device = session.machine ?? machineId();
@@ -35,15 +24,8 @@ export function addressabilityRecoveryHint(session, fallbackId) {
     }
     return `This session has no addressable terminal rail (not tmux, iTerm, or an IDE terminal). ${interactive ? `Enable tmux wrapping with \`${tmuxCmd}\` and re-launch, or ` : ''}use \`${resumeCmd}\` to continue this session.`;
 }
-/**
- * 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 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,
@@ -51,7 +33,6 @@ export function resolveInjectTargetForSession(session, opts = {}) {
             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,
@@ -59,9 +40,6 @@ export function resolveInjectTargetForSession(session, opts = {}) {
             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) {
@@ -77,8 +55,6 @@ export function resolveInjectTargetForSession(session, opts = {}) {
             target: { backend: 'vscodium', terminalId: session.sessionId, cli: variant.cli, scheme: variant.scheme },
         };
     }
-    // 4. 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 {
@@ -102,12 +78,6 @@ export function resolveInjectTargetForSession(session, opts = {}) {
         hint: addressabilityRecoveryHint(session),
     };
 }
-/**
- * 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' };