@phnx-labs/agents-cli 1.22.24 → 1.22.26

package/dist/lib/secrets/push.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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;
+/** Where the bundle should live ON THE REMOTE. */
+export type RemoteBackend = 'keychain' | 'file';
+/** A bundle read once, ready to push to any number of hosts. */
+export interface ResolvedBundleForPush {
+    /** key -> value. Never logged; only its KEY NAMES are ever surfaced. */
+    env: Record<string, string>;
+    /** The same values as a dotenv blob, shipped over ssh stdin (never argv). */
+    dotenv: string;
+    keyCount: number;
+}
+export interface PushBundleOptions {
+    remoteBackend: RemoteBackend;
+    /** Overwrite a key that already exists on the remote. */
+    force?: boolean;
+    /**
+     * Forwarded to the remote as the FIRST stdin line for the FILE backend only,
+     * and only when non-empty.
+     *
+     * Empty is the DEFAULT and the good path: the remote's file store then
+     * auto-provisions its own machine-local key (0600, `~/.agents/.secrets-key/`)
+     * and reads headlessly. Setting this keys the remote bundle under a shared
+     * off-disk secret instead — an opt-in, never a requirement. Requiring one is
+     * what pushed operators toward exporting the master key fleet-wide (RUSH-1968).
+     */
+    passphrase?: string;
+    /** Label for the audit trail — `export --host` vs `fleet apply`. */
+    operation: string;
+}
+export interface PushBundleResult {
+    ok: boolean;
+    host: string;
+    bundle: string;
+    keyCount: number;
+    /** One line for the caller to render. Never contains a secret value. */
+    message: string;
+}
+/**
+ * Read and resolve a bundle once, for pushing to one or more hosts.
+ *
+ * `agentOnly` + `keyMode: 'storage'` match what `export --host` has always
+ * passed: storage-shaped values, and the headless guard that fails fast rather
+ * than popping Touch ID inside an automated run.
+ */
+export declare function resolveBundleForPush(bundle: string, caller: string): ResolvedBundleForPush;
+/**
+ * WHICH transport a (backend, target-OS) pair selects, and the exact bytes it
+ * will send. One of four outcomes, and picking the wrong one is silent: a
+ * Windows target handed a POSIX `bash -lc` produces garbage, and a Windows
+ * target handed `--from -` hangs forever on a stdin the `agents.ps1` shim never
+ * forwards. Neither shows up as a failed ssh, so the selection is the thing
+ * worth pinning.
+ *
+ * Separated from execution so it is decidable without a network: the branch is
+ * chosen from the device registry alone, and `pushResolvedBundleToHost` below
+ * does nothing but run what this returns.
+ */
+export type PushTransport = 
+/** No supported command exists for this pair — fail loud, never a wrong path. */
+{
+    kind: 'refuse';
+    message: string;
+}
+/** A command sent over the raw ssh engine, with the .env on stdin. */
+ | {
+    kind: 'ssh';
+    remoteCmd: string;
+    input: string;
+}
+/** The OS-aware `agents secrets` wrapper, the READ inverse's own path. */
+ | {
+    kind: 'remote-secrets';
+    args: string[];
+    input: string;
+};
+/** Choose the transport for one push. Pure: registry read in, plan out. */
+export declare function planPushTransport(resolved: ResolvedBundleForPush, bundle: string, host: string, opts: PushBundleOptions): PushTransport;
+/**
+ * Push an already-resolved bundle to ONE host.
+ *
+ * Drives the remote's own `agents secrets import --from -`, so the values land
+ * in the remote's chosen backend and the .env is read off ssh stdin rather than
+ * parsed by a remote shell. `import` auto-creates the bundle.
+ */
+export declare function pushResolvedBundleToHost(resolved: ResolvedBundleForPush, bundle: string, host: string, opts: PushBundleOptions): PushBundleResult;
+/** Resolve and push in one call — for a single host. */
+export declare function pushBundleToHost(bundle: string, host: string, opts: PushBundleOptions): PushBundleResult;

package/dist/lib/secrets/push.js

