@phnx-labs/agents-cli 1.20.77 → 1.20.82

package/dist/lib/session/active.js

@@ -25,19 +25,33 @@ 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 { loadHookSessionIndex, resolveHookSessionRecord } from './hook-sessions.js';
-import { buildClaudeLabelMap } from './discover.js';
+import { readSessionActorRecord } from './actor-sidecar.js';
+import { loadHookSessionIndex, resolveHookSessionRecord, readStateSessionRecord } from './hook-sessions.js';
+import { buildClaudeLabelMap, getAgentSessionDirs } from './discover.js';
 import { buildRunNameMap } from './run-names.js';
 import { latestSessionFileForCwd } from './db.js';
 import { extractSessionTopic } from './prompt.js';
 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 { detectProvenance } from './provenance.js';
 import { loadDevices } from '../devices/registry.js';
 import { presenceFromStore } from './detached.js';
 import { mapBounded } from '../concurrency.js';
 const execFileAsync = promisify(execFile);
+/**
+ * The owner (actor id) to show for a session in `--active`. Prefers the actor
+ * recorded on the live-attribution source (the pid registry / teammate record),
+ * but falls back to the durable per-session actor sidecar — written at spawn and,
+ * unlike the pid entry, NOT overwritten by the SessionStart hook's own by-pid
+ * write. Without this fallback a real `agents run` shows no owner whenever the
+ * hook's actor-less entry wins the by-pid file (RUSH-2018 fix).
+ */
+export function resolveOwner(pidActor, sessionId) {
+    return pidActor ?? (sessionId ? readSessionActorRecord(sessionId)?.actor : undefined) ?? undefined;
+}
 /**
  * Per-PID `lsof` probes run bounded and staggered rather than as one parallel
  * fan-out: a simultaneous system-wide `lsof` burst reads to behavioral EDR
@@ -67,7 +81,6 @@ export function activeStatusFromCloudStatus(status) {
             return 'queued';
     }
 }
-const HOME = os.homedir();
 const LIVE_TERMINALS_FILE = path.join(getTerminalsDir(), 'live-terminals.json');
 /**
  * A process is classified `running` if its session file was touched in the
@@ -83,6 +96,16 @@ const ACTIVE_MTIME_WINDOW_MS = 2 * 60_000;
  * transcript just because a GUI app service with the same basename is alive.
  */
 export const ACTIVE_SESSION_STALE_MS = 24 * 60 * 60_000;
