@phnx-labs/agents-cli 1.22.115 → 1.22.116

package/dist/lib/session/tail.js

@@ -73,3 +73,222 @@ export function readSessionTailWithRaw(filePath, agent, maxBytes = DEFAULT_MAX_B
 export function readSessionTail(filePath, agent, maxBytes = DEFAULT_MAX_BYTES, maxEvents = DEFAULT_MAX_EVENTS) {
     return readSessionTailWithRaw(filePath, agent, maxBytes, maxEvents).events;
 }
+/** A session's original first turn is typically within the first few KiB —
+ * far smaller than the tail window, since it's exactly one line near the
+ * start of the file, not a rolling window of recent activity. */
+const DEFAULT_HEAD_MAX_BYTES = 32 * 1024;
+/**
+ * Read exactly the first `maxBytes` of the file and, if that chunk doesn't
+ * reach EOF, drop a trailing partial line so downstream per-line parsers only
+ * see whole lines. This is the plain, cheap path — correct and unchanged for
+ * the overwhelming majority of transcripts, where the opening JSONL record is
+ * a few hundred bytes. Returns '' on any error, an empty file, or a chunk that
+ * turned out to hold no complete line at all (the record is bigger than
+ * `maxBytes`) — callers needing to recover from THAT case use
+ * {@link readSessionHeadContentBounded}, not this.
+ */
+function readSessionHeadChunk(filePath, maxBytes) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const size = fs.fstatSync(fd).size;
+        if (size === 0)
+            return { content: '', sawEof: true };
+        const len = Math.min(size, maxBytes);
+        const buf = Buffer.alloc(len);
+        fs.readSync(fd, buf, 0, len, 0);
+        return { content: buf.toString('utf8'), sawEof: len >= size };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Read the FIRST `maxBytes` of a JSONL transcript as cleaned text — the mirror
+ * of {@link readSessionTailContent}, for recovering the session's ACTUAL
+ * original request boundedly when it isn't already indexed
+ * (`SessionMeta.firstUserMessage`). Returns '' on any error, an empty file, or
+ * a first record too large to fit `maxBytes` (bare — no elision fallback; see
+ * {@link readSessionHeadContentBounded} for that).
+ */
+export function readSessionHeadContent(filePath, maxBytes = DEFAULT_HEAD_MAX_BYTES) {
+    const chunk = readSessionHeadChunk(filePath, maxBytes);
+    if (!chunk)
+        return '';
+    let content = chunk.content;
+    if (!chunk.sawEof) {
+        // Didn't reach EOF: the last line in this chunk may be a partial write
+        // of a longer record. Keep only whole lines.
+        const lastNl = content.lastIndexOf('\n');
+        content = lastNl >= 0 ? content.slice(0, lastNl) : '';
+    }
+    return content;
+}
+/**
+ * Hard ceiling on how far {@link readSessionHeadContentBounded} will read
+ * looking for the opening record's closing newline. A JSONL record is one
+ * line, so a user turn that embeds a multi-megabyte image (base64, inline in
+ * the same `"data": "..."` string) can push that line's own terminator
+ * arbitrarily far past the plain {@link DEFAULT_HEAD_MAX_BYTES} chunk — this
+ * is the point past which the record is treated as unrecoverable (`partial`),
+ * never guessed at from a truncated fragment.
+ */
+const HEAD_ELISION_MAX_READ_BYTES = 4 * 1024 * 1024;
+/** Keep at most this many UTF-16 units of any single JSON string value
+ * verbatim; the remainder is replaced with a short marker. Bounds the ELIDED
+ * OUTPUT size independent of how large the source string (an image's base64
+ * payload can be tens of megabytes) actually is, while staying far larger
+ * than any real first-turn text block ever needs to be. */
+const HEAD_ELISION_STRING_KEEP_UNITS = 2048;
+/** Wall-clock ceiling on the elision scan itself. The scan runs over data
+ * already bounded by {@link HEAD_ELISION_MAX_READ_BYTES} and does O(1) work
+ * per character, so this should never trip in practice — it exists as a
+ * defense-in-depth budget, not the primary bound. */
+const HEAD_ELISION_MAX_MS = 200;
+/** How many characters the elision scan advances between wall-clock checks —
+ * frequent enough that the time budget above is actually honored, infrequent
+ * enough that `Date.now()` isn't on the hot path of every character. */
+const HEAD_ELISION_TIME_CHECK_MASK = 0x3ffff; // every ~262k chars
+/**
+ * A single-pass, JSON-string-aware elision scan: copies `input` verbatim
+ * except inside a string literal whose content exceeds
+ * {@link HEAD_ELISION_STRING_KEEP_UNITS}, where it keeps a short prefix and
+ * splices in a `…[elided N chars]` marker for the rest — but still tracks
+ * escape/quote state through to that string's real closing quote, so
+ * surrounding JSON structure (a text block that follows an oversized image
+ * block in the same content array) stays syntactically valid. This is a
+ * generic JSON-string eliser, not an image-specific one: it does not care
+ * WHAT is inside the oversized string, only that it is too large to keep.
+ *
+ * `deadlineMs` is an absolute `Date.now()` value. `truncatedByBudget: true`
+ * means the scan did not finish (ran out of time) — critically, the output
+ * up to that point NEVER includes the unflushed tail of a string that had
+ * already crossed the elision threshold (the flush happens once, the moment
+ * the threshold is crossed, not at the closing quote), so a cutoff mid-scan
+ * can never smuggle megabytes of un-elided content into the result.
+ */
+function elideOversizedJsonStrings(input, deadlineMs) {
+    const outParts = [];
+    let spanStart = 0;
+    let inString = false;
+    let escaped = false;
+    let stringStart = 0;
+    let skipping = false; // current string already crossed the keep threshold
+    const n = input.length;
+    for (let i = 0; i < n; i++) {
+        if ((i & HEAD_ELISION_TIME_CHECK_MASK) === 0 && Date.now() > deadlineMs) {
+            if (!skipping)
+                outParts.push(input.slice(spanStart, i));
+            return { text: outParts.join(''), truncatedByBudget: true };
+        }
+        const ch = input.charCodeAt(i);
+        if (!inString) {
+            if (ch === 0x22 /* '"' */) {
+                inString = true;
+                stringStart = i + 1;
+                skipping = false;
+            }
+            continue;
+        }
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (ch === 0x5c /* '\\' */) {
+            escaped = true;
+            continue;
+        }
+        if (ch === 0x22 /* '"' */) {
+            inString = false;
+            if (skipping) {
+                const elidedUnits = i - stringStart - HEAD_ELISION_STRING_KEEP_UNITS;
+                outParts.push(`…[elided ${elidedUnits} chars]`);
+                spanStart = i; // resume normal copying AT the closing quote
+                skipping = false; // the string is closed; the final flush must still emit the record's own tail ("}\n) even when this was the last string literal
+            }
+            continue;
+        }
+        if (!skipping && (i - stringStart) === HEAD_ELISION_STRING_KEEP_UNITS) {
+            outParts.push(input.slice(spanStart, i)); // flush the kept prefix now
+            skipping = true;
+        }
+    }
+    if (!skipping)
+        outParts.push(input.slice(spanStart, n));
+    return { text: outParts.join(''), truncatedByBudget: false };
+}
+/**
+ * Recover the transcript's opening JSONL record even when it doesn't fit the
+ * plain {@link DEFAULT_HEAD_MAX_BYTES} chunk — the case a first turn carrying
+ * a multi-megabyte inline image produces, where the record's own closing
+ * newline sits past whatever small chunk was read, so the old bare head
+ * reader dropped the WHOLE record (and with it, the real original request)
+ * rather than the oversized value inside it.
+ *
+ * Only invoked when the cheap path already failed to find a complete line
+ * (bounded — see {@link readSessionHeadChunk}'s `sawEof`), so an ordinary
+ * transcript never pays this cost. Reads up to {@link HEAD_ELISION_MAX_READ_BYTES}
+ * from byte 0, runs it through {@link elideOversizedJsonStrings} (bounded by
+ * {@link HEAD_ELISION_MAX_MS}), and returns the first complete elided line —
+ * text before and after the oversized value is preserved verbatim (only the
+ * oversized value itself is shortened), UTF-8 decoding and escape handling
+ * both go through the exact same path an unelided record would. Returns ''
+ * (a partial result, not a guess) when the scan is cut off by either budget
+ * before a complete line was ever produced — never a followup/tail turn
+ * substituted for it.
+ */
+export function readSessionHeadContentBounded(filePath, maxReadBytes = HEAD_ELISION_MAX_READ_BYTES) {
+    const chunk = readSessionHeadChunk(filePath, maxReadBytes);
+    if (!chunk || !chunk.content)
+        return '';
+    const { text, truncatedByBudget } = elideOversizedJsonStrings(chunk.content, Date.now() + HEAD_ELISION_MAX_MS);
+    const firstNl = text.indexOf('\n');
+    if (firstNl >= 0)
+        return text.slice(0, firstNl);
+    // No line terminator found anywhere in the elided text: either the record
+    // (minus its oversized values) is STILL bigger than the read budget, or the
+    // elision scan itself hit its time budget first, or we reached real EOF
+    // with no trailing newline at all (a truncated/interrupted write).
+    if (truncatedByBudget)
+        return '';
+    return chunk.sawEof ? text : '';
+}
+/**
+ * Read the FIRST `maxEvents` normalized events from a JSONL transcript's
+ * head — the session's actual opening turns, bounded and cheap (one small
+ * read from byte 0, the same shared Claude/Codex content parsers `readSessionTail`
+ * uses, zero duplicated parse logic). Only Claude and Codex are supported,
+ * matching {@link readSessionTailWithRaw}; other agents return no events.
+ *
+ * When the plain bounded chunk holds no complete first line at all — an
+ * opening user turn embedding a multi-megabyte inline image is the real case
+ * this covers — falls back to {@link readSessionHeadContentBounded}'s
+ * JSON-aware elision scan rather than returning nothing: the same content
+ * parsers then see a syntactically valid record with the oversized value
+ * shortened, so a text block before or after an elided image block is
+ * recovered exactly as if the image had never been oversized (the parser's
+ * own image-handling path, e.g. Claude's `normalizedAttachmentEvent`, still
+ * runs — it just sees a short placeholder `source.data` instead of the real
+ * payload, so an attachment's derived byte size is not meaningful when this
+ * fallback fired, only the surrounding TEXT is trustworthy).
+ */
+export function readSessionHead(filePath, agent, maxBytes = DEFAULT_HEAD_MAX_BYTES, maxEvents = DEFAULT_MAX_EVENTS) {
+    if (agent !== 'claude' && agent !== 'codex')
+        return [];
+    let content = readSessionHeadContent(filePath, maxBytes);
+    if (!content.trim())
+        content = readSessionHeadContentBounded(filePath);
+    if (!content.trim())
+        return [];
+    const events = agent === 'codex' ? parseCodexContent(content) : parseClaudeContent(content);
+    sanitizeEvents(events);
+    return events.length > maxEvents ? events.slice(0, maxEvents) : events;
+}

package/dist/lib/setup-tool-install.js

@@ -1,8 +1,9 @@
 import { installCli, resolveCliManifest } from './cli-resources.js';
 import { getCachedToolSetup, refreshToolSetup } from './setup-tool-status.js';
 const PACKAGES = {
-    browser: '@phnx-labs/browser-cli@0.1.3',
+    browser: '@phnx-labs/browser-cli@0.1.5',
     computer: '@phnx-labs/computer-cli@0.1.5',
+    term: '@phnx-labs/term-cli@0.1.0',
 };
 /** Use the host installer; setup must not install or start a tool from a read. */
 export async function installSetupTool(tool) {

package/dist/lib/setup-tool-status.d.ts

@@ -1,4 +1,4 @@
-export declare const SETUP_TOOLS: readonly ["browser", "computer", "secrets"];
+export declare const SETUP_TOOLS: readonly ["browser", "computer", "secrets", "term"];
 export type SetupTool = typeof SETUP_TOOLS[number];
 export interface ToolSetupRow {
     tool: SetupTool;

package/dist/lib/setup-tool-status.js

@@ -6,7 +6,7 @@ import { atomicWriteJsonSync, withFileLockAsync } from './fs-atomic.js';
 import { probeCapture } from './probe.js';
 import { invocation, isStandaloneComputer } from './computer-client.js';
 import { getSocketPath as browserSocketPath } from './browser/ipc.js';
-export const SETUP_TOOLS = ['browser', 'computer', 'secrets'];
+export const SETUP_TOOLS = ['browser', 'computer', 'secrets', 'term'];
 export function toolSetupCacheDir(options = {}) {
     return path.join(options.cacheDir ?? getCacheDir(), 'setup-tools');
 }
@@ -139,6 +139,11 @@ async function checkTool(row) {
     // unlock the broker merely to paint a settings row.
     if (row.tool === 'secrets')
         return { ...row, checkedAtMs: Date.now(), detail: 'Installed. Secret access is checked when used; this check does not unlock secrets.' };
+    // term is a headless PTY engine with no `status --json` health surface; it is
+    // spawned on demand by the OAuth device-code driver (fleet login / auth mint).
+    // Presence on PATH is the whole readiness signal — do not probe it.
+    if (row.tool === 'term')
+        return { ...row, readiness: 'ready', detail: 'Installed. Spawned on demand by fleet login and auth mint.', checkedAtMs: Date.now() };
     try {
         const { command, prefix } = invocation(row.executable);
         const { stdout } = await probeCapture(command, [...prefix, 'status', '--json'], 8000, { acceptedExitCodes: [0, 1], maxOutputBytes: 256 * 1024 });

package/dist/lib/signin-badge.d.ts

@@ -6,15 +6,30 @@ export type AccountProvisioning = 'portable' | 'per-device';
 /**
  * The exact command that logs a given agent in — for warn banners and nudges.
  * Driven off the registry `cliCommand` with the per-agent subcommand overrides
- * (verified against the real CLIs): codex/grok use `<cli> login`, opencode uses
- * `<cli> auth login`, claude logs in from inside its TUI via `/login`, and the
- * remaining agents (kimi, gemini, …) start their device/oauth flow on launch.
+ * (verified against the real CLIs): codex/grok/opencode run the finite login
+ * subcommand `HARNESS_AUTH` wires (`loginSubcommand`), claude logs in from
+ * inside its TUI via `/login`, and the remaining agents (kimi, gemini, …) start
+ * their device/oauth flow on launch.
  */
 export declare function loginHint(agentId: AgentId): string;
+/**
+ * Harnesses that log back in through a finite native subcommand runnable via
+ * `agents run <agent>@<version> -- <args>`. Claude logs in from inside its TUI
+ * (`/login`); cursor and the rest start their device/oauth flow on launch.
+ */
+export declare const SUBCOMMAND_LOGIN_AGENTS: readonly AgentId[];
+/**
+ * The finite native login subcommand (`login`, `login --device-auth`,
+ * `auth login`) for a {@link SUBCOMMAND_LOGIN_AGENTS} harness, read from the one
+ * `HARNESS_AUTH` row so every surface that spells it — the hint, the per-version
+ * fix, `agents doctor` — agrees. Null for every other harness.
+ */
+export declare function loginSubcommand(agent: AgentId): string | null;
 /**
  * Exact action shown beside a non-live account. Every emitted command exists
  * today — never a planned surface and never a hidden verb:
- * - Per-device harnesses repair per box via `agents devices login`.
+ * - Per-device harnesses (kimi/antigravity) repair on the box itself: run the
+ *   harness there (`loginHint`) and complete its native login.
  * - Named accounts re-auth through `agents accounts login <harness>#<name>`.
  *   A known account with no slot on a headed device is onboarded with
  *   `agents accounts add <harness> <name>`. A worker never runs an

package/dist/lib/signin-badge.js

@@ -11,13 +11,15 @@
 import chalk from 'chalk';
 import { addWorkerRefusal } from './accounts/add.js';
 import { AGENTS } from './agents.js';
+import { HARNESS_AUTH } from './harness-auth-capabilities.js';
 import { CONFIG_ENV_ISOLATED_AGENTS } from './installations/shims.js';
 /**
  * The exact command that logs a given agent in — for warn banners and nudges.
  * Driven off the registry `cliCommand` with the per-agent subcommand overrides
- * (verified against the real CLIs): codex/grok use `<cli> login`, opencode uses
- * `<cli> auth login`, claude logs in from inside its TUI via `/login`, and the
- * remaining agents (kimi, gemini, …) start their device/oauth flow on launch.
+ * (verified against the real CLIs): codex/grok/opencode run the finite login
+ * subcommand `HARNESS_AUTH` wires (`loginSubcommand`), claude logs in from
+ * inside its TUI via `/login`, and the remaining agents (kimi, gemini, …) start
+ * their device/oauth flow on launch.
  */
 export function loginHint(agentId) {
     const cli = AGENTS[agentId]?.cliCommand ?? agentId;
@@ -26,9 +28,8 @@ export function loginHint(agentId) {
             return `${cli}, then /login`;
         case 'codex':
         case 'grok':
-            return `${cli} login`;
         case 'opencode':
-            return `${cli} auth login`;
+            return `${cli} ${loginSubcommand(agentId)}`;
         // Warp Agent CLI has no `login` subcommand: running `warp` opens a browser
         // sign-in on launch (or set WARP_API_KEY / pass --api-key), so the default
         // bare-`warp` hint is correct.
@@ -36,10 +37,28 @@ export function loginHint(agentId) {
             return cli;
     }
 }
+/**
+ * Harnesses that log back in through a finite native subcommand runnable via
+ * `agents run <agent>@<version> -- <args>`. Claude logs in from inside its TUI
+ * (`/login`); cursor and the rest start their device/oauth flow on launch.
+ */
+export const SUBCOMMAND_LOGIN_AGENTS = ['codex', 'grok', 'opencode'];
+/**
+ * The finite native login subcommand (`login`, `login --device-auth`,
+ * `auth login`) for a {@link SUBCOMMAND_LOGIN_AGENTS} harness, read from the one
+ * `HARNESS_AUTH` row so every surface that spells it — the hint, the per-version
+ * fix, `agents doctor` — agrees. Null for every other harness.
+ */
+export function loginSubcommand(agent) {
+    if (!SUBCOMMAND_LOGIN_AGENTS.includes(agent))
+        return null;
+    return HARNESS_AUTH[agent].login.join(' ');
+}
 /**
  * Exact action shown beside a non-live account. Every emitted command exists
  * today — never a planned surface and never a hidden verb:
- * - Per-device harnesses repair per box via `agents devices login`.
+ * - Per-device harnesses (kimi/antigravity) repair on the box itself: run the
+ *   harness there (`loginHint`) and complete its native login.
  * - Named accounts re-auth through `agents accounts login <harness>#<name>`.
  *   A known account with no slot on a headed device is onboarded with
  *   `agents accounts add <harness> <name>`. A worker never runs an
@@ -55,7 +74,7 @@ export function fixFor(input) {
     if (verdict === 'live' || verdict === 'rate_limited' || verdict === 'unverified' || verdict === 'ready')
         return null;
     if (input.provisioning === 'per-device' || verdict === 'per-device') {
-        return `agents devices login --agents ${agent}`;
+        return loginHint(agent);
     }
     if (input.name) {
         const worker = addWorkerRefusal(agent, input.name);
@@ -70,10 +89,9 @@ export function fixFor(input) {
         return loginHint(agent);
     if (agent === 'claude')
         return `agents run ${agent}@${version}, then /login`;
-    if (agent === 'codex' || agent === 'grok')
-        return `agents run ${agent}@${version} -- login`;
-    if (agent === 'opencode')
-        return `agents run ${agent}@${version} -- auth login`;
+    const sub = loginSubcommand(agent);
+    if (sub)
+        return `agents run ${agent}@${version} -- ${sub}`;
     return `agents run ${agent}@${version}`;
 }
 /**

package/dist/lib/term-driver.d.ts

@@ -0,0 +1,24 @@
+/** The subset of the `term` CLI a screen-scraping drive loop needs — faked in tests. */
+export interface TermDriver {
+    start(opts?: {
+        rows?: number;
+        cols?: number;
+    }): Promise<string>;
+    exec(id: string, command: string): Promise<void>;
+    write(id: string, input: string): Promise<void>;
+    screen(id: string): Promise<{
+        screen: string;
+        exited: boolean;
+    }>;
+    stop(id: string): Promise<void>;
+}
+/** Real driver over the standalone `term` CLI (`./term-client.js`). */
+export declare function defaultTermDriver(): TermDriver;
+export interface DriveOptions {
+    /** Wait after launching before steering / scraping (default 4000ms). */
+    initialDelayMs?: number;
+    /** Poll cadence for the scrape loop (default 1000ms). */
+    pollMs?: number;
+    /** Overall scrape deadline (default 90000ms). */
+    timeoutMs?: number;
+}

package/dist/lib/term-driver.js

@@ -0,0 +1,36 @@
+/**
+ * Injectable terminal driver over the standalone `term` CLI.
+ *
+ * A small seam that lets a flow drive a PTY session — start, exec, write,
+ * screen-scrape, stop — through the real `term` CLI in production and a fake in
+ * tests. The setup-token mint (`lib/auth-mint.ts`) is the sole consumer today.
+ */
+import { termStart, termExec, termWrite, termScreen, termStop } from './term-client.js';
+/** Real driver over the standalone `term` CLI (`./term-client.js`). */
+export function defaultTermDriver() {
+    const expectOk = (res, what) => {
+        if (!res.ok)
+            throw new Error(`term ${what} failed: ${res.error ?? 'unknown'}`);
+    };
+    return {
+        async start(opts) {
+            const res = await termStart({ rows: opts?.rows ?? 40, cols: opts?.cols ?? 120 });
+            expectOk(res, 'start');
+            return res.id;
+        },
+        async exec(id, command) {
+            expectOk(await termExec(id, command), 'exec');
+        },
+        async write(id, input) {
+            expectOk(await termWrite(id, input), 'write');
+        },
+        async screen(id) {
+            const res = await termScreen(id);
+            expectOk(res, 'screen');
+            return { screen: res.screen ?? '', exited: Boolean(res.exited) };
+        },
+        async stop(id) {
+            await termStop(id).catch(() => undefined);
+        },
+    };
+}

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

@@ -14,7 +14,7 @@ export { makeVscodiumAgentBackend, spawnUri, EDITOR_VARIANTS, type EditorVariant
 export { planLayouts, type Packing } from './policy.js';
 export { specForRequest, buildRequests, openSurface, openSurfaces, type OpenOptions, type OpenManyOptions, type BuildRequestsOptions, type SurfaceItem, } from './engine.js';
 export { runLocal, runRemote, runSpec, remoteCommand, type HostResolver, type RunResult } from './transport.js';
-export { injectIntoTerminal, tmuxSendKeysArgv, tmuxInjectSpecs, itermInjectScript, ghosttyInjectScript, appleScriptInjectSpec, vscodiumInjectUri, vscodiumInjectSpec, type InjectTarget, type InjectBackend, type InjectOptions, type InjectResult, } from './inject.js';
+export { backendCarriesPaste, injectIntoTerminal, tmuxSendKeysArgv, tmuxInjectSpecs, itermInjectScript, ghosttyInjectScript, appleScriptInjectSpec, vscodiumInjectUri, vscodiumInjectSpec, type InjectTarget, type InjectBackend, type InjectOptions, type InjectResult, } from './inject.js';
 export { resolveInjectTarget, resolveInjectTargetForSession, type InjectResolution, type InjectRail, type ResolveOptions, } from './resolve.js';
 export { iLoginShell } from './shell.js';
 export { shellQuote } from './quote.js';

package/dist/lib/terminal/index.js

@@ -5,7 +5,7 @@ export { makeVscodiumAgentBackend, spawnUri, EDITOR_VARIANTS } from './backends/
 export { planLayouts } from './policy.js';
 export { specForRequest, buildRequests, openSurface, openSurfaces, } from './engine.js';
 export { runLocal, runRemote, runSpec, remoteCommand } from './transport.js';
-export { injectIntoTerminal, tmuxSendKeysArgv, tmuxInjectSpecs, itermInjectScript, ghosttyInjectScript, appleScriptInjectSpec, vscodiumInjectUri, vscodiumInjectSpec, } from './inject.js';
+export { backendCarriesPaste, injectIntoTerminal, tmuxSendKeysArgv, tmuxInjectSpecs, itermInjectScript, ghosttyInjectScript, appleScriptInjectSpec, vscodiumInjectUri, vscodiumInjectSpec, } from './inject.js';
 export { resolveInjectTarget, resolveInjectTargetForSession, } from './resolve.js';
 export { iLoginShell } from './shell.js';
 export { shellQuote } from './quote.js';

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

@@ -88,6 +88,21 @@ export interface InjectOptions {
     ctx?: EngineContext;
     /** Don't execute — return the spec(s) that WOULD run. Lets the macOS paths be asserted on Linux. */
     dryRun?: boolean;
+    /**
+     * Hard bound for the WHOLE injection, in ms. Each spec is run under the
+     * remaining budget with process-group cancellation, and a spec is never
+     * STARTED once the budget is gone — an operator-facing caller must be able to
+     * return a verdict on time without leaving a launcher running behind it
+     * (PHNX-3999). Omitted keeps the historical unbounded behaviour.
+     */
+    deadlineMs?: number;
+    /**
+     * Frame the text in bracketed-paste markers so a TUI inserts it verbatim
+     * instead of reading each embedded newline as a submit. Required for a
+     * multiline free-text answer. Only the tmux rail can carry it (see
+     * {@link backendCarriesPaste}); every other backend refuses with an error.
+     */
+    paste?: boolean;
 }
 export interface InjectResult {
     ok: boolean;
@@ -106,10 +121,33 @@ export interface InjectResult {
     confirmed: boolean;
     /** Discrete writes delivered: 2 for the Ink-safe text+Enter split, 1 when combined or enter=false. */
     writes: number;
+    /**
+     * How many specs were STARTED. This -- not `writes` -- is what says whether
+     * anything may have reached the terminal: a spec that failed or timed out may
+     * still have written bytes before dying, so only `started === 0` proves
+     * nothing landed and the answer is cleanly retryable (PHNX-3999).
+     */
+    started: number;
     /** For the tmux / AppleScript backends (or any dryRun), the spec(s) that ran / would run. */
     specs?: LaunchSpec[];
     error?: string;
 }
+/**
+ * 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 declare const BRACKETED_PASTE_START = "\u001B[200~";
+export declare 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 declare function backendCarriesPaste(backend: InjectBackend): boolean;
 /**
  * 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

package/dist/lib/terminal/inject.js

@@ -53,6 +53,24 @@ function backendConfirmsDelivery(backend) {
 }
 /** 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
@@ -191,12 +209,21 @@ export function vscodiumInjectSpec(target, text, opts) {
 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: [],
+            error: `The ${target.backend} rail cannot deliver a bracketed paste — open the session and paste it there.`,
+        };
+    }
+    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, text, { enter, combined, socket: opts.socket })
+        ? tmuxInjectSpecs(target, payload, { enter, combined, socket: opts.socket })
         : target.backend === 'vscodium'
-            ? [vscodiumInjectSpec(target, text, { enter, combined })]
-            : [appleScriptInjectSpec(target, text, enter, combined)];
+            ? [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
@@ -208,7 +235,7 @@ export async function injectIntoTerminal(target, text, opts = {}) {
             : enter && !combined ? 2 : 1;
     const confirmed = backendConfirmsDelivery(target.backend);
     if (opts.dryRun)
-        return { ok: true, confirmed, backend: target.backend, writes, specs };
+        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') {
@@ -216,14 +243,33 @@ export async function injectIntoTerminal(target, text, opts = {}) {
             const backend = target.backend === 'iterm' ? itermBackend : ghosttyBackend;
             const ctx = opts.ctx ?? currentContext();
             if (!backend.isAvailable(ctx)) {
-                return { ok: false, confirmed: false, backend: target.backend, writes: 0, specs, error: `${backend.label} is not available here (platform ${ctx.platform})` };
+                return { ok: false, confirmed: false, backend: target.backend, writes: 0, started: 0, specs, error: `${backend.label} is not available here (platform ${ctx.platform})` };
             }
         }
     }
+    const endMs = opts.deadlineMs === undefined ? undefined : Date.now() + opts.deadlineMs;
+    let sent = 0;
+    let started = 0;
     for (const spec of specs) {
-        const res = await runSpec(spec, opts.host, opts.resolveHost);
-        if (!res.ok)
-            return { ok: false, confirmed: false, backend: target.backend, writes: 0, specs, error: res.error };
+        // 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 {
+                ok: false, confirmed: false, backend: target.backend, writes: sent, started, specs,
+                error: `injection ran out of budget after ${sent} of ${specs.length} write(s)`,
+            };
+        }
+        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;
     }
-    return { ok: true, confirmed, backend: target.backend, writes, specs };
+    return { ok: true, confirmed, backend: target.backend, writes, started, specs };
 }

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

@@ -5,11 +5,21 @@ export interface RunResult {
     ok: boolean;
     error?: string;
 }
-/** Run the spec on this machine: spawn the launcher, resolve when it exits. */
-export declare function runLocal(spec: LaunchSpec): Promise<RunResult>;
+/** Grace between SIGTERM and SIGKILL when a deadline cancels a launcher. */
+export declare const SPEC_KILL_GRACE_MS = 250;
+/**
+ * Run the spec on this machine: spawn the launcher, resolve when it exits.
+ *
+ * `timeoutMs` makes the call genuinely bounded rather than merely raced: the
+ * child is spawned in its OWN process group (`detached`) and the whole group is
+ * signalled on expiry, so a launcher that itself spawned something (osascript →
+ * the app, tmux → the server) cannot keep running after the caller has given up.
+ * Racing the promise alone leaves the process behind (PHNX-3999).
+ */
+export declare function runLocal(spec: LaunchSpec, timeoutMs?: number): Promise<RunResult>;
 /** Serialize a launch argv into a single POSIX-quoted shell command string. */
 export declare function remoteCommand(spec: LaunchSpec): string;
-/** Run the spec on a remote host over SSH. */
-export declare function runRemote(spec: LaunchSpec, target: string): RunResult;
+/** Run the spec on a remote host over SSH. `timeoutMs` bounds the ssh client. */
+export declare function runRemote(spec: LaunchSpec, target: string, timeoutMs?: number): RunResult;
 /** Run a spec locally (no host / 'local') or on a resolved remote host. */
-export declare function runSpec(spec: LaunchSpec, host?: string, resolveHost?: HostResolver): Promise<RunResult>;
+export declare function runSpec(spec: LaunchSpec, host?: string, resolveHost?: HostResolver, timeoutMs?: number): Promise<RunResult>;