@@ -0,0 +1,145 @@
+/**
+ * Push one bundle's values to a remote host over SSH — the provisioning
+ * primitive behind `agents secrets export --host` and, from RUSH-1968, behind
+ * `agents fleet apply --provision-secrets`.
+ *
+ * This logic used to live inline in the `export --host` command action. It moved
+ * here because `lib/fleet/apply.ts` needs it and a lib MUST NOT import a command
+ * module — and because the absence of a callable primitive is part of why
+ * `fleet apply` never provisioned secrets at all, leaving an operator to
+ * hand-export the file store's master key across the fleet.
+ *
+ * Two rules shape the shape of this module:
+ *
+ * - **It never prints.** The lib layer stays `console.*`-free (SEC-14/SEC-16), so
+ *   every outcome is returned as data and the CALLER renders it. That is also
+ *   what lets `fleet apply` fold a push into its own per-device report instead of
+ *   interleaving stray lines into it.
+ * - **Resolve once, push N times.** `resolveBundleForPush` is separate because
+ *   reading a bundle can prompt (Touch ID); doing it per host would prompt per
+ *   host. `export --host a,b,c` resolves once and pushes three times.
+ */
+import { sshExec } from '../ssh-exec.js';
+import { remoteShellFor, buildWindowsStdinImportCommand } from '../hosts/remote-cmd.js';
+import { resolveRemoteOsSync } from '../hosts/remote-os.js';
+import { remoteSecretsRaw, verifyRemoteKeychainPush, keychainWriteFailureMessage, buildRemoteFileImportCommand, } from './remote.js';
+import { readAndResolveBundleEnv } from './bundles.js';
+/**
+ * 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';
+}
+/**
+ * Read and resolve a bundle once, for pushing to one or more hosts.
+ *
+ * `agentOnly` + `keyMode: 'storage'` match what `export --host` has always
+ * passed: storage-shaped values, and the headless guard that fails fast rather
+ * than popping Touch ID inside an automated run.
+ */
+export function resolveBundleForPush(bundle, caller) {
+    const { env } = readAndResolveBundleEnv(bundle, { caller, keyMode: 'storage', agentOnly: true });
+    return { env, dotenv: bundleEnvToDotenv(env), keyCount: Object.keys(env).length };
+}
+function isPowershellTarget(host) {
+    return remoteShellFor(resolveRemoteOsSync(host.split('@').pop() ?? host)) === 'powershell';
+}
+/** Choose the transport for one push. Pure: registry read in, plan out. */
+export function planPushTransport(resolved, bundle, host, opts) {
+    const powershell = isPowershellTarget(host);
+    if (opts.remoteBackend === 'file') {
+        // Both file-backend paths build a POSIX `bash -lc` command. Refuse a Windows
+        // target cleanly rather than emit broken PowerShell (fail loud at the
+        // boundary, never a silent wrong path).
+        if (powershell) {
+            return { kind: 'refuse', message: 'file backend export to a Windows target is not yet supported' };
+        }
+        const { remoteCmd, input } = buildRemoteFileImportCommand(bundle, resolved.dotenv, {
+            passphrase: opts.passphrase ?? '',
+            force: opts.force,
+        });
+        return { kind: 'ssh', remoteCmd, input };
+    }
+    if (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; the .env still only ever crosses
+        // the wire over ssh stdin.
+        return {
+            kind: 'ssh',
+            remoteCmd: buildWindowsStdinImportCommand(bundle, { force: opts.force }),
+            input: resolved.dotenv,
+        };
+    }
+    // Keychain on a POSIX target: OS-aware wrapping + the hardened ssh engine
+    // (BatchMode, ConnectTimeout, keepalive, control-socket reuse) via the same
+    // path the READ inverse (`remoteResolveEnv`) uses.
+    return {
+        kind: 'remote-secrets',
+        args: ['import', bundle, '--from', '-', ...(opts.force ? ['--force'] : [])],
+        input: resolved.dotenv,
+    };
+}
+/**
+ * Push an already-resolved bundle to ONE host.
+ *
+ * Drives the remote's own `agents secrets import --from -`, so the values land
+ * in the remote's chosen backend and the .env is read off ssh stdin rather than
+ * parsed by a remote shell. `import` auto-creates the bundle.
+ */
+export function pushResolvedBundleToHost(resolved, bundle, host, opts) {
+    const fail = (message) => ({ ok: false, host, bundle, keyCount: resolved.keyCount, message });
+    const plan = planPushTransport(resolved, bundle, host, opts);
+    if (plan.kind === 'refuse')
+        return fail(plan.message);
+    const res = plan.kind === 'ssh'
+        ? sshExec(host, plan.remoteCmd, { input: plan.input })
+        : remoteSecretsRaw(host, plan.args, { input: plan.input, osLookupName: host });
+    if (res.code === null) {
+        return fail(res.stderr.trim() || (res.timedOut ? 'ssh timed out' : 'ssh failed'));
+    }
+    if (res.code !== 0) {
+        const msg = (res.stderr || res.stdout || '').trim();
+        return fail(`remote import failed (exit ${res.code})${msg ? `: ${msg}` : ''}`);
+    }
+    // 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 it back the way a release will and FAIL LOUDLY, rather than leave a
+    // metadata-only bundle that breaks later with "stored item not found". The
+    // file backend is headless-readable by construction, so it is skipped.
+    if (opts.remoteBackend === 'keychain') {
+        const verdict = verifyRemoteKeychainPush(host, bundle, Object.keys(resolved.env), { osLookupName: host });
+        if (!verdict.ok) {
+            return fail(verdict.kind === 'locked-keychain'
+                ? keychainWriteFailureMessage(host, bundle, verdict.reason)
+                : `pushed '${bundle}' but could not verify it on the remote: ${verdict.reason}`);
+        }
+    }
+    const remoteMsg = (res.stdout || '').trim().split('\n').map((l) => l.trim()).filter(Boolean).pop();
+    return {
+        ok: true,
+        host,
+        bundle,
+        keyCount: resolved.keyCount,
+        message: remoteMsg || `${resolved.keyCount} key(s) exported`,
+    };
+}
+/** Resolve and push in one call — for a single host. */
+export function pushBundleToHost(bundle, host, opts) {
+    return pushResolvedBundleToHost(resolveBundleForPush(bundle, opts.operation), bundle, host, opts);
+}

