@phnx-labs/agents-cli 1.15.0 → 1.17.0

package/dist/lib/session/active.js

@@ -2,7 +2,7 @@
  * Active-session detection across every context an agent can run in:
  *
  *   - `terminal` — agents launched from VS Code / Cursor / Codium via the
- *     agents-cli extension. Published to `~/.agents/runtime/live-terminals.json`
+ *     agents-cli extension. Published to `~/.agents/.cache/terminals/live-terminals.json`
  *     with PID + session UUID per entry.
  *   - `teams`    — agents spawned by `agents teams add`, tracked in
  *     `~/.agents/teams/agents/<id>/meta.json` with a PID the manager polls.
@@ -23,10 +23,12 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { listActiveTasks } from '../cloud/store.js';
 import { AgentManager } from '../teams/agents.js';
-import { getUserAgentsDir } from '../state.js';
+import { getTerminalsDir } from '../state.js';
+import { buildClaudeLabelMap } from './discover.js';
+import { extractSessionTopic } from './prompt.js';
 const execFileAsync = promisify(execFile);
 const HOME = os.homedir();
-const LIVE_TERMINALS_FILE = path.join(getUserAgentsDir(), 'runtime', 'live-terminals.json');
+const LIVE_TERMINALS_FILE = path.join(getTerminalsDir(), 'live-terminals.json');
 /**
  * A process is classified `running` if its session file was touched in the
  * last 2 minutes. Every Claude/Codex tool-call appends an event, so a
@@ -80,9 +82,9 @@ function readLiveTerminals() {
     }
     return Array.from(merged.values());
 }
-/** Convert an absolute cwd to the Claude-project folder name (slashes → dashes). */
+/** Convert an absolute cwd to the Claude-project folder name (slashes and dots → dashes). */
 function claudeProjectDirName(cwd) {
-    return cwd.replace(/\//g, '-');
+    return cwd.replace(/[/.]/g, '-');
 }
 /**
  * Locate the active Claude session file for a process. If we know the session
@@ -126,6 +128,79 @@ function classifyActivity(sessionFile) {
         return 'running';
     }
 }
+/**
+ * Extract the first user message's content from a Claude JSONL file.
+ * Reads only the first ~50 lines for speed, since the user message is
+ * typically near the top (after system/queue events).
+ */
+function extractClaudeUserText(parsed) {
+    const msg = parsed.message;
+    if (!msg?.content)
+        return undefined;
+    const content = Array.isArray(msg.content) ? msg.content : [msg.content];
+    const texts = [];
+    for (const block of content) {
+        if (typeof block === 'string')
+            texts.push(block);
+        else if (block?.type === 'text' && typeof block.text === 'string')
+            texts.push(block.text);
+    }
+    return texts.join('\n').trim() || undefined;
+}
+function quickExtractTopic(sessionFile) {
+    let fd;
+    try {
+        fd = fs.openSync(sessionFile, 'r');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const chunkSize = 256 * 1024;
+        const maxBytes = 2 * 1024 * 1024;
+        let buffer = '';
+        let totalRead = 0;
+        let linesChecked = 0;
+        const maxLines = 30;
+        while (totalRead < maxBytes && linesChecked < maxLines) {
+            const chunk = Buffer.alloc(chunkSize);
+            const bytesRead = fs.readSync(fd, chunk, 0, chunkSize, totalRead);
+            if (bytesRead === 0)
+                break;
+            totalRead += bytesRead;
+            buffer += chunk.toString('utf8', 0, bytesRead);
+            let lineStart = 0;
+            let lineEnd;
+            while ((lineEnd = buffer.indexOf('\n', lineStart)) !== -1 && linesChecked < maxLines) {
+                const line = buffer.slice(lineStart, lineEnd);
+                lineStart = lineEnd + 1;
+                linesChecked++;
+                if (!line.trim())
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (parsed.type === 'user') {
+                    const text = extractClaudeUserText(parsed);
+                    if (text) {
+                        const topic = extractSessionTopic(text);
+                        if (topic)
+                            return topic;
+                    }
+                }
+            }
+            buffer = buffer.slice(lineStart);
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return undefined;
+}
 /** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
 export async function listTeamsActive() {
     const mgr = new AgentManager();
@@ -135,6 +210,7 @@ export async function listTeamsActive() {
         const sessionFile = a.agentType === 'claude' && a.cwd
             ? findClaudeSessionFile(a.cwd, sessionId ?? undefined)
             : undefined;
+        const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
         return {
             context: 'teams',
             kind: a.agentType,
@@ -142,6 +218,7 @@ export async function listTeamsActive() {
             sessionId,
             cwd: a.cwd ?? undefined,
             label: a.name ?? undefined,
+            topic,
             sessionFile,
             startedAtMs: a.startedAt.getTime(),
             status: classifyActivity(sessionFile),
@@ -160,10 +237,16 @@ export async function listTerminalsActive() {
     const procByPid = new Map();
     for (const r of await readProcessTable())
         procByPid.set(r.pid, r);
+    // Build label map from Claude's sessions/*.json for /rename support
+    const labelMap = buildClaudeLabelMap();
     return entries.map((t) => {
         const sessionFile = t.kind === 'claude' && t.cwd
             ? findClaudeSessionFile(t.cwd, t.sessionId)
             : undefined;
+        // Prefer label from live terminal, fall back to Claude's session label
+        const label = t.label ?? (t.sessionId ? labelMap.get(t.sessionId) : undefined) ?? undefined;
+        // Extract topic from session file (first meaningful user message)
+        const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
         return {
             context: 'terminal',
             kind: t.kind,
@@ -171,7 +254,8 @@ export async function listTerminalsActive() {
             pid: t.pid,
             sessionId: t.sessionId,
             cwd: t.cwd ?? undefined,
-            label: t.label ?? undefined,
+            label,
+            topic,
             sessionFile,
             startedAtMs: t.startedAtMs,
             status: classifyActivity(sessionFile),
@@ -355,6 +439,7 @@ export async function listUnattributedActive(attributed) {
         const { pid, kind } = candidates[i];
         const cwd = cwds[i];
         const sessionFile = kind === 'claude' && cwd ? findClaudeSessionFile(cwd) : undefined;
+        const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
         const host = detectHost(pid, procByPid);
         const context = host && UI_HOSTS.has(host) ? 'terminal' : 'headless';
         out.push({
@@ -363,6 +448,7 @@ export async function listUnattributedActive(attributed) {
             host,
             pid,
             cwd,
+            topic,
             sessionFile,
             status: classifyActivity(sessionFile),
         });

package/dist/lib/session/cloud.js

@@ -13,10 +13,10 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
-import { getAgentsDir } from '../state.js';
+import { getCacheDir } from '../state.js';
 const PROXY_BASE = process.env.RUSH_PROXY_BASE ?? 'https://api.prix.dev';
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
-const CLOUD_CACHE_DIR = path.join(getAgentsDir(), 'cache', 'cloud-runs');
+const CLOUD_CACHE_DIR = path.join(getCacheDir(), 'cloud-runs');
 function readToken() {
     if (!fs.existsSync(USER_YAML)) {
         throw new Error('Not logged in to Rush. Run `rush login` first.');

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

@@ -55,6 +55,24 @@ export interface QueryOptions {
 export declare function getDB(): Database.Database;
 /** Close the cached database connection. */
 export declare function closeDB(): void;
+/**
+ * Try to claim the right to run the incremental scan. Returns true if this
+ * process should proceed with scanning, false if another live process is
+ * already scanning (caller should skip the scan and serve from the DB).
+ *
+ * Uses the `meta` table so it survives crashes — dead PIDs are detected via
+ * process.kill(pid, 0), stale entries via TTL. No external lock files needed.
+ *
+ * Wrapped in db.transaction() (BEGIN IMMEDIATE) so the read-then-write is
+ * atomic and busy_timeout retries correctly — bare auto-commit DML in WAL
+ * mode can return SQLITE_BUSY_SNAPSHOT which bypasses the busy handler.
+ */
+export declare function tryClaimScan(pid: number): boolean;
+/**
+ * Release the scan claim written by tryClaimScan. Only deletes the entry
+ * if it still belongs to this process (guards against TTL takeovers).
+ */
+export declare function releaseScan(pid: number): void;
 /** Return the absolute path to the sessions database file. */
 export declare function getDBPath(): string;
 /**

package/dist/lib/session/db.js

@@ -9,9 +9,9 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import Database from '../sqlite.js';
-import { getUserAgentsDir } from '../state.js';
-const SESSIONS_DIR = path.join(getUserAgentsDir(), 'sessions');
-const DB_PATH = path.join(SESSIONS_DIR, 'sessions.db');
+import { getSessionsDir, getSessionsDbPath } from '../state.js';
+const SESSIONS_DIR = getSessionsDir();
+const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. */
 const SCHEMA_VERSION = 5;
 /**
@@ -151,11 +151,17 @@ export function getDB() {
     db.pragma('journal_mode = WAL');
     db.pragma('synchronous = NORMAL');
     db.pragma('temp_store = MEMORY');
+    // Wait up to 30s instead of failing immediately on SQLITE_BUSY. Multiple
+    // agents (CLIs, skills, hooks) open this DB concurrently. The first scan of
+    // a new version home can take longer than 10s; concurrent callers need enough
+    // headroom to wait. The ledger-recheck in upsertSessionsBatch makes
+    // subsequent writers near-instant, so 30s is a rarely-reached safety net.
+    db.pragma('busy_timeout = 30000');
     db.exec(SCHEMA);
     const current = db.prepare(`SELECT value FROM meta WHERE key = 'schema_version'`).get();
     const currentVersion = current ? parseInt(current.value, 10) : 0;
     if (!current) {
-        db.prepare(`INSERT INTO meta(key, value) VALUES ('schema_version', ?)`).run(String(SCHEMA_VERSION));
+        db.prepare(`INSERT OR IGNORE INTO meta(key, value) VALUES ('schema_version', ?)`).run(String(SCHEMA_VERSION));
     }
     else if (currentVersion < SCHEMA_VERSION) {
         migrateSchema(db, currentVersion);
@@ -176,7 +182,7 @@ export function getDB() {
             }
             catch { /* ignore */ }
         }
-        db.prepare(`INSERT INTO meta(key, value) VALUES ('legacy_indexes_removed', '1')`).run();
+        db.prepare(`INSERT OR IGNORE INTO meta(key, value) VALUES ('legacy_indexes_removed', '1')`).run();
     }
     dbInstance = db;
     return db;
