@phnx-labs/agents-cli 1.22.114 → 1.22.116

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/smart-launch.d.ts

@@ -117,16 +117,12 @@ type DeviceAutoHostOptions = {
     device?: string;
     on?: string;
     computer?: string;
-    /** @deprecated Hidden alias for `--device auto`. */
-    smart?: boolean;
     balanced?: boolean;
     strategy?: string;
 };
 export type DeviceAutoApplyResult = {
     /** True when automatic placement ran successfully. */
     attempted: boolean;
-    /** True when deprecated `--smart` was seen. */
-    deprecationSmart: boolean;
     /** Present when affinity resolved without error. */
     banner?: {
         hostLabel: string;
@@ -135,7 +131,7 @@ export type DeviceAutoApplyResult = {
     };
 };
 /**
- * Apply `--device auto` (and deprecated `--smart`) onto run options.
+ * Apply `--device auto` onto run options.
  * Mutates `options` in place. Placement failures propagate without rewriting
  * `auto`, so callers fail loud instead of silently launching locally.
  */

package/dist/lib/smart-launch.js

@@ -176,7 +176,7 @@ export async function resolveDeviceAuto(agent, opts = {}) {
     if (eligiblePool.length === 0) {
         throw new Error(formatNoHealthyDeviceError(pool, signals, agent));
     }
-    // `agents devices prefer <name>` boosts a device in the ranking — resolved
+    // `agents devices config <name> auto-launch.preferred on` boosts a device in the ranking — resolved
     // over the same pool so a fleet default reaches a doc-less box.
     const preferred = opts.preferred ?? autoLaunchPreferredSet(pool, { roster: pool });
     const picked = pickBestDevice(eligiblePool, [], { signals, agentLabel: agent, preferred });
@@ -260,21 +260,14 @@ export function isDeviceAuto(value) {
 }
 const HOST_SLOTS = ['host', 'device', 'on', 'computer'];
 /**
- * Apply `--device auto` (and deprecated `--smart`) onto run options.
+ * Apply `--device auto` onto run options.
  * Mutates `options` in place. Placement failures propagate without rewriting
  * `auto`, so callers fail loud instead of silently launching locally.
  */
 export async function applyDeviceAutoToOptions(options, deps = {}) {
-    let deprecationSmart = false;
-    if (options.smart) {
-        const anyHost = HOST_SLOTS.some((k) => typeof options[k] === 'string' && options[k].trim() !== '');
-        if (!anyHost)
-            options.device = 'auto';
-        deprecationSmart = true;
-    }
     const hasAuto = HOST_SLOTS.some((k) => isDeviceAuto(options[k]));
     if (!hasAuto) {
-        return { attempted: false, deprecationSmart };
+        return { attempted: false };
     }
     const accountPickerRequested = deps.accountPickerRequested ?? false;
     const resolve = deps.resolve ?? ((accountPicker) => resolveDeviceAuto(deps.agent, { accountPicker }));
@@ -296,7 +289,6 @@ export async function applyDeviceAutoToOptions(options, deps = {}) {
     const acctNote = accountPickerRequested ? 'accounts=picker' : 'accounts=balanced';
     return {
         attempted: true,
-        deprecationSmart,
         banner: { hostLabel, deviceHint, acctNote },
     };
 }

package/dist/lib/ssh-exec.d.ts

@@ -173,6 +173,50 @@ interface SshExecRawStreamOptions extends SshExecOptions {
  * offset-resumed log following where a UTF-8 decode boundary must not shift the
  * byte cursor.
  */
+/** Grace between SIGTERM and SIGKILL for a stream that will not stop. */
+export declare const SSH_STREAM_KILL_GRACE_MS = 3000;
+/** Bytes of a stream's stderr retained; the rest is dropped, with a note. */
+export declare const SSH_STREAM_MAX_STDERR: number;
+export interface SshStreamResult {
+    code: number | null;
+    stderr: Buffer;
+    timedOut: boolean;
+    /** True when the child had to be SIGKILLed after ignoring SIGTERM. */
+    killed: boolean;
+    /** True when stderr was truncated at {@link SSH_STREAM_MAX_STDERR}. */
+    stderrTruncated: boolean;
+}
+/**
+ * Stream one ssh command's stdout, with the args and env a CALLER built.
+ *
+ * This exists because {@link sshExecRawStream} assembles its own ssh args, which
+ * means it cannot carry a device's canonical auth — the askpass shim for a
+ * password-auth box, `-i`/`IdentitiesOnly` for an explicit identity file, or the
+ * managed known-hosts pinning. A caller that has already built those through
+ * `buildSshInvocation` needs a way to run them, and duplicating the transport to
+ * get it would be the worse answer. So this takes `args`/`env` verbatim and adds
+ * only the lifecycle guarantees:
+ *
+ * - **SIGTERM then SIGKILL.** A timeout or abort that only sends SIGTERM leaks a
+ *   child that ignores it — ssh does, mid-handshake — and the promise never
+ *   settles. After {@link SSH_STREAM_KILL_GRACE_MS} the child is SIGKILLed and
+ *   `killed` says so.
+ * - **Bounded stderr.** A peer that writes endlessly to stderr would otherwise
+ *   grow this buffer without limit; it is capped and `stderrTruncated` says so.
+ * - **`onStdout` cannot break the caller's cleanup.** A throw from the consumer
+ *   is captured and re-thrown by the awaiting caller, so a write failure ends the
+ *   transfer instead of escaping as an unhandled error inside a stream event.
+ */
+export declare function sshStreamWithArgs(opts: {
+    args: string[];
+    env?: Record<string, string>;
+    onStdout: (chunk: Buffer) => void;
+    timeoutMs?: number;
+    killGraceMs?: number;
+    maxStderrBytes?: number;
+    signal?: AbortSignal;
+    sshBin?: string;
+}): Promise<SshStreamResult>;
 export declare function sshExecRawStream(target: string, remoteCmd: string, opts: SshExecRawStreamOptions): Promise<Omit<SshExecRawResult, 'stdout'>>;
 /** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
 export declare function sshReachable(target: string, timeoutMs?: number): boolean;

package/dist/lib/ssh-exec.js

@@ -317,6 +317,125 @@ export function sshExecRaw(target, remoteCmd, opts = {}) {
  * offset-resumed log following where a UTF-8 decode boundary must not shift the
  * byte cursor.
  */
+/** Grace between SIGTERM and SIGKILL for a stream that will not stop. */
+export const SSH_STREAM_KILL_GRACE_MS = 3_000;
+/** Bytes of a stream's stderr retained; the rest is dropped, with a note. */
+export const SSH_STREAM_MAX_STDERR = 8 * 1024;
+/**
+ * Stream one ssh command's stdout, with the args and env a CALLER built.
+ *
+ * This exists because {@link sshExecRawStream} assembles its own ssh args, which
+ * means it cannot carry a device's canonical auth — the askpass shim for a
+ * password-auth box, `-i`/`IdentitiesOnly` for an explicit identity file, or the
+ * managed known-hosts pinning. A caller that has already built those through
+ * `buildSshInvocation` needs a way to run them, and duplicating the transport to
+ * get it would be the worse answer. So this takes `args`/`env` verbatim and adds
+ * only the lifecycle guarantees:
+ *
+ * - **SIGTERM then SIGKILL.** A timeout or abort that only sends SIGTERM leaks a
+ *   child that ignores it — ssh does, mid-handshake — and the promise never
+ *   settles. After {@link SSH_STREAM_KILL_GRACE_MS} the child is SIGKILLed and
+ *   `killed` says so.
+ * - **Bounded stderr.** A peer that writes endlessly to stderr would otherwise
+ *   grow this buffer without limit; it is capped and `stderrTruncated` says so.
+ * - **`onStdout` cannot break the caller's cleanup.** A throw from the consumer
+ *   is captured and re-thrown by the awaiting caller, so a write failure ends the
+ *   transfer instead of escaping as an unhandled error inside a stream event.
+ */
+export function sshStreamWithArgs(opts) {
+    const maxStderr = opts.maxStderrBytes ?? SSH_STREAM_MAX_STDERR;
+    const grace = opts.killGraceMs ?? SSH_STREAM_KILL_GRACE_MS;
+    return new Promise((resolve, reject) => {
+        const child = spawn(opts.sshBin ?? 'ssh', opts.args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: opts.env ? { ...process.env, ...opts.env } : process.env,
+            windowsHide: true,
+            // Own process group on POSIX so a kill reaches the whole tree. Killing only
+            // the ssh pid is not enough: a descendant that inherited stdout keeps the
+            // pipe open, `'close'` never fires, and the promise hangs for as long as
+            // that grandchild lives — which defeats the timeout entirely.
+            detached: process.platform !== 'win32',
+        });
+        const stderr = [];
+        let stderrBytes = 0;
+        let stderrTruncated = false;
+        let timedOut = false;
+        let killed = false;
+        let consumerError;
+        let settled = false;
+        let killTimer;
+        /** Signal the whole group where the platform supports it, else just the child. */
+        const signal = (sig) => {
+            try {
+                if (process.platform !== 'win32' && child.pid)
+                    process.kill(-child.pid, sig);
+                else
+                    child.kill(sig);
+            }
+            catch { /* already gone */ }
+        };
+        const escalate = () => {
+            signal('SIGTERM');
+            // Escalation, not a second polite ask: a child still alive after the grace
+            // is one that is not going to honour SIGTERM.
+            killTimer = setTimeout(() => { killed = true; signal('SIGKILL'); }, grace);
+            killTimer.unref?.();
+        };
+        const stop = () => escalate();
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            opts.signal?.removeEventListener('abort', stop);
+            if (consumerError !== undefined) {
+                reject(consumerError);
+                return;
+            }
+            resolve({ code, stderr: Buffer.concat(stderr), timedOut, killed, stderrTruncated });
+        };
+        const timer = opts.timeoutMs
+            ? setTimeout(() => { timedOut = true; escalate(); }, opts.timeoutMs)
+            : null;
+        child.stdout.on('data', (chunk) => {
+            if (consumerError !== undefined)
+                return;
+            try {
+                opts.onStdout(chunk);
+            }
+            catch (error) {
+                // Captured, not thrown: a throw here would surface as an unhandled error
+                // on the stream and skip the caller's cleanup entirely.
+                consumerError = error;
+                escalate();
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            const room = maxStderr - stderrBytes;
+            if (room <= 0) {
+                stderrTruncated = true;
+                return;
+            }
+            if (chunk.length > room) {
+                stderrTruncated = true;
+                stderr.push(chunk.subarray(0, room));
+                stderrBytes = maxStderr;
+                return;
+            }
+            stderr.push(chunk);
+            stderrBytes += chunk.length;
+        });
+        child.once('error', () => finish(null));
+        child.once('close', finish);
+        if (opts.signal?.aborted)
+            escalate();
+        else
+            opts.signal?.addEventListener('abort', stop, { once: true });
+    });
+}
 export function sshExecRawStream(target, remoteCmd, opts) {
     assertValidSshTarget(target);
     const mux = opts.multiplex === false ? [] : controlOpts();

package/dist/lib/startup/command-registry.d.ts

@@ -17,15 +17,17 @@ export declare const KNOWN_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
  * name is gone, the spellchecker finds a neighbour, and the CLI runs something
  * the user never asked for instead of saying the command is gone.
  *
- * `set` moved under `agents models`/`agents config` (RUSH-2579); `share` moved
- * under `agents artifacts share` (RUSH-2580). login/logout/budget/bench/mine/
+ * `set` moved under `agents models`/`agents config` (RUSH-2579); `share`,
+ * `unshare`, and the whole `artifacts` group moved OUT to the standalone
+ * `artifacts` CLI (`@phnx-labs/artifacts-cli`, PHNX-3992) — artifact sharing is
+ * no longer an agents-cli surface at all. login/logout/budget/bench/mine/
  * cost/output/profiles/snapshot/cp/resume/roster moved under nested homes
  * (cli-surface-consolidate). `timeline` was removed as a duplicated surface —
  * use `agents feed --filter updates` (RUSH-2692). `status` moved under
  * `agents sync status` (RUSH-2864). `tickets` was removed — use `linear`
  * (linear-cli) (RUSH-2932). `alias` moved under `agents setup alias` (RUSH-2965).
- * `inbox` was a pure alias of `agents feed` (RUSH-2984). `unshare` nested under
- * `agents artifacts unshare` (RUSH-2989). `audit` nested under `agents events audit`.
+ * `inbox` was a pure alias of `agents feed` (RUSH-2984). `audit` nested under
+ * `agents events audit`.
  * `trends` was removed with the insights recipe collapse — the one counter
  * surface is `agents insights mix` (PHNX-3391). `serve` (the
  * read-only local web companion + `--control` anchor) was removed with the

package/dist/lib/startup/command-registry.js

@@ -2,14 +2,14 @@ const LOADED_COMMAND_NAMES = [
     'accounts', 'auth', 'view', 'inspect', 'feedback', 'commands', 'hooks', 'skills', 'rules', 'memory',
     'permissions', 'mcp', 'clis', 'subagents', 'plugins', 'workflows', 'add', 'use',
     'remove', 'rm', 'purge', 'update', 'prune', 'import', 'registry', 'search', 'install', 'packages',
-    'routines', 'monitors', 'projects', 'run', '_callback', 'open', 'reconnect', 'fork', 'config',
+    'routines', 'monitors', 'projects', 'run', '_callback', 'open', 'fork', 'config',
     'models', 'modes', 'trash', 'restore', 'doctor',
     'route', 'routes', 'harness', 'harnesses', 'secrets', 'menubar', 'sync',
     'refresh-rules', 'factory', 'insights', 'trace', 'reminders',
     'tmux', 'watchdog', 'browser', 'computer', 'logs', 'events',
     'ssh', 'devices', 'fleet', 'repos', 'repo', 'setup', 'uninstall', 'upgrade', 'sessions',
-    'teams', 'cloud', 'message', 'send', 'notify', 'feed',
-    'mailboxes', 'mailbox', 'artifacts', 'webhooks',
+    'teams', 'cloud', 'message', 'send', 'feed',
+    'mailboxes', 'mailbox', 'webhooks',
     'humans', 'daemon', 'traces',
 ];
 const INLINE_COMMAND_NAMES = [
@@ -37,15 +37,17 @@ export const KNOWN_TOP_LEVEL_COMMANDS = new Set([
  * name is gone, the spellchecker finds a neighbour, and the CLI runs something
  * the user never asked for instead of saying the command is gone.
  *
- * `set` moved under `agents models`/`agents config` (RUSH-2579); `share` moved
- * under `agents artifacts share` (RUSH-2580). login/logout/budget/bench/mine/
+ * `set` moved under `agents models`/`agents config` (RUSH-2579); `share`,
+ * `unshare`, and the whole `artifacts` group moved OUT to the standalone
+ * `artifacts` CLI (`@phnx-labs/artifacts-cli`, PHNX-3992) — artifact sharing is
+ * no longer an agents-cli surface at all. login/logout/budget/bench/mine/
  * cost/output/profiles/snapshot/cp/resume/roster moved under nested homes
  * (cli-surface-consolidate). `timeline` was removed as a duplicated surface —
  * use `agents feed --filter updates` (RUSH-2692). `status` moved under
  * `agents sync status` (RUSH-2864). `tickets` was removed — use `linear`
  * (linear-cli) (RUSH-2932). `alias` moved under `agents setup alias` (RUSH-2965).
- * `inbox` was a pure alias of `agents feed` (RUSH-2984). `unshare` nested under
- * `agents artifacts unshare` (RUSH-2989). `audit` nested under `agents events audit`.
+ * `inbox` was a pure alias of `agents feed` (RUSH-2984). `audit` nested under
+ * `agents events audit`.
  * `trends` was removed with the insights recipe collapse — the one counter
  * surface is `agents insights mix` (PHNX-3391). `serve` (the
  * read-only local web companion + `--control` anchor) was removed with the
@@ -81,6 +83,7 @@ export const RETIRED_TOP_LEVEL_COMMANDS = new Set([
     'roster',
     'set',
     'share',
+    'artifacts',
     'timeline',
     'status',
     'tickets',

package/dist/lib/state.js

@@ -215,8 +215,8 @@ export function getOptionalUserAgentsDir() {
  * Origin `owner/repo` slug (lowercased, `.git` stripped) of a git checkout, or
  * null when `dir` isn't a git repo / has no origin. Extracts the slug from any
  * remote URL form: `git@host:owner/repo.git`, `https://host/owner/repo.git`,
- * `ssh://git@host/owner/repo`. Sync (mirrors readGitConfigUser in git.ts) so it
- * can be used from the synchronous getProjectAgentsDir walk.
+ * `ssh://git@host/owner/repo`. Sync (uses `execFileSync`, not the async git
+ * helpers) so it can be used from the synchronous getProjectAgentsDir walk.
  */
 function gitOriginSlug(dir) {
     let url;

package/dist/lib/storage/selection.d.ts

@@ -13,8 +13,8 @@
  * covers — those differ (share uses an email-handle namespace with public reads
  * and covers; a traces/sessions adapter uses the userId and differs again). Each
  * surface keeps its own DISCRIMINATED, typed adapter that reads this decision and
- * returns its own `kind`-tagged backend. See `lib/share/backend.ts` and
- * `lib/traces/backend.ts` for the two adapters.
+ * returns its own `kind`-tagged backend. See `lib/traces/backend.ts` for a
+ * concrete adapter.
  */
 import { type PhoenixSession } from '../identity/client.js';
 /** The two legitimate principals any managed-capable surface can resolve to. */

package/dist/lib/storage/selection.js

@@ -13,8 +13,8 @@
  * covers — those differ (share uses an email-handle namespace with public reads
  * and covers; a traces/sessions adapter uses the userId and differs again). Each
  * surface keeps its own DISCRIMINATED, typed adapter that reads this decision and
- * returns its own `kind`-tagged backend. See `lib/share/backend.ts` and
- * `lib/traces/backend.ts` for the two adapters.
+ * returns its own `kind`-tagged backend. See `lib/traces/backend.ts` for a
+ * concrete adapter.
  */
 import { readSession } from '../identity/client.js';
 /**

package/dist/lib/sync-umbrella.d.ts

@@ -15,6 +15,7 @@
  *               arrives with `agents secrets vault unlock`, #366/#367)
  *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
  */
+import type { ResourceSelection } from './installations/versions.js';
 /** The umbrella flags off `agents sync`. */
 export interface UmbrellaFlags {
     repos?: boolean;
@@ -87,6 +88,10 @@ interface RunUmbrellaArgs {
      * `agents sync --json` / fleet fan-out leave stdout as a single JSON object.
      */
     quiet?: boolean;
+    /** Optional resource-only reconcile across installed versions. */
+    selection?: ResourceSelection;
+    /** Explicit consent for selected plugins that add executable surfaces. */
+    allowExecSurfaces?: boolean;
 }
 /**
  * Execute the planned stages in order: repos -> secrets -> reconcile.

package/dist/lib/sync-umbrella.js

@@ -53,7 +53,7 @@ export function planUmbrellaStages(f) {
  * reconcile — `agents sync` should make as much current as it can in one pass.
  */
 export async function runUmbrellaSync(args) {
-    const { flags, log, yes, passphrase, quiet = false } = args;
+    const { flags, log, yes, passphrase, quiet = false, selection, allowExecSurfaces = false } = args;
     const plan = planUmbrellaStages(flags);
     const result = { plan, reconciled: false, declined: [], reconciledVersions: [] };
     if (plan.fetchRepos) {
@@ -131,7 +131,13 @@ export async function runUmbrellaSync(args) {
     }
     if (plan.reconcile) {
         const { refresh } = await import('./refresh.js');
-        const refreshed = await refresh({ skipPrompts: yes, quiet });
+        const refreshed = await refresh({
+            skipPrompts: yes,
+            quiet,
+            skipClis: selection !== undefined,
+            selection,
+            allowExecSurfaces,
+        });
         result.reconciled = true;
         result.declined = refreshed.declined;
         result.reconciledVersions = refreshed.reconciled;
@@ -140,14 +146,16 @@ export async function runUmbrellaSync(args) {
         // rather than silently adding them (refresh mode). Soft: a machine without
         // tailscale is a clean no-op, never a sync failure. First-run population is
         // `agents setup` / manual `agents devices sync` (bootstrap).
-        const { runDeviceSync } = await import('./devices/sync.js');
-        const { reconcilePendingSentinels } = await import('./devices/pending.js');
-        const dev = await runDeviceSync({ soft: true, mode: 'refresh' });
-        if (dev.ok)
-            await reconcilePendingSentinels(dev.pending);
-        result.devices = { synced: dev.synced, pending: dev.pending.length, skipped: !dev.ok };
-        if (dev.ok) {
-            log(`devices: ${dev.synced} refreshed${dev.pending.length ? `, ${dev.pending.length} new pending` : ''}`);
+        if (!selection) {
+            const { runDeviceSync } = await import('./devices/sync.js');
+            const { reconcilePendingSentinels } = await import('./devices/pending.js');
+            const dev = await runDeviceSync({ soft: true, mode: 'refresh' });
+            if (dev.ok)
+                await reconcilePendingSentinels(dev.pending);
+            result.devices = { synced: dev.synced, pending: dev.pending.length, skipped: !dev.ok };
+            if (dev.ok) {
+                log(`devices: ${dev.synced} refreshed${dev.pending.length ? `, ${dev.pending.length} new pending` : ''}`);
+            }
         }
     }
     return result;

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