package/dist/lib/secrets/rc-hygiene.d.ts

@@ -32,6 +32,20 @@ export interface RcSecretFinding {
     /** The file-store master passphrase gets called out separately — it is the highest-severity case. */
     isMasterPassphrase: boolean;
 }
+/** The file-store master key. Its own resolution prefers an off-env 0600 file, so
+ *  a shell-rc export is always wrong once the store exists (RUSH-1968). */
+export declare const MASTER_PASSPHRASE = "AGENTS_SECRETS_PASSPHRASE";
+/**
+ * True when the file-store master key is live in THIS process's environment.
+ *
+ * The scanner above reads FILES, and that leaves a hole: a value inherited by a
+ * long-lived process outlives the rc line that set it, so deleting the export
+ * makes `scanRcExports` report clean while every shell, editor and agent started
+ * beforehand still carries the key and passes it to everything it spawns.
+ * Returns a boolean — never the value — so a finding built from it can be
+ * printed, logged, or shipped without leaking the secret.
+ */
+export declare function masterPassphraseInEnv(): boolean;
 /** True if a variable name looks like it holds a credential value. */
 export declare function isCredentialName(name: string): boolean;
 /**

package/dist/lib/secrets/rc-hygiene.js

@@ -33,7 +33,20 @@ export const RC_FILENAMES = [
 ];
 /** The file-store master key. Its own resolution prefers an off-env 0600 file, so
  *  a shell-rc export is always wrong once the store exists (RUSH-1968). */
