@phnx-labs/agents-cli 1.22.83 → 1.22.85

package/dist/lib/secrets/read-backoff.js

@@ -1,64 +0,0 @@
-/**
- * Negative memo for failed/cancelled macOS keychain reads (the "back-off").
- *
- * A cancelled Touch ID sheet is the user saying "not now" — but a polling
- * caller (AGI EXT host's `agents view` loop, a watch script)
- * retries the same read a few seconds later and pops the sheet again, forever.
- * The headless guard (index.ts `assertRawKeychainReadAllowed`) covers the
- * no-TTY case; this memo covers a context that CAN prompt but just had its
- * prompt cancelled or fail: the next read of the same item within the TTL
- * throws the back-off error instead of re-prompting. Any successful read (or
- * write) of the item clears the memo.
- *
- * Stored as regenerable state under `~/.agents/.cache/keychain-read-backoff/`,
- * one file per item (filename is a hash of the item name; the file carries no
- * secret material — a name and a deadline only). All operations are
- * best-effort: a lost memo costs at most one extra prompt, never a read.
- */
-import { createHash } from 'node:crypto';
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-/** How long a failed/cancelled read suppresses retries of the same item. */
-export const KEYCHAIN_READ_BACKOFF_TTL_MS = 5 * 60 * 1000;
-let dirOverride = null;
-/** Test seam: point the memo at a temp dir so tests never touch the real cache. */
-export function setKeychainReadBackoffDirForTest(dir) {
-    dirOverride = dir;
-}
-function backoffDir() {
-    return dirOverride ?? path.join(os.homedir(), '.agents', '.cache', 'keychain-read-backoff');
-}
-function backoffFile(key) {
-    const digest = createHash('sha256').update(key).digest('hex').slice(0, 24);
-    return path.join(backoffDir(), `${digest}.json`);
-}
-/** True while `key` is inside the back-off window opened by a failed/cancelled read. */
-export function isKeychainReadBackedOff(key, now = Date.now()) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(backoffFile(key), 'utf8'));
-        return typeof parsed.until === 'number' && parsed.until > now;
-    }
-    catch {
-        return false; // absent or malformed memo → no back-off
-    }
-}
-/** Open (or refresh) the back-off window for `key` after a failed/cancelled read. */
-export function noteKeychainReadFailure(key, now = Date.now()) {
-    try {
-        fs.mkdirSync(backoffDir(), { recursive: true, mode: 0o700 });
-        fs.writeFileSync(backoffFile(key), JSON.stringify({ item: key, until: now + KEYCHAIN_READ_BACKOFF_TTL_MS }), { mode: 0o600 });
-    }
-    catch {
-        /* best-effort — the cache dir is regenerable; a lost memo costs one prompt */
-    }
-}
-/** Clear the memo: a successful read or write of the item resets the back-off. */
-export function clearKeychainReadBackoff(key) {
-    try {
-        fs.rmSync(backoffFile(key), { force: true });
-    }
-    catch {
-        /* best-effort */
-    }
-}

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

