@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/sessions-export.js

@@ -36,7 +36,6 @@ import { buildRecord, makeHeader, mergeRecords, serializeBundle, writeBundleFile
 import { knownSecretValuesFromEnv } from '../lib/redact.js';
 import { pullBundlesFromHosts } from '../lib/session/remote-bundle.js';
 import { setHelpSections } from '../lib/help.js';
-/** Default cap when exporting a scope (not explicit ids) and the user gave no -n. */
 const DEFAULT_LIMIT = 500;
 export function registerSessionsExportCommand(sessionsCmd) {
     const cmd = sessionsCmd
@@ -80,11 +79,6 @@ nor the storage provider can decrypt it. Restore with 'agents sessions import --
 }
 async function runExport(selectors, command) {
     const g = command.optsWithGlobals();
-    // --to-r2 preflight. MANAGED-FIRST: a signed-in user backs up to the managed
-    // Phoenix store with no bucket to set up; --byo (or an unauthenticated user
-    // with an r2.backups bundle) uses their own bucket. isSyncConfigured() is
-    // consulted ONLY on the BYO path (it reads the keychain); the managed path
-    // authenticates with the Phoenix session and skips it entirely.
     let sessionsClient;
     let managedClient;
     let managedBackupUserId;
@@ -105,9 +99,6 @@ async function runExport(selectors, command) {
                 managedBackupUserId = backend.userId;
             }
             else {
-                // Preserve the explicit BYO gate used by the on-demand backup path and
-                // daemon sync cycle. resolveSessionsBackend already loaded the bundle,
-                // so this is a cached, non-prompting verification.
                 const gateErr = r2ExportGateError(g, isSyncConfigured());
                 if (gateErr)
                     throw new Error(gateErr);
@@ -119,8 +110,6 @@ async function runExport(selectors, command) {
             process.exit(1);
         }
     }
-    // --host: export sessions that live on remote peer(s) — run export there and
-    // stream the bundle back over the existing SSH transport (RUSH-1712).
     if (g.host && g.host.length > 0) {
         await runRemoteExport(g, selectors, command);
         return;
@@ -131,14 +120,12 @@ async function runExport(selectors, command) {
     const explicitLimit = command.parent?.getOptionValueSource?.('limit') === 'cli';
     const limit = explicitLimit ? Math.max(1, parseInt(String(g.limit), 10) || DEFAULT_LIMIT) : DEFAULT_LIMIT;
     const agentFilter = parseAgentFilter(resolveAgentShorthand(g));
-    // 1. Discover candidate sessions in scope.
     const metas = await discoverSessions({
         all: g.all !== false,
         agent: agentFilter.agent ?? undefined,
         since: g.since,
         limit,
     });
-    // 2. Narrow to the selection (ids > query > everything-in-scope).
     const selected = selectSessions(metas, selectors);
     if (selected.length === 0) {
         process.stderr.write(chalk.yellow('No sessions matched the selection.\n'));
@@ -147,7 +134,6 @@ async function runExport(selectors, command) {
     if (!selectors.length && selected.length >= limit) {
         process.stderr.write(chalk.yellow(`Note: capped at ${limit} sessions. Raise -n to bundle more.\n`));
     }
-    // 3. Resolve each selected session to its on-disk file(s).
     const index = buildLocalIndex();
     const self = machineId();
     const files = [];
@@ -166,8 +152,6 @@ async function runExport(selectors, command) {
             }
         }
         else if (meta.filePath && fs.existsSync(meta.filePath)) {
-            // Not in the live-home index (e.g. a mirror of another machine): fall back
-            // to the single discovered file, deriving its subdir-relative key.
             const relKey = relKeyFromPath(meta.filePath, meta.agent, machine, spec.subdir);
             files.push({ agent: meta.agent, machine, sessionId: meta.id, relKey, absPath: meta.filePath, label: meta.label });
         }
@@ -179,11 +163,7 @@ async function runExport(selectors, command) {
         process.stderr.write(chalk.red('Selected sessions have no exportable transcript files.\n'));
         process.exit(1);
     }
-    // 4. Resolve encryption key (opt-in) + redaction (default on via parent --no-redact).
-    //    A BYO R2 backup uses the fleet-shared R2_SYNC_ENC_KEY (an ephemeral key would
-    //    be unrecoverable on a fresh box). A MANAGED backup resolves a per-account DEK
-    //    that is MANDATORY and never null — the managed path never uploads plaintext —
-    //    minting + escrowing one on first use so a fresh box recovers it with zero setup.
+    // Managed off-box backup requires client-side AES-GCM; BYO storage without a key warns explicitly.
     let encryptKey;
     if (g.toR2 && managedBackupUserId) {
         encryptKey = await resolveManagedBackupKey(managedClient, managedBackupUserId);
@@ -198,11 +178,7 @@ async function runExport(selectors, command) {
         encryptKey = null;
     }
     const redact = g.redact !== false;
-    // Value-aware redaction: mask live credential values already in the
-    // environment (e.g. an injected secrets bundle) verbatim, whatever their
-    // format. Only meaningful when redacting.
     const knownSecrets = redact ? knownSecretValuesFromEnv() : undefined;
-    // 5. Build records + header.
     const records = [];
     for (const f of files) {
         try {
@@ -229,21 +205,6 @@ async function runExport(selectors, command) {
     }
     emitBundle(header, records, g);
 }
-/**
- * Upload each record to R2 as its own self-describing one-record bundle, keyed by
- * the surviving object layout (`sessions/<machine>/<agent>/<sessionId>.jsonl`, or
- * `.../<sessionId>/<relKey>` for dir-shaped agents). Each object is independently
- * a valid bundle, so `import --from-r2` restores it through the same parse/place
- * path as a local bundle. Fails loud on the first upload error (no silent
- * partial-success).
- */
-/**
- * `--to-r2` preflight as a pure, unit-testable function: the impossible-combo +
- * not-configured gate. Returns the message to fail loud with, or null when the
- * export may proceed. Only meaningful when `g.toR2` is set (the caller gates on
- * that). Kept pure — no process.exit, no keychain read — so both the command and
- * its test drive the exact same decision.
- */
 export function r2ExportGateError(g, isConfigured) {
     if (!g.toR2)
         return null;
@@ -258,9 +219,6 @@ export function r2ExportGateError(g, isConfigured) {
     return null;
 }
 export async function uploadToR2(header, records, resolvedClient) {
-    // The resolved client (managed HTTP or BYO R2) is passed in by the command.
-    // The no-client overload preserves the original BYO-only signature for the
-    // direct unit test (loadR2Config() from the r2.backups bundle).
     let client;
     if (resolvedClient) {
         client = resolvedClient;
@@ -304,7 +262,6 @@ export async function uploadToR2(header, records, resolvedClient) {
         `(${uploaded} object${uploaded === 1 ? '' : 's'}${header.encrypted ? ', encrypted' : ', UNENCRYPTED'}) → ` +
         `${client.kind === 'managed' ? 'managed Phoenix store' : 'R2'}.\n`));
 }
-/** Fail-closed guard at the managed transport boundary, not only at record construction. */
 export function managedUploadEncryptionError(header, records) {
     if (!header.encrypted ||
         records.some(record => !record.encrypted || !isTranscriptEnvelope(record.body))) {
@@ -312,19 +269,11 @@ export function managedUploadEncryptionError(header, records) {
     }
     return null;
 }
-/** R2 object key for one record — dir-shaped agents key by relKey, file-shaped by session. */
 export function r2KeyForRecord(rec) {
     const spec = specForAgent(rec.agent);
     const relKey = spec?.dirShaped ? rec.relKey : undefined;
     return objectKey(rec.machine, rec.agent, rec.sessionId, relKey);
 }
-/**
- * Resolve the AES key for an R2 backup: the fleet-shared R2_SYNC_ENC_KEY from the
- * r2.backups bundle so any box on the bundle can restore. Unlike a local bundle,
- * an ephemeral key is useless here (it is never stored, so a fresh box could not
- * decrypt), so a missing key means the objects go up unencrypted (R2 server-side
- * encryption only) with a loud warning — never a silent weaker default.
- */
 export function resolveR2BackupKey() {
     const key = resolveSyncEncKey(loadR2Config());
     if (key)
@@ -334,12 +283,7 @@ export function resolveR2BackupKey() {
         '  agents secrets add r2.backups R2_SYNC_ENC_KEY   # value: openssl rand -base64 32\n'));
     return null;
 }
-/**
- * --host path: run `agents sessions export …` on each peer over SSH, stream the
- * bundles back, merge (dedup by origin machine) and emit one local bundle.
- * Encryption is not combined with a remote pull (each peer would seal under its
- * own key); the SSH transport already encrypts the stream in transit.
- */
+// Remote pull is SSH-only and never combines per-host encryption keys.
 async function runRemoteExport(g, selectors, command) {
     if (g.encrypt) {
         process.stderr.write(chalk.yellow('Note: --encrypt is ignored with --device (the SSH stream is already encrypted). Encrypt a local bundle instead.\n'));
@@ -361,7 +305,6 @@ async function runRemoteExport(g, selectors, command) {
     });
     emitBundle(header, records, g);
 }
-/** Reconstruct the export flags to forward to a peer's own `sessions export`. */
 function forwardExportArgs(g, selectors, command) {
     const args = [...selectors];
     if (g.since)
@@ -377,7 +320,6 @@ function forwardExportArgs(g, selectors, command) {
         args.push('-n', String(g.limit));
     return args;
 }
-/** Write the assembled bundle to stdout or a file. */
 function emitBundle(header, records, g) {
     const wire = serializeBundle(header, records);
     if (g.stdout) {
@@ -390,7 +332,6 @@ function emitBundle(header, records, g) {
         `(${header.count} file${header.count === 1 ? '' : 's'}${header.encrypted ? ', encrypted' : ''}${header.redacted ? ', redacted' : ''}) ` +
         `→ ${outPath}\n`));
 }
-/** Map the parent's agent shorthands (--claude, --codex, …) or -a/--agent to a filter string. */
 function resolveAgentShorthand(g) {
     if (g.agent)
         return g.agent;
@@ -408,7 +349,7 @@ function resolveAgentShorthand(g) {
         return 'antigravity';
     return undefined;
 }
-/** ids > query > everything-in-scope. Exported for the id-resolution test. */
+// An id-shaped selector that misses selects nothing; never widen it to content search and export unrelated transcripts.
 export function selectSessions(metas, selectors) {
     if (selectors.length === 0)
         return metas;
@@ -416,10 +357,6 @@ export function selectSessions(metas, selectors) {
     const unmatched = [];
     for (const sel of selectors) {
         const trimmed = sel.trim();
-        // Same reason as resolveSessionQuery: the discovered pool is a minority of
-        // the index, so an id-shaped selector absent from it may still be indexed
-        // here. Gate on looksLikeSessionId, not isCompleteSessionId, so a SHORT id
-        // ("d3470b57") also resolves through the index instead of falling to content.
         const hits = resolveSessionById(metas, trimmed);
         const resolved = hits.length > 0 || !looksLikeSessionId(trimmed) ? hits : findSessionsById(trimmed);
         if (resolved.length > 0)
@@ -431,20 +368,13 @@ export function selectSessions(metas, selectors) {
         const seen = new Set();
         return byId.filter(s => (seen.has(s.id) ? false : (seen.add(s.id), true)));
     }
-    // A selector that is an id (complete OR a short hex id/prefix) and still missed
-    // cannot be widened: the id is unique, so the text query below could only bundle
-    // sessions that merely mention it. Bundling those would ship unrelated
-    // transcripts to whoever receives the export, so select nothing and let the
-    // caller report it — a short id like "d3470b57" must never content-search.
     const missingIds = unmatched.filter(looksLikeSessionId);
     if (missingIds.length > 0) {
         process.stderr.write(chalk.red(`No session with id ${missingIds.join(', ')} on this machine.\n`));
         return [];
     }
-    // Any selector that isn't an id → treat the whole thing as a text query.
     return filterSessionsByQuery(metas, selectors.join(' '));
 }
-/** Build `${agent}:${sessionId}` → LocalTranscript across every sync agent (live home only). */
 function buildLocalIndex() {
     const index = new Map();
     for (const spec of SYNC_AGENTS) {
@@ -454,18 +384,12 @@ function buildLocalIndex() {
     }
     return index;
 }
-/** Derive the subdir-relative key for a mirror file path, else fall back to the basename. */
 function relKeyFromPath(filePath, agent, machine, subdir) {
     const prefix = path.join(getHistoryDir(), 'backups', agent, machine, subdir) + path.sep;
     if (filePath.startsWith(prefix))
         return filePath.slice(prefix.length);
     return path.basename(filePath);
 }
-/**
- * Resolve the AES key for --encrypt: prefer the fleet-shared R2_SYNC_ENC_KEY (so
- * any machine on the sync bundle can decrypt), else mint an ephemeral key and
- * print it once — it is NOT stored in the bundle.
- */
 function resolveExportKey() {
     try {
         const key = resolveSyncEncKey(loadR2Config());
@@ -473,14 +397,12 @@ function resolveExportKey() {
             return key;
     }
     catch {
-        // sync bundle not configured — fall through to an ephemeral key
     }
     const b64 = generateSyncEncKey();
     process.stderr.write(chalk.yellow(`Bundle encrypted with a fresh key (not in the bundle). Decrypt with:\n` +
         `  agents sessions import <bundle> --decrypt ${b64}\n`));
     return Buffer.from(b64, 'base64');
 }
-/** Default output file when neither -o nor --stdout is given. */
 function defaultBundlePath() {
     const stamp = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
     return path.join(process.cwd(), `agents-sessions-${stamp}.bundle`);

package/dist/commands/sessions-import.d.ts

@@ -2,19 +2,5 @@ import type { Command } from 'commander';
 import { type SessionsBackupClient } from '../lib/session/sync/net-client.js';
 import { type ParsedBundle } from '../lib/session/bundle.js';
 export declare function registerSessionsImportCommand(sessionsCmd: Command): void;
-/**
- * --from-r2: download every session-backup object from the r2.backups bucket and
- * assemble them into one bundle for the normal placement path. Each object is a
- * self-describing one-record bundle written by `export --to-r2`, so it parses
- * with the same parseBundle. A non-bundle object under the prefix (e.g. a legacy
- * plaintext transcript from the retired sync) is skipped with a count, never
- * silently swallowed. Fails loud when the bucket holds no restorable backups.
- */
-/**
- * `--from-r2` preflight as a pure, unit-testable function: fail loud when the
- * backup target is not configured. Returns the message to fail loud with, or null
- * when the restore may proceed. Kept pure (no process.exit, no keychain read) so
- * the command and its test drive the same decision.
- */
 export declare function r2ImportGateError(fromR2: boolean, isConfigured: boolean): string | null;
 export declare function pullFromR2(resolvedClient?: SessionsBackupClient): Promise<ParsedBundle>;

package/dist/commands/sessions-import.js

@@ -1,13 +1,3 @@
-/**
- * `agents sessions import <bundle|->` — restore an export bundle (RUSH-1711).
- *
- * The inverse of `sessions export`: read a bundle (file or stdin), validate it,
- * and place each transcript where the cross-machine sync would — a mirror keyed
- * by the session's ORIGIN machine (see bundle.ts / mirrorPath). Placement dedups
- * byte-exact against what is already on disk and never clobbers this machine's
- * own live sessions ("local always wins" falls out of the scanner's
- * live-home-first dedup), so a re-import or an overlapping bundle is safe.
- */
 import * as fs from 'fs';
 import chalk from 'chalk';
 import { isSyncConfigured, loadR2Config } from '../lib/session/sync/config.js';
@@ -63,10 +53,7 @@ R2_SYNC_ENC_KEY (or pass --decrypt <key>). It is the inverse of
     });
 }
 async function runImport(bundlePath, options, g, command) {
-    // 1. Obtain the bundle — from R2, remote peer(s), stdin, or a file.
     let bundle;
-    // A managed restore recovers the per-account DEK (from the local cache or the
-    // Worker escrow) and decrypts with it; BYO falls back to the r2.backups key.
     let managedDecryptKey;
     if (options.byo && !options.fromR2) {
         process.stderr.write(chalk.red('--byo is only valid with --from-r2.\n'));
@@ -123,7 +110,6 @@ async function runImport(bundlePath, options, g, command) {
             process.exit(1);
         }
     }
-    // 2. Optional agent filter.
     if (options.agent) {
         bundle = { header: bundle.header, records: bundle.records.filter(r => r.agent === options.agent) };
         if (bundle.records.length === 0) {
@@ -131,13 +117,9 @@ async function runImport(bundlePath, options, g, command) {
             process.exit(1);
         }
     }
-    // 3. Resolve the decryption key if the bundle is encrypted. A managed restore
-    //    already recovered the per-account DEK; otherwise fall back to an explicit
-    //    --decrypt <key> or the shared r2.backups key.
     const decryptKey = bundle.header.encrypted
         ? (managedDecryptKey ?? resolveDecryptKey(options.decrypt))
         : null;
-    // 4. Plan.
     let plan;
     try {
         plan = planImport(bundle, { decryptKey });
@@ -150,7 +132,6 @@ async function runImport(bundlePath, options, g, command) {
         printDryRun(plan, bundle);
         return;
     }
-    // 5. Write.
     const res = writeImport(plan, { overwrite: options.overwrite === true, decryptKey });
     const parts = [];
     if (res.placed)
@@ -165,20 +146,12 @@ async function runImport(bundlePath, options, g, command) {
         parts.push(chalk.yellow(`${res.unknown} unknown-agent skipped`));
     process.stderr.write(chalk.green(`Imported: ${parts.join(', ') || 'nothing to do'}.\n`));
 }
-/** Drain all of stdin to a string. Works for pipes (non-seekable) and redirects
- *  alike — unlike readFileSync(0), which fails on a pipe. */
 async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin)
         chunks.push(Buffer.from(chunk));
     return Buffer.concat(chunks).toString('utf-8');
 }
-/**
- * --from-host: run `agents sessions export …` on each peer over SSH and merge
- * the streamed bundles into one for import. The optional positional acts as a
- * remote selector (id/query); the parent selection flags (--since, -a, --all,
- * -n) forward too.
- */
 async function pullForImport(hosts, selector, g, command) {
     const args = [];
     if (selector && selector !== '-')
@@ -209,20 +182,6 @@ async function pullForImport(hosts, selector, g, command) {
     });
     return { header, records };
 }
-/**
- * --from-r2: download every session-backup object from the r2.backups bucket and
- * assemble them into one bundle for the normal placement path. Each object is a
- * self-describing one-record bundle written by `export --to-r2`, so it parses
- * with the same parseBundle. A non-bundle object under the prefix (e.g. a legacy
- * plaintext transcript from the retired sync) is skipped with a count, never
- * silently swallowed. Fails loud when the bucket holds no restorable backups.
- */
-/**
- * `--from-r2` preflight as a pure, unit-testable function: fail loud when the
- * backup target is not configured. Returns the message to fail loud with, or null
- * when the restore may proceed. Kept pure (no process.exit, no keychain read) so
- * the command and its test drive the same decision.
- */
 export function r2ImportGateError(fromR2, isConfigured) {
     if (fromR2 && !isConfigured) {
         return ('R2 restore is not configured: the r2.backups secrets bundle is missing or locked.\n' +
@@ -231,10 +190,6 @@ export function r2ImportGateError(fromR2, isConfigured) {
     return null;
 }
 export async function pullFromR2(resolvedClient) {
-    // The resolved client (managed HTTP or BYO R2) is passed in by the command; the
-    // no-client overload preserves the original BYO-only signature (loadR2Config)
-    // for the direct unit test. The managed client's list() ignores the prefix and
-    // enumerates the whole owner namespace, so one call site serves both.
     let client;
     let bucket;
     if (resolvedClient) {
@@ -267,7 +222,6 @@ export async function pullFromR2(resolvedClient) {
     let redactedAll = true;
     let skipped = 0;
     for (const key of keys) {
-        // The retired sync wrote a per-machine manifest.json; it is not a bundle.
         if (key.endsWith('/manifest.json'))
             continue;
         let body;
@@ -288,11 +242,6 @@ export async function pullFromR2(resolvedClient) {
             skipped++;
             continue;
         }
-        // Managed transcripts are mandatory AES-256-GCM (SES-51). A plaintext object
-        // in the managed store is a contract violation — an older/buggy writer or
-        // tampering — so fail loud rather than importing readable plaintext. Check
-        // the header AND every record body (matching the Worker's per-record
-        // isEncryptedManagedBundle boundary guard), never just the header flag.
         if (client.kind === 'managed') {
             const plaintext = !parsed.header.encrypted
                 || parsed.records.some(rec => !rec.encrypted || !isTranscriptEnvelope(rec.body));
@@ -326,11 +275,6 @@ export async function pullFromR2(resolvedClient) {
     });
     return { header, records: deduped };
 }
-/**
- * Decrypt-key resolution: an explicit `--decrypt <key>` (base64 or hex) wins;
- * otherwise fall back to the fleet-shared R2_SYNC_ENC_KEY from the r2.backups
- * bundle. Fails loudly when an encrypted bundle has no usable key.
- */
 function resolveDecryptKey(decrypt) {
     if (typeof decrypt === 'string' && decrypt.trim()) {
         const raw = decrypt.trim();
@@ -347,15 +291,12 @@ function resolveDecryptKey(decrypt) {
             return key;
     }
     catch {
-        // sync bundle not configured
     }
     process.stderr.write(chalk.red('This bundle is encrypted but no key is available. Pass --decrypt <key>, ' +
         'or configure the r2.backups sync bundle so its shared key is used.\n'));
     process.exit(1);
 }
-/** Print the dry-run table, grouped by session. Reads disk, writes nothing. */
 function printDryRun(plan, bundle) {
-    // Group file-level plan items by session for a readable table.
     const bySession = new Map();
     for (const item of plan) {
         const key = `${item.record.agent}:${item.record.machine}:${item.record.sessionId}`;

package/dist/commands/sessions-inject.d.ts

@@ -1,74 +1,14 @@
-/**
- * `agents sessions inject <sessionId> <text>` — deliver text into the terminal a
- * running session lives in. The CLI face of the Terminal Engine's Gap 2 primitive
- * (`injectIntoTerminal`, src/lib/terminal/inject.ts), so a native watchdog
- * (RUSH-1415) can shell out to nudge a stalled agent with "continue".
- *
- * Resolution: find the active session by id, then resolve its exact split through
- * the SAME canonical resolver the watchdog uses — `resolveInjectTargetForSession`
- * (lib/terminal/resolve.ts), precedence tmux > iterm > vscodium. Sharing one
- * resolver keeps the manual unblock path and the watchdog in agreement on which
- * sessions are addressable (a prior duplicate resolver read only `provenance.reply`
- * and could not address a VSCodium/Cursor terminal the watchdog handled fine).
- * `--pane` targets a backend directly when the handle is already known.
- */
 import type { Command } from 'commander';
-import { type ActiveSession } from '../lib/session/active.js';
 interface InjectOptions {
     pane?: string;
     socket?: string;
-    /**
-     * The remote device. A single `--device box` arrives here as `['box']` because
-     * the parent `sessions` command's variadic `-D, --device <target...>` shadows
-     * this subcommand's scalar option under `optsWithGlobals()` — normalize it with
-     * {@link normalizeInjectDevice} before use (PHNX-3688).
-     */
     device?: string | string[];
     enter?: boolean;
     combined?: boolean;
     json?: boolean;
 }
-/**
- * Whether an active session is the one `sessions inject <token>` means. Matches
- * a resolvable session id (exact or unique prefix) AND — for a tmux-hosted row
- * whose full id never resolved (`sessionId` absent) — the `ag-<agent>-<shortid>`
- * tmux name's `shortid` suffix (exact or prefix), the full tmux name, and the
- * pane id. Those are the only selectors an id-less remote tmux row exposes, so
- * without this an operator has no tool-native way to nudge it (PHNX-3688).
- */
-export declare function matchInjectSelector(session: ActiveSession, token: string): boolean;
-/**
- * The `--device` selector, normalized to a single host string. `optsWithGlobals()`
- * merges the parent `sessions` command's variadic `-D, --device <target...>` over
- * this subcommand's scalar `--device`, so a single `--device box` arrives as
- * `['box']` — which flowed straight into `sshExec` and crashed on
- * `host.startsWith` (PHNX-3688). Delegates to the shared
- * {@link normalizeSingleDeviceOption} (also used by `sessions resume`,
- * PHNX-3940) rather than re-implementing the array/scalar coercion here.
- */
 export declare function normalizeInjectDevice(value: string | string[] | undefined): string | undefined;
-/**
- * The `agents sessions inject` argv to re-run ON a device (its tmux panes live
- * there, so resolution must happen there). Every flag rides along EXCEPT
- * `--device`: the command runs on the device, resolving locally. Pure so the
- * forwarded invocation is asserted without an SSH hop (PHNX-3688).
- */
 export declare function buildRemoteInjectArgv(sessionId: string, text: string, options: InjectOptions): string[];
-/**
- * Resolve `device` (registry alias or `user@host`) to an ssh target and re-run
- * `agents sessions inject` there, so a bare session id + `--device` resolves on
- * the box that actually holds the session's tmux panes. The tool-native form of
- * the `agents ssh <device> "agents sessions inject <id> …"` workaround (PHNX-3688).
- */
-/**
- * Resolve `--device` to an ssh target. A registered device becomes its
- * `user@dnsName`; a bare unknown name (an ad-hoc `user@host` or ssh_config alias)
- * is handed to ssh verbatim (`resolveHost` returns null for it). A registered
- * device we CANNOT dial — password-auth, addressless — throws its typed error and
- * is NOT degraded to the raw name, which could ssh a coincidentally-matching but
- * unrelated `~/.ssh/config` Host (PHNX-3688 review).
- */
 export declare function resolveInjectSshTarget(device: string): Promise<string>;
-/** Attach the `inject` subcommand to an existing `sessions` command. */
 export declare function registerSessionsInjectCommand(sessionsCmd: Command): void;
 export {};

package/dist/commands/sessions-inject.js

@@ -1,66 +1,14 @@
-/**
- * `agents sessions inject <sessionId> <text>` — deliver text into the terminal a
- * running session lives in. The CLI face of the Terminal Engine's Gap 2 primitive
- * (`injectIntoTerminal`, src/lib/terminal/inject.ts), so a native watchdog
- * (RUSH-1415) can shell out to nudge a stalled agent with "continue".
- *
- * Resolution: find the active session by id, then resolve its exact split through
- * the SAME canonical resolver the watchdog uses — `resolveInjectTargetForSession`
- * (lib/terminal/resolve.ts), precedence tmux > iterm > vscodium. Sharing one
- * resolver keeps the manual unblock path and the watchdog in agreement on which
- * sessions are addressable (a prior duplicate resolver read only `provenance.reply`
- * and could not address a VSCodium/Cursor terminal the watchdog handled fine).
- * `--pane` targets a backend directly when the handle is already known.
- */
 import chalk from 'chalk';
-import { getActiveSessions, shortIdFromName } from '../lib/session/active.js';
-import { injectIntoTerminal, resolveInjectTargetForSession } from '../lib/terminal/index.js';
+import { injectIntoTerminal } from '../lib/terminal/index.js';
+import { resolveLiveInjectTarget } from '../lib/session/inject-target.js';
 import { sshExec, shellQuote } from '../lib/ssh-exec.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { setHelpSections } from '../lib/help.js';
 import { normalizeSingleDeviceOption } from './utils.js';
-/**
- * Whether an active session is the one `sessions inject <token>` means. Matches
- * a resolvable session id (exact or unique prefix) AND — for a tmux-hosted row
- * whose full id never resolved (`sessionId` absent) — the `ag-<agent>-<shortid>`
- * tmux name's `shortid` suffix (exact or prefix), the full tmux name, and the
- * pane id. Those are the only selectors an id-less remote tmux row exposes, so
- * without this an operator has no tool-native way to nudge it (PHNX-3688).
- */
-export function matchInjectSelector(session, token) {
-    if (!token)
-        return false;
-    const sid = session.sessionId;
-    if (sid && (sid === token || sid.startsWith(token)))
-        return true;
-    const short = session.tmuxName ? shortIdFromName(session.tmuxName) : undefined;
-    if (short && (short === token || short.startsWith(token)))
-        return true;
-    if (session.tmuxName && session.tmuxName === token)
-        return true;
-    if (session.paneId && session.paneId === token)
-        return true;
-    return false;
-}
-/**
- * The `--device` selector, normalized to a single host string. `optsWithGlobals()`
- * merges the parent `sessions` command's variadic `-D, --device <target...>` over
- * this subcommand's scalar `--device`, so a single `--device box` arrives as
- * `['box']` — which flowed straight into `sshExec` and crashed on
- * `host.startsWith` (PHNX-3688). Delegates to the shared
- * {@link normalizeSingleDeviceOption} (also used by `sessions resume`,
- * PHNX-3940) rather than re-implementing the array/scalar coercion here.
- */
 export function normalizeInjectDevice(value) {
     return normalizeSingleDeviceOption(value, 'sessions inject');
 }
-/**
- * The `agents sessions inject` argv to re-run ON a device (its tmux panes live
- * there, so resolution must happen there). Every flag rides along EXCEPT
- * `--device`: the command runs on the device, resolving locally. Pure so the
- * forwarded invocation is asserted without an SSH hop (PHNX-3688).
- */
 export function buildRemoteInjectArgv(sessionId, text, options) {
     const argv = ['agents', 'sessions', 'inject', sessionId, text];
     if (options.enter === false)
@@ -75,20 +23,6 @@ export function buildRemoteInjectArgv(sessionId, text, options) {
         argv.push('--json');
     return argv;
 }
-/**
- * Resolve `device` (registry alias or `user@host`) to an ssh target and re-run
- * `agents sessions inject` there, so a bare session id + `--device` resolves on
- * the box that actually holds the session's tmux panes. The tool-native form of
- * the `agents ssh <device> "agents sessions inject <id> …"` workaround (PHNX-3688).
- */
-/**
- * Resolve `--device` to an ssh target. A registered device becomes its
- * `user@dnsName`; a bare unknown name (an ad-hoc `user@host` or ssh_config alias)
- * is handed to ssh verbatim (`resolveHost` returns null for it). A registered
- * device we CANNOT dial — password-auth, addressless — throws its typed error and
- * is NOT degraded to the raw name, which could ssh a coincidentally-matching but
- * unrelated `~/.ssh/config` Host (PHNX-3688 review).
- */
 export async function resolveInjectSshTarget(device) {
     const host = await resolveHost(device);
     return host ? sshTargetFor(host) : device;
@@ -115,24 +49,6 @@ async function injectOnDevice(sessionId, text, options, device) {
     if (res.code !== 0)
         process.exit(res.code ?? 1);
 }
-/** Resolve a session id (short or full) to an addressable terminal target, via the
- * same resolver the watchdog uses so both agree on what is reachable. */
-async function resolveTarget(sessionId) {
-    const sessions = await getActiveSessions();
-    const match = sessions.find((s) => matchInjectSelector(s, sessionId));
-    if (!match)
-        return { target: null, reason: `No active session matches "${sessionId}".` };
-    const resolution = resolveInjectTargetForSession(match);
-    if (!resolution.addressable) {
-        // Surface the resolver's precise reason (host/rail), not a generic "not tmux".
-        return {
-            target: null,
-            reason: `Session "${sessionId}": ${resolution.reason}`,
-            hint: resolution.hint,
-        };
-    }
-    return { target: resolution.target };
-}
 async function runInject(sessionId, text, options) {
     let device;
     try {
@@ -146,21 +62,15 @@ async function runInject(sessionId, text, options) {
             console.error(chalk.red(message));
         process.exit(1);
     }
-    // Direct-target shortcut skips the session lookup — the watchdog often already
-    // holds the pane id it wants to type into. The pane's exact address is known,
-    // so it composes with --device (tmux send-keys over SSH).
     let target = null;
     if (options.pane) {
         target = { backend: 'tmux', pane: options.pane, socket: options.socket };
     }
     else if (device) {
-        // A bare session id + a device: the session's tmux panes live ON that device,
-        // so getActiveSessions here can't see them. Resolve + deliver THERE by re-running
-        // inject over SSH (the same command, minus --device) — PHNX-3688.
         return injectOnDevice(sessionId, text, options, device);
     }
     else {
-        const resolved = await resolveTarget(sessionId);
+        const resolved = await resolveLiveInjectTarget(sessionId);
         if (!resolved.target) {
             const message = resolved.hint ? `${resolved.reason}\n${resolved.hint}` : resolved.reason;
             if (options.json)
@@ -189,7 +99,6 @@ async function runInject(sessionId, text, options) {
     if (!res.ok)
         process.exit(1);
 }
-/** Attach the `inject` subcommand to an existing `sessions` command. */
 export function registerSessionsInjectCommand(sessionsCmd) {
     const injectCmd = sessionsCmd
         .command('inject <sessionId> <text>')
@@ -228,8 +137,6 @@ export function registerSessionsInjectCommand(sessionsCmd) {
         the lookup on that box (its tmux panes live there, not here).
     `,
     });
-    // The parent `sessions` command also defines --json, so it binds there;
-    // optsWithGlobals() merges parent + subcommand options so --json is honored.
     injectCmd.action(async (sessionId, text, _options, command) => {
         await runInject(sessionId, text, command.optsWithGlobals());
     });