@phnx-labs/agents-cli 1.22.25 → 1.22.26

package/dist/commands/insights.js

@@ -1,23 +1,26 @@
 /**
- * Insights command — how you actually work, split by the account that did the work.
+ * Insights command — one observe verb for "how work looks".
  *
- * The behavioural sibling of the existing rollups, and deliberately not a duplicate of
- * any of them:
+ * Two data paths under one name (do not re-split into peer top-level commands):
  *
- *   agents cost      what you spent            ($ and duration)
- *   agents output    what shipped              (burn vs PRs and commits)
- *   agents usage     live quota headroom       (rate-limit windows, right now)
- *   agents trends    aggregate distributions   (harness mix, tools-per-session, token ratios)
- *   agents sessions  browse individual work    (search, resume, render)
- *   agents insights  HOW you work              (tools, friction, rhythm, per account)
+ *   agents insights              HOW you work (transcript content: tools, friction,
+ *                                rhythm, edits) — split by Claude account by default
+ *   agents insights mix          COUNTERS (sessions index + usage.db recipes:
+ *                                harness/model mix, token ratios, secrets, browser)
+ *   agents insights <recipe>     One baked mix recipe (harness-mix, tools-per-session, …)
+ *   agents insights query        Raw usage.db rows
  *
- * The closest neighbour is `agents trends`, and the boundary is the data path: trends
- * reads counters — `tool_scan_ledger` call counts and the analytics warehouse — to
- * produce distributions ("how many tool calls per session, by harness"). This reads
- * transcript CONTENT through `parseSession` to produce behaviour ("which tools, which
- * languages, where it went wrong, when you were working"), and splits all of it by
- * account, a dimension trends does not have. They overlap in spirit on tool and model
- * mix; they do not read the same store or answer the same question.
+ * Sibling observe verbs (stay separate — different questions):
+ *
+ *   agents cost       what you spent ($ and duration)
+ *   agents output     what shipped (burn vs PRs and commits)
+ *   agents usage      live quota headroom
+ *   agents perf       latency (hooks, CLI commands, agent.run) — not popularity
+ *   agents sessions stats  which skills/slash-commands were explicitly invoked
+ *
+ * Why mix lives here (not a second top-level `trends`): two abstract "analytics"
+ * nouns taught agents and humans to guess. One verb, two engines — cheap SQL mix
+ * vs transcript facets. Latency stays on `perf` so it is never confused with mix.
  *
  * Modelled on Claude Code's `/insights`, with the difference that motivated it: that
  * command reads one account's directory, while `balanced` rotation sprays sessions
@@ -27,6 +30,8 @@
  * The deterministic report makes zero network calls. `--narrative` is opt-in and adds
  * the coaching prose by piping the AGGREGATE (never raw transcripts) through a headless
  * `claude -p`.
+ *
+ * `agents trends` is a thin deprecated alias of the mix tree only (see commands/trends.ts).
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
@@ -37,11 +42,25 @@ import { setHelpSections } from '../lib/help.js';
 import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
 import { querySessions, readSessionInsights, writeSessionInsights, clearSessionInsights, } from '../lib/session/db.js';
 import { parseSession } from '../lib/session/parse.js';
-import { computeInsightFacets, mergeFacets, newFacetAccumulator, detectOverlap, percentile, bucketGaps, topEntries, } from '../lib/session/insights.js';
+import { computeInsightFacets, mergeFacets, newFacetAccumulator, detectOverlap, percentile, bucketGaps, topEntries, buildInsightActions, } from '../lib/session/insights.js';
 import { formatUsd } from '../lib/pricing/index.js';
 import { formatDuration } from '../lib/session/render.js';
 import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
+import { registerMixCommands } from '../lib/analytics/mix-commands.js';
 const execFileAsync = promisify(execFile);
+function collectAgent(value, previous) {
+    return [...previous, value];
+}
+function agentsFromArgv(argv) {
+    const values = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--agent' && argv[i + 1])
+            values.push(argv[++i]);
+        else if (argv[i].startsWith('--agent='))
+            values.push(argv[i].slice('--agent='.length));
+    }
+    return values;
+}
 function resolveGroup(by) {
     if (by === undefined)
         return 'account';
@@ -187,7 +206,7 @@ function renderHours(hours, out) {
     out.push(`  ${chalk.cyan(spark)}`);
     out.push(`  ${chalk.gray('0h'.padEnd(6))}${chalk.gray('6h'.padEnd(6))}${chalk.gray('12h'.padEnd(6))}${chalk.gray('18h'.padEnd(5))}${chalk.gray('23h')}`);
 }
-function renderReport(groups, dim, meta) {
+function renderReport(groups, dim, meta, actions, harnesses) {
     const out = [];
     const scope = meta.since ? `last ${meta.since}` : 'all time';
     out.push(chalk.bold('Insights') + chalk.gray(`  ${scope} · ${meta.analyzed} of ${meta.scanned} sessions`));
@@ -232,6 +251,22 @@ function renderReport(groups, dim, meta) {
         for (const e of errs)
             out.push(`    ${chalk.gray('·')} ${padToWidth(e.name, 16)} ${chalk.gray(String(e.count))}`);
     }
+    renderCounts('Friction / thrash', topEntries(all.frictionSignals, 10), out);
+    renderCounts('Dissatisfaction / corrections', topEntries(all.correctionSignals, 10), out);
+    renderCounts('Automatable repeats', topEntries(all.automationSignals, 10), out);
+    renderCounts('Harness split', harnesses, out);
+    out.push('');
+    out.push(chalk.bold('Actions'));
+    if (actions.length === 0) {
+        out.push(chalk.gray('  No repeated action pattern met the evidence threshold in this window.'));
+    }
+    else {
+        out.push(chalk.gray('  pri     category    evidence  sample sessions  action'));
+        for (const action of actions.slice(0, 12)) {
+            out.push(`  ${padToWidth(action.priority, 7)} ${padToWidth(action.category, 11)} ` +
+                `${String(action.evidenceCount).padStart(8)}  ${padToWidth(action.sampleSessionIds.join(', '), 25)} ${action.action}`);
+        }
+    }
     // Output
     out.push('');
     out.push(chalk.bold('What you changed'));
@@ -351,11 +386,11 @@ async function insightsAction(options) {
     if (options.refresh)
         clearSessionInsights();
     const filter = { sinceMs };
-    if (options.agent)
-        filter.agent = options.agent;
     const scanned = querySessions(filter);
     const wanted = options.account?.toLowerCase();
     const inScope = scanned.filter((m) => {
+        if (options.agent?.length && !options.agent.includes(m.agent))
+            return false;
         if (!wanted)
             return true;
         return [m.accountKey, m.account, m.accountOrg]
@@ -381,6 +416,15 @@ async function insightsAction(options) {
     });
     const overlap = detectOverlap(spans);
     const groups = buildGroups(substantive, facetsById, dim);
+    const evidence = substantive.flatMap((m) => {
+        const facets = facetsById.get(m.id);
+        return facets ? [{ id: m.id, facets }] : [];
+    });
+    const actions = buildInsightActions(evidence);
+    const harnesses = topEntries(substantive.reduce((counts, row) => {
+        counts[row.agent] = (counts[row.agent] ?? 0) + 1;
+        return counts;
+    }, {}), 20);
     if (options.json) {
         const payload = {
             generatedAt: new Date().toISOString(),
@@ -392,6 +436,8 @@ async function insightsAction(options) {
             minMessages,
             by: dim,
             overlap,
+            actions,
+            harnesses,
             groups: groups.map((g) => ({
                 key: g.key,
                 label: g.label,
@@ -420,7 +466,7 @@ async function insightsAction(options) {
         unreadable,
         minMessages,
         overlap,
-    });
+    }, actions, harnesses);
     if (options.narrative) {
         await renderNarrative(groups.map((g) => ({
             account: g.label, sessions: g.sessions, costUsd: g.costUsd,
@@ -434,49 +480,77 @@ async function insightsAction(options) {
         })));
     }
 }
-export function registerInsightsCommand(program) {
-    const cmd = addHostOption(program.command('insights'))
-        .description('How you work — tools, friction, and rhythm, split by the account that did the work')
+function configureInsightsCommand(cmd) {
+    addHostOption(cmd)
+        .description('How work looks — behavioural report (default) or counter mix (`mix`, recipes)')
         .option('--json', 'Output the full report as JSON')
         .option('--since <time>', 'Window: 7d, 4w, 3mo, an ISO date, or "all" (default 30d)')
         .option('--all', 'Every session ever indexed. Alias for --since all')
         .option('--by <dimension>', 'Group by: account (default), agent, project, or day')
         .option('--account <match>', 'Only sessions whose account key, email, or org contains this')
-        .option('--agent <id>', 'Only one harness (claude, codex, droid, …)')
+        .option('--agent <id>', 'Only these harnesses; repeat for more than one', collectAgent, [])
         .option('--min-messages <n>', 'Skip sessions under this many messages, both roles counted (default 2)')
         .option('--refresh', 'Discard cached facets and re-read every transcript')
         .option('--narrative', 'Add a written read on the numbers via a headless `claude -p`')
         .action(async (options) => {
-        await insightsAction(options);
+        const inherited = cmd.parent?.name() === 'sessions'
+            ? cmd.parent.opts()
+            : {};
+        const inheritedAgent = typeof inherited.agent === 'string' ? [inherited.agent] : [];
+        const rawAgents = agentsFromArgv(process.argv.slice(2));
+        await insightsAction({
+            ...inherited,
+            ...options,
+            agent: rawAgents.length > 0 ? rawAgents : [...inheritedAgent, ...(options.agent ?? [])],
+            json: options.json ?? inherited.json,
+            since: options.since ?? inherited.since,
+        });
     });
+    // Cheap counter recipes (former top-level `agents trends`) — same parent, no peer verb.
+    registerMixCommands(cmd);
     setHelpSections(cmd, {
         examples: `
-      # Last 30 days, split by Claude account — the default
+      # Behavioural report — last 30 days, split by Claude account (default)
       agents insights
 
       # Which repo is eating the time
       agents insights --by project --since 90d
 
+      # Counter mix board (harness/model/token/secrets recipes) — former agents trends
+      agents insights mix
+      agents insights mix --days 30
+      agents insights harness-mix --json
+      agents insights query --kind secret --days 7
+
       # One account only, all of its history
       agents insights --account "Turing Labs" --all
 
       # Machine-readable, for a dashboard or a slash command
-      agents insights --json
+      agents sessions insights --agent claude --agent codex --json
 
       # Add a written read on what to change
       agents insights --narrative
     `,
         notes: `
-      Answers "how do you work". For "what did it cost" use \`agents cost\`, for "what
-      shipped" use \`agents output\`, for live quota use \`agents usage\`.
+      Two paths under one verb:
+        bare \`agents insights\`     — transcript behaviour (tools, friction, rhythm, by account)
+        \`agents insights mix\`      — cheap counters from sessions.db + usage.db
+      Latency is \`agents perf\` (not mix). Quota is \`agents usage\`. Skill/slash popularity
+      is \`agents sessions stats\`. \`agents trends\` is a deprecated alias of the mix tree.
 
-      The first run parses every in-scope transcript and caches the result; later runs
+      The behavioural report parses in-scope transcripts once and caches facets; later runs
       re-read only files that changed. \`--refresh\` forces a full re-read.
 
-      Account attribution is Claude-only today. Sessions from other harnesses group
-      under \`unattributed:<agent>\`.
+      \`agents insights\` is the top-level alias of \`agents sessions insights\`.
+      Repeat \`--agent\` to compare several harnesses in one report.
 
       Everything except \`--narrative\` is local and makes no network calls.
     `,
     });
 }
+export function registerInsightsCommand(program) {
+    configureInsightsCommand(program.command('insights'));
+}
+export function registerSessionsInsightsCommand(sessions) {
+    configureInsightsCommand(sessions.command('insights'));
+}

package/dist/commands/reconnect.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `agents reconnect [session-id]` — get me back into an agent terminal whose ssh
+ * link dropped.
+ *
+ * The auto-reconnect in lib/hosts/reconnect.ts already re-attaches a live remote
+ * pane over its own bounded backoff on a transient blink. This is the MANUAL
+ * recovery for after it gave up — a sustained outage, or a VS Code terminal tab
+ * that closed with the dead ssh client. One verb that always tries hardest to put
+ * you back into that agent: attach the live pane if it still exists, else resume
+ * the session; live pane > resumed copy > a clear message about what was lost.
+ *
+ * It delegates to `focus`, which already does exactly attach-else-resume for a
+ * resolved id ({@link focusAction} → `focusResolvedSession`), so there is no second
+ * recovery path to keep in sync. What `reconnect` adds is the recovery framing and,
+ * with no id, targeting the MOST RECENT session in this shell's directory — the one
+ * that most likely just dropped — instead of opening the full fleet picker.
+ */
+import type { Command } from 'commander';
+import type { SessionMeta } from '../lib/session/types.js';
+/**
+ * The recency signal a no-id reconnect targets: last activity if the scan
+ * computed one, else the creation time. A row with neither parseable sorts last.
+ * Pure so target selection is unit-tested without the scanner.
+ */
+export declare function sessionRecency(s: Pick<SessionMeta, 'lastActivity' | 'timestamp'>): number;
+/**
+ * Pick the session to reconnect when the user gave no id: the most recently
+ * active one in scope — the terminal that most likely just dropped. Pure; returns
+ * undefined for an empty scope so the caller can print guidance.
+ */
+export declare function pickMostRecentSession(sessions: SessionMeta[]): SessionMeta | undefined;
+/**
+ * Resolve the no-id target: prefer the most recent session started from THIS
+ * directory (the shell the user is reconnecting from), falling back to the most
+ * recent session anywhere when the current directory has none. Best-effort — a
+ * discovery failure yields undefined, never throws. Injectable `discover` keeps
+ * the two-step scope preference testable without touching the real scanner.
+ */
+export declare function resolveRecentTarget(cwd: string, discover?: (opts: {
+    cwd?: string;
+    all?: boolean;
+    since?: string;
+    limit?: number;
+}) => Promise<SessionMeta[]>): Promise<SessionMeta | undefined>;
+export declare function reconnectAction(id: string | undefined): Promise<void>;
+export declare function registerReconnectCommand(program: Command): void;