@@ -1,90 +0,0 @@
-/**
- * Reaper for orphaned / wedged keychain-helper processes.
- *
- * coreauthd / LocalAuthentication hangs can leave helper (and parent `agents`)
- * processes pile up. The pure planner ({@link planKeychainReap}) is unit-testable
- * without a real `ps`; the driver ({@link reapOrphanedKeychainProcesses}) shells
- * `ps` once per tick and kills through {@link killTree}.
- */
-/** Grace before a helper whose parent exited is considered an orphan. */
-export declare const ORPHAN_GRACE_SEC = 30;
-/** Grace before a helper with a live parent is considered stuck. */
-export declare const STUCK_GRACE_SEC = 90;
-/** Snapshot of one process row from `ps`, fed into the pure planner. */
-export interface KeychainProcessSnapshot {
-    pid: number;
-    ppid: number;
-    /** Elapsed seconds since the process started. */
-    elapsedSec: number;
-    /** Stable start-time fingerprint from {@link captureProcessStartTime}; null fails closed. */
-    startTime: string | null;
-    /** True for a reap-eligible helper invocation (short-lived keychain verb). */
-    isHelper: boolean;
-    /**
-     * True for the deliberately long-lived `watch-lock` watcher
-     * (auto-lock-on-sleep). Mutually exclusive with {@link isHelper}; killing it
-     * silently disables auto-lock-on-sleep, so it is reaped only once the owning
-     * daemon is provably dead (RUSH-2419).
-     */
-    isWatchLock?: boolean;
-}
-/** Tracked state for a stuck parent across two-sweep debounce. */
-export interface StuckParentCandidate {
-    pid: number;
-    startTime: string | null;
-    helperPid: number;
-    helperStartTime: string | null;
-    firstSeenAt: number;
-    stage: 'watch' | 'escalate';
-}
-/** Result of one planning pass. */
-export interface ReapPlan {
-    /** PIDs to kill this tick. */
-    kill: number[];
-    /** Candidates to carry forward to the next sweep. */
-    nextCandidates: Map<number, StuckParentCandidate>;
-}
-/**
- * Pure predicate: decide which processes to kill given a `ps`-like snapshot.
- *
- * Three conservative classes:
- *   1. Orphaned helper: PPID == 1, helper path, alive longer than grace.
- *   2. Stuck `agents` parent: helper child alive longer than stuck grace,
- *      recorded on first sight, child killed on second sweep, parent on third.
- *   3. Orphaned `watch-lock`: long-lived watcher whose owning daemon is gone.
- *
- * Fails closed when start time can't be captured.
- */
-export declare function planKeychainReap(snapshots: KeychainProcessSnapshot[], now: number, prevCandidates: ReadonlyMap<number, StuckParentCandidate>): ReapPlan;
-/**
- * Parse macOS `ps -o etime=` elapsed time into whole seconds.
- *
- * BSD `etime` renders as `[[dd-]hh:]mm:ss`. `etimes` (raw seconds) is a GNU
- * extension that macOS `ps` rejects, so darwin uses `etime`.
- */
-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. Returns false for the
- * long-lived `watch-lock` watcher, which must never be mistaken for a stuck read.
- */
-export declare function isReapableHelperCommand(command: string, helperPath: string): boolean;
-/**
- * Whether a `ps` command line is the deliberately long-lived `watch-lock`
- * watcher. Inverse of {@link isReapableHelperCommand} for the watch-lock verb.
- */
-export declare function isWatchLockHelperCommand(command: string, helperPath: string): boolean;
-/** Test seam: reset the persisted candidate state. */
-export declare function resetKeychainReaperCandidatesForTest(): void;
-/**
- * Impure driver: snapshot all processes once with `ps`, plan the reap, then
- * execute kills through {@link killTree}.
- *
- * Path-matches the full helper path so an unrelated binary named "Agents CLI" is
- * never targeted. Returns on non-darwin without shelling anything.
- */
-export declare function reapOrphanedKeychainProcesses(): Promise<{
-    reaped: number;
-    details: string[];
-    plan: ReapPlan;
-}>;

package/dist/lib/secrets/reaper.js