+/**
+ * A session whose transcript hasn't been written in this long is ABANDONED /
+ * dangling — the framework can no longer treat it as live work, whether its PID
+ * is dead (long gone) or still alive but making no progress (a hung agent).
+ * Two days: past a normal work gap, well short of a session legitimately kept
+ * open across a long weekend. Deliberately far wider than
+ * {@link ACTIVE_SESSION_STALE_MS} (which bounds transcript-borrowing, a different
+ * concern) — this is the lifecycle threshold, not the freshness window.
+ */
+export const ABANDONED_STALE_MS = 2 * 24 * 60 * 60_000;
 /** Executables we recognize as agent CLIs when scanning the process table. */
 const AGENT_CLI_NAMES = {
     claude: 'claude',
@@ -217,9 +240,45 @@ function claudeProjectDirName(cwd) {
  * Locate the active Claude session file for a process. If we know the session
  * UUID (from terminal env or team parent), prefer the exact match. Otherwise
  * fall back to the most-recent-mtime .jsonl in the project's folder.
+ *
+ * Searches EVERY version-home project root, not just the live `~/.claude`
+ * symlink. `~/.claude` points at the currently-installed agent version; a
+ * session launched under an EARLIER version keeps its transcript under that
+ * version's home (`…/.history/versions/claude/<ver>/home/.claude/projects/`).
+ * Resolving only `~/.claude/projects` meant that the instant a newer version
+ * was installed, every still-running older-version session lost its transcript
+ * here — no `sessionFile`, so no start/activity time, so `agents sessions`
+ * rendered it `unknown` and the watchdog skipped it as "no activity timestamp".
+ * `getAgentSessionDirs('claude','projects')` is the same version-aware enumerator
+ * the rest of the CLI uses, so this stays in lockstep with discovery.
  */
 function findClaudeSessionFile(cwd, sessionId) {
-    return pickSessionFile(path.join(HOME, '.claude', 'projects', claudeProjectDirName(cwd)), sessionId);
+    return pickClaudeSessionFileAcrossRoots(getAgentSessionDirs('claude', 'projects'), cwd, sessionId);
+}
+/**
+ * Resolve a Claude transcript for `cwd` across the given project roots, newest
+ * mtime winning when the same id/cwd resolves in more than one version home
+ * (the actively-written copy is the newest). Pure over `projectRoots`, so it is
+ * testable against temp dirs without touching the real home directory.
+ */
+export function pickClaudeSessionFileAcrossRoots(projectRoots, cwd, sessionId) {
+    const enc = claudeProjectDirName(cwd);
+    let best;
+    for (const root of projectRoots) {
+        const hit = pickSessionFile(path.join(root, enc), sessionId);
+        if (!hit)
+            continue;
+        let mtime;
+        try {
+            mtime = fs.statSync(hit).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (!best || mtime > best.mtime)
+            best = { path: hit, mtime };
+    }
+    return best?.path;
 }
 /**
  * Pick a Claude transcript file within a project dir.
@@ -274,46 +333,68 @@ export function sessionFileTimes(sessionFile) {
         return {};
     }
 }
+/**
+ * The lifecycle status computed purely from the two hard signals the framework
+ * always has — PID liveness and transcript last-write (mtime) — independent of
+ * anything the agent self-reports or what its last transcript turn happened to
+ * look like. Returns the definitive lifecycle label when one applies, or
+ * `undefined` when the process is live and fresh (so the caller uses the richer
+ * activity-derived status instead).
+ *
+ *   - No write in {@link ABANDONED_STALE_MS} ⇒ `abandoned` (dangling): a
+ *     days-stale session is not live work, whether its PID is dead (long gone)
+ *     or still alive but stuck. Checked first — it outranks a bare `closed`.
+ *   - Otherwise, PID dead ⇒ `closed`: the process has exited. This is the fix
+ *     for the old "dead PID reports idle" lie — `idle` reads as "done, waiting
+ *     for you", but a dead process is done, period.
+ *   - Otherwise (alive + fresh) ⇒ `undefined`: defer to the activity engine.
+ */
+export function lifecycleStatus(pidAlive, mtimeMs, nowMs = Date.now()) {
+    if (mtimeMs !== undefined && nowMs - mtimeMs >= ABANDONED_STALE_MS)
+        return 'abandoned';
+    if (!pidAlive)
+        return 'closed';
+    return undefined;
+}
 /**
  * The ONE place a fallback status is decided when no rich transcript state is
- * available — a non-Claude/Codex kind we cannot parse, or a Claude/Codex tail
- * that was empty or unreadable. Honest by construction: it never asserts a status
- * it cannot justify from a measured signal.
+ * available — an opaque kind we cannot parse (cursor, openclaw), or a transcript
+ * whose parse/tail was empty or unreadable. Honest by construction: computed from
+ * PID + mtime, never a fabricated `idle`.
  *
- *   - Resolvable transcript, readable mtime → the MEASURED freshness signal:
- *     written within ACTIVE_MTIME_WINDOW_MS ⇒ `running`, else `idle`.
- *   - Resolvable transcript whose `stat` throws (file vanished / permission) → we
- *     genuinely cannot tell ⇒ `unknown`. (This branch previously returned
- *     `running`, which contradicted the `idle` default one branch up.)
- *   - No resolvable transcript but the process is alive → alive-but-opaque ⇒
- *     `unknown`. This is the truthful answer for a live gemini / droid / cursor /
- *     opencode whose format we don't parse — NOT a fabricated `idle` (which the
- *     UI reads as "done and waiting"), and it never lies as `running` either.
- *   - No transcript and the process is not known alive → nothing to report ⇒ `idle`.
+ *   - Dead PID, or a days-stale transcript ⇒ {@link lifecycleStatus} (`closed` /
+ *     `abandoned`). A dead process is `closed`, not the old fabricated `idle`
+ *     (which the UI reads as "done, waiting for you"); a dead process whose file
+ *     also vanished is still `closed` (death is a definitive answer, not `unknown`).
+ *   - Live + fresh ⇒ `running`. A live process is, at minimum, running: we may
+ *     not see WHAT an opaque harness (or an empty tail) is doing, but the process
+ *     being alive is a positive signal — never a blank `unknown` (the old blanket
+ *     bug for every non-claude/codex live agent) nor a downgraded `idle`.
  */
-export function resolveFallbackStatus(sessionFile, pidAlive) {
-    if (!sessionFile)
-        return pidAlive ? 'unknown' : 'idle';
-    try {
-        const mtimeMs = fs.statSync(sessionFile).mtimeMs;
-        return Date.now() - mtimeMs < ACTIVE_MTIME_WINDOW_MS ? 'running' : 'idle';
-    }
-    catch {
-        return 'unknown';
-    }
+export function resolveFallbackStatus(sessionFile, pidAlive, nowMs = Date.now()) {
+    const { mtimeMs } = sessionFileTimes(sessionFile);
+    return lifecycleStatus(pidAlive, mtimeMs, nowMs) ?? 'running';
 }
 /**
- * Locate the live transcript for an agent process. Claude files are keyed by
- * cwd (+ optional session uuid); Codex files are date-partitioned, so we resolve
- * the newest indexed Codex session for the cwd instead.
+ * Locate the live transcript for an agent process. Claude files are keyed by cwd
+ * (+ optional session uuid), so they resolve straight off disk. Every OTHER
+ * tracked harness — Codex (date-partitioned), plus grok / droid / rush / gemini /
+ * kimi / hermes / opencode / antigravity (per-session dirs, SQLite, single-JSON)
+ * — is resolved through the session index by cwd: the newest indexed transcript
+ * for that cwd, bounded by ACTIVE_SESSION_STALE_MS so a live pid never borrows a
+ * weeks-old transcript. This is what lets a live NON-claude/codex agent get a real
+ * status instead of falling through to `unknown` (the file feeds
+ * {@link computeLiveSignals}). An opaque kind we don't track (cursor) still yields
+ * undefined here and degrades honestly to a live `running`.
  */
 export function findSessionFileForKind(kind, cwd, sessionId) {
     if (!cwd)
         return undefined;
     if (kind === 'claude')
         return findClaudeSessionFile(cwd, sessionId);
-    if (kind === 'codex')
-        return latestSessionFileForCwd('codex', cwd, { maxAgeMs: ACTIVE_SESSION_STALE_MS });
+    if (isSessionTrackedAgent(kind)) {
+        return latestSessionFileForCwd(kind, cwd, { maxAgeMs: ACTIVE_SESSION_STALE_MS });
+    }
     return undefined;
 }
 /** Recover the session UUID from a transcript filename (Claude `<uuid>.jsonl`, Codex `rollout-…-<uuid>.jsonl`). */
@@ -323,28 +404,64 @@ function sessionIdFromFile(file) {
         return undefined;
     return path.basename(file).match(UUID_RE)?.[0];
 }
+/** Cap the events fed to state inference for a non-tailable harness — the last
+ * turns are all `inferActivity` needs, and a bound keeps a huge transcript cheap. */
+const LIVE_STATE_MAX_EVENTS = 80;
 /**
- * Read a session file's tail ONCE and derive both the inferred state and the
- * output-token throughput from it. State needs the normalized event model;
- * throughput needs the raw lines the event model drops (Codex `token_count`), so
- * both come off the same {@link readSessionTailWithRaw} read. Only Claude/Codex
- * carry live state; other kinds yield an empty signal set.
+ * Parse a NON-claude/codex transcript with that harness's own parser and return
+ * its last events for state inference. These formats vary too much for the
+ * single-file byte-tail fast path (per-session dirs for grok/kimi, SQLite for
+ * opencode/antigravity, single-JSON for gemini/hermes), so parse the whole
+ * (size-guarded, via safeReadSessionFile) transcript and keep the tail. A parse
+ * failure yields no events, degrading honestly to the live fallback.
  */
-function computeLiveSignals(kind, sessionFile, cwd, pidAlive) {
+function parseTailEventsForKind(agent, sessionFile) {
+    let events;
+    try {
+        events = parseSession(sessionFile, agent);
+    }
+    catch {
+        return [];
+    }
+    return events.length > LIVE_STATE_MAX_EVENTS ? events.slice(-LIVE_STATE_MAX_EVENTS) : events;
+}
+/**
+ * Derive the inferred state (working / waiting / idle + preview/badges) and, for
+ * the two harnesses whose raw lines carry it, the output-token throughput.
+ *
+ * Claude/Codex take the fast bounded byte-tail ({@link readSessionTailWithRaw}) —
+ * the hot path, and the only two that also yield throughput (their raw lines
+ * carry usage the event model drops). EVERY OTHER tracked harness (grok, droid,
+ * rush, gemini, kimi, hermes, opencode, antigravity) is parsed with its own
+ * parser and run through the SAME {@link inferSessionState}, so a live
+ * non-claude/codex agent gets a real working/waiting/idle instead of the blanket
+ * `unknown` it used to fall through to. An opaque/untracked kind (cursor) or an
+ * unreadable/empty transcript yields an empty signal set, and the caller's
+ * {@link resolveFallbackStatus} reports the honest live floor (`running`).
+ */
+export function computeLiveSignals(kind, sessionFile, cwd, pidAlive) {
     if (!sessionFile)
         return {};
-    const agent = kind === 'codex' ? 'codex' : 'claude';
-    const { events, content } = readSessionTailWithRaw(sessionFile, agent);
-    if (events.length === 0)
-        return {};
     let mtimeMs;
     try {
         mtimeMs = fs.statSync(sessionFile).mtimeMs;
     }
     catch { /* vanished between calls */ }
-    const state = inferSessionState(events, { cwd, pidAlive, mtimeMs, activeWindowMs: ACTIVE_MTIME_WINDOW_MS });
-    const tokPerSec = computeTokPerSec(content, agent);
-    return { state, tokPerSec: tokPerSec > 0 ? tokPerSec : undefined };
+    const ctx = { cwd, pidAlive, mtimeMs, activeWindowMs: ACTIVE_MTIME_WINDOW_MS };
+    if (kind === 'claude' || kind === 'codex') {
+        const { events, content } = readSessionTailWithRaw(sessionFile, kind);
+        if (events.length === 0)
+            return {};
+        const state = inferSessionState(events, ctx);
+        const tokPerSec = computeTokPerSec(content, kind);
+        return { state, tokPerSec: tokPerSec > 0 ? tokPerSec : undefined };
+    }
+    if (!isSessionTrackedAgent(kind))
+        return {};
+    const events = parseTailEventsForKind(kind, sessionFile);
+    if (events.length === 0)
+        return {};
+    return { state: inferSessionState(events, ctx) };
 }
 /** Map inferred activity onto the coarse ActiveStatus used by the renderer and counts. */
 function statusFromActivity(activity) {
@@ -352,17 +469,23 @@ function statusFromActivity(activity) {
 }
 /**
  * Fold a computed SessionState onto an active-session row: rich status +
- * preview + PR/worktree/ticket badges. With no state (unreadable/non-Claude/
- * Codex file) it degrades to {@link resolveFallbackStatus}, which needs
- * `pidAlive` to tell an alive-but-opaque process (`unknown`) from a dead one
- * (`idle`).
+ * preview + PR/worktree/ticket badges. With no state (an opaque/untracked kind,
+ * or an unreadable/empty transcript) it degrades to
+ * {@link resolveFallbackStatus}, which reports the honest live floor (`running`
+ * for an alive process) rather than the old blanket `unknown`.
  */
 function applyState(base, state, fallbackFile, pidAlive) {
     if (!state)
         return { ...base, status: resolveFallbackStatus(fallbackFile, pidAlive) };
+    // Lifecycle (closed/abandoned) is computed from PID + mtime and OVERRIDES the
+    // activity-derived status: a dead or days-stale process is closed/abandoned no
+    // matter what its last parsed transcript turn looked like (a dead session whose
+    // tail ended mid-tool-call must not read as `running`). `base.lastActivityMs` is
+    // the transcript mtime the row already resolved — reuse it, no extra stat.
+    const life = lifecycleStatus(pidAlive, base.lastActivityMs ?? sessionFileTimes(fallbackFile).mtimeMs);
     return {
         ...base,
-        status: statusFromActivity(state.activity),
+        status: life ?? statusFromActivity(state.activity),
         activity: state.activity,
         awaitingReason: state.awaitingReason,
         question: state.question,
@@ -477,6 +600,10 @@ export async function listTeamsActive() {
             lastActivityMs: sessionFileTimes(sessionFile).mtimeMs,
             teamName: a.taskName,
             agentId: a.agentId,
+            // The frozen actor stamped on the teammate record (RUSH-2028) — who ran
+            // this teammate, surfaced as the owner in --active (RUSH-2018); sidecar
+            // fallback for a teammate record predating the actor field.
+            owner: resolveOwner(a.actor, sessionId ?? sessionIdFromFile(sessionFile)),
         }, state, sessionFile, pidAlive);
     });
 }
@@ -505,7 +632,8 @@ export async function listTerminalsActive() {
         // back to the stale cached id — the duplicate-card fix comes from
         // pickSessionFile no longer borrowing a sibling, not from this lookup. Kept as
         // a forward-looking hook for the cases where the pid does line up.
-        const resolvedId = readPidSessionEntry(t.pid)?.sessionId ?? t.sessionId;
+        const pidEntry = readPidSessionEntry(t.pid);
+        const resolvedId = pidEntry?.sessionId ?? t.sessionId;
         const sessionFile = findSessionFileForKind(t.kind, t.cwd ?? undefined, resolvedId);
         // Prefer label from live terminal, fall back to Claude's session label
         const label = t.label ?? (t.sessionId ? labelMap.get(t.sessionId) : undefined) ?? undefined;
@@ -531,6 +659,7 @@ export async function listTerminalsActive() {
             startedAtMs: t.startedAtMs,
             lastActivityMs: sessionFileTimes(sessionFile).mtimeMs,
             windowId: t.windowId,
+            owner: resolveOwner(pidEntry?.actor, resolvedId),
         }, state, sessionFile, pidAlive);
     });
 }
@@ -932,7 +1061,7 @@ export async function listUnattributedActive(attributed) {
         const context = host && UI_HOSTS.has(host) ? 'terminal' : 'headless';
         // pidAlive is true by construction: this pid was just enumerated from the
         // live process table, so an opaque (non-parseable) kind resolves to
-        // `unknown`, not a fake `idle`.
+        // `running`, not a fake `idle` or blanket `unknown`.
         const { state, tokPerSec } = computeLiveSignals(kind, sessionFile, cwd, true);
         const { birthtimeMs, mtimeMs } = sessionFileTimes(sessionFile);
         // Durable run name from `agents run --name`, resolved by the run's session id
@@ -961,6 +1090,7 @@ export async function listUnattributedActive(attributed) {
             startedAtMs: hookRec?.ts ?? birthtimeMs,
             lastActivityMs: mtimeMs,
             pidCount: 1 + (foldedByRoot.get(pid) ?? 0),
+            owner: resolveOwner(entry?.actor, resolvedId),
         }, state, sessionFile, true));
     }
     // Housekeeping: drop registry files for pids that have since died.