package/dist/commands/reconnect.js

@@ -0,0 +1,109 @@
+/**
+ * `agents reconnect [session-id]` — get me back into an agent terminal whose ssh
+ * link dropped.
+ *
+ * The auto-reconnect in lib/hosts/reconnect.ts already re-attaches a live remote
+ * pane over its own bounded backoff on a transient blink. This is the MANUAL
+ * recovery for after it gave up — a sustained outage, or a VS Code terminal tab
+ * that closed with the dead ssh client. One verb that always tries hardest to put
+ * you back into that agent: attach the live pane if it still exists, else resume
+ * the session; live pane > resumed copy > a clear message about what was lost.
+ *
+ * It delegates to `focus`, which already does exactly attach-else-resume for a
+ * resolved id ({@link focusAction} → `focusResolvedSession`), so there is no second
+ * recovery path to keep in sync. What `reconnect` adds is the recovery framing and,
+ * with no id, targeting the MOST RECENT session in this shell's directory — the one
+ * that most likely just dropped — instead of opening the full fleet picker.
+ */
+import chalk from 'chalk';
+import { focusAction } from './focus.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { setHelpSections } from '../lib/help.js';
+/**
+ * The recency signal a no-id reconnect targets: last activity if the scan
+ * computed one, else the creation time. A row with neither parseable sorts last.
+ * Pure so target selection is unit-tested without the scanner.
+ */
+export function sessionRecency(s) {
+    const t = Date.parse(s.lastActivity ?? s.timestamp ?? '');
+    return Number.isFinite(t) ? t : Number.NEGATIVE_INFINITY;
+}
+/**
+ * Pick the session to reconnect when the user gave no id: the most recently
+ * active one in scope — the terminal that most likely just dropped. Pure; returns
+ * undefined for an empty scope so the caller can print guidance.
+ */
+export function pickMostRecentSession(sessions) {
+    let best;
+    for (const s of sessions) {
+        if (!best || sessionRecency(s) > sessionRecency(best))
+            best = s;
+    }
+    return best;
+}
+/**
+ * Resolve the no-id target: prefer the most recent session started from THIS
+ * directory (the shell the user is reconnecting from), falling back to the most
+ * recent session anywhere when the current directory has none. Best-effort — a
+ * discovery failure yields undefined, never throws. Injectable `discover` keeps
+ * the two-step scope preference testable without touching the real scanner.
+ */
+export async function resolveRecentTarget(cwd, discover = discoverSessions) {
+    try {
+        const here = await discover({ cwd, since: '7d', limit: 200 });
+        const local = pickMostRecentSession(here);
+        if (local)
+            return local;
+        const any = await discover({ all: true, since: '7d', limit: 200 });
+        return pickMostRecentSession(any);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function reconnectAction(id) {
+    if (id) {
+        // focus already attaches a live pane or recovers a dropped one for a resolved
+        // id — on the origin device for a remote session. Reconnect is that path with
+        // a recovery-first name; no reason to duplicate the resolution/attach logic.
+        await focusAction(id, {});
+        return;
+    }
+    const recent = await resolveRecentTarget(process.cwd());
+    if (!recent) {
+        console.log(chalk.gray('No recent session to reconnect from here.'));
+        console.log(chalk.gray('  reconnect a specific one:  agents reconnect <session-id>'));
+        console.log(chalk.gray('  or pick from the fleet:    agents sessions'));
+        return;
+    }
+    const where = recent.machine ? ` on ${recent.machine}` : '';
+    console.log(chalk.gray(`Reconnecting ${recent.shortId}${where} (most recent here)…`));
+    await focusAction(recent.id, {});
+}
+export function registerReconnectCommand(program) {
+    const cmd = program
+        .command('reconnect')
+        .argument('[session-id]', 'Session id/prefix to reconnect (default: the most recent session started here)')
+        .description('Re-enter a dropped agent terminal: attach the live pane if it survived, else resume the session')
+        .action(async (id) => {
+        await reconnectAction(id);
+    });
+    setHelpSections(cmd, {
+        examples: `
+      # Reconnect the session that just dropped in this shell (most recent here)
+      agents reconnect
+
+      # Reconnect one specific agent terminal by id/prefix
+      agents reconnect 74b13b0b
+
+      # Same, spelled under the sessions group
+      agents sessions reconnect 74b13b0b
+    `,
+        notes: `
+      - Best-effort recovery: a living remote tmux pane is JOINED (a second client, no fork); a dropped one is RESUMED on its origin device (a copy if it was mid-run, a /continue if idle).
+      - With no id, targets the most recent session started from this directory (the terminal that most likely just dropped), not the full fleet picker. Falls back to the most recent session anywhere when this directory has none.
+      - This is the manual companion to the automatic reconnect that runs during a live 'agents run --device <box>' when the network blinks; use it after that gave up or the terminal tab closed.
+      - Related: 'agents sessions focus' (attach/recover with a picker) and 'agents sessions resume' (multi-select history -> tabs).
+    `,
+    });
+}

package/dist/commands/routines.js

@@ -12,7 +12,7 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, } from '../lib/daemon.js';
 import { assertSchedulerEnabled } from '../lib/device-config.js';
-import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
+import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError, ROUTINE_AGENT_IDS } from '../lib/agents.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
 import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, routineStats, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, HOST_STRATEGIES, computeProjectGroup, computeProjectGroupKind, projectGroupKey, projectGroupTitle, projectGroupOrder, normalizeProjects, } from '../lib/routines.js';
 import { listProjectDefs, isSafeProjectName } from '../lib/projects.js';