-const MASTER_PASSPHRASE = 'AGENTS_SECRETS_PASSPHRASE';
+export const MASTER_PASSPHRASE = 'AGENTS_SECRETS_PASSPHRASE';
+/**
+ * True when the file-store master key is live in THIS process's environment.
+ *
+ * The scanner above reads FILES, and that leaves a hole: a value inherited by a
+ * long-lived process outlives the rc line that set it, so deleting the export
+ * makes `scanRcExports` report clean while every shell, editor and agent started
+ * beforehand still carries the key and passes it to everything it spawns.
+ * Returns a boolean — never the value — so a finding built from it can be
+ * printed, logged, or shipped without leaking the secret.
+ */
+export function masterPassphraseInEnv() {
+    return (process.env[MASTER_PASSPHRASE] ?? '').length > 0;
+}
 /**
  * Last `_`-delimited segment values that mark a variable as credential-shaped.
  * Matched against the FINAL segment (segment equality, not substring) so

package/dist/lib/secrets/reaper.d.ts

@@ -27,7 +27,12 @@ export interface KeychainProcessSnapshot {
      * `null` means "could not capture" — the planner must fail closed.
      */
     startTime: string | null;
-    /** True when this process's executable path matches the installed helper. */
+    /**
+     * True when this process is a REAP-ELIGIBLE helper invocation — the installed
+     * helper binary running a short-lived keychain verb. False for a non-helper
+     * process AND for the long-lived `watch-lock` watcher (see
+     * {@link isReapableHelperCommand}), which must never be reaped.
+     */
     isHelper: boolean;
 }
 /**
@@ -78,6 +83,15 @@ export declare function planKeychainReap(snapshots: KeychainProcessSnapshot[], n
  * Returns null for an unparseable value so the caller drops the row.
  */
 export declare function parseEtimeToSeconds(raw: string): number | null;
+/**
+ * Whether a `ps` command line is a REAP-ELIGIBLE helper invocation: the installed
+ * helper binary running a short-lived keychain verb (get/has/list/set/delete/
+ * migrate-*) that a wedged `coreauthd` can hang. Returns false for a non-helper
+ * command AND for the deliberately long-lived `watch-lock` watcher — matching by
+ * the full argv (`ps … command=`), so a live-parent `watch-lock` child is never
+ * mistaken for a stuck read and killed. Pure; unit-tested.
+ */
+export declare function isReapableHelperCommand(command: string, helperPath: string): boolean;
 /** Test seam: reset the persisted candidate state. */
 export declare function resetKeychainReaperCandidatesForTest(): void;
 /**

package/dist/lib/secrets/reaper.js

@@ -134,6 +134,31 @@ function parsePsLine(line) {
         return null;
     return { pid, ppid, elapsedSec, command };
 }
+/**
+ * The one helper verb that is DELIBERATELY long-lived: the broker's auto-lock
+ * sleep/lock watcher (`spawn(getKeychainHelperPath(), ['watch-lock'], …)` in
+ * `agent.ts`). It lives for the broker's whole hold — potentially days — as a
+ * healthy child of the live broker/daemon, emitting LOCK/SLEEP lines that wipe
+ * the in-memory secret store on sleep. It is NOT a stuck keychain read, so the
+ * reaper must never target it: killing it silently disables auto-lock-on-sleep.
+ */
+const HELPER_WATCH_LOCK_VERB = 'watch-lock';
+/**
+ * Whether a `ps` command line is a REAP-ELIGIBLE helper invocation: the installed
+ * helper binary running a short-lived keychain verb (get/has/list/set/delete/
+ * migrate-*) that a wedged `coreauthd` can hang. Returns false for a non-helper
+ * command AND for the deliberately long-lived `watch-lock` watcher — matching by
+ * the full argv (`ps … command=`), so a live-parent `watch-lock` child is never
+ * mistaken for a stuck read and killed. Pure; unit-tested.
+ */
+export function isReapableHelperCommand(command, helperPath) {
+    if (command === helperPath)
+        return true; // bare exec, no verb — never watch-lock
+    if (!command.startsWith(`${helperPath} `))
+        return false; // not our helper
+    const firstArg = command.slice(helperPath.length + 1).trimStart().split(/\s+/)[0];
+    return firstArg !== HELPER_WATCH_LOCK_VERB;
+}
 /** Module-state for the two-sweep stuck-parent debounce. */
 let stuckParentCandidates = new Map();
 /** Test seam: reset the persisted candidate state. */
