@phnx-labs/agents-cli 1.22.21 → 1.22.23

package/dist/lib/secrets/reaper.js

@@ -0,0 +1,184 @@
+/**
+ * Reaper for orphaned / wedged keychain-helper processes.
+ *
+ * macOS keychain-helper calls are synchronous spawnSync invocations. When
+ * coreauthd / LocalAuthentication hangs, the helper process (and sometimes its
+ * parent `agents` process) can pile up forever. This module detects two classes
+ * of stale process and kills them.
+ *
+ * The design splits cleanly into:
+ *   - a pure planner ({@link planKeychainReap}) that is unit-testable without a
+ *     real `ps` shell, and
+ *   - an impure driver ({@link reapOrphanedKeychainProcesses}) that shells `ps`
+ *     once per tick and executes kills through {@link killTree}.
+ */
+import { execFileSync } from 'child_process';
+import { killTree, captureProcessStartTime } from '../platform/process.js';
+import { getKeychainHelperPath } from './install-helper.js';
+/** Elapsed grace before a helper whose parent exited is considered an orphan. */
+export const ORPHAN_GRACE_SEC = 30;
+/** Elapsed 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.
+ *
+ * Mirrors the shape of {@link isExpiredPoolStray} in `lib/crabbox/lease.ts`:
+ * a side-effect-free classifier that the impure driver shells `ps` for. Two
+ * conservative reap classes:
+ *
+ *   1. Orphaned helper: PPID == 1, path-matches the helper, alive longer than
+ *      {@link ORPHAN_GRACE_SEC}.
+ *   2. Stuck `agents` parent: helper child alive longer than
+ *      {@link STUCK_GRACE_SEC}. Recorded on first sight, child killed on the
+ *      second consecutive sweep with the same PID + startTime, parent killed on
+ *      the third sweep if the helper child is still present.
+ *
+ * Never reaps a process whose start time could not be captured, whose path does
+ * not match the helper, or whose parent is no longer in the snapshot.
+ */
+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: parent is init/launchd. Fail closed if we can't prove
+            // the process identity with a start-time fingerprint.
+            if (s.elapsedSec <= ORPHAN_GRACE_SEC)
+                continue;
+            if (s.startTime == null)
+                continue;
+            kill.push(s.pid);
+            continue;
+        }
+        // Stuck agents: a helper with a live parent that has been wedged for longer
+        // than the interactive timeout. The parent must still exist in the snapshot.
+        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 the parent's spawnSync returns.
+                // Keep the parent candidate at stage 'escalate' for the next sweep.
+                kill.push(s.pid);
+                nextCandidates.set(parent.pid, { ...prev, stage: 'escalate' });
+                continue;
+            }
+            // Third sweep: child did not free the parent, so the parent itself 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',
+        });
+    }
+    return { kill, nextCandidates };
+}
+/**
+ * Parse one `ps` output line.
+ *
+ * Expected format from `ps -ax -o pid=,ppid=,etimes=,command=`:
+ *   "<pid> <ppid> <etimes> <command...>"
+ * The command field is the remainder of the line and may contain spaces.
+ */
+function parsePsLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    const m = trimmed.match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/);
+    if (!m)
+        return null;
+    const pid = parseInt(m[1], 10);
+    const ppid = parseInt(m[2], 10);
+    const elapsedSec = parseInt(m[3], 10);
+    const command = m[4];
+    if (isNaN(pid) || isNaN(ppid) || isNaN(elapsedSec))
+        return null;
+    return { pid, ppid, elapsedSec, command };
+}
+/** 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-matching uses the full helper path (proc_pidpath-style), not just the
+ * executable name, so an unrelated binary named "Agents CLI" is never targeted.
+ *
+ * Returns on non-darwin platforms without shelling anything — the helper only
+ * exists on macOS.
+ */
+export 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;
+    try {
+        out = execFileSync('ps', ['-ax', '-o', 'pid=,ppid=,etimes=,command='], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch (err) {
+        return { reaped: 0, details: [`ps failed: ${err.message}`], plan: { kill: [], nextCandidates: new Map() } };
+    }
+    const snapshots = [];
+    for (const line of out.split('\n')) {
+        const parsed = parsePsLine(line);
+        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} `);
+        snapshots.push({
+            pid,
+            ppid,
+            elapsedSec,
+            startTime: captureProcessStartTime(pid),
+            isHelper,
+        });
+    }
+    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

@@ -177,3 +177,32 @@ export declare function keychainWriteFailureMessage(host: string, bundle: string
 export declare function verifyRemoteKeychainPush(target: string, bundle: string, pushedKeys: string[], opts?: {
     osLookupName?: string;
 }): RemoteKeychainWriteVerification;
+/**
+ * The `bash -lc` command + stdin payload that drives a **file-backed** remote
+ * import for `secrets export --host … --remote-backend file`.
+ *
+ * The file store is passphrase-free by default: with `AGENTS_SECRETS_PASSPHRASE`
+ * unset the remote `agents secrets import --backend file` auto-provisions the
+ * remote's own machine-local key (0600 under `~/.agents/.secrets-key/`), so its
+ * reads are HEADLESS — no passphrase, no Touch ID. A passphrase is therefore
+ * OPTIONAL and only forwarded when the operator sets one locally (opt-in, e.g. to
+ * key the bundle off-disk under a shared secret):
+ *
+ * - **No passphrase** → the remote runs `import … --backend file` directly with
+ *   ONLY the .env on stdin. No `read`/`export AGENTS_SECRETS_PASSPHRASE`
+ *   prologue, so `AGENTS_SECRETS_PASSPHRASE` stays UNSET on the remote → the
+ *   machine-local key path → headless reads.
+ * - **Passphrase set** → forward it as the FIRST stdin line, consumed by
+ *   `IFS= read -r` (so it never lands in argv / `ps` / remote shell history),
+ *   then the .env. The remote then keys the bundle under that shared passphrase.
+ *
+ * Pure — no I/O — so the exact command string and stdin ordering are unit-testable
+ * against the SSH boundary the same way `remoteSecretsRaw` is.
+ */
+export declare function buildRemoteFileImportCommand(bundle: string, dotenv: string, opts?: {
+    passphrase?: string;
+    force?: boolean;
+}): {
+    remoteCmd: string;
+    input: string;
+};

package/dist/lib/secrets/remote.js

@@ -15,7 +15,7 @@
  * file-backend passphrase travels over ssh stdin (first line) so it never lands
  * in argv / `ps` / remote shell history. Nothing is persisted locally.
  */
-import { sshExec, sshStream, assertValidSshTarget } from '../ssh-exec.js';
+import { sshExec, sshStream, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
 import { emitSecretAudit } from './audit.js';
 import { sshTargetFor } from '../hosts/types.js';
@@ -348,3 +348,39 @@ export function verifyRemoteKeychainPush(target, bundle, pushedKeys, opts = {})
     }
     return evaluateKeychainWriteVerification(pushedKeys, { ok: true, keys });
 }
+/**
+ * The `bash -lc` command + stdin payload that drives a **file-backed** remote
+ * import for `secrets export --host … --remote-backend file`.
+ *
+ * The file store is passphrase-free by default: with `AGENTS_SECRETS_PASSPHRASE`
+ * unset the remote `agents secrets import --backend file` auto-provisions the
+ * remote's own machine-local key (0600 under `~/.agents/.secrets-key/`), so its
+ * reads are HEADLESS — no passphrase, no Touch ID. A passphrase is therefore
+ * OPTIONAL and only forwarded when the operator sets one locally (opt-in, e.g. to
+ * key the bundle off-disk under a shared secret):
+ *
+ * - **No passphrase** → the remote runs `import … --backend file` directly with
+ *   ONLY the .env on stdin. No `read`/`export AGENTS_SECRETS_PASSPHRASE`
+ *   prologue, so `AGENTS_SECRETS_PASSPHRASE` stays UNSET on the remote → the
+ *   machine-local key path → headless reads.
+ * - **Passphrase set** → forward it as the FIRST stdin line, consumed by
+ *   `IFS= read -r` (so it never lands in argv / `ps` / remote shell history),
+ *   then the .env. The remote then keys the bundle under that shared passphrase.
+ *
+ * Pure — no I/O — so the exact command string and stdin ordering are unit-testable
+ * against the SSH boundary the same way `remoteSecretsRaw` is.
+ */
+export function buildRemoteFileImportCommand(bundle, dotenv, opts = {}) {
+    const force = opts.force ? ' --force' : '';
+    const importCmd = `agents secrets import ${shellQuote(bundle)} --from - --backend file${force}`;
+    const passphrase = opts.passphrase ?? '';
+    if (passphrase) {
+        // Opt-in shared passphrase: read it off the FIRST stdin line, export it, then
+        // let `import --from -` read the .env remainder.
+        const remoteAgents = `IFS= read -r AGENTS_SECRETS_PASSPHRASE; export AGENTS_SECRETS_PASSPHRASE; ${importCmd}`;
+        return { remoteCmd: `bash -lc ${shellQuote(remoteAgents)}`, input: `${passphrase}\n${dotenv}` };
+    }
+    // No passphrase: NO prologue — AGENTS_SECRETS_PASSPHRASE stays unset on the
+    // remote, so the file store falls back to its machine-local key (headless).
+    return { remoteCmd: `bash -lc ${shellQuote(importCmd)}`, input: dotenv };
+}

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

@@ -2,7 +2,7 @@ import type { CloudTaskStatus } from '../cloud/types.js';
 import { type PidSessionEntry } from './pid-registry.js';
 import { type HookSessionIndex } from './hook-sessions.js';
 import { type SessionState, type SessionActivity, type AwaitingReason, type StructuredQuestion, type TodoProgress, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
-import { type SessionAttachment } from './types.js';
+import { type SessionAgentId, type SessionAttachment } from './types.js';
 import { type SessionProvenance } from './provenance.js';
 import { type DeviceRegistry } from '../devices/registry.js';
 import { type Presence } from './detached.js';
@@ -111,6 +111,13 @@ export interface ActiveSession {
     attachments?: SessionAttachment[];
     sessionFile?: string;
     startedAtMs?: number;
+    /**
+     * Agent version (e.g. `2.1.207`) for the row's `agent version` cell. Not a
+     * live-scan signal — a running process does not report its own semver — so it
+     * is backfilled at render time from the indexed {@link SessionMeta} by session
+     * id (RUSH-2205), never asserted by a source.
+     */
+    version?: string;
     /**
      * Last-activity epoch — the transcript's last write (mtime). Distinct from
      * {@link startedAtMs} (session START): a session begun 3h ago but last touched
@@ -294,6 +301,16 @@ export declare const ACTIVE_SESSION_STALE_MS: number;
  * concern) — this is the lifecycle threshold, not the freshness window.
  */
 export declare const ABANDONED_STALE_MS: number;
+/**
+ * Every process executable ("comm") name that identifies a given session-agent
+ * kind in the headless `ps`-scan. Driven off the AGENTS registry's `cliCommand`
+ * (the real executable name — e.g. `agy` for antigravity, `cursor-agent` for
+ * cursor) plus {@link EXTRA_SESSION_AGENT_COMMS} for members with no registry
+ * row. Exported so the completeness test can assert every {@link SESSION_AGENTS}
+ * member resolves — the fix for the harness-parity gap where bare-headless
+ * grok/kimi/antigravity/openclaw/hermes/rush were silently dropped.
+ */
+export declare function sessionAgentComms(id: SessionAgentId): string[];
 /**
  * Resolve an agent kind from a process's reported executable. `comm` may be an
  * absolute path (shim-launched agents), and Windows image names carry an
@@ -600,6 +617,24 @@ export declare function foldHostLink(rows: ActiveSession[]): void;
  * renderer shows the short id. Pure over the array; exported for tests.
  */
 export declare function annotateOrchestratorLabels(sessions: ActiveSession[]): void;
+/**
+ * Attach provenance (host / local-vs-SSH / tmux pane / reply rail) to every
+ * session that has a live pid. Mutates in place. Runs after dedupe so we probe
+ * each session once, not once per fork pid. Probes run in parallel — each is a
+ * single /proc read (Linux) or `ps` call (macOS); failures leave `provenance`
+ * undefined rather than blocking the listing. The probes use the same bounded
+ * concurrency as the adjacent per-PID lsof sweep so large session lists cannot
+ * spawn one `ps eww` subprocess per row at once on macOS.
+ *
+ * A row that already carries provenance (the tmux path, which knows its exact
+ * mux/reply from the pane) is not skipped — it is probe-and-MERGED. The tmux
+ * path can only stamp a `transport:'local'` placeholder because the pane alone
+ * doesn't reveal how the shell above it was reached; the process env does. So we
+ * still read the env and fill in the real SSH origin/term, while preserving the
+ * authoritative mux/reply the pane already gave us. Skipping this (the old
+ * behavior) is exactly why ssh-launched tmux sessions rendered as local.
+ */
+export declare function enrichProvenance(sessions: ActiveSession[], probe?: (pid: number) => Promise<SessionProvenance | undefined>): Promise<void>;
 /**
  * Match an SSH client IP to a registered device (pure — testable with a plain
  * registry object). Returns the device name + ssh login user when the IP is a

package/dist/lib/session/active.js

@@ -25,7 +25,7 @@ import { listActiveTasks } from '../cloud/store.js';
 import { AgentManager } from '../teams/agents.js';
 import { getTerminalsDir } from '../state.js';
 import { readPidSessionEntry, listPidSessionEntries, prunePidSessionRegistry } from './pid-registry.js';
-import { readSessionActorRecord } from './actor-sidecar.js';
+import { readSessionActorRecord, writeSessionAliasRecord } from './actor-sidecar.js';
 import { loadHookSessionIndex, resolveHookSessionRecord, readStateSessionRecord } from './hook-sessions.js';
 import { buildClaudeLabelMap, getAgentSessionDirs } from './discover.js';
 import { buildRunNameMap } from './run-names.js';
@@ -35,7 +35,8 @@ import { readSessionTailWithRaw } from './tail.js';
 import { parseSession } from './parse.js';
 import { computeTokPerSec } from './throughput.js';
 import { inferSessionState } from './state.js';
-import { isSessionTrackedAgent } from './types.js';
+import { isSessionTrackedAgent, SESSION_AGENTS } from './types.js';
+import { AGENTS } from '../agents.js';
 import { detectProvenance } from './provenance.js';
 import { loadDevices } from '../devices/registry.js';
 import { presenceFromStore } from './detached.js';
@@ -132,15 +133,47 @@ export const ABANDONED_STALE_MS = 2 * 24 * 60 * 60_000;
  * just reintroduce the same class of bug with a lower probability.
  */
 const TMUX_FIELD_SEP = ':';
-/** Executables we recognize as agent CLIs when scanning the process table. */
-const AGENT_CLI_NAMES = {
-    claude: 'claude',
-    codex: 'codex',
-    gemini: 'gemini',
-    'cursor-agent': 'cursor',
-    opencode: 'opencode',
-    droid: 'droid',
+/**
+ * Process comm names that are NOT derivable from the AGENTS registry's
+ * `cliCommand`. `rush` is a {@link SESSION_AGENTS} member with no AGENTS registry
+ * row (it is the Rush app, not a managed harness), so its executable name is
+ * mapped explicitly here. Everything else flows from the registry below.
+ */
+const EXTRA_SESSION_AGENT_COMMS = {
+    rush: ['rush'],
 };
+/**
+ * Every process executable ("comm") name that identifies a given session-agent
+ * kind in the headless `ps`-scan. Driven off the AGENTS registry's `cliCommand`
+ * (the real executable name — e.g. `agy` for antigravity, `cursor-agent` for
+ * cursor) plus {@link EXTRA_SESSION_AGENT_COMMS} for members with no registry
+ * row. Exported so the completeness test can assert every {@link SESSION_AGENTS}
+ * member resolves — the fix for the harness-parity gap where bare-headless
+ * grok/kimi/antigravity/openclaw/hermes/rush were silently dropped.
+ */
+export function sessionAgentComms(id) {
+    const comms = new Set();
+    const cli = AGENTS[id]?.cliCommand;
+    if (cli)
+        comms.add(cli);
+    for (const extra of EXTRA_SESSION_AGENT_COMMS[id] ?? [])
+        comms.add(extra);
+    return [...comms];
+}
+/**
+ * Executables we recognize as agent CLIs when scanning the process table. Built
+ * once from {@link sessionAgentComms} across {@link SESSION_AGENTS} — a single
+ * derived source, not a second hand-maintained allowlist that drifts from the
+ * discovery surface (the harness-parity code-review rule).
+ */
+const AGENT_CLI_NAMES = (() => {
+    const map = {};
+    for (const id of SESSION_AGENTS) {
+        for (const comm of sessionAgentComms(id))
+            map[comm] = id;
+    }
+    return map;
+})();
 /**
  * Resolve an agent kind from a process's reported executable. `comm` may be an
  * absolute path (shim-launched agents), and Windows image names carry an
@@ -1310,7 +1343,7 @@ export async function listTmuxAgentSessions() {
     try {
         res = await runTmux({
             socket,
-            args: ['list-panes', '-a', '-F', ['#{pane_id}', '#{session_name}', '#{pane_pid}', '#{pane_current_path}'].join(TMUX_FIELD_SEP)],
+            args: ['list-panes', '-a', '-F', ['#{pane_id}', '#{session_name}', '#{pane_pid}', '#{pane_dead}', '#{pane_current_path}'].join(TMUX_FIELD_SEP)],
             throwOnError: false,
             // A wedged tmux server must not hang the whole active-session scan. The
             // catch below turns a timeout into an empty tmux source (the other sources
@@ -1351,8 +1384,8 @@ export async function listTmuxAgentSessions() {
         // The path is the LAST field, so rejoin its tail: a directory containing the
         // separator must not truncate it (the earlier fields cannot contain one).
         const parts = line.split(TMUX_FIELD_SEP);
-        const [pane, sessName, pidRaw] = parts;
-        const curPath = parts.slice(3).join(TMUX_FIELD_SEP);
+        const [pane, sessName, pidRaw, paneDeadRaw] = parts;
+        const curPath = parts.slice(4).join(TMUX_FIELD_SEP);
         if (!pane || !sessName)
             continue;
         const meta = readSessionMeta(sessName);
@@ -1378,6 +1411,9 @@ export async function listTmuxAgentSessions() {
             if (backfilled)
                 id = { ...id, sessionId: backfilled };
         }
+        if (id.sessionId && shortIdFromName(sessName)) {
+            writeSessionAliasRecord(id.sessionId, sessName);
+        }
         // Dedupe by resolved session id; an as-yet-unresolved id (a hookless/lagging
         // split) keys on the unique pane so it still surfaces as its own row.
         const dedupKey = id.sessionId ?? pane;
@@ -1395,7 +1431,10 @@ export async function listTmuxAgentSessions() {
         // bug). Refuse to guess: an id-less pane surfaces as its own row instead.
         const sessionFile = id.sessionId ? findSessionFileForKind(id.agent, cwd, id.sessionId) : undefined;
         const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
-        const pidAlive = pid ? isPidAlive(pid, liveEntry?.startedAtMs) : true;
+        // `remain-on-exit` retains the pane after its child exits. pane_dead is the
+        // authoritative signal; a retained pane is diagnostic, not attachable.
+        const paneDead = paneDeadRaw === '1';
+        const pidAlive = !paneDead && (pid ? isPidAlive(pid, liveEntry?.startedAtMs) : true);
         const { state, tokPerSec } = computeLiveSignals(id.agent, sessionFile, cwd, pidAlive);
         const { birthtimeMs, mtimeMs } = sessionFileTimes(sessionFile);
         // The mux/reply rails are known exactly here (the pane IS a tmux pane), so we
@@ -1620,7 +1659,9 @@ function foldPresence(rows) {
  * session that has a live pid. Mutates in place. Runs after dedupe so we probe
  * each session once, not once per fork pid. Probes run in parallel — each is a
  * single /proc read (Linux) or `ps` call (macOS); failures leave `provenance`
- * undefined rather than blocking the listing.
+ * undefined rather than blocking the listing. The probes use the same bounded
+ * concurrency as the adjacent per-PID lsof sweep so large session lists cannot
+ * spawn one `ps eww` subprocess per row at once on macOS.
  *
  * A row that already carries provenance (the tmux path, which knows its exact
  * mux/reply from the pane) is not skipped — it is probe-and-MERGED. The tmux
@@ -1630,11 +1671,11 @@ function foldPresence(rows) {
  * authoritative mux/reply the pane already gave us. Skipping this (the old
  * behavior) is exactly why ssh-launched tmux sessions rendered as local.
  */
-async function enrichProvenance(sessions) {
-    await Promise.all(sessions.map(async (s) => {
+export async function enrichProvenance(sessions, probe = detectProvenance) {
+    await mapBounded(sessions, async (s) => {
         if (!s.pid)
             return;
-        const probed = await detectProvenance(s.pid);
+        const probed = await probe(s.pid);
         if (!probed)
             return;
         if (!s.provenance) {
@@ -1649,7 +1690,7 @@ async function enrichProvenance(sessions) {
         }
         if (probed.term && !s.provenance.term)
             s.provenance.term = probed.term;
-    }));
+    }, { concurrency: LSOF_CONCURRENCY });
 }
 /**
  * Match an SSH client IP to a registered device (pure — testable with a plain

package/dist/lib/session/actor-sidecar.d.ts

@@ -7,6 +7,8 @@ export interface SessionActorRecord {
     initiatedBy?: 'human' | 'agent';
     /** Effective permissions mode used by the launcher. */
     mode?: SessionRunMode;
+    /** Stable wrapper names that resolve to this native session id. */
+    aliases?: string[];
     startedAtMs: number;
 }
 /**
@@ -15,6 +17,18 @@ export interface SessionActorRecord {
  * No-ops without a concrete session id (nothing to key on).
  */
 export declare function writeSessionActorRecord(record: SessionActorRecord): void;
+export declare function writeSessionAliasRecord(sessionId: string, alias: string): void;
+export type SessionAliasResolution = {
+    kind: 'resolved';
+    sessionId: string;
+} | {
+    kind: 'ambiguous';
+    sessionIds: string[];
+} | {
+    kind: 'not-found';
+};
+/** Resolve an exact alias, or a unique prefix/suffix of at least six chars. */
+export declare function resolveSessionAlias(selector: string): SessionAliasResolution;
 /** Read one session's actor record. Returns undefined if absent/corrupt. */
 export declare function readSessionActorRecord(sessionId: string): SessionActorRecord | undefined;
 /**

package/dist/lib/session/actor-sidecar.js

@@ -33,6 +33,25 @@ function isSafeSessionId(sessionId) {
 function recordPath(sessionId) {
     return path.join(sidecarDir(), `${sessionId}.json`);
 }
+function isSafeAlias(alias) {
+    return /^ag-[a-z][a-z0-9-]*-[0-9a-f]{8}$/i.test(alias);
+}
+function hasRecordData(record) {
+    return typeof record.actor === 'string'
+        || typeof record.mode === 'string'
+        || (Array.isArray(record.aliases) && record.aliases.some(alias => typeof alias === 'string'));
+}
+function normalizedAliases(aliases) {
+    if (!Array.isArray(aliases))
+        return [];
+    return [...new Set(aliases
+            .filter((alias) => typeof alias === 'string' && isSafeAlias(alias))
+            .map(alias => alias.toLowerCase()))];
+}
+function writeRecord(record) {
+    fs.mkdirSync(sidecarDir(), { recursive: true });
+    fs.writeFileSync(recordPath(record.sessionId), JSON.stringify(record), 'utf8');
+}
 /**
  * Record the actor a session was launched under. Never throws — the sidecar is
  * an attribution optimization; a session with no record simply scans unattributed.
@@ -42,13 +61,57 @@ export function writeSessionActorRecord(record) {
     if (!isSafeSessionId(record.sessionId))
         return;
     try {
-        fs.mkdirSync(sidecarDir(), { recursive: true });
-        fs.writeFileSync(recordPath(record.sessionId), JSON.stringify(record), 'utf8');
+        const previous = readSessionActorRecord(record.sessionId);
+        writeRecord({
+            ...previous,
+            ...record,
+            aliases: normalizedAliases([...(previous?.aliases ?? []), ...(record.aliases ?? [])]),
+        });
     }
     catch {
         /* degrade to an unattributed row */
     }
 }
+export function writeSessionAliasRecord(sessionId, alias) {
+    if (!isSafeSessionId(sessionId) || !isSafeAlias(alias))
+        return;
+    try {
+        const previous = readSessionActorRecord(sessionId);
+        writeRecord({
+            sessionId,
+            actor: previous?.actor,
+            initiatedBy: previous?.initiatedBy,
+            mode: previous?.mode,
+            aliases: normalizedAliases([...(previous?.aliases ?? []), alias]),
+            startedAtMs: previous?.startedAtMs ?? Date.now(),
+        });
+    }
+    catch {
+        /* the native id remains usable */
+    }
+}
+/** Resolve an exact alias, or a unique prefix/suffix of at least six chars. */
+export function resolveSessionAlias(selector) {
+    const normalized = selector.trim().toLowerCase();
+    if (!normalized)
+        return { kind: 'not-found' };
+    const exact = new Set();
+    const fuzzy = new Set();
+    for (const record of loadSessionActorIndex().values()) {
+        for (const alias of normalizedAliases(record.aliases)) {
+            if (alias === normalized)
+                exact.add(record.sessionId);
+            else if (normalized.length >= 6 && (alias.startsWith(normalized) || alias.endsWith(normalized)))
+                fuzzy.add(record.sessionId);
+        }
+    }
+    const matches = exact.size > 0 ? [...exact] : [...fuzzy];
+    if (matches.length === 0)
+        return { kind: 'not-found' };
+    if (matches.length > 1)
+        return { kind: 'ambiguous', sessionIds: matches.sort() };
+    return { kind: 'resolved', sessionId: matches[0] };
+}
 /** Read one session's actor record. Returns undefined if absent/corrupt. */
 export function readSessionActorRecord(sessionId) {
     if (!isSafeSessionId(sessionId))
@@ -63,7 +126,7 @@ export function readSessionActorRecord(sessionId) {
     try {
         const parsed = JSON.parse(raw);
         if (parsed && typeof parsed === 'object' && typeof parsed.sessionId === 'string' &&
-            (typeof parsed.actor === 'string' || typeof parsed.mode === 'string')) {
+            hasRecordData(parsed)) {
             return parsed;
         }
     }
@@ -91,7 +154,7 @@ export function loadSessionActorIndex() {
         try {
             const parsed = JSON.parse(fs.readFileSync(path.join(sidecarDir(), f), 'utf8'));
             if (parsed && typeof parsed === 'object' && typeof parsed.sessionId === 'string' &&
-                (typeof parsed.actor === 'string' || typeof parsed.mode === 'string')) {
+                hasRecordData(parsed)) {
                 out.set(parsed.sessionId, parsed);
             }
         }

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

@@ -12,7 +12,7 @@ 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 = 33;
+export declare const SCHEMA_VERSION = 34;
 /**
  * Bump to force `agents sessions backfill resources` to re-derive every
  * session's skill/slash-command tallies on its next run (resource_scan_ledger
@@ -20,6 +20,13 @@ export declare const SCHEMA_VERSION = 33;
  * TOOL_INDEX_VERSION gives the tool backfill).
  */
 export declare const RESOURCE_INDEX_VERSION = 1;
+/**
+ * Bumping this invalidates every cached facet row without touching the schema
+ * version, so a change to the extraction logic (a new metric, a corrected bucket)
+ * 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;
 /** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
@@ -317,6 +324,33 @@ export interface UsageRollupRow {
     outputTokens: number;
 }
 /** What to group a usage rollup by. */
+/**
+ * Read cached facets for the given sessions, dropping any row that is stale.
+ *
+ * Staleness is decided in SQL against the session's own `file_mtime_ms` / `file_size`,
+ * the same pair the scanner maintains — so the cache cannot disagree with the index,
+ * `IS` rather than `=` so a source with no statable file — NULL on both sides — is a
+ * cache HIT rather than a permanent miss that re-parses it on every run.
+ */
+export declare function readSessionInsights<T>(ids: string[]): Map<string, T>;
+/**
+ * Persist freshly computed facets against the stamp of the bytes actually parsed.
+ *
+ * The caller passes the stat it observed when it read the file. Re-reading the stamp
+ * from the sessions table inside this INSERT would race: a concurrent rescan between
+ * the parse and the write (the cold path flushes in batches, so the window is minutes
+ * wide, and this module treats concurrent access as a design assumption) stamps NEW
+ * bytes onto OLD facets — a permanent false cache hit until the file changes again.
+ * tool-index.ts sets the precedent: stat at parse time, carry the stamp into the write.
+ */
+export declare function writeSessionInsights<T>(entries: Array<{
+    id: string;
+    fileMtimeMs: number | null;
+    fileSize: number | null;
+    facets: T;
+}>): void;
+/** Drop every cached facet row. Backs `agents insights --refresh`. */
+export declare function clearSessionInsights(): void;
 export type UsageRollupGroup = 'agent' | 'project' | 'day' | 'account';
 /**
  * Smart-launch affinity priors: group sessions by origin machine, harness, or