@phnx-labs/agents-cli 1.22.21 → 1.22.23

package/dist/commands/insights.js

@@ -0,0 +1,478 @@
+/**
+ * Insights command — how you actually work, split by the account that did the work.
+ *
+ * The behavioural sibling of the existing rollups, and deliberately not a duplicate of
+ * any of them:
+ *
+ *   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)
+ *
+ * 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.
+ *
+ * Modelled on Claude Code's `/insights`, with the difference that motivated it: that
+ * command reads one account's directory, while `balanced` rotation sprays sessions
+ * across every signed-in account. This reads the whole index and reports the accounts
+ * apart — see lib/session/claude-accounts.ts for how a transcript is attributed.
+ *
+ * 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`.
+ */
+import * as fs from 'fs';
+import chalk from 'chalk';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { addHostOption } from '../lib/hosts/option.js';
+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 { formatUsd } from '../lib/pricing/index.js';
+import { formatDuration } from '../lib/session/render.js';
+import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
+const execFileAsync = promisify(execFile);
+function resolveGroup(by) {
+    if (by === undefined)
+        return 'account';
+    if (by === 'account' || by === 'agent' || by === 'project' || by === 'day')
+        return by;
+    console.error(chalk.red('error: --by must be one of: account, agent, project, day'));
+    process.exit(1);
+}
+/**
+ * Sessions too short to say anything about how you work.
+ *
+ * Inspired by the filter `/insights` applies, but NOT identical and deliberately not
+ * claimed to be: `/insights` counts USER messages, while `messageCount` on the index
+ * counts both roles, so the same threshold is a weaker bar here. Matching it exactly
+ * would mean parsing every session just to decide whether to parse it. The dropped
+ * count is always reported, never silent.
+ */
+function isSubstantive(m, minMessages) {
+    if ((m.messageCount ?? 0) < minMessages)
+        return false;
+    if ((m.durationMs ?? 0) < 60_000)
+        return false;
+    return true;
+}
+function groupKeyFor(m, dim) {
+    switch (dim) {
+        case 'account': return m.accountKey ?? `unattributed:${m.agent}`;
+        case 'agent': return m.agent;
+        case 'project': return m.project || '(no project)';
+        case 'day': return m.timestamp.slice(0, 10);
+    }
+}
+function groupLabelFor(m, dim, key) {
+    if (dim !== 'account')
+        return key;
+    if (m.accountOrg && m.account)
+        return `${m.accountOrg} <${m.account}>`;
+    return key;
+}
+/**
+ * Load facets for every in-scope session, parsing only what the cache does not
+ * already hold. A cold first run parses every transcript once; after that only files
+ * whose (mtime, size) changed are re-read.
+ */
+async function collectFacets(rows, onProgress) {
+    let unreadable = 0;
+    const cached = readSessionInsights(rows.map((r) => r.id));
+    const stale = rows.filter((r) => !cached.has(r.id) && r.filePath);
+    if (stale.length === 0)
+        return { facets: cached, unreadable };
+    const fresh = [];
+    let done = 0;
+    for (const row of stale) {
+        try {
+            // Stat BEFORE reading, so the stamp we persist describes bytes no newer than the
+            // ones parsed: a rescan landing mid-read then reads as stale, not as a hit.
+            const st = fs.statSync(row.filePath);
+            // includeInterrupts: the default event array is a versioned contract, so the
+            // marker is opt-in and this is the reader that opts in.
+            const events = parseSession(row.filePath, row.agent, { includeInterrupts: true });
+            const facets = computeInsightFacets(events);
+            cached.set(row.id, facets);
+            fresh.push({ id: row.id, fileMtimeMs: Math.floor(st.mtimeMs), fileSize: st.size, facets });
+        }
+        catch {
+            // Deleted or corrupt since it was indexed. Counted and reported below, never
+            // silently contributing zero.
+            unreadable++;
+        }
+        done++;
+        if (done % 25 === 0)
+            onProgress(done, stale.length);
+        // Persist in batches so an interrupted cold run does not lose everything.
+        if (fresh.length >= 200) {
+            writeSessionInsights(fresh.splice(0, fresh.length));
+        }
+    }
+    if (fresh.length > 0)
+        writeSessionInsights(fresh);
+    onProgress(stale.length, stale.length);
+    return { facets: cached, unreadable };
+}
+function buildGroups(rows, facetsById, dim) {
+    const byKey = new Map();
+    for (const m of rows) {
+        const key = groupKeyFor(m, dim);
+        let g = byKey.get(key);
+        if (!g) {
+            g = {
+                key,
+                label: groupLabelFor(m, dim, key),
+                plan: null,
+                sessions: 0,
+                costUsd: 0,
+                durationMs: 0,
+                outputTokens: 0,
+                facets: newFacetAccumulator(),
+            };
+            byKey.set(key, g);
+        }
+        g.sessions++;
+        g.costUsd += m.costUsd ?? 0;
+        g.durationMs += m.durationMs ?? 0;
+        g.outputTokens += m.outputTokens ?? 0;
+        const f = facetsById.get(m.id);
+        if (f)
+            mergeFacets(g.facets, f);
+    }
+    return [...byKey.values()].sort((a, b) => b.sessions - a.sessions || a.key.localeCompare(b.key));
+}
+/** A compact bar for a count relative to the row maximum. */
+function bar(count, max, width) {
+    if (max <= 0)
+        return '';
+    const filled = Math.max(1, Math.round((count / max) * width));
+    return '█'.repeat(filled);
+}
+function renderCounts(title, entries, out) {
+    if (entries.length === 0)
+        return;
+    out.push('');
+    out.push(chalk.bold(title));
+    const nameW = Math.max(...entries.map((e) => stringWidth(e.name)));
+    const countW = Math.max(...entries.map((e) => String(e.count).length));
+    const max = Math.max(...entries.map((e) => e.count));
+    const barW = Math.max(6, Math.min(28, terminalWidth() - nameW - countW - 8));
+    for (const e of entries) {
+        out.push(`  ${padToWidth(e.name, nameW)}  ${chalk.cyan(String(e.count).padStart(countW))}  ` +
+            chalk.gray(bar(e.count, max, barW)));
+    }
+}
+function renderHours(hours, out) {
+    const total = hours.reduce((a, b) => a + b, 0);
+    if (total === 0)
+        return;
+    const blocks = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+    const max = Math.max(...hours);
+    const spark = hours
+        .map((h) => (h === 0 ? ' ' : blocks[Math.min(blocks.length - 1, Math.floor((h / max) * (blocks.length - 1)))]))
+        .join('');
+    out.push('');
+    out.push(chalk.bold('When you work') + chalk.gray('  (local time)'));
+    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) {
+    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`));
+    if (groups.length === 0) {
+        out.push('');
+        out.push(chalk.gray('  No sessions in scope. Try a wider --since, or run `agents sessions --all` to index.'));
+        console.log(out.join('\n'));
+        return;
+    }
+    // Per-group table — the headline, and the thing no sibling command produces.
+    out.push('');
+    out.push(chalk.bold(`By ${dim}`));
+    const labelW = Math.min(Math.max(...groups.map((g) => stringWidth(g.label)), 5), Math.max(20, terminalWidth() - 46));
+    const sessW = Math.max(...groups.map((g) => String(g.sessions).length), 3);
+    for (const g of groups) {
+        const cost = g.costUsd > 0 ? formatUsd(g.costUsd) : '—';
+        const dur = g.durationMs > 0 ? formatDuration(g.durationMs) : '—';
+        out.push(`  ${padToWidth(truncateToWidth(g.label, labelW), labelW)}  ` +
+            `${chalk.gray(String(g.sessions).padStart(sessW))} ${chalk.gray('sess')}  ` +
+            `${chalk.green(padToWidth(cost, 9))}  ${chalk.gray(dur)}`);
+    }
+    // Everything below is the whole scope folded together; per-group detail is in --json.
+    const all = newFacetAccumulator();
+    for (const g of groups)
+        mergeFacets(all, g.facets);
+    renderCounts('Top tools', topEntries(all.toolCounts, 8), out);
+    renderCounts('Languages', topEntries(all.languages, 6), out);
+    renderCounts('Models', topEntries(all.models, 6), out);
+    // Friction — the section that earns the command.
+    const gaps = all.responseGaps;
+    out.push('');
+    out.push(chalk.bold('Friction'));
+    out.push(`  ${padToWidth('interruptions', 18)}  ${chalk.cyan(String(all.interruptions))}` +
+        chalk.gray('   turns you cut short'));
+    out.push(`  ${padToWidth('tool errors', 18)}  ${chalk.cyan(String(all.errorCount))}`);
+    if (gaps.length > 0) {
+        out.push(`  ${padToWidth('your reply time', 18)}  ` +
+            chalk.cyan(`p50 ${Math.round(percentile(gaps, 50))}s`) + chalk.gray(` · p90 ${Math.round(percentile(gaps, 90))}s`));
+    }
+    const errs = topEntries(all.errorCategories, 6);
+    if (errs.length > 0) {
+        for (const e of errs)
+            out.push(`    ${chalk.gray('·')} ${padToWidth(e.name, 16)} ${chalk.gray(String(e.count))}`);
+    }
+    // Output
+    out.push('');
+    out.push(chalk.bold('What you changed'));
+    // Gate on whether anything was actually measured, not on whether an edit-shaped call
+    // was seen. Codex patches through `exec`, so it can log edit-class calls and still
+    // expose no line arguments to count — rendering that as "0 lines" would read as "wrote
+    // nothing" for a harness that wrote plenty.
+    if (all.linesTouchedAfter > 0 || all.linesTouchedBefore > 0) {
+        // "touched", not "+/-": these are the before/after line counts of each edit, so an
+        // Edit with unchanged context lines counts them on both sides. Not a diffstat, and
+        // labelled so nobody reads it as one.
+        out.push(`  ${chalk.cyan(String(all.linesTouchedAfter))} ${chalk.gray('lines written,')} ` +
+            `${chalk.cyan(String(all.linesTouchedBefore))} ${chalk.gray('replaced')}  ` +
+            chalk.gray('(lines touched, not a diff)'));
+    }
+    else {
+        out.push(`  ${chalk.gray('lines touched  —  not measurable for this harness (edits go through the shell)')}`);
+    }
+    out.push(`  ${chalk.gray(`${all.filesCreated} created, ${all.filesModified} modified, ${all.filesDeleted} deleted`)}`);
+    // Same not-measurable rule as the lines above. These are substring-matched from
+    // shell command TEXT, and not every harness exposes it — the codex parser populates
+    // `command` for `exec_command` but not plain `exec`, its dominant tool — so gate on
+    // whether we had anything to search rather than on seeing a shell-shaped tool call.
+    // When we did, the count is real, and still disagrees with `agents output`, which
+    // counts deduped SHAs from git log.
+    if (all.shellCommandsSeen > 0) {
+        out.push(`  ${chalk.gray(`${all.gitCommits} commits · ${all.gitPushes} pushes (seen in shell commands)`)}`);
+    }
+    else {
+        out.push(`  ${chalk.gray('commits  —  not measurable for this harness')}`);
+    }
+    renderHours(all.messageHours, out);
+    // Concurrency — direct evidence that a single-account view would be wrong.
+    if (meta.overlap.overlappingPairs > 0) {
+        out.push('');
+        out.push(chalk.bold('Parallel sessions'));
+        out.push(`  ${chalk.cyan(String(meta.overlap.sessionsInvolved))} ${chalk.gray('sessions ran alongside another')}`);
+        // Pairs, not sessions — stated as pairs so the two numbers are not read as a
+        // subset of each other.
+        const crossNote = meta.overlap.crossAccountPairs > 0
+            ? `, ${meta.overlap.crossAccountPairs} of them across two different accounts`
+            : '';
+        out.push(chalk.gray(`  ${meta.overlap.overlappingPairs} overlapping pairs${crossNote}`));
+    }
+    if (meta.filteredOut > 0) {
+        out.push('');
+        out.push(chalk.gray(`  ${meta.filteredOut} sessions excluded as too short (under ${meta.minMessages} messages or 1 minute).`));
+    }
+    if (meta.unreadable > 0) {
+        if (meta.filteredOut === 0)
+            out.push('');
+        out.push(chalk.yellow(`  ${meta.unreadable} transcripts could not be read; their behaviour is missing from these totals.`));
+    }
+    if (all.gapsOverCeiling > 0) {
+        out.push(chalk.gray(`  ${all.gapsOverCeiling} reply gaps over an hour excluded from the percentiles.`));
+    }
+    out.push('');
+    out.push(chalk.gray('  `agents insights --by project` to see it per repo'));
+    out.push(chalk.gray('  `agents insights --narrative` for a written read on what to change'));
+    console.log(out.join('\n'));
+}
+/**
+ * The opt-in coaching layer. Pipes the AGGREGATE through a headless `claude -p` — never
+ * raw transcripts, unlike `/insights`, which ships session text to the API. Reuses
+ * whatever account the shim resolves, so there is no API key handling here.
+ */
+async function renderNarrative(payload) {
+    const prompt = [
+        'You are reading a developer\'s own coding-session telemetry, already aggregated.',
+        'Write a short, direct read for them. Four sections, 2-3 sentences each:',
+        '1. What is working — the patterns worth keeping.',
+        '2. What is costing you — split into the assistant\'s fault vs your own workflow.',
+        '3. Quick wins — concrete, tied to a number in the data.',
+        '4. Worth trying — one more ambitious workflow change.',
+        'Be specific and cite the numbers. No preamble, no flattery, no bullet padding.',
+        '',
+        JSON.stringify(payload),
+    ].join('\n');
+    try {
+        const { stdout } = await execFileAsync('claude', ['-p', prompt], {
+            timeout: 180_000,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        // stderr, always. Under --json stdout is a machine contract, and prose appended
+        // after the closing brace makes the payload unparseable; on a TTY stderr renders
+        // identically, so there is nothing to special-case.
+        process.stderr.write('\n' + chalk.bold('Narrative') + '\n');
+        process.stderr.write(stdout.trim().split('\n').map((l) => `  ${l}`).join('\n') + '\n');
+    }
+    catch (err) {
+        const msg = err.code === 'ENOENT'
+            ? 'claude is not on PATH'
+            : (err.message ?? 'unknown error');
+        console.error('');
+        console.error(chalk.red(`✗ narrative unavailable: ${msg}`));
+        console.error(chalk.gray('  The report above is complete; only the written section was skipped.'));
+        // A scripted caller asked for this section and did not get it. Say so in the exit
+        // code rather than reporting success for a partial result.
+        process.exitCode = 1;
+    }
+}
+async function insightsAction(options) {
+    const dim = resolveGroup(options.by);
+    const minMessages = Number.parseInt(options.minMessages ?? '2', 10);
+    if (!Number.isFinite(minMessages) || minMessages < 0) {
+        console.error(chalk.red('error: --min-messages must be a non-negative integer'));
+        process.exit(1);
+    }
+    const since = options.since ?? '30d';
+    const sinceMs = since === 'all' ? undefined : parseTimeFilter(since);
+    // Refresh the index first, exactly as `agents cost` does, so a report never silently
+    // describes a stale picture of disk.
+    await discoverSessions({ all: true, since: since === 'all' ? undefined : since, limit: 1 });
+    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 (!wanted)
+            return true;
+        return [m.accountKey, m.account, m.accountOrg]
+            .some((v) => v?.toLowerCase().includes(wanted));
+    });
+    const substantive = inScope.filter((m) => isSubstantive(m, minMessages));
+    const filteredOut = inScope.length - substantive.length;
+    const isTty = process.stdout.isTTY && !options.json;
+    const { facets: facetsById, unreadable } = await collectFacets(substantive, (done, total) => {
+        if (isTty && done < total)
+            process.stderr.write(`\rReading transcripts ${done}/${total}…`);
+        else if (isTty)
+            process.stderr.write('\r'.padEnd(40) + '\r');
+    });
+    const spans = substantive.map((m) => {
+        const start = new Date(m.timestamp).getTime();
+        return {
+            id: m.id,
+            accountKey: m.accountKey ?? `unattributed:${m.agent}`,
+            startMs: start,
+            endMs: start + (m.durationMs ?? 0),
+        };
+    });
+    const overlap = detectOverlap(spans);
+    const groups = buildGroups(substantive, facetsById, dim);
+    if (options.json) {
+        const payload = {
+            generatedAt: new Date().toISOString(),
+            window: { since: since === 'all' ? null : since },
+            scanned: inScope.length,
+            analyzed: substantive.length,
+            filteredOut,
+            unreadable,
+            minMessages,
+            by: dim,
+            overlap,
+            groups: groups.map((g) => ({
+                key: g.key,
+                label: g.label,
+                sessions: g.sessions,
+                costUsd: g.costUsd,
+                durationMs: g.durationMs,
+                outputTokens: g.outputTokens,
+                ...g.facets,
+                responseGapP50: Math.round(percentile(g.facets.responseGaps, 50)),
+                responseGapP90: Math.round(percentile(g.facets.responseGaps, 90)),
+                responseGapBuckets: bucketGaps(g.facets.responseGaps),
+                // The raw sample is large and uninteresting once bucketed.
+                responseGaps: undefined,
+            })),
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        if (options.narrative)
+            await renderNarrative(payload);
+        return;
+    }
+    renderReport(groups, dim, {
+        since: since === 'all' ? undefined : since,
+        scanned: inScope.length,
+        analyzed: substantive.length,
+        filteredOut,
+        unreadable,
+        minMessages,
+        overlap,
+    });
+    if (options.narrative) {
+        await renderNarrative(groups.map((g) => ({
+            account: g.label, sessions: g.sessions, costUsd: g.costUsd,
+            topTools: topEntries(g.facets.toolCounts, 8),
+            languages: topEntries(g.facets.languages, 6),
+            errorCategories: topEntries(g.facets.errorCategories, 6),
+            interruptions: g.facets.interruptions,
+            linesTouchedAfter: g.facets.linesTouchedAfter, linesTouchedBefore: g.facets.linesTouchedBefore,
+            gitCommits: g.facets.gitCommits,
+            replyP50s: Math.round(percentile(g.facets.responseGaps, 50)),
+        })));
+    }
+}
+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')
+        .option('--json', 'Output the full report as JSON')
+        .option('--since <time>', 'Window: 7d, 4w, 3mo, an ISO date, or "all" (default 30d)')
+        .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('--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);
+    });
+    setHelpSections(cmd, {
+        examples: `
+      # Last 30 days, split by Claude account — the default
+      agents insights
+
+      # Which repo is eating the time
+      agents insights --by project --since 90d
+
+      # One account only, all of its history
+      agents insights --account "Turing Labs" --since all
+
+      # Machine-readable, for a dashboard or a slash command
+      agents insights --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\`.
+
+      The first run parses every in-scope transcript and caches the result; 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>\`.
+
+      Everything except \`--narrative\` is local and makes no network calls.
+    `,
+    });
+}

