@phnx-labs/agents-cli 1.22.22 → 1.22.24

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/secrets/sync-passphrase.d.ts

@@ -0,0 +1,27 @@
+/** The current variable for transport/sync passphrases. */
+export declare const SYNC_PASSPHRASE_ENV = "AGENTS_SYNC_PASSPHRASE";
+/** The file-store master key, honoured for sync only as a deprecated fallback. */
+export declare const LEGACY_PASSPHRASE_ENV = "AGENTS_SECRETS_PASSPHRASE";
+/** Reset the one-shot warning latches. Tests only — production never re-warns. */
+export declare function resetSyncPassphraseWarnings(): void;
+/** Where a resolved sync passphrase came from, so callers can report honestly. */
+export type SyncPassphraseSource = 'sync-env' | 'legacy-env' | null;
+export interface ResolvedSyncPassphrase {
+    value: string | null;
+    source: SyncPassphraseSource;
+}
+/**
+ * Read the transport passphrase from the environment, preferring the current
+ * variable and falling back to the deprecated one with a single warning.
+ * Returns `{ value: null }` when neither is set — the caller decides whether to
+ * prompt (TTY) or fail (headless). Never prompts, never throws.
+ */
+export declare function resolveSyncPassphraseFromEnv(): ResolvedSyncPassphrase;
+/**
+ * The one-shot reminder that an env-sourced passphrase is readable by other
+ * same-user processes. Separate from the deprecation notice above so a caller
+ * using the CURRENT variable still gets the readability warning exactly once.
+ */
+export declare function warnEnvPassphraseReadableOnce(): void;
+/** The message a headless caller shows when no passphrase is available. */
+export declare function missingSyncPassphraseMessage(): string;

package/dist/lib/secrets/sync-passphrase.js

@@ -0,0 +1,78 @@
+/**
+ * The passphrase that seals a bundle for TRANSPORT — `secrets push`/`pull` and
+ * the portable `export --to-file` / `import --from-file` envelope.
+ *
+ * This is deliberately a DIFFERENT secret from the file store's master key
+ * (`AGENTS_SECRETS_PASSPHRASE`, `filestore.ts:getPassphrase`). The two were one
+ * variable, and that overload is what put a master key into `~/.zshenv` on seven
+ * worker boxes (RUSH-1968): the file store stopped needing a passphrase once it
+ * auto-provisioned a machine-local key, but headless `push`/`pull` still hard-
+ * failed without one, so an operator exported the master key fleet-wide to make
+ * sync work — handing every same-user process the key to the whole store.
+ *
+ * Splitting them means a box that only needs headless sync sets
+ * `AGENTS_SYNC_PASSPHRASE` and never has the store's master key in its
+ * environment at all.
+ *
+ * Resolution order:
+ *   1. `AGENTS_SYNC_PASSPHRASE`        — the current name.
+ *   2. `AGENTS_SECRETS_PASSPHRASE`     — deprecated fallback, warns once.
+ *   3. (caller prompts, or fails)
+ *
+ * The fallback exists so already-scripted CI and release automation keep working
+ * across the upgrade; it is not a second supported spelling.
+ */
+import chalk from 'chalk';
+/** The current variable for transport/sync passphrases. */
+export const SYNC_PASSPHRASE_ENV = 'AGENTS_SYNC_PASSPHRASE';
+/** The file-store master key, honoured for sync only as a deprecated fallback. */
+export const LEGACY_PASSPHRASE_ENV = 'AGENTS_SECRETS_PASSPHRASE';
+/** Warn at most once per process: a `--all` push over many bundles must not
+ *  flood stderr with the same notice. */
+let deprecatedVarWarned = false;
+/** Same, for the "this came from an env var at all" readability notice. */
+let envPassphraseWarned = false;
+/** Reset the one-shot warning latches. Tests only — production never re-warns. */
+export function resetSyncPassphraseWarnings() {
+    deprecatedVarWarned = false;
+    envPassphraseWarned = false;
+}
+/**
+ * Read the transport passphrase from the environment, preferring the current
+ * variable and falling back to the deprecated one with a single warning.
+ * Returns `{ value: null }` when neither is set — the caller decides whether to
+ * prompt (TTY) or fail (headless). Never prompts, never throws.
+ */
+export function resolveSyncPassphraseFromEnv() {
+    const current = process.env[SYNC_PASSPHRASE_ENV];
+    if (current)
+        return { value: current, source: 'sync-env' };
+    const legacy = process.env[LEGACY_PASSPHRASE_ENV];
+    if (legacy) {
+        if (!deprecatedVarWarned) {
+            deprecatedVarWarned = true;
+            process.stderr.write(chalk.yellow(`warn: ${LEGACY_PASSPHRASE_ENV} is deprecated for sync — it is the file store's master key, ` +
+                `not a transport passphrase. Set ${SYNC_PASSPHRASE_ENV} instead; the old name still works ` +
+                'for now. Keeping the master key in the environment exposes the whole store to every ' +
+                'same-user process (RUSH-1968).\n'));
+        }
+        return { value: legacy, source: 'legacy-env' };
+    }
+    return { value: null, source: null };
+}
+/**
+ * The one-shot reminder that an env-sourced passphrase is readable by other
+ * same-user processes. Separate from the deprecation notice above so a caller
+ * using the CURRENT variable still gets the readability warning exactly once.
+ */
+export function warnEnvPassphraseReadableOnce() {
+    if (envPassphraseWarned)
+        return;
+    envPassphraseWarned = true;
+    process.stderr.write(chalk.yellow('warn: using a sync passphrase from the environment. Env vars are readable by other ' +
+        'same-user processes (/proc, ps, crash dumps, CI logs) — rotate after CI use.\n'));
+}
+/** The message a headless caller shows when no passphrase is available. */
+export function missingSyncPassphraseMessage() {
+    return `A sync passphrase is required. Run from a TTY, or set ${SYNC_PASSPHRASE_ENV}.`;
+}

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