@@ -1063,9 +1193,24 @@ export async function listTmuxAgentSessions() {
             continue;
         const meta = readSessionMeta(sessName);
         const liveEntry = liveByPane.get(pane);
-        const id = resolvePaneIdentity(pane, meta, liveEntry, getHookIndex);
+        let id = resolvePaneIdentity(pane, meta, liveEntry, getHookIndex);
         if (!id)
             continue;
+        // RUSH-2007 Layer A: a non-Claude tmux session whose id resolved via neither the
+        // launch registry (no id minted at spawn) nor the session-tracker index (not
+        // deployed on the fleet — its dir is empty) — backfill it from the DEPLOYED
+        // hook's own per-pid record at state/sessions/<pid>.json. Targeted single-file
+        // reads on the pane leaf pid, then the registry launch pid; freshness-guarded by
+        // the launch's known start so a reused-pid graveyard file can't cross sessions.
+        // Without this the session surfaces id-less (keyed on the bare pane) and is
+        // invisible to `agents sessions focus` — the remaining RUSH-2007 discovery gap.
+        if (!id.sessionId) {
+            const panePid = parseInt(pidRaw, 10) || undefined;
+            const backfilled = (panePid ? readStateSessionRecord(panePid, liveEntry?.startedAtMs)?.session_id : undefined)
+                ?? (liveEntry ? readStateSessionRecord(liveEntry.pid, liveEntry.startedAtMs)?.session_id : undefined);
+            if (backfilled)
+                id = { ...id, sessionId: backfilled };
+        }
         // 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;
@@ -1108,6 +1253,7 @@ export async function listTmuxAgentSessions() {
             startedAtMs: birthtimeMs,
             lastActivityMs: mtimeMs,
             provenance,
+            owner: resolveOwner(liveEntry?.actor, id.sessionId ?? sessionIdFromFile(sessionFile)),
         }, state, sessionFile, pidAlive));
     }
     return out;

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

