@phnx-labs/agents-cli 1.20.86 → 1.20.88

package/dist/lib/project-resources.js

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, agentConfigDirName, isAgentHardDeprecated } from './agents.js';
 import { supports } from './capabilities.js';
-import { buildCommandSkillContent, commandSkillName, readSkillSourceCommandMarker, shouldInstallCommandAsSkill } from './command-skills.js';
+import { buildCommandSkillContent, commandSkillName, readSkillSourceCommandMarker, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill } from './command-skills.js';
 import { commandAppliesTo, parseCommandMetadata } from './commands.js';
 import { markdownToToml } from './convert.js';
 import { safeJoin } from './paths.js';
@@ -134,6 +134,7 @@ function skip(dest, projectRoot, result) {
 function syncProjectCommands(agent, version, projectAgentsDir, agentRoot, result, manifestPaths) {
     const cfg = AGENTS[agent];
     const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
+    const commandsAlsoAsSkills = shouldAlsoInstallCommandAsSkill(agent, version);
     const supportsCommands = supports(agent, 'commands', version).ok;
     if (!commandsAsSkills && !supportsCommands)
         return;
@@ -146,37 +147,50 @@ function syncProjectCommands(agent, version, projectAgentsDir, agentRoot, result
         const metadata = parseCommandMetadata(srcFile);
         if (!commandAppliesTo(agent, version, metadata).ok)
             continue;
-        if (commandsAsSkills) {
+        const written = [];
+        if (commandsAsSkills || commandsAlsoAsSkills) {
             const sourceMarker = readSkillSourceCommandMarker(name, [path.join(projectAgentsDir, 'skills')]);
-            if (pathExists(path.join(projectAgentsDir, 'skills', name)) && sourceMarker !== name)
-                continue;
-            const skillName = commandSkillName(name);
-            const rel = path.join('skills', skillName);
-            const destDir = path.join(agentRoot, rel);
-            if (pathExists(destDir)) {
-                skip(destDir, projectRoot, result);
+            if (pathExists(path.join(projectAgentsDir, 'skills', name)) && sourceMarker !== name) {
+                if (commandsAsSkills)
+                    continue;
+            }
+            else {
+                const skillName = commandSkillName(name);
+                const rel = path.join('skills', skillName);
+                const destDir = path.join(agentRoot, rel);
+                if (pathExists(destDir)) {
+                    skip(destDir, projectRoot, result);
+                }
+                else {
+                    fs.mkdirSync(destDir, { recursive: true });
+                    fs.writeFileSync(path.join(destDir, 'SKILL.md'), buildCommandSkillContent(name, srcFile), 'utf-8');
+                    written.push(rel);
+                }
+            }
+            if (commandsAsSkills) {
+                if (written.length > 0)
+                    record('commands', name, written, result, manifestPaths);
                 continue;
             }
-            fs.mkdirSync(destDir, { recursive: true });
-            fs.writeFileSync(path.join(destDir, 'SKILL.md'), buildCommandSkillContent(name, srcFile), 'utf-8');
-            record('commands', name, [rel], result, manifestPaths);
-            continue;
         }
         const ext = cfg.format === 'toml' ? '.toml' : '.md';
         const rel = path.join(cfg.commandsSubdir, `${name}${ext}`);
         const destFile = path.join(agentRoot, rel);
         if (pathExists(destFile)) {
             skip(destFile, projectRoot, result);
-            continue;
-        }
-        fs.mkdirSync(path.dirname(destFile), { recursive: true });
-        if (cfg.format === 'toml') {
-            fs.writeFileSync(destFile, markdownToToml(name, fs.readFileSync(srcFile, 'utf-8')), 'utf-8');
         }
         else {
-            fs.copyFileSync(srcFile, destFile);
+            fs.mkdirSync(path.dirname(destFile), { recursive: true });
+            if (cfg.format === 'toml') {
+                fs.writeFileSync(destFile, markdownToToml(name, fs.readFileSync(srcFile, 'utf-8')), 'utf-8');
+            }
+            else {
+                fs.copyFileSync(srcFile, destFile);
+            }
+            written.push(rel);
         }
-        record('commands', name, [rel], result, manifestPaths);
+        if (written.length > 0)
+            record('commands', name, written, result, manifestPaths);
     }
 }
 function syncProjectSkills(agent, version, projectAgentsDir, agentRoot, result, manifestPaths) {

package/dist/lib/runner.d.ts

@@ -23,6 +23,9 @@ export interface RunResult {
     meta: RunMeta;
     reportPath: string | null;
 }
+/** Agents the daemon can actually run, derived from the command table above
+ * so the `--agent` help and any validation can never drift from it. */
+export declare const ROUTINE_AGENT_IDS: readonly string[];
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export declare function buildJobCommand(config: JobConfig, resolvedPrompt: string): string[];
 export declare function archiveRoutineTranscripts(meta: Pick<RunMeta, 'jobName' | 'runId' | 'agent'>, runDir: string, overlayHome?: string): void;
@@ -63,7 +66,7 @@ export declare function dispatchesViaAgentsRun(config: Pick<JobConfig, 'workflow
  * (CLAUDE_CONFIG_DIR / CODEX_HOME / …) so routines share account isolation
  * with `agents run`.
  */
-export declare function buildRoutineSpawnEnv(baseEnv: Record<string, string>, agent: AgentId, version: string | undefined, timezone?: string): Record<string, string>;
+export declare function buildRoutineSpawnEnv(baseEnv: Record<string, string>, agent: AgentId, version: string | undefined, timezone?: string, overlayHome?: string): Record<string, string>;
 export declare function executeJob(config: JobConfig, deps?: LoopDeps): Promise<RunResult>;
 /**
  * Optional lifecycle callbacks for a detached routine run. The daemon passes an
@@ -80,5 +83,15 @@ export interface RoutineHooks {
 export declare function executeJobDetached(config: JobConfig, hooks?: RoutineHooks): Promise<RunMeta>;
 /** Extract the final assistant message from a stream-JSON log file as a markdown report. */
 export declare function extractReport(stdoutPath: string, agentType: AgentId): string | null;
+/** Derive the final status of a detached run by reading the agent's stream-json
+ *  tail. Detached children fire-and-forget, so we never see their exit code
+ *  directly — but Claude's stream-json terminates with a `type: result` line
+ *  that carries `is_error`. If we find it, the run completed cleanly (modulo
+ *  agent-reported error). If not, the process likely died mid-stream and the
+ *  caller should treat the run as failed. */
+export declare function inferFinalStatusFromLog(stdoutPath: string, agent: AgentId): {
+    status: 'completed' | 'failed';
+    exitCode: number;
+} | null;
 /** Scan all runs marked "running" and finalize any whose process has exited. */
 export declare function monitorRunningJobs(): void;

package/dist/lib/runner.js

@@ -32,17 +32,23 @@ import { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js
 import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
 import { readAuthHealth, isDeadVerdict } from './auth-health.js';
 import { machineId } from './machine-id.js';
+import { isSelfUpdatingAgent } from './agents.js';
 /** CLI command templates per agent, with {prompt} as a placeholder. */
 const AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
     codex: ['codex', 'exec', '--sandbox', 'workspace-write', '{prompt}', '--json'],
     gemini: ['gemini', '{prompt}', '--output-format', 'stream-json'],
+    cursor: ['cursor-agent', '-p', '{prompt}', '--output-format', 'stream-json'],
     kimi: ['kimi', '--prompt', '{prompt}', '--output-format', 'stream-json'],
     droid: ['droid', 'exec', '{prompt}', '-o', 'stream-json'],
 };
+/** Agents the daemon can actually run, derived from the command table above
+ * so the `--agent` help and any validation can never drift from it. */
+export const ROUTINE_AGENT_IDS = Object.freeze(Object.keys(AGENT_COMMANDS));
 const ROUTINE_TRANSCRIPT_SPECS = {
     claude: [{ root: ['.claude', 'projects'], ext: '.jsonl' }],
     codex: [{ root: ['.codex', 'sessions'], ext: '.jsonl' }],
+    cursor: [{ root: ['.cursor', 'projects'], ext: '.jsonl' }],
 };
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export function buildJobCommand(config, resolvedPrompt) {
@@ -133,6 +139,20 @@ export function buildJobCommand(config, resolvedPrompt) {
         }
         appendModelAndReasoning(cmd, config);
     }
+    if (config.agent === 'cursor') {
+        // cursor-agent supports --plan, but the capability registry has not been
+        // upgraded yet. RUSH-2101 tracks adding that read-only mode after PR #1721.
+        const cursorMode = resolveHeadlessMode('cursor', mode, false, `routine ${config.name}`);
+        if (cursorMode === 'skip') {
+            cmd.push('-f');
+        }
+        else {
+            // The configured cwd is the user's workspace trust decision. --trust is
+            // narrower than --yolo/-f because it does not bypass tool permissions.
+            cmd.push('--trust');
+        }
+        appendModelAndReasoning(cmd, config);
+    }
     if (config.agent === 'kimi') {
         // kimi daemon jobs always run headless via `--prompt`, which cannot be
         // combined with any startup-mode flag (--plan/--auto/--yolo all abort with
@@ -385,7 +405,7 @@ export function dispatchesViaAgentsRun(config) {
  * (CLAUDE_CONFIG_DIR / CODEX_HOME / …) so routines share account isolation
  * with `agents run`.
  */
-export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone) {
+export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone, overlayHome) {
     const execEnv = buildExecEnv({
         agent,
         version,
@@ -415,6 +435,11 @@ export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone) {
     // provisioned box does. Drop it here so a routine always uses the login of the
     // machine it runs on.
     delete out.CLAUDE_CODE_OAUTH_TOKEN;
+    if (agent === 'cursor' && overlayHome) {
+        // prepareJobHome links this host's Cursor auth file here. Pin XDG_CONFIG_HOME
+        // to the overlay so an ambient value cannot bypass the routine sandbox.
+        out.XDG_CONFIG_HOME = path.join(overlayHome, '.config');
+    }
     if (timezone)
         out.TZ = timezone;
     return out;
@@ -621,16 +646,20 @@ export async function executeJob(config, deps) {
     const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
     // Loop path: delegate to runLoop (same driver as `agents run --loop` / workflow loop:).
     if (config.loop) {
-        const spawnEnv = buildRoutineSpawnEnv(baseEnv, effectiveAgent, primaryVersion, config.timezone);
+        const spawnEnv = buildRoutineSpawnEnv(baseEnv, effectiveAgent, primaryVersion, config.timezone, overlayHome);
         const execOptions = {
             agent: effectiveAgent,
-            version: primaryVersion,
+            // Routine-supported self-updating CLIs (Cursor/Droid) use one global
+            // binary; a versioned shim would point at a nonexistent isolated install.
+            version: isSelfUpdatingAgent(effectiveAgent) ? undefined : primaryVersion,
             prompt: resolvedPrompt,
             mode: normalizeMode(config.mode),
             effort: config.effort,
             env: spawnEnv,
             json: true,
             headless: true,
+            modeWarningContext: `routine ${config.name}`,
+            modeWarningState: {},
             ...(config.config?.model ? { model: config.config.model } : {}),
             ...(config.allow?.dirs ? {
                 addDirs: config.allow.dirs
@@ -681,7 +710,7 @@ export async function executeJob(config, deps) {
                     e.TZ = config.timezone;
                 return e;
             })()
-            : buildRoutineSpawnEnv(baseEnv, attemptAgent, attemptVersion, config.timezone);
+            : buildRoutineSpawnEnv(baseEnv, attemptAgent, attemptVersion, config.timezone, overlayHome);
         // Remaining timeout budget shared across failover attempts.
         const elapsed = Date.now() - Date.parse(meta.startedAt);
         const remaining = Math.max(1_000, timeoutMs - (Number.isFinite(elapsed) ? elapsed : 0));
@@ -1067,7 +1096,7 @@ export async function executeJobDetached(config, hooks) {
             return e;
         })()
         // Non-command path only: config.agent is always set here (command/workflow branch earlier).
-        : buildRoutineSpawnEnv(baseEnv, config.agent, version, config.timezone);
+        : buildRoutineSpawnEnv(baseEnv, config.agent, version, config.timezone, overlayHome);
     const effectiveAgent = config.workflow ? 'claude' : config.agent;
     const meta = {
         jobName: config.name,
@@ -1262,7 +1291,7 @@ export function extractReport(stdoutPath, agentType) {
         for (const line of lines) {
             try {
                 const parsed = JSON.parse(line);
-                if (agentType === 'claude') {
+                if (agentType === 'claude' || agentType === 'cursor') {
                     if (parsed.type === 'assistant' && parsed.message?.content) {
                         for (const block of parsed.message.content) {
                             if (block.type === 'text' && block.text) {
@@ -1298,7 +1327,7 @@ export function extractReport(stdoutPath, agentType) {
  *  that carries `is_error`. If we find it, the run completed cleanly (modulo
  *  agent-reported error). If not, the process likely died mid-stream and the
  *  caller should treat the run as failed. */
-function inferFinalStatusFromLog(stdoutPath, agent) {
+export function inferFinalStatusFromLog(stdoutPath, agent) {
     if (!fs.existsSync(stdoutPath))
         return null;
     try {
@@ -1309,7 +1338,7 @@ function inferFinalStatusFromLog(stdoutPath, agent) {
         for (let i = lines.length - 1, scanned = 0; i >= 0 && scanned < 20; i--, scanned++) {
             try {
                 const parsed = JSON.parse(lines[i]);
-                if (agent === 'claude' && parsed.type === 'result') {
+                if ((agent === 'claude' || agent === 'cursor') && parsed.type === 'result') {
                     return parsed.is_error
                         ? { status: 'failed', exitCode: 1 }
                         : { status: 'completed', exitCode: 0 };

package/dist/lib/sandbox.d.ts

@@ -21,6 +21,8 @@ export declare function buildSpawnEnv(overlayHome: string, extraEnv?: Record<str
 export declare function getJobHomePath(name: string): string;
 /** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
 export declare function prepareJobHome(config: JobConfig): string;
+/** Link this host's Cursor login and CLI config into the disposable overlay. */
+export declare function generateCursorConfig(overlayHome: string): void;
 /** Remove a job's overlay HOME directory entirely. */
 export declare function cleanJobHome(name: string): void;
 /** Symlink allowed directories into the overlay HOME, skipping paths outside the real HOME. */

package/dist/lib/sandbox.js

@@ -100,11 +100,49 @@ export function prepareJobHome(config) {
     else if (config.agent === 'gemini') {
         generateGeminiConfig(overlayHome, config);
     }
+    else if (config.agent === 'cursor') {
+        generateCursorConfig(overlayHome);
+    }
     if (config.allow?.dirs) {
         symlinkAllowedDirs(overlayHome, config.allow.dirs);
     }
     return overlayHome;
 }
+/** Link this host's Cursor login and CLI config into the disposable overlay. */
+export function generateCursorConfig(overlayHome) {
+    const realConfigHome = process.env.XDG_CONFIG_HOME || path.join(resolveRealHome(), '.config');
+    const realAuth = path.join(realConfigHome, 'cursor', 'auth.json');
+    if (!fs.existsSync(realAuth))
+        return;
+    const overlayCursorDir = path.join(overlayHome, '.config', 'cursor');
+    fs.mkdirSync(overlayCursorDir, { recursive: true });
+    const overlayAuth = path.join(overlayCursorDir, 'auth.json');
+    if (process.platform === 'win32') {
+        // File symlinks need Developer Mode on Windows. A same-volume hard link
+        // shares the credential inode without copying its contents to another host.
+        try {
+            fs.linkSync(realAuth, overlayAuth);
+        }
+        catch { /* cross-volume or link creation refused: Cursor will fail auth loudly */ }
+    }
+    else {
+        fs.symlinkSync(realAuth, overlayAuth);
+    }
+    // Setting XDG_CONFIG_HOME makes Cursor look for cli-config.json beside auth.json.
+    // This file carries account identity (authId, displayName, email, userId) as
+    // well as preferences, so it must remain linked rather than copied.
+    const realCliConfig = path.join(resolveRealHome(), '.cursor', 'cli-config.json');
+    if (fs.existsSync(realCliConfig)) {
+        const overlayCliConfig = path.join(overlayCursorDir, 'cli-config.json');
+        try {
+            if (process.platform === 'win32')
+                fs.linkSync(realCliConfig, overlayCliConfig);
+            else
+                fs.symlinkSync(realCliConfig, overlayCliConfig);
+        }
+        catch { /* cross-volume or link creation refused: Cursor will fail auth loudly */ }
+    }
+}
 /** Remove a job's overlay HOME directory entirely. */
 export function cleanJobHome(name) {
     const overlayHome = getJobHomePath(name);

package/dist/lib/secrets/rc-hygiene.d.ts

@@ -47,9 +47,3 @@ export declare function scanRcExports(basename: string, content: string): RcSecr
  * unreadable files are skipped silently — an advisory, not a hard requirement.
  */
 export declare function scanUserRcFiles(homeDir?: string): RcSecretFinding[];
-/**
- * Build the advisory lines for `agents doctor` from a set of findings. Returns
- * `[]` when there is nothing to report. The first line is the headline; the
- * rest are indented detail. Names only — never values.
- */
-export declare function rcSecretWarningLines(findings: RcSecretFinding[]): string[];

package/dist/lib/secrets/rc-hygiene.js

@@ -128,27 +128,3 @@ export function scanUserRcFiles(homeDir = os.homedir()) {
     }
     return out;
 }
-/**
- * Build the advisory lines for `agents doctor` from a set of findings. Returns
- * `[]` when there is nothing to report. The first line is the headline; the
- * rest are indented detail. Names only — never values.
- */
-export function rcSecretWarningLines(findings) {
-    if (findings.length === 0)
-        return [];
-    const lines = [];
-    const master = findings.filter((f) => f.isMasterPassphrase);
-    const others = findings.filter((f) => !f.isMasterPassphrase);
-    const total = findings.length;
-    lines.push(`${total} credential-shaped export${total === 1 ? '' : 's'} found in shell rc files — ` +
-        `readable from /proc/<pid>/environ by any same-user process.`);
-    for (const f of master) {
-        lines.push(`${f.file}:${f.line} ${f.name} — the file-store master key. Move it off-env to ` +
-            `~/.agents/.secrets-key/passphrase (chmod 600) and delete the export.`);
-    }
-    for (const f of others) {
-        lines.push(`${f.file}:${f.line} ${f.name} — move to \`agents secrets\` and inject via \`agents secrets exec\`.`);
-    }
-    lines.push('Rule: no credentials in env vars or shell config. Use the keychain-backed store.');
-    return lines;
-}

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

@@ -298,7 +298,7 @@ export declare function sessionFileTimes(sessionFile: string | undefined): {
 export declare function lifecycleStatus(pidAlive: boolean, mtimeMs: number | undefined, nowMs?: number): ActiveStatus | undefined;
 /**
  * The ONE place a fallback status is decided when no rich transcript state is
- * available — an opaque kind we cannot parse (cursor, openclaw), or a transcript
+ * available — an opaque kind we cannot parse (openclaw), or a transcript
  * whose parse/tail was empty or unreadable. Honest by construction: computed from
  * PID + mtime, never a fabricated `idle`.
  *
@@ -316,13 +316,13 @@ export declare function resolveFallbackStatus(sessionFile: string | undefined, p
  * 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)
+ * kimi / hermes / opencode / antigravity / cursor (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`.
+ * {@link computeLiveSignals}). An opaque kind we don't track still yields undefined
+ * here and degrades honestly to a live `running`.
  */
 export declare function findSessionFileForKind(kind: string, cwd?: string, sessionId?: string): string | undefined;
 /** Live per-session signals derived from one transcript-tail read. */
@@ -339,10 +339,10 @@ interface LiveSignals {
  * 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
+ * rush, gemini, kimi, hermes, opencode, antigravity, cursor) 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
+ * `unknown` it used to fall through to. An opaque/untracked kind or an
  * unreadable/empty transcript yields an empty signal set, and the caller's
  * {@link resolveFallbackStatus} reports the honest live floor (`running`).
  */

package/dist/lib/session/active.js

@@ -358,7 +358,7 @@ export function lifecycleStatus(pidAlive, mtimeMs, nowMs = Date.now()) {
 }
 /**
  * The ONE place a fallback status is decided when no rich transcript state is
- * available — an opaque kind we cannot parse (cursor, openclaw), or a transcript
+ * available — an opaque kind we cannot parse (openclaw), or a transcript
  * whose parse/tail was empty or unreadable. Honest by construction: computed from
  * PID + mtime, never a fabricated `idle`.
  *
@@ -379,13 +379,13 @@ export function resolveFallbackStatus(sessionFile, pidAlive, nowMs = Date.now())
  * 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)
+ * kimi / hermes / opencode / antigravity / cursor (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`.
+ * {@link computeLiveSignals}). An opaque kind we don't track still yields undefined
+ * here and degrades honestly to a live `running`.
  */
 export function findSessionFileForKind(kind, cwd, sessionId) {
     if (!cwd)
@@ -432,10 +432,10 @@ function parseTailEventsForKind(agent, sessionFile) {
  * 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
+ * rush, gemini, kimi, hermes, opencode, antigravity, cursor) 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
+ * `unknown` it used to fall through to. An opaque/untracked kind or an
  * unreadable/empty transcript yields an empty signal set, and the caller's
  * {@link resolveFallbackStatus} reports the honest live floor (`running`).
  */

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

@@ -8,6 +8,10 @@
  */
 import Database from '../sqlite.js';
 import type { SessionAgentId, SessionMeta } from './types.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 = 21;
 /** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
@@ -40,6 +44,7 @@ export interface SessionRow {
     pr_number: number | null;
     worktree_slug: string | null;
     ticket_id: string | null;
+    spawned_team: string | null;
     plan: string | null;
     machine: string | null;
     todos: string | null;
@@ -297,6 +302,22 @@ export declare function queryAffinityRollup(options: {
 export declare function queryUsageRollup(options: QueryOptions & {
     groupBy: UsageRollupGroup;
 }): UsageRollupRow[];
+/** Who spawned a team: the orchestrator session, from its transcript. */
+export interface TeamSpawner {
+    sessionId: string;
+    shortId: string;
+    /** The human the orchestrator ran as, when the row carries actor provenance. */
+    actor?: string;
+}
+/**
+ * Map every team name to the session that ran `agents teams create/add` for it.
+ *
+ * One scan over the rows that carry a `spawned_team`, rather than a query per
+ * team — `agents teams list` needs the whole map at once, and the column has no
+ * index. When two sessions spawned the same team name (a team re-created after a
+ * disband), the most recent wins, which is the one whose work the name refers to.
+ */
+export declare function teamSpawners(): Map<string, TeamSpawner>;
 /** A session with its cost, for the top-N-by-cost listing. */
 export interface TopCostSession {
     meta: SessionMeta;

package/dist/lib/session/db.js

@@ -16,8 +16,10 @@ import { machineForSessionFile } from './origin-machine.js';
 import { loadSessionActorIndex, readSessionActorRecord } from './actor-sidecar.js';
 const SESSIONS_DIR = getSessionsDir();
 const DB_PATH = getSessionsDbPath();
-/** Current schema version; bumped when migrations are added. */
-const SCHEMA_VERSION = 20;
+/** 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 = 21;
 /**
  * Canonicalize a file path for use as a scan_ledger key. The same physical
  * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
@@ -74,6 +76,7 @@ CREATE TABLE IF NOT EXISTS sessions (
   pr_number INTEGER,
   worktree_slug TEXT,
   ticket_id TEXT,
+  spawned_team TEXT,
   plan TEXT,
   machine TEXT,
   todos TEXT,
@@ -383,6 +386,19 @@ function migrateSchema(db, fromVersion) {
             db.exec(`ALTER TABLE sessions ADD COLUMN model TEXT`);
         db.exec(`DELETE FROM scan_ledger; DELETE FROM dir_ledger;`);
     }
+    if (fromVersion < 21) {
+        // v20 → v21: persist the team a session SPAWNED (`agents teams create/add`).
+        // The value was already derived at scan time (discover.ts detectSpawnedTeam)
+        // and set on SessionMeta, but had no column — so it was dropped at the write
+        // and no consumer ever saw it. Wipe BOTH ledgers, not just scan_ledger: with
+        // dir_ledger intact, collectChangedFilesInLeafDirs treats every non-live-root
+        // dir as unchanged and derives its hot set from the scan stamps just deleted,
+        // so archived dirs would never be re-parsed and would stay NULL forever.
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some(c => c.name === 'spawned_team'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN spawned_team TEXT`);
+        db.exec(`DELETE FROM scan_ledger; DELETE FROM dir_ledger;`);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -744,7 +760,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     project, cwd, git_branch, topic, label, message_count, token_count,
     output_tokens, cost_usd, duration_ms, model,
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin,
-    pr_url, pr_number, worktree_slug, ticket_id, plan, todos,
+    pr_url, pr_number, worktree_slug, ticket_id, spawned_team, plan, todos,
     recent_directories_touched, linear_project, linear_project_url, machine,
     actor, initiated_by
   ) VALUES (
@@ -753,7 +769,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
     @output_tokens, @cost_usd, @duration_ms, @model,
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin,
-    @pr_url, @pr_number, @worktree_slug, @ticket_id, @plan, @todos,
+    @pr_url, @pr_number, @worktree_slug, @ticket_id, @spawned_team, @plan, @todos,
     @recent_directories_touched, @linear_project, @linear_project_url, @machine,
     @actor, @initiated_by
   )
@@ -795,6 +811,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     pr_number = excluded.pr_number,
     worktree_slug = excluded.worktree_slug,
     ticket_id = excluded.ticket_id,
+    spawned_team = excluded.spawned_team,
     plan = excluded.plan,
     todos = excluded.todos,
     recent_directories_touched = excluded.recent_directories_touched,
@@ -911,6 +928,7 @@ export function upsertSession(meta, content, scan) {
         pr_number: meta.prNumber ?? null,
         worktree_slug: meta.worktreeSlug ?? null,
         ticket_id: meta.ticketId ?? null,
+        spawned_team: meta.spawnedTeam ?? null,
         plan: meta.plan ?? null,
         todos: meta.todos ? JSON.stringify(meta.todos) : null,
         recent_directories_touched: meta.recentDirectoriesTouched ? JSON.stringify(meta.recentDirectoriesTouched) : null,
@@ -1031,6 +1049,7 @@ export function upsertSessionsBatch(entries) {
                     pr_number: meta.prNumber ?? null,
                     worktree_slug: meta.worktreeSlug ?? null,
                     ticket_id: meta.ticketId ?? null,
+                    spawned_team: meta.spawnedTeam ?? null,
                     plan: meta.plan ?? null,
                     todos: meta.todos ? JSON.stringify(meta.todos) : null,
                     recent_directories_touched: meta.recentDirectoriesTouched ? JSON.stringify(meta.recentDirectoriesTouched) : null,
@@ -1219,6 +1238,7 @@ function rowToMeta(row) {
         prNumber: row.pr_number ?? undefined,
         worktreeSlug: row.worktree_slug ?? undefined,
         ticketId: row.ticket_id ?? undefined,
+        spawnedTeam: row.spawned_team ?? undefined,
         plan: row.plan ?? undefined,
         todos: parseJsonColumn(row.todos),
         recentDirectoriesTouched: parseJsonColumn(row.recent_directories_touched),
@@ -1483,6 +1503,27 @@ export function queryUsageRollup(options) {
   `;
     return db.prepare(sql).all(...params);
 }
+/**
+ * Map every team name to the session that ran `agents teams create/add` for it.
+ *
+ * One scan over the rows that carry a `spawned_team`, rather than a query per
+ * team — `agents teams list` needs the whole map at once, and the column has no
+ * index. When two sessions spawned the same team name (a team re-created after a
+ * disband), the most recent wins, which is the one whose work the name refers to.
+ */
+export function teamSpawners() {
+    const db = getDB();
+    const rows = db
+        .prepare(`SELECT spawned_team, id, short_id, actor FROM sessions
+       WHERE spawned_team IS NOT NULL AND spawned_team != ''
+       ORDER BY timestamp ASC`)
+        .all();
+    const out = new Map();
+    for (const r of rows) {
+        out.set(r.spawned_team, { sessionId: r.id, shortId: r.short_id, actor: r.actor ?? undefined });
+    }
+    return out;
+}
 /**
  * Return the N most expensive sessions (cost_usd DESC, NULLs excluded),
  * honoring the same filter shape as querySessions. Drops rows whose JSONL

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

@@ -622,6 +622,11 @@ export declare function __codexScanBranchCountsForTest(): {
 };
 /** Test seam: reset the Codex parse-branch counters to observe a scan from a clean slate. */
 export declare function __resetCodexScanBranchCountsForTest(): void;
+/** Parse one Cursor transcript and enrich it with the matching chat meta.json. */
+export declare function readCursorMeta(filePath: string, currentVersion?: string): {
+    meta: SessionMeta;
+    content: string;
+} | null;
 /** Parse a single Kimi session state.json file to extract session metadata. */
 export declare function readKimiMeta(filePath: string, priorRow?: {
     parserState: string | null;