@@ -21,7 +21,7 @@ import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js'
 import { getRoutinesDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
 import { safeJoin } from '../lib/paths.js';
-import { executeJob, monitorRunningJobs, ROUTINE_AGENT_IDS } from '../lib/runner.js';
+import { executeJob, monitorRunningJobs } from '../lib/runner.js';
 import { JobScheduler } from '../lib/scheduler.js';
 import { detectOverdueJobs } from '../lib/overdue.js';
 import { runCatchup } from '../lib/catchup.js';

package/dist/commands/secrets.d.ts

@@ -8,6 +8,8 @@
 import { type Command } from 'commander';
 import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg } from '../lib/platform/index.js';
+import { bundleEnvToDotenv } from '../lib/secrets/push.js';
+export { bundleEnvToDotenv };
 import { type SecretsBackend, type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
 import { type SecretsListFilterOpts } from '../lib/secrets/list-filter.js';
 import { type BundleUsageSummary } from '../lib/secrets/usage-db.js';
@@ -78,14 +80,6 @@ export { SSH_TARGET_RE, assertValidSshTarget };
  * the executed command.
  */
 export declare function buildSecretsExecEnv(parentEnv: NodeJS.ProcessEnv, secretEnv: Record<string, string>): NodeJS.ProcessEnv;
-/**
- * Serialize a resolved env map to `.env` lines that round-trip losslessly through
- * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
- * quote pair and takes the inner bytes verbatim (no unescaping), so any single-line
- * value survives unchanged with no escaping. Newlines would break its line-based
- * parse, so multi-line values are rejected rather than silently corrupted.
- */
-export declare function bundleEnvToDotenv(env: Record<string, string>): string;
 /**
  * Encrypt a resolved env map to an offline bundle file using AES-256-GCM
  * (the same EncFile envelope as the per-item file store). Inner plaintext is

package/dist/commands/secrets.js

@@ -12,12 +12,12 @@ import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/widt
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { SSH_TARGET_RE, assertValidSshTarget, sshExec } from '../lib/ssh-exec.js';
+import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg, composeWin32CommandLine } from '../lib/platform/index.js';
 import { ensureDaemonStarted, isDaemonRunning } from '../lib/daemon.js';
-import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, verifyRemoteKeychainPush, keychainWriteFailureMessage, buildRemoteFileImportCommand, } from '../lib/secrets/remote.js';
-import { remoteShellFor, buildWindowsStdinImportCommand } from '../lib/hosts/remote-cmd.js';
-import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
+import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, } from '../lib/secrets/remote.js';
+import { resolveBundleForPush, pushResolvedBundleToHost, bundleEnvToDotenv } from '../lib/secrets/push.js';
+export { bundleEnvToDotenv };
 import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, healKeychainBundleMetadataAclOnce, isHeadlessSecretsContext, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, readBundleIfDecryptable, reAclBundleItems, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, SECRET_TYPES, } from '../lib/secrets/bundles.js';
 import { parseListFilters, bundleMatchesFilter, bundleExpiry, filterIsActive, describeFilter, parseSortField, sortBundles, SORT_FIELDS, REF_KINDS, DEFAULT_EXPIRING_DAYS, } from '../lib/secrets/list-filter.js';
 import { encryptForFallback, decryptForFallback } from '../lib/secrets/filestore.js';
@@ -354,24 +354,6 @@ function getCliVersion() {
         return '0.0.0';
     }
 }
-/**
- * Serialize a resolved env map to `.env` lines that round-trip losslessly through
- * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
- * quote pair and takes the inner bytes verbatim (no unescaping), so any single-line
- * value survives unchanged with no escaping. Newlines would break its line-based
- * parse, so multi-line values are rejected rather than silently corrupted.
- */
-export function bundleEnvToDotenv(env) {
-    const lines = [];
-    for (const [k, v] of Object.entries(env)) {
-        if (/[\r\n]/.test(v)) {
-            throw new Error(`Key '${k}' has a multi-line value; the SSH .env transport can't carry newlines. ` +
-                `Set it directly on the remote with 'agents secrets add ${k} --value-stdin'.`);
-        }
-        lines.push(`${k}="${v}"`);
-    }
-    return lines.join('\n') + '\n';
-}
 /**
  * Encrypt a resolved env map to an offline bundle file using AES-256-GCM
  * (the same EncFile envelope as the per-item file store). Inner plaintext is
@@ -2115,100 +2097,42 @@ Examples:
             if (hosts.length > 0) {
                 for (const h of hosts)
                     assertValidSshTarget(h);
-                const remoteBackend = parseBackendOpt(opts.remoteBackend);
+                const parsedBackend = parseBackendOpt(opts.remoteBackend);
+                // `--remote-backend` documents keychain|file only, and parseBackendOpt
+                // exits on anything else — but its return type still admits 'vault',
+                // which has no remote-push path. Refuse it here rather than let it fall
+                // through to the keychain branch and half-work.
+                if (parsedBackend === 'vault') {
+                    console.error(chalk.red("--remote-backend vault is not supported; use 'keychain' or 'file'."));
+                    process.exit(1);
+                }
+                const remoteBackend = parsedBackend;
                 // For a file-backed remote bundle a passphrase is OPTIONAL. The file
                 // store is passphrase-free by default: with AGENTS_SECRETS_PASSPHRASE
                 // unset the remote `import --backend file` auto-provisions the remote's
                 // own machine-local key (0600 under ~/.agents/.secrets-key/), so reads
                 // are HEADLESS. We forward the LOCAL AGENTS_SECRETS_PASSPHRASE only when
-                // the operator opts in by setting it (e.g. to key the bundle off-disk
-                // under a shared secret) — shipped as the FIRST stdin line so it never
-                // lands in argv / `ps` / the remote shell history. Forcing a shared
-                // passphrase would defeat headless reads, so we no longer require one.
+                // the operator opts in by setting it. Forcing a shared passphrase would
+                // defeat headless reads, so we no longer require one.
                 const remotePassphrase = remoteBackend === 'file' ? (process.env.AGENTS_SECRETS_PASSPHRASE ?? '') : '';
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `ssh export`, keyMode: 'storage', agentOnly: true });
-                const dotenv = bundleEnvToDotenv(env);
-                const keyCount = Object.keys(env).length;
-                // Drive the remote's own `agents secrets import --from -` so the values
-                // land in its chosen backend, reading the .env off ssh stdin (never
-                // parsed by a remote shell — `--from -` replaces the POSIX-only
-                // `/dev/stdin`). The keychain path is built OS-aware via
-                // `remoteSecretsRaw` (bash -lc on POSIX, PowerShell on Windows), so it
-                // works on macOS, Linux AND Windows targets. `import` auto-creates the
-                // bundle, so no separate `create` (the old `|| true` was a POSIXism
-                // that broke on PowerShell: `'true' is not recognized`).
+                // Resolve ONCE for N hosts — reading a bundle can prompt, and doing it
+                // per host would prompt per host.
+                const resolvedForPush = resolveBundleForPush(resolvedBundleName, 'ssh export');
+                const keyCount = resolvedForPush.keyCount;
                 let failures = 0;
                 for (const host of hosts) {
-                    let res;
-                    if (remoteBackend === 'file') {
-                        // File backend: headless-readable via the remote's machine-local key
-                        // when no passphrase is set; otherwise forwards AGENTS_SECRETS_PASSPHRASE
-                        // as the FIRST stdin line (consumed by `read`, so it never lands in
-                        // argv / `ps` / remote history), then the .env. Both build a POSIX
-                        // `bash -lc` command — refuse a Windows target cleanly rather than
-                        // emit broken PowerShell.
-                        if (remoteShellFor(resolveRemoteOsSync(host.split('@').pop() ?? host)) === 'powershell') {
-                            failures++;
-                            console.error(chalk.red(`${host}: file backend export to a Windows target is not yet supported.`));
-                            continue;
-                        }
-                        const { remoteCmd, input } = buildRemoteFileImportCommand(resolvedBundleName, dotenv, {
-                            passphrase: remotePassphrase,
-                            force: opts.force,
-                        });
-                        res = sshExec(host, remoteCmd, { input });
-                    }
-                    else if (remoteShellFor(resolveRemoteOsSync(host.split('@').pop() ?? host)) === 'powershell') {
-                        // Keychain on a Windows target: the `agents.ps1` shim doesn't
-                        // forward ssh-piped stdin to node, so `--from -` would hang.
-                        // Bridge the piped .env through PowerShell into a temp file and
-                        // import `--from <file>` (deleted afterwards). Same hardened ssh
-                        // engine, .env still only ever crosses the wire over ssh stdin.
-                        res = sshExec(host, buildWindowsStdinImportCommand(resolvedBundleName, { force: opts.force }), { input: dotenv });
-                    }
-                    else {
-                        // Keychain on a POSIX target: OS-aware wrapping + hardened ssh
-                        // engine (BatchMode, ConnectTimeout, keepalive, control-socket
-                        // reuse) via the same path the READ inverse (`remoteResolveEnv`)
-                        // uses. `--from -` reads the .env off ssh stdin.
-                        res = remoteSecretsRaw(host, ['import', resolvedBundleName, '--from', '-', ...(opts.force ? ['--force'] : [])], { input: dotenv, osLookupName: host });
-                    }
-                    if (res.code === null) {
-                        failures++;
-                        console.error(chalk.red(`${host}: ${res.stderr.trim() || (res.timedOut ? 'ssh timed out' : 'ssh failed')}`));
-                        continue;
-                    }
-                    if (res.code !== 0) {
+                    const out = pushResolvedBundleToHost(resolvedForPush, resolvedBundleName, host, {
+                        remoteBackend,
+                        force: opts.force,
+                        passphrase: remotePassphrase,
+                        operation: 'ssh export',
+                    });
+                    if (!out.ok) {
                         failures++;
-                        const msg = (res.stderr || res.stdout || '').trim();
-                        console.error(chalk.red(`${host}: remote import failed (exit ${res.code})${msg ? `: ${msg}` : ''}`));
+                        console.error(chalk.red(`${host}: ${out.message}`));
                         continue;
                     }
-                    // A keychain-backed push to a macOS remote over headless SSH can land
-                    // the bundle metadata but no READABLE value items: the remote login
-                    // keychain is locked in the non-interactive SSH context, so Security
-                    // accepts the write but the biometry-ACL'd item is unreadable, and the
-                    // remote `import` still exits 0. Read the bundle back the same way a
-                    // release will (drops the plaintext, keeps only key presence; the
-                    // remote's headless `agentOnly` guard fails fast, so no Touch ID) and
-                    // FAIL LOUDLY if the keys didn't materialize — rather than leave a
-                    // metadata-only bundle that breaks later with "stored item not found".
-                    // The file backend is headless-readable by construction, so skip it.
-                    if (remoteBackend === 'keychain') {
-                        const verdict = verifyRemoteKeychainPush(host, resolvedBundleName, Object.keys(env), { osLookupName: host });
-                        if (!verdict.ok) {
-                            failures++;
-                            if (verdict.kind === 'locked-keychain') {
-                                console.error(chalk.red(keychainWriteFailureMessage(host, resolvedBundleName, verdict.reason)));
-                            }
-                            else {
-                                console.error(chalk.red(`${host}: pushed '${resolvedBundleName}' but could not verify it on the remote: ${verdict.reason}`));
-                            }
-                            continue;
-                        }
-                    }
-                    const remoteMsg = (res.stdout || '').trim().split('\n').map((l) => l.trim()).filter(Boolean).pop();
-                    console.log(chalk.green(`${host} -> '${resolvedBundleName}': ${remoteMsg || `${keyCount} key(s) exported`}`));
+                    console.log(chalk.green(`${host} -> '${resolvedBundleName}': ${out.message}`));
                 }
                 emitSecretAudit({ event: 'secrets.export', bundle: resolvedBundleName, operation: `export --host ${hosts.join(',')}`, source: 'ssh', host: hosts.join(','), status: failures > 0 ? 'error' : 'success', keyCount });
                 if (failures > 0)