@@ -0,0 +1,23 @@
+export interface SessionActorRecord {
+    sessionId: string;
+    /** Resolved actor id (`resolveActor().id`) — the responsible human/agent. */
+    actor: string;
+    /** Actor kind (`resolveActor().kind`). */
+    initiatedBy: 'human' | 'agent';
+    startedAtMs: number;
+}
+/**
+ * Record the actor a session was launched under. Never throws — the sidecar is
+ * an attribution optimization; a session with no record simply scans unattributed.
+ * No-ops without a concrete session id (nothing to key on).
+ */
+export declare function writeSessionActorRecord(record: SessionActorRecord): void;
+/** Read one session's actor record. Returns undefined if absent/corrupt. */
+export declare function readSessionActorRecord(sessionId: string): SessionActorRecord | undefined;
+/**
+ * Load every session actor record into a `sessionId -> record` map, for the scan
+ * path to join a whole batch of sessions in one directory read instead of a
+ * stat-per-row. Best-effort: unreadable/corrupt files are skipped, a missing dir
+ * yields an empty map.
+ */
+export declare function loadSessionActorIndex(): Map<string, SessionActorRecord>;

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

@@ -0,0 +1,101 @@
+/**
+ * Durable sessionId -> actor sidecar (RUSH-2019, P3 lineage).
+ *
+ * The actor behind a run is resolved at spawn (`resolveActor()`), but the session
+ * transcript on disk carries no record of it — so the scanner that indexes those
+ * transcripts into `sessions.db` (`discover.ts` -> `upsertSessionsBatch`) has
+ * nothing to attribute a session to a person with. The pid-registry answers this
+ * for LIVE processes (`--active` owner, RUSH-2018), but it lives under `.cache`
+ * and is pruned when the pid dies, so it can't back a DURABLE, historical listing.
+ *
+ * This module writes one small, durable record per launched session — keyed by
+ * session id, under `~/.agents/.history` (never pruned) — that the scanner joins
+ * on to fill the write-once `actor` / `initiated_by` columns. Best-effort
+ * throughout: a failed write or a corrupt file degrades to an unattributed row,
+ * never throws into the launch or the scan path.
+ */
+import fs from 'fs';
+import path from 'path';
+import { getHistoryDir } from '../state.js';
+function sidecarDir() {
+    return path.join(getHistoryDir(), 'by-session');
+}
+/**
+ * A session id safe to use as a filename: no path separators or `..`, so a
+ * caller-supplied `--session-id` can never escape `by-session/` via
+ * `path.join`. Session ids are uuids in practice; anything else is rejected
+ * rather than sanitized, so a bad id degrades to no record, never a write
+ * outside the directory.
+ */
+function isSafeSessionId(sessionId) {
+    return sessionId.length > 0 && !/[/\\]/.test(sessionId) && sessionId !== '.' && sessionId !== '..';
+}
+function recordPath(sessionId) {
+    return path.join(sidecarDir(), `${sessionId}.json`);
+}
+/**
+ * Record the actor a session was launched under. Never throws — the sidecar is
+ * an attribution optimization; a session with no record simply scans unattributed.
+ * No-ops without a concrete session id (nothing to key on).
+ */
+export function writeSessionActorRecord(record) {
+    if (!isSafeSessionId(record.sessionId))
+        return;
+    try {
+        fs.mkdirSync(sidecarDir(), { recursive: true });
+        fs.writeFileSync(recordPath(record.sessionId), JSON.stringify(record), 'utf8');
+    }
+    catch {
+        /* degrade to an unattributed row */
+    }
+}
+/** Read one session's actor record. Returns undefined if absent/corrupt. */
+export function readSessionActorRecord(sessionId) {
+    if (!isSafeSessionId(sessionId))
+        return undefined;
+    let raw;
+    try {
+        raw = fs.readFileSync(recordPath(sessionId), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && typeof parsed.sessionId === 'string' && typeof parsed.actor === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        /* unparseable */
+    }
+    return undefined;
+}
+/**
+ * Load every session actor record into a `sessionId -> record` map, for the scan
+ * path to join a whole batch of sessions in one directory read instead of a
+ * stat-per-row. Best-effort: unreadable/corrupt files are skipped, a missing dir
+ * yields an empty map.
+ */
+export function loadSessionActorIndex() {
+    const out = new Map();
+    let files;
+    try {
+        files = fs.readdirSync(sidecarDir()).filter(f => f.endsWith('.json'));
+    }
+    catch {
+        return out;
+    }
+    for (const f of files) {
+        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') {
+                out.set(parsed.sessionId, parsed);
+            }
+        }
+        catch {
+            /* raced with a writer, or corrupt — skip */
+        }
+    }
+    return out;
+}

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