package/dist/lib/session/db.js

@@ -26,7 +26,7 @@ const DB_PATH = getSessionsDbPath();
 /** 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 const SCHEMA_VERSION = 33;
+export 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
@@ -779,6 +779,37 @@ function migrateSchema(db, fromVersion) {
         db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_account_key ON sessions(account_key)`);
         backfillClaudeAccounts(db);
     }
+    if (fromVersion < 34) {
+        // v33 -> v34: claude-opus-5 and claude-sonnet-5 were missing from the pricing
+        // table. `getModelPricing` matches on a dash-bounded prefix, so neither could fall
+        // back to its Claude 4 entry: both resolved to null and every session using them
+        // priced to $0 -- silently, because an unpriced model contributes nothing rather
+        // than raising. On one real index that was 526 sessions, 478 of them the current
+        // default model.
+        //
+        // Adding the prices alone fixes nothing already indexed: cost_usd is computed at
+        // scan time, and the scanner skips any transcript whose (file_mtime_ms, file_size)
+        // is unchanged. Nor can those rows be repaired in place -- the row stores
+        // token_count and output_tokens, not the uncached-input / cache-read / cache-write
+        // split the price table needs -- so the figure has to come from re-reading the
+        // transcript.
+        //
+        // Flush ONLY the affected transcripts, not the whole ledger. A blanket
+        // `DELETE FROM scan_ledger` (what v5 -> v6 did when cost was introduced) would
+        // re-parse every session on the next scan and break the contract the other
+        // migrations here are tested against: adding a column must not invalidate warm
+        // session ledgers. Scoping it to the rows that actually mispriced keeps every
+        // other ledger entry warm and still guarantees the numbers correct themselves.
+        db.exec(`
+      DELETE FROM scan_ledger
+      WHERE file_path IN (
+        SELECT file_path FROM sessions
+        WHERE cost_usd IS NULL
+          AND file_path IS NOT NULL AND file_path <> ''
+          AND (model LIKE 'claude-opus-5%' OR model LIKE 'claude-sonnet-5%')
+      );
+    `);
+    }
 }
 /**
  * Stamp `account_key` / `account_org` / `account` on every Claude row from its