package/dist/commands/resume.js

@@ -22,8 +22,8 @@ export function buildResumeRunArgs(session, prompt, options) {
 }
 export function registerResumeCommand(program) {
     const cmd = program
-        .command('resume <session-id> [prompt]')
-        .description('Resume a session with its original harness, version, device, account, cwd, and mode')
+        .command('resume <session> [prompt]')
+        .description('Resume a session by id, tmux alias, or exact label with its original harness, version, device, account, cwd, and mode. Searches the fleet automatically; a local full-id hit resumes with zero SSH.')
         .option('-m, --mode <mode>', 'Override the recorded launch mode')
         .option('-i, --interactive', 'Resume interactively even when a prompt is provided')
         .option('--headless', 'Resume headlessly (a prompt is required)')
@@ -71,10 +71,17 @@ export function registerResumeCommand(program) {
       # Resume and continue headlessly
       agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 "finish the tests"
 
+      # Resume by exact label (auto-resumes the one match)
+      agents resume "fix the flaky ssh test"
+
+      # Resume by durable tmux alias or its unique suffix
+      agents resume ag-codex-c1f3d813
+      agents resume c1f3d813
+
       # Deliberately change permissions
       agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 --mode edit`,
         notes: `
-      Full IDs resolve from the local session database first; an SSH fleet lookup runs only after a local miss.
+      A full ID resolves from the local session database first (zero SSH) and, on a local miss, fans out with the first peer holding it cancelling the rest. An exact label always consults the fleet (labels are not globally unique) and auto-resumes the one match; a cross-machine label collision surfaces as an ambiguity.
       Use agents run auto --resume <id> when the original account is unavailable and another harness may continue.`,
     });
 }

package/dist/commands/secrets.js

@@ -15,7 +15,7 @@ import * as path from 'path';
 import { SSH_TARGET_RE, assertValidSshTarget, sshExec } 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, } from '../lib/secrets/remote.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 { 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';
@@ -333,10 +333,6 @@ function getCliVersion() {
         return '0.0.0';
     }
 }
-/** POSIX single-quote a string for safe interpolation into a remote shell command. */
-function shellQuote(s) {
-    return `'${s.replace(/'/g, `'\\''`)}'`;
-}
 /**
  * Serialize a resolved env map to `.env` lines that round-trip losslessly through
  * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
@@ -1332,7 +1328,7 @@ export function registerSecretsCommands(program) {
             if (bundle.allow_exec)
                 console.log(chalk.yellow('allow_exec: true'));
             if (bundle.backend === 'file')
-                console.log(chalk.gray('backend: file (passphrase-encrypted; reads need AGENTS_SECRETS_PASSPHRASE, no Touch ID)'));
+                console.log(chalk.gray('backend: file (encrypted at rest; headless reads via a machine-local key, or AGENTS_SECRETS_PASSPHRASE if set — no Touch ID)'));
             if (bundle.backend === 'vault')
                 console.log(chalk.gray('storage: synced (age-encrypted ~/.agents/vault.age; needs agents login)'));
             if (bundlePolicy(bundle) === 'never') {
@@ -1588,7 +1584,7 @@ export function registerSecretsCommands(program) {
                 console.log(chalk.red('Stored without biometry protection — reads are silent. Automation-only; rotate anything sensitive out of it.'));
             }
             if (backend === 'file') {
-                console.log(chalk.gray('File-backed: items are AES-256-GCM encrypted under AGENTS_SECRETS_PASSPHRASE (no Touch ID).'));
+                console.log(chalk.gray('File-backed: items are AES-256-GCM encrypted at rest under a machine-local key (or AGENTS_SECRETS_PASSPHRASE if set); headless reads, no Touch ID.'));
             }
             if (backend === 'vault') {
                 console.log(chalk.gray('Synced: items are encrypted in ~/.agents/vault.age. Copy that file with your sync tool of choice.'));
@@ -2064,7 +2060,7 @@ Examples:
         .option('--vault <name>', '1Password vault name (used with --to-1password)')
         .option('--host <target...>', 'Push the bundle over SSH to this target (host alias or user@host); repeatable for multiple machines')
         .option('--device <target...>', 'Alias for --host; repeatable')
-        .option('--remote-backend <backend>', 'Backend for the bundle on the remote (with --host): keychain (default) or file (passphrase-encrypted, headless-readable). file forwards AGENTS_SECRETS_PASSPHRASE over stdin.', 'keychain')
+        .option('--remote-backend <backend>', 'Backend for the bundle on the remote (with --host): keychain (default) or file. file is headless-readable via the remote\'s machine-local key; it forwards AGENTS_SECRETS_PASSPHRASE over stdin only if set (opt-in).', 'keychain')
         .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --host)')
         .option('--format <shell|json>', 'Output for --plaintext export: shell (default) or json (lossless, machine-readable; used by remote resolve)', 'shell')
         .option('--to-file <path>', 'Write the bundle as an AES-256-GCM encrypted offline file (needs AGENTS_SECRETS_PASSPHRASE; symmetric counterpart of import --from-file)')
@@ -2097,20 +2093,16 @@ Examples:
                 for (const h of hosts)
                     assertValidSshTarget(h);
                 const remoteBackend = parseBackendOpt(opts.remoteBackend);
-                // For a file-backed remote bundle the remote must encrypt at rest with
-                // a passphrase. We forward the LOCAL AGENTS_SECRETS_PASSPHRASE — the
-                // operator unlocks it once on this (trusted, biometry-gated) machine —
-                // and ship it as the FIRST stdin line so it never lands in argv / `ps`
-                // / the remote shell history. The remote `read -r` consumes that line;
-                // `agents secrets import --from /dev/stdin` reads the .env remainder.
-                let remotePassphrase = '';
-                if (remoteBackend === 'file') {
-                    remotePassphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
-                    if (!remotePassphrase) {
-                        throw new Error('--remote-backend file needs AGENTS_SECRETS_PASSPHRASE set locally to encrypt the ' +
-                            'bundle at rest on the remote. Set it for this command, then unlock it the same way per run.');
-                    }
-                }
+                // 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.
+                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;
@@ -2126,19 +2118,22 @@ Examples:
                 for (const host of hosts) {
                     let res;
                     if (remoteBackend === 'file') {
-                        // File backend forwards AGENTS_SECRETS_PASSPHRASE as the FIRST stdin
-                        // line (consumed by `read`, so it never lands in argv / `ps` /
-                        // remote history), then the .env. That `read`/`export` prologue is
-                        // POSIX shell — refuse a Windows target cleanly rather than emit
-                        // broken PowerShell.
+                        // 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 remoteAgents = `IFS= read -r AGENTS_SECRETS_PASSPHRASE; export AGENTS_SECRETS_PASSPHRASE; ` +
-                            `agents secrets import ${shellQuote(resolvedBundleName)} --from - --backend file${opts.force ? ' --force' : ''}`;
-                        res = sshExec(host, `bash -lc ${shellQuote(remoteAgents)}`, { input: `${remotePassphrase}\n${dotenv}` });
+                        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

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

@@ -28,6 +28,8 @@ export interface SessionPickerConfig {
     initialSearch?: string;
     /** Verb shown on the Enter key in the footer (default 'resume'). */
     enterHint?: string;
+    /** Lines the caller printed above the prompt (hidden-session footer). */
+    linesAbovePrompt?: number;
 }
 /** Build a cached multi-line preview string for display in the session picker. */
 export declare function buildPreview(session: SessionMeta): string;

package/dist/commands/sessions-picker.js

@@ -801,6 +801,7 @@ export async function sessionPicker(config) {
         initialSearch: config.initialSearch,
         emptyMessage: 'No sessions match.',
         enterHint: config.enterHint ?? 'resume',
+        linesAbovePrompt: config.linesAbovePrompt,
     });
     if (!picked)
         return null;