@@ -1,243 +0,0 @@
-/**
- * Reaper for orphaned / wedged keychain-helper processes.
- *
- * coreauthd / LocalAuthentication hangs can leave helper (and parent `agents`)
- * processes pile up. The pure planner ({@link planKeychainReap}) is unit-testable
- * without a real `ps`; the driver ({@link reapOrphanedKeychainProcesses}) shells
- * `ps` once per tick and kills through {@link killTree}.
- */
-import { killTree, captureProcessStartTime } from '../platform/process.js';
-import { execFileBounded } from '../exec-bounded.js';
-/** Deadline for the whole-process-table `ps` on the keychain-reap tick. */
-const KEYCHAIN_PS_TIMEOUT_MS = 5_000;
-import { getKeychainHelperPath } from './install-helper.js';
-/** Grace before a helper whose parent exited is considered an orphan. */
-export const ORPHAN_GRACE_SEC = 30;
-/** Grace before a helper with a live parent is considered stuck. */
-export const STUCK_GRACE_SEC = 90;
-/**
- * Pure predicate: decide which processes to kill given a `ps`-like snapshot.
- *
- * Three conservative classes:
- *   1. Orphaned helper: PPID == 1, helper path, alive longer than grace.
- *   2. Stuck `agents` parent: helper child alive longer than stuck grace,
- *      recorded on first sight, child killed on second sweep, parent on third.
- *   3. Orphaned `watch-lock`: long-lived watcher whose owning daemon is gone.
- *
- * Fails closed when start time can't be captured.
- */
-export function planKeychainReap(snapshots, now, prevCandidates) {
-    const pidMap = new Map(snapshots.map((s) => [s.pid, s]));
-    const kill = [];
-    const nextCandidates = new Map();
-    for (const s of snapshots) {
-        if (!s.isHelper)
-            continue;
-        if (s.ppid === 1) {
-            // Orphaned helper: fail closed without a start-time fingerprint.
-            if (s.elapsedSec <= ORPHAN_GRACE_SEC)
-                continue;
-            if (s.startTime == null)
-                continue;
-            kill.push(s.pid);
-            continue;
-        }
-        // Stuck agents: helper with a live parent wedged longer than the timeout.
-        if (s.elapsedSec <= STUCK_GRACE_SEC)
-            continue;
-        const parent = pidMap.get(s.ppid);
-        if (!parent)
-            continue;
-        if (s.startTime == null || parent.startTime == null)
-            continue;
-        const prev = prevCandidates.get(parent.pid);
-        if (prev &&
-            prev.helperPid === s.pid &&
-            prev.helperStartTime === s.startTime &&
-            prev.startTime === parent.startTime) {
-            if (prev.stage === 'watch') {
-                // Second sweep: kill the child first so spawnSync returns; escalate next.
-                kill.push(s.pid);
-                nextCandidates.set(parent.pid, { ...prev, stage: 'escalate' });
-                continue;
-            }
-            // Third sweep: child did not free the parent, so the parent is wedged.
-            kill.push(parent.pid);
-            continue;
-        }
-        // First sight of this (parent, helper) pair — record it and wait.
-        nextCandidates.set(parent.pid, {
-            pid: parent.pid,
-            startTime: parent.startTime,
-            helperPid: s.pid,
-            helperStartTime: s.startTime,
-            firstSeenAt: now,
-            stage: 'watch',
-        });
-    }
-    // Separate path for orphaned watch-lock watchers: only reap when the owning
-    // daemon is provably absent from the process table.
-    for (const s of snapshots) {
-        if (!s.isWatchLock)
-            continue;
-        if (s.startTime == null)
-            continue;
-        if (s.elapsedSec <= ORPHAN_GRACE_SEC)
-            continue;
-        if (s.ppid !== 1) {
-            const parent = pidMap.get(s.ppid);
-            if (parent)
-                continue;
-            // Parent missing means the owner is dead (or reparenting race); safe to reap.
-        }
-        kill.push(s.pid);
-    }
-    return { kill, nextCandidates };
-}
-/**
- * Parse macOS `ps -o etime=` elapsed time into whole seconds.
- *
- * BSD `etime` renders as `[[dd-]hh:]mm:ss`. `etimes` (raw seconds) is a GNU
- * extension that macOS `ps` rejects, so darwin uses `etime`.
- */
-export function parseEtimeToSeconds(raw) {
-    const m = raw.match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);
-    if (!m)
-        return null;
-    const days = m[1] ? parseInt(m[1], 10) : 0;
-    const hours = m[2] ? parseInt(m[2], 10) : 0;
-    const mins = parseInt(m[3], 10);
-    const secs = parseInt(m[4], 10);
-    if ([days, hours, mins, secs].some(isNaN))
-        return null;
-    return ((days * 24 + hours) * 60 + mins) * 60 + secs;
-}
-/**
- * Parse one `ps` output line.
- *
- * Expected format from `ps -ax -o pid=,ppid=,etime=,command=`:
- *   "<pid> <ppid> <etime> <command...>"
- */
-function parsePsLine(line) {
-    const trimmed = line.trim();
-    if (!trimmed)
-        return null;
-    const m = trimmed.match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/);
-    if (!m)
-        return null;
-    const pid = parseInt(m[1], 10);
-    const ppid = parseInt(m[2], 10);
-    const elapsedSec = parseEtimeToSeconds(m[3]);
-    const command = m[4];
-    if (isNaN(pid) || isNaN(ppid) || elapsedSec == null)
-        return null;
-    return { pid, ppid, elapsedSec, command };
-}
-/** The one helper verb that is deliberately long-lived: the auto-lock watcher. */
-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. Returns false for the
- * long-lived `watch-lock` watcher, which must never be mistaken for a stuck read.
- */
-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;
-}
-/**
- * Whether a `ps` command line is the deliberately long-lived `watch-lock`
- * watcher. Inverse of {@link isReapableHelperCommand} for the watch-lock verb.
- */
-export function isWatchLockHelperCommand(command, helperPath) {
-    if (!command.startsWith(`${helperPath} `))
-        return false;
-    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. */
-export function resetKeychainReaperCandidatesForTest() {
-    stuckParentCandidates = new Map();
-}
-/**
- * Impure driver: snapshot all processes once with `ps`, plan the reap, then
- * execute kills through {@link killTree}.
- *
- * Path-matches the full helper path so an unrelated binary named "Agents CLI" is
- * never targeted. Returns on non-darwin without shelling anything.
- */
-export async function reapOrphanedKeychainProcesses() {
-    const details = [];
-    if (process.platform !== 'darwin') {
-        return { reaped: 0, details, plan: { kill: [], nextCandidates: new Map() } };
-    }
-    let helperPath;
-    try {
-        helperPath = getKeychainHelperPath();
-    }
-    catch (err) {
-        return { reaped: 0, details: [`helper path resolution failed: ${err.message}`], plan: { kill: [], nextCandidates: new Map() } };
-    }
-    let out;
-    {
-        // Async, deadline-bounded: this whole-process-table `ps` runs on the daemon's
-        // shared event loop every keychain-reap tick, so a synchronous `execFileSync`
-        // (unbounded) would freeze it (PHNX-3695).
-        const res = await execFileBounded('ps', ['-ax', '-o', 'pid=,ppid=,etime=,command='], { timeoutMs: KEYCHAIN_PS_TIMEOUT_MS });
-        if (res.code !== 0) {
-            return { reaped: 0, details: [`ps failed${res.timedOut ? ' (timed out)' : ''}: ${res.stderr.trim() || `exit ${res.code}`}`], plan: { kill: [], nextCandidates: new Map() } };
-        }
-        out = res.stdout;
-    }
-    const rows = [];
-    for (const line of out.split('\n')) {
-        const parsed = parsePsLine(line);
-        if (!parsed)
-            continue;
-        const { pid, ppid, elapsedSec, command } = parsed;
-        // Match the full argv so the long-lived `watch-lock` watcher is never
-        // mistaken for a stuck read. Orphaned watch-locks are tracked separately.
-        const isHelper = isReapableHelperCommand(command, helperPath);
-        const isWatchLock = isWatchLockHelperCommand(command, helperPath);
-        rows.push({ pid, ppid, elapsedSec, isHelper, isWatchLock, startTime: null });
-    }
-    const rowByPid = new Map(rows.map((r) => [r.pid, r]));
-    for (const row of rows) {
-        if (!row.isHelper && !row.isWatchLock)
-            continue;
-        row.startTime = captureProcessStartTime(row.pid);
-        if (row.isHelper && row.ppid !== 1 && row.elapsedSec > STUCK_GRACE_SEC) {
-            const parent = rowByPid.get(row.ppid);
-            if (parent && parent.startTime === null) {
-                parent.startTime = captureProcessStartTime(row.ppid);
-            }
-        }
-    }
-    const snapshots = rows.map((r) => ({
-        pid: r.pid,
-        ppid: r.ppid,
-        elapsedSec: r.elapsedSec,
-        startTime: r.startTime,
-        isHelper: r.isHelper,
-        isWatchLock: r.isWatchLock,
-    }));
-    const plan = planKeychainReap(snapshots, Date.now(), stuckParentCandidates);
-    stuckParentCandidates = plan.nextCandidates;
-    for (const pid of plan.kill) {
-        if (pid === process.pid)
-            continue; // never self-terminate the reaper
-        try {
-            killTree(pid);
-            details.push(`killed pid ${pid}`);
-        }
-        catch (err) {
-            details.push(`failed to kill pid ${pid}: ${err.message}`);
-        }
-    }
-    return { reaped: plan.kill.length, details, plan };
-}

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

@@ -1,152 +0,0 @@
-/**
- * Remote secrets — read and use `agents secrets` bundles that live on another
- * host over the same SSH path that `agents secrets export --device` uses.
- *
- * Browse streams remote stdout verbatim; use resolves a bundle to an env map
- * and injects it ephemerally without persisting it locally.
- */
-import { type SshExecResult } from '../ssh-exec.js';
-export declare const REMOTE_TIMEOUT_MS = 30000;
-export interface RemoteSecretsRawOptions {
-    tty?: boolean;
-    input?: string;
-    osLookupName?: string;
-    secret?: boolean;
-    timeoutMs?: number;
-}
-/**
- * SSH options for secret-carrying transport. Pins the managed host key and
- * disables multiplex so no reusable control socket lingers for other invocations.
- */
-export declare function credentialTransportSshOpts(target: string): {
-    hostKeyOpts: string[];
-    multiplex: false;
-};
-/** Refuse durable credential transfer until the destination SSH key is pinned. */
-export declare function assertCredentialTransportHostPinned(target: string, pinned?: boolean): void;
-/**
- * Trust boundary for a remote-resolved env map. A peer's export output is
- * untrusted input that could reshape this process once merged into the env, so
- * block dangerous override classes here for every consumer:
- * loader/interpreter vars, GIT_*, *_PROXY, and *_BASE_URL.
- */
-export declare function isDangerousRemoteEnvKey(name: string): boolean;
-/**
- * Resolve a `--device` value to an ssh target string for the remote-secrets
- * path. Delegates to the same resolver `run --device` uses; on a miss, treats
- * the value as a raw ssh target and validates it.
- */
-export declare function resolveHostSshTarget(nameOrAlias: string): Promise<string>;
-/**
- * Merge `--host` / `--hosts` (and their `--device` / `--devices` aliases) into
- * an ordered, de-duplicated list. Empty when none is set.
- */
-export declare function parseHostsOption(opts: {
-    host?: string;
-    hosts?: string;
-    device?: string;
-    devices?: string;
-}): string[];
-/**
- * Split a `bundle@host` reference. No `@` → a local bundle. Bundle names can't
- * contain `@`, so the FIRST `@` separates bundle from ssh target; the target
- * itself may be `user@host` (e.g. `r2.backups@muqsit@box`).
- */
-export declare function splitBundleRef(ref: string): {
-    bundle: string;
-    host?: string;
-};
-/**
- * Run `agents secrets <args>` on a remote host over ssh and return the raw
- * result. Used by browse commands; `tty` forces `-tt` so remote passphrase
- * prompts can surface.
- */
-export declare function remoteSecretsRaw(target: string, args: string[], opts?: RemoteSecretsRawOptions): SshExecResult;
-/** Async, kill-bounded inverse of {@link remoteSecretsRaw} for daemon callers. */
-export declare function remoteSecretsRawAsync(target: string, args: string[], opts?: RemoteSecretsRawOptions): Promise<SshExecResult>;
-/**
- * Run a remote `agents secrets <args>` foreground with local stdio inherited,
- * so the remote sees a real TTY and its passphrase prompt surfaces and reads
- * keystrokes. Output streams to the terminal; only the exit code is returned.
- */
-export declare function remoteSecretsStream(target: string, args: string[], opts?: {
-    osLookupName?: string;
-}): number;
-/**
- * Resolve a remote bundle to a plaintext env map by driving the remote's
- * `agents secrets export <bundle> --plaintext --format json`. Values cross over
- * ssh stdout, parsed in memory, never persisted.
- *
- * The remote unlocks the bundle with its own credentials; this machine does NOT
- * forward its passphrase because the remote bundle is encrypted with the
- * remote's passphrase.
- */
-export declare function remoteResolveEnv(target: string, bundle: string, opts?: {
-    osLookupName?: string;
-}): Promise<Record<string, string>>;
-/**
- * Outcome of a post-push read-back verification.
- *   - `ok`              — the pushed keys materialized readably.
- *   - `locked-keychain` — read-back gave the specific locked-keychain signal.
- *   - `error`           — a different failure (SSH, timeout, etc.).
- */
-export type RemoteKeychainWriteVerification = {
-    ok: true;
-} | {
-    ok: false;
-    kind: 'locked-keychain';
-    reason: string;
-} | {
-    ok: false;
-    kind: 'error';
-    reason: string;
-};
-/**
- * Decide whether a keychain-backed push to a remote actually persisted its
- * secret value items by reading the bundle back the same way a later resolve
- * will. Catches the silent failure where headless SSH writes metadata but not
- * readable value items to a locked macOS login keychain.
- */
-export declare function evaluateKeychainWriteVerification(pushedKeys: string[], readBack: {
-    ok: true;
-    keys: string[];
-} | {
-    ok: false;
-    stderr: string;
-}): RemoteKeychainWriteVerification;
-/**
- * Actionable error message for a failed keychain-over-SSH push. Names the cause
- * (locked remote login keychain) and steers to the two real fixes.
- */
-export declare function keychainWriteFailureMessage(host: string, bundle: string, reason: string): string;
-/**
- * Read a bundle back from a remote over SSH and confirm the pushed keys
- * materialized. Drives the marker-gated json transport but keeps only KEY NAMES;
- * plaintext values are discarded immediately. Returns a verification verdict.
- */
-export declare function verifyRemoteKeychainPush(target: string, bundle: string, pushedKeys: string[], opts?: {
-    osLookupName?: string;
-    secret?: boolean;
-    timeoutMs?: number;
-}): RemoteKeychainWriteVerification;
-/** Async, kill-bounded read-back verification for daemon-originated pushes. */
-export declare function verifyRemoteKeychainPushAsync(target: string, bundle: string, pushedKeys: string[], opts?: {
-    osLookupName?: string;
-    secret?: boolean;
-    timeoutMs?: number;
-}): Promise<RemoteKeychainWriteVerification>;
-/**
- * `bash -lc` command + stdin payload for a file-backed remote import.
- *
- * The file store is passphrase-free: the remote auto-provisions its own machine-
- * local key, so reads are headless. AGENTS_SECRETS_PASSPHRASE must NOT be
- * forwarded (PHNX-2371): a remote keyed to a secret its daemon does not hold
- * reports "Imported N key(s)" then fails every later decrypt.
- */
-export declare function buildRemoteFileImportCommand(bundle: string, dotenv: string, opts?: {
-    force?: boolean;
-    policyNever?: boolean;
-}): {
-    remoteCmd: string;
-    input: string;
-};