@@ -2,7 +2,7 @@
  * SQLite-backed session index and full-text search.
  *
  * Stores session metadata and user-prompt text in a WAL-mode SQLite database
- * at ~/.agents/sessions/sessions.db. Provides incremental upsert, scan-stamp
+ * at ~/.agents/.history/sessions/sessions.db. Provides incremental upsert, scan-stamp
  * ledger (mtime/size tracking to skip unchanged files), FTS5 search with
  * BM25 ranking, and label-first search for /rename'd sessions.
  */
@@ -30,6 +30,7 @@ export interface SessionRow {
     output_tokens: number | null;
     cost_usd: number | null;
     duration_ms: number | null;
+    model: string | null;
     file_path: string;
     file_mtime_ms: number | null;
     file_size: number | null;
@@ -40,10 +41,13 @@ export interface SessionRow {
     worktree_slug: string | null;
     ticket_id: string | null;
     plan: string | null;
+    machine: string | null;
     todos: string | null;
     recent_directories_touched: string | null;
     linear_project: string | null;
     linear_project_url: string | null;
+    actor: string | null;
+    initiated_by: string | null;
 }
 /** File stat snapshot used to detect changes between scan runs. */
 export interface ScanStamp {
@@ -248,6 +252,42 @@ export interface UsageRollupRow {
 }
 /** What to group a usage rollup by. */
 export type UsageRollupGroup = 'agent' | 'project' | 'day';
+/**
+ * Smart-launch affinity priors: group sessions by origin machine, harness, or
+ * joint (machine + agent). Ordered by launch count desc.
+ *
+ * SQL shape (device example):
+ *   SELECT machine, COUNT(*) launches, SUM(duration_ms), SUM(token_count)
+ *   FROM sessions
+ *   WHERE timestamp >= ? AND origin = 'cli' AND is_team_origin = 0
+ *   GROUP BY machine ORDER BY launches DESC
+ *
+ * Account rotation is NOT done here — that stays on live rate-limit windows
+ * via `--strategy balanced` / rotate.ts.
+ */
+export type AffinityGroup = 'machine' | 'agent' | 'machine_agent';
+export interface AffinityRow {
+    /** Group key: machine name, agent id, or "machine\\tagent". */
+    key: string;
+    machine?: string;
+    agent?: string;
+    launches: number;
+    durationMs: number;
+    tokenCount: number;
+    costUsd: number;
+}
+export declare function queryAffinityRollup(options: {
+    groupBy: AffinityGroup;
+    /** ISO cutoff or ms; defaults to 14 days ago when omitted. */
+    sinceMs?: number;
+    /** Restrict to these harnesses (e.g. claude/codex/kimi). */
+    agents?: SessionAgentId[];
+    /** Default true: only origin=cli rows. */
+    onlyCli?: boolean;
+    /** Default true: drop team-spawned sessions. */
+    excludeTeamOrigin?: boolean;
+    project?: string;
+}): AffinityRow[];
 /**
  * Aggregate cost / duration / tokens across sessions, grouped by agent,
  * project, or calendar day. Honors the same filter shape as querySessions