@@ -188,6 +194,75 @@ export function closeDB() {
         dbInstance = null;
     }
 }
+// ---------------------------------------------------------------------------
+// Scan coordinator — prevents concurrent full scans across processes
+// ---------------------------------------------------------------------------
+/** How long a scan claim is trusted before it's considered stale (ms). */
+const SCAN_CLAIM_TTL_MS = 120_000; // 2 minutes
+function isProcessAlive(pid) {
+    if (!pid || isNaN(pid))
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Try to claim the right to run the incremental scan. Returns true if this
+ * process should proceed with scanning, false if another live process is
+ * already scanning (caller should skip the scan and serve from the DB).
+ *
+ * Uses the `meta` table so it survives crashes — dead PIDs are detected via
+ * process.kill(pid, 0), stale entries via TTL. No external lock files needed.
+ *
+ * Wrapped in db.transaction() (BEGIN IMMEDIATE) so the read-then-write is
+ * atomic and busy_timeout retries correctly — bare auto-commit DML in WAL
+ * mode can return SQLITE_BUSY_SNAPSHOT which bypasses the busy handler.
+ */
+export function tryClaimScan(pid) {
+    const db = getDB();
+    const txn = db.transaction(() => {
+        const existing = db
+            .prepare(`SELECT value FROM meta WHERE key = 'scan_in_progress'`)
+            .get();
+        if (existing) {
+            const parts = existing.value.split(':');
+            const existingPid = parseInt(parts[0], 10);
+            const existingTs = parseInt(parts[1], 10);
+            const ageMs = Date.now() - existingTs;
+            if (isProcessAlive(existingPid) && ageMs < SCAN_CLAIM_TTL_MS) {
+                return false; // another live process is scanning — skip
+            }
+            // Dead PID or expired TTL — take over below
+        }
+        db.prepare(`INSERT OR REPLACE INTO meta (key, value) VALUES ('scan_in_progress', ?)`)
+            .run(`${pid}:${Date.now()}`);
+        return true;
+    });
+    return txn();
+}
+/**
+ * Release the scan claim written by tryClaimScan. Only deletes the entry
+ * if it still belongs to this process (guards against TTL takeovers).
+ */
+export function releaseScan(pid) {
+    const db = getDB();
+    const txn = db.transaction(() => {
+        const existing = db
+            .prepare(`SELECT value FROM meta WHERE key = 'scan_in_progress'`)
+            .get();
+        if (!existing)
+            return;
+        const claimPid = parseInt(existing.value.split(':')[0], 10);
+        if (claimPid === pid) {
+            db.prepare(`DELETE FROM meta WHERE key = 'scan_in_progress'`).run();
+        }
+    });
+    txn();
+}
 /** Return the absolute path to the sessions database file. */
 export function getDBPath() {
     return DB_PATH;
@@ -362,8 +437,37 @@ export function upsertSessionsBatch(entries) {
       file_size = excluded.file_size,
       scanned_at = excluded.scanned_at
   `);
+    // Build a lookup from canonical file path → entry, used inside the write
+    // transaction to re-check the ledger AFTER acquiring the lock. When a
+    // concurrent process already committed the same files between our
+    // filterChangedFiles call and now, the ledger will have matching (mtime, size)
+    // rows — we skip those entries, making the second writer's transaction a
+    // near-instant no-op rather than redundant work.
+    const byPath = new Map(entries
+        .filter(e => e.scan && e.meta.filePath)
+        .map(e => [canonicalLedgerKey(e.meta.filePath), e]));
     const txn = db.transaction((items) => {
+        // Re-read the ledger now that we hold the write lock. Any file committed
+        // by a concurrent process since our pre-scan is visible here.
+        const CHUNK = 500; // stay under SQLite's 999-variable limit
+        const alreadyIndexed = new Set();
+        const paths = [...byPath.keys()];
+        for (let i = 0; i < paths.length; i += CHUNK) {
+            const chunk = paths.slice(i, i + CHUNK);
+            const phs = chunk.map(() => '?').join(',');
+            const rows = db
+                .prepare(`SELECT file_path, file_mtime_ms, file_size FROM scan_ledger WHERE file_path IN (${phs})`)
+                .all(...chunk);
+            for (const row of rows) {
+                const entry = byPath.get(row.file_path);
+                if (entry && row.file_mtime_ms === entry.scan.fileMtimeMs && row.file_size === entry.scan.fileSize) {
+                    alreadyIndexed.add(entry.meta.id);
+                }
+            }
+        }
         for (const { meta, content, scan } of items) {
+            if (alreadyIndexed.has(meta.id))
+                continue;
             upsert.run({
                 id: meta.id,
                 short_id: meta.shortId,

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

@@ -37,6 +37,12 @@ export interface ScanProgress {
 /**
  * Discover sessions. Scans only files whose (mtime, size) have changed since
  * the last run; everything else is served from the SQLite cache.
+ *
+ * Only one process runs the incremental scan at a time. When many agents boot
+ * simultaneously (e.g. after a restart), the first to claim the scan slot does
+ * the work; the rest skip parsing entirely and serve from the DB. The claim is
+ * stored in the `meta` table — crash-safe via dead-PID detection and a 2-min
+ * TTL, no external lock files needed.
  */
 export declare function discoverSessions(options?: DiscoverOptions): Promise<SessionMeta[]>;
 /**

package/dist/lib/session/discover.js

@@ -13,16 +13,22 @@ import * as crypto from 'crypto';
 import * as readline from 'readline';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { getAgentsDir } from '../state.js';
+import { getAgentsDir, getHistoryDir } from '../state.js';
 const execFileAsync = promisify(execFile);
 import { AGENTS, getCliVersion } from '../agents.js';
 import { walkForFiles } from '../fs-walk.js';
 import { getConfigSymlinkVersion } from '../shims.js';
 import { SESSION_AGENTS } from './types.js';
 import { extractSessionTopic } from './prompt.js';
-import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, upsertSessionsBatch, querySessions, countSessions, ftsSearch, } from './db.js';
+import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, } from './db.js';
 const HOME = os.homedir();
-const AGENTS_DIR = getAgentsDir();
+// Versions can live under either repo: the user repo (current canonical
+// location, ~/.agents/.history/versions/) or the system repo (legacy / npm-shipped,
+// ~/.agents-system/versions/). Both must be scanned — sessions written by
+// any installed version end up in that version's projects/ dir, and the user
+// can be running one repo's version while another repo holds older versions
+// whose JSONLs the user still wants to search.
+const VERSIONS_ROOTS = [getHistoryDir(), getAgentsDir()];
 const RUSH_SESSIONS_DIR = path.join(HOME, '.rush', 'sessions');
 const HERMES_SESSIONS_DIR = path.join(HOME, '.hermes', 'sessions');
 /** How long OpenClaw channel/cron snapshots stay valid before we re-shell-out. */
@@ -32,24 +38,36 @@ const cachedAgentVersions = new Map();
 /**
  * Discover sessions. Scans only files whose (mtime, size) have changed since
  * the last run; everything else is served from the SQLite cache.
+ *
+ * Only one process runs the incremental scan at a time. When many agents boot
+ * simultaneously (e.g. after a restart), the first to claim the scan slot does
+ * the work; the rest skip parsing entirely and serve from the DB. The claim is
+ * stored in the `meta` table — crash-safe via dead-PID detection and a 2-min
+ * TTL, no external lock files needed.
  */
 export async function discoverSessions(options) {
     // Touch the DB so the schema is ready and connection is cached for this run.
     getDB();
     const agents = options?.agent ? [options.agent] : SESSION_AGENTS;
     const onProgress = options?.onProgress;
-    // Incrementally re-scan changed files across all selected agents in parallel.
-    await Promise.all(agents.map(agent => {
-        switch (agent) {
-            case 'claude': return scanClaudeIncremental(onProgress);
-            case 'codex': return scanCodexIncremental(onProgress);
-            case 'gemini': return scanGeminiIncremental(onProgress);
-            case 'opencode': return scanOpenCodeIncremental();
-            case 'openclaw': return scanOpenClawIncremental();
-            case 'rush': return scanRushIncremental(onProgress);
-            case 'hermes': return scanHermesIncremental(onProgress);
+    if (tryClaimScan(process.pid)) {
+        try {
+            await Promise.all(agents.map(agent => {
+                switch (agent) {
+                    case 'claude': return scanClaudeIncremental(onProgress);
+                    case 'codex': return scanCodexIncremental(onProgress);
+                    case 'gemini': return scanGeminiIncremental(onProgress);
+                    case 'opencode': return scanOpenCodeIncremental();
+                    case 'openclaw': return scanOpenClawIncremental();
+                    case 'rush': return scanRushIncremental(onProgress);
+                    case 'hermes': return scanHermesIncremental(onProgress);
+                }
+            }));
         }
-    }));
+        finally {
+            releaseScan(process.pid);
+        }
+    }
     const sessions = querySessions(buildQueryOptions(options, agents, { includeLimit: true }));
     return sessions;
 }
@@ -184,8 +202,10 @@ export function getAgentSessionDirs(agent, subdir) {
         dirs.push(dir);
     }
     addDir(path.join(HOME, `.${agent}`, subdir));
-    const versionsBase = path.join(AGENTS_DIR, 'versions', agent);
-    if (fs.existsSync(versionsBase)) {
+    for (const root of VERSIONS_ROOTS) {
+        const versionsBase = path.join(root, 'versions', agent);
+        if (!fs.existsSync(versionsBase))
+            continue;
         try {
             for (const version of fs.readdirSync(versionsBase)) {
                 addDir(path.join(versionsBase, version, 'home', `.${agent}`, subdir));
@@ -193,7 +213,7 @@ export function getAgentSessionDirs(agent, subdir) {
         }
         catch { /* dir unreadable */ }
     }
-    const backupsBase = path.join(AGENTS_DIR, 'backups', agent);
+    const backupsBase = path.join(getHistoryDir(), 'backups', agent);
     if (fs.existsSync(backupsBase)) {
         try {
             for (const ts of fs.readdirSync(backupsBase)) {
@@ -219,8 +239,10 @@ function getClaudeAccount() {
         path.join(HOME, '.claude', '.claude.json'),
         path.join(HOME, '.claude.json'),
     ];
-    const versionsBase = path.join(AGENTS_DIR, 'versions', 'claude');
-    if (fs.existsSync(versionsBase)) {
+    for (const root of VERSIONS_ROOTS) {
+        const versionsBase = path.join(root, 'versions', 'claude');
+        if (!fs.existsSync(versionsBase))
+            continue;
         try {
             for (const version of fs.readdirSync(versionsBase)) {
                 candidates.push(path.join(versionsBase, version, 'home', '.claude', '.claude.json'));
@@ -405,8 +427,10 @@ function getCodexAccount() {
     if (cachedCodexAccount !== undefined)
         return cachedCodexAccount || undefined;
     const candidates = [path.join(HOME, '.codex', 'auth.json')];
-    const versionsBase = path.join(AGENTS_DIR, 'versions', 'codex');
-    if (fs.existsSync(versionsBase)) {
+    for (const root of VERSIONS_ROOTS) {
+        const versionsBase = path.join(root, 'versions', 'codex');
+        if (!fs.existsSync(versionsBase))
+            continue;
         try {
             for (const version of fs.readdirSync(versionsBase)) {
                 candidates.push(path.join(versionsBase, version, 'home', '.codex', 'auth.json'));
@@ -1451,22 +1475,24 @@ function normalizeVersion(version) {
     const trimmed = version?.trim();
     return trimmed ? trimmed : undefined;
 }
-/** Extract the version number from a managed ~/.agents/versions/<agent>/<version>/... path. */
+/** Extract the version number from a managed versions/<agent>/<version>/... path under either repo. */
 function extractVersionFromManagedPath(agent, sourcePath) {
     if (!sourcePath)
         return undefined;
     const candidates = [sourcePath, safeRealpathSync(sourcePath) || ''];
-    const marker = `/.agents/versions/${agent}/`;
+    const markers = [`/.agents/versions/${agent}/`, `/.agents-system/versions/${agent}/`];
     for (const candidate of candidates) {
         if (!candidate)
             continue;
         const normalized = candidate.split(path.sep).join('/');
-        const start = normalized.indexOf(marker);
-        if (start === -1)
-            continue;
-        const version = normalized.slice(start + marker.length).split('/')[0];
-        if (version)
-            return version;
+        for (const marker of markers) {
+            const start = normalized.indexOf(marker);
+            if (start === -1)
+                continue;
+            const version = normalized.slice(start + marker.length).split('/')[0];
+            if (version)
+                return version;
+        }
     }
     return undefined;
 }

package/dist/lib/session/team-filter.js

@@ -9,12 +9,12 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { getAgentsDir } from '../state.js';
+import { getTeamsAgentsDir } from '../state.js';
 const HOME = os.homedir();
 // Default path; tests can override via AGENTS_TEAMS_DIR env var.
 /** Resolve the directory containing per-session team metadata files. */
 function teamsAgentsDir() {
-    return process.env.AGENTS_TEAMS_DIR ?? path.join(getAgentsDir(), 'teams', 'agents');
+    return process.env.AGENTS_TEAMS_DIR ?? getTeamsAgentsDir();
 }
 /**
  * Determine whether `session` was spawned by `agents teams`.

package/dist/lib/shims.d.ts

@@ -13,15 +13,6 @@ export interface ConflictInfo {
     version: string;
     conflicts: string[];
 }
-/**
- * Detect conflicting files between source and destination directories.
- * Returns list of filenames that exist in both locations (excluding symlinks in dest).
- */
-export declare function detectConflicts(src: string, dest: string, prefix?: string): string[];
-/**
- * Prompt user for conflict resolution strategy.
- */
-export declare function promptConflictStrategy(conflictInfos: ConflictInfo[]): Promise<ConflictStrategy | null>;
 /**
  * Generate the shim script content for an agent.
  *
@@ -57,8 +48,10 @@ export declare function promptConflictStrategy(conflictInfos: ConflictInfo[]): P
  *        and capability flag `memoryImports` → `rulesImports`.
  *   v8 — versions moved from ~/.agents-system/versions to ~/.agents/versions
  *        (two-repo split: system = shipped defaults, user = operational state).
+ *   v9 — claude shim exports CLAUDE_CODE_OAUTH_TOKEN from per-version
+ *        .oauth_token file on Linux (keychain-less sandbox fallback).
  */
-export declare const SHIM_SCHEMA_VERSION = 8;
+export declare const SHIM_SCHEMA_VERSION = 10;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -90,7 +83,7 @@ export declare function removeShim(agent: AgentId): boolean;
  *   v6 — versions moved from ~/.agents-system/versions to ~/.agents/versions
  *        (two-repo split: system = shipped defaults, user = operational state).
  */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 6;
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 7;
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary
@@ -128,14 +121,6 @@ export declare function removeVersionedAlias(agent: AgentId, version: string): b
  * Check if a versioned alias exists.
  */
 export declare function versionedAliasExists(agent: AgentId, version: string): boolean;
-/**
- * Detect conflicts that would occur when switching config symlink for an agent/version.
- * This allows collecting conflicts upfront before prompting for a strategy.
- *
- * Returns null if no migration is needed (already symlink or doesn't exist),
- * or ConflictInfo with the list of conflicting files.
- */
-export declare function detectMigrationConflicts(agent: AgentId, version: string): ConflictInfo | null;
 /**
  * Switch the agent's config symlink to point to a specific version.
  * e.g., ~/.claude -> ~/.agents/versions/claude/2.0.65/home/.claude/
@@ -185,14 +170,6 @@ export declare function switchHomeFileSymlinks(agent: AgentId, version: string):
  *   - Symlink points elsewhere: replace it.
  */
 export declare function ensureClaudeInsideSymlink(version: string): void;
-/**
- * Apply `ensureClaudeInsideSymlink` to every installed Claude version.
- * Safe to call repeatedly; per-version calls are idempotent.
- */
-export declare function ensureAllClaudeInsideSymlinks(): {
-    migrated: string[];
-    errors: string[];
-};
 /**
  * Get the current config symlink target version, if any.
  */
@@ -201,17 +178,6 @@ export declare function getConfigSymlinkVersion(agent: AgentId): string | null;
  * Check if shim exists for an agent.
  */
 export declare function shimExists(agent: AgentId): boolean;
-/**
- * Read the schema version embedded in an existing on-disk shim. Returns
- * `null` if the shim doesn't exist or has no version marker (pre-v2 shim).
- */
-export declare function readShimSchemaVersion(agent: AgentId): number | null;
-/**
- * True if the on-disk shim's schema version matches `SHIM_SCHEMA_VERSION`.
- * False means either the shim is missing, is pre-v2 (no marker), or is an
- * older version that needs regeneration.
- */
-export declare function isShimCurrent(agent: AgentId): boolean;
 /**
  * Regenerate the shim if it's missing or outdated. Returns a status describing
  * what happened — callers can surface a one-line notice to the user ("Updated
@@ -276,10 +242,6 @@ export declare function addShimsToPath(overrides?: {
     error?: string;
 };
 export declare function listAgentsWithInstalledVersions(): AgentId[];
-/**
- * Create shims for all installed agents.
- */
-export declare function ensureAllShims(): void;
 /**
  * Resource diff between two versions. Each field lists resources present in
  * the current version but missing from the target.
@@ -295,17 +257,7 @@ export interface ResourceDiff {
     }[];
     mcp: string[];
 }
-/**
- * Compare resources between two versions.
- * Returns resources that exist in currentVersion but not in targetVersion.
- */
-export declare function compareVersionResources(agent: AgentId, currentVersion: string, targetVersion: string): ResourceDiff;
 /**
  * Check if a ResourceDiff has any differences.
  */
 export declare function hasResourceDiff(diff: ResourceDiff): boolean;
-/**
- * Copy resources from one version to another.
- * Only copies resources listed in the diff (i.e., ones missing in target).
- */
-export declare function copyResourcesToVersion(agent: AgentId, fromVersion: string, toVersion: string, diff: ResourceDiff): void;