@@ -178,9 +203,11 @@ export function reapOrphanedKeychainProcesses() {
         if (!parsed)
             continue;
         const { pid, ppid, elapsedSec, command } = parsed;
-        // Exact path-match: the helper invocation's command line begins with the
-        // absolute helper path, followed by a space and its arguments (or nothing).
-        const isHelper = command === helperPath || command.startsWith(`${helperPath} `);
+        // Reap-eligible = the helper binary running a short-lived keychain verb. The
+        // full-argv match excludes the deliberately long-lived `watch-lock` watcher,
+        // whose live-parent child would otherwise be killed as if it were stuck
+        // (RUSH-2232 — that silently disabled auto-lock-on-sleep).
+        const isHelper = isReapableHelperCommand(command, helperPath);
         rows.push({ pid, ppid, elapsedSec, isHelper, startTime: null });
     }
     const rowByPid = new Map(rows.map((r) => [r.pid, r]));

package/dist/lib/session/active.d.ts

@@ -126,6 +126,10 @@ export interface ActiveSession {
      */
     lastActivityMs?: number;
     status: ActiveStatus;
+    /** Indexed launch origin, backfilled by the sessions command for JSON consumers. */
+    origin?: 'cli' | 'routine';
+    /** Routine definition name when origin is `routine`. */
+    routineName?: string;
     /**
      * Foreground/background presence for the detach/attach model:
      *   `attached`   — live interactive TUI you're watching;

package/dist/lib/session/db.d.ts

@@ -7,12 +7,12 @@
  * BM25 ranking, and label-first search for /rename'd sessions.
  */
 import Database from '../sqlite.js';
-import type { SessionAgentId, SessionMeta } from './types.js';
+import type { SessionAgentId, SessionEvent, SessionMeta } from './types.js';
 import { type IndexedToolCall } from './tool-calls.js';
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 34;
+export declare const SCHEMA_VERSION = 36;
 /**
  * Bump to force `agents sessions backfill resources` to re-derive every
  * session's skill/slash-command tallies on its next run (resource_scan_ledger
@@ -26,7 +26,7 @@ export declare const RESOURCE_INDEX_VERSION = 1;
  * re-derives on the next `agents insights` instead of silently reporting stale
  * numbers alongside fresh ones. Same role as RESOURCE_INDEX_VERSION.
  */
-export declare const INSIGHTS_EXTRACTOR_VERSION = 3;
+export declare const INSIGHTS_EXTRACTOR_VERSION = 4;
 /** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
@@ -149,6 +149,23 @@ export interface FtsOptimizeResult {
  * the DB file; run VACUUM (with the daemon stopped) to return it to the OS.
  */
 export declare function optimizeSessionSearchIndex(): FtsOptimizeResult[];
+/**
+ * Keep the FTS indexes from degrading on the normal scan path.
+ *
+ * `optimizeSessionSearchIndex` is the full, unbounded compaction behind
+ * `agents sessions optimize`. Leaving it as the ONLY compaction meant the index
+ * degraded until a human happened to run that command, which is how
+ * `tool_call_text_data` reached gigabytes for tens of MB of content. This is the
+ * automatic counterpart: bounded, threshold-gated, and safe to call after every
+ * batch of writes. Non-destructive — merging never changes what is searchable.
+ *
+ * Returns one result per table it actually merged (empty when every table is
+ * under the threshold, which is the common case on a warm index).
+ */
+export declare function maintainSessionSearchIndex(db?: Database.Database, options?: {
+    segmentThreshold?: number;
+    mergePages?: number;
+}): FtsOptimizeResult[];
 /**
  * Try to claim the right to run the incremental scan. Returns true if this
  * process should proceed with scanning, false if another live process is
@@ -245,6 +262,7 @@ export declare function upsertSessionsBatch(entries: Array<{
     scan?: ScanStamp;
     parserState?: string;
     contentText?: string;
+    events?: SessionEvent[];
     toolCalls?: IndexedToolCall[];
     toolScan?: ScanStamp;
     toolIndexMode?: 'replace' | 'append';