@phnx-labs/agents-cli 1.16.0 → 1.17.0

package/dist/lib/resource-patterns.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Resource selection patterns for agents.yaml versions: entries.
+ *
+ * Pattern syntax: [!]source:name
+ *   "system:*"     — all resources from ~/.agents-system/
+ *   "user:*"       — all resources from ~/.agents/
+ *   "rush:*"       — all resources from ~/.agents-rush/  (extra repo alias)
+ *   "project:*"    — all resources from .agents/ in the project root
+ *   "user:foo"     — specifically the resource named "foo" from ~/.agents/
+ *   "!user:temp"   — exclude "temp" from the user repo
+ *
+ * Evaluation rule: union all inclusions, then subtract all exclusions.
+ */
+export interface ParsedPattern {
+    negate: boolean;
+    source: string;
+    name: string;
+}
+export declare function parsePattern(p: string): ParsedPattern;
+/** Returns true if the string is a legacy plain name with no source: prefix. */
+export declare function isLegacyName(p: string): boolean;
+/**
+ * Expand a list of patterns against an available name→source map.
+ * Returns the union of matching names with exclusions subtracted.
+ *
+ * Supports comma-grouped names to avoid repeating the source prefix:
+ *   "system:brain-scan,mq"  →  includes brain-scan and mq from system
+ *   "!user:temp,draft"      →  excludes temp and draft from user
+ *
+ * Note: in YAML flow sequences ([...]) a comma inside a pattern requires
+ * quoting ("system:brain-scan,mq"). Block-style items and yaml.stringify
+ * output handle this automatically.
+ */
+export declare function expandPatterns(patterns: string[], available: Map<string, string>): string[];
+/**
+ * Build the default pattern list for a resource type.
+ * Order: system → user → alias1 → alias2 → ... → project (base-to-override).
+ * @param extraAliases  Alias names of enabled extra repos, in insertion order.
+ * @param includeProject  Whether to append "project:*". False for hooks (security).
+ */
+export declare function defaultPatterns(extraAliases?: string[], includeProject?: boolean): string[];

package/dist/lib/resource-patterns.js

@@ -0,0 +1,82 @@
+/**
+ * Resource selection patterns for agents.yaml versions: entries.
+ *
+ * Pattern syntax: [!]source:name
+ *   "system:*"     — all resources from ~/.agents-system/
+ *   "user:*"       — all resources from ~/.agents/
+ *   "rush:*"       — all resources from ~/.agents-rush/  (extra repo alias)
+ *   "project:*"    — all resources from .agents/ in the project root
+ *   "user:foo"     — specifically the resource named "foo" from ~/.agents/
+ *   "!user:temp"   — exclude "temp" from the user repo
+ *
+ * Evaluation rule: union all inclusions, then subtract all exclusions.
+ */
+export function parsePattern(p) {
+    const negate = p.startsWith('!');
+    const raw = negate ? p.slice(1) : p;
+    const colon = raw.indexOf(':');
+    if (colon === -1) {
+        throw new Error(`Invalid resource pattern "${p}": expected "source:name" format`);
+    }
+    return { negate, source: raw.slice(0, colon), name: raw.slice(colon + 1) };
+}
+/** Returns true if the string is a legacy plain name with no source: prefix. */
+export function isLegacyName(p) {
+    return !p.startsWith('!') && !p.includes(':');
+}
+/**
+ * Expand a list of patterns against an available name→source map.
+ * Returns the union of matching names with exclusions subtracted.
+ *
+ * Supports comma-grouped names to avoid repeating the source prefix:
+ *   "system:brain-scan,mq"  →  includes brain-scan and mq from system
+ *   "!user:temp,draft"      →  excludes temp and draft from user
+ *
+ * Note: in YAML flow sequences ([...]) a comma inside a pattern requires
+ * quoting ("system:brain-scan,mq"). Block-style items and yaml.stringify
+ * output handle this automatically.
+ */
+export function expandPatterns(patterns, available) {
+    const included = new Set();
+    const excluded = new Set();
+    for (const p of patterns) {
+        try {
+            const { negate, source, name } = parsePattern(p);
+            const target = negate ? excluded : included;
+            // Comma-grouped names: "system:brain-scan,mq" → ['brain-scan', 'mq']
+            const names = name === '*' ? ['*'] : name.split(',').map(n => n.trim()).filter(Boolean);
+            for (const n of names) {
+                if (n === '*') {
+                    for (const [rn, rs] of available) {
+                        if (rs === source)
+                            target.add(rn);
+                    }
+                }
+                else {
+                    if (available.has(n))
+                        target.add(n);
+                }
+            }
+        }
+        catch {
+            // Skip malformed patterns
+        }
+    }
+    return [...included].filter(n => !excluded.has(n));
+}
+/**
+ * Build the default pattern list for a resource type.
+ * Order: system → user → alias1 → alias2 → ... → project (base-to-override).
+ * @param extraAliases  Alias names of enabled extra repos, in insertion order.
+ * @param includeProject  Whether to append "project:*". False for hooks (security).
+ */
+export function defaultPatterns(extraAliases = [], includeProject = true) {
+    const patterns = ['system:*', 'user:*'];
+    for (const alias of extraAliases) {
+        patterns.push(`${alias}:*`);
+    }
+    if (includeProject) {
+        patterns.push('project:*');
+    }
+    return patterns;
+}

package/dist/lib/resources/index.d.ts

@@ -13,6 +13,7 @@ export { RulesHandler, type RuleItem } from './rules.js';
 export { McpHandler, getMcpConfigPath, type McpItem } from './mcp.js';
 export { PermissionsHandler, type PermissionItem } from './permissions.js';
 export { SubagentsHandler, subagentsHandler, type SubagentItem } from './subagents.js';
+export { WorkflowsHandler, type WorkflowItem } from './workflows.js';
 import type { ResourceKind, ResourceHandler } from './types.js';
 /** All resource handlers keyed by kind. */
 export declare const handlers: {
@@ -29,6 +30,22 @@ export declare const handlers: {
     readonly permissions: ResourceHandler<import("../types.js").PermissionSet>;
     readonly subagent: import("./subagents.js").SubagentsHandler;
     readonly subagents: import("./subagents.js").SubagentsHandler;
+    readonly workflow: {
+        readonly kind: "workflow";
+        listAll(_agent: import("./types.js").AgentId, cwd?: string): import("./types.js").ResolvedItem<import("./workflows.js").WorkflowItem>[];
+        resolve(_agent: import("./types.js").AgentId, name: string, cwd?: string): import("./types.js").ResolvedItem<import("./workflows.js").WorkflowItem> | null;
+        sync(_agent: import("./types.js").AgentId, _versionHome: string, _cwd?: string): void;
+        format(_agent: import("./types.js").AgentId): "md";
+        targetDir(_agent: import("./types.js").AgentId): string;
+    };
+    readonly workflows: {
+        readonly kind: "workflow";
+        listAll(_agent: import("./types.js").AgentId, cwd?: string): import("./types.js").ResolvedItem<import("./workflows.js").WorkflowItem>[];
+        resolve(_agent: import("./types.js").AgentId, name: string, cwd?: string): import("./types.js").ResolvedItem<import("./workflows.js").WorkflowItem> | null;
+        sync(_agent: import("./types.js").AgentId, _versionHome: string, _cwd?: string): void;
+        format(_agent: import("./types.js").AgentId): "md";
+        targetDir(_agent: import("./types.js").AgentId): string;
+    };
 };
 /** Get a handler by resource kind. */
 export declare function getHandler(kind: ResourceKind): ResourceHandler<unknown> | null;

package/dist/lib/resources/index.js

@@ -13,6 +13,7 @@ export { RulesHandler } from './rules.js';
 export { McpHandler, getMcpConfigPath } from './mcp.js';
 export { PermissionsHandler } from './permissions.js';
 export { SubagentsHandler, subagentsHandler } from './subagents.js';
+export { WorkflowsHandler } from './workflows.js';
 import { commandsHandler } from './commands.js';
 import { HooksHandler } from './hooks.js';
 import { SkillsHandler } from './skills.js';
@@ -20,6 +21,7 @@ import { RulesHandler } from './rules.js';
 import { McpHandler } from './mcp.js';
 import { PermissionsHandler } from './permissions.js';
 import { subagentsHandler } from './subagents.js';
+import { WorkflowsHandler } from './workflows.js';
 /** All resource handlers keyed by kind. */
 export const handlers = {
     command: commandsHandler,
@@ -35,6 +37,8 @@ export const handlers = {
     permissions: PermissionsHandler,
     subagent: subagentsHandler,
     subagents: subagentsHandler,
+    workflow: WorkflowsHandler,
+    workflows: WorkflowsHandler,
 };
 /** Get a handler by resource kind. */
 export function getHandler(kind) {
@@ -53,6 +57,8 @@ export function getHandler(kind) {
             return PermissionsHandler;
         case 'subagent':
             return subagentsHandler;
+        case 'workflow':
+            return WorkflowsHandler;
         default:
             return null;
     }
@@ -66,4 +72,5 @@ export const RESOURCE_KINDS = [
     'mcp',
     'permission',
     'subagent',
+    'workflow',
 ];

package/dist/lib/resources/types.d.ts

@@ -7,7 +7,7 @@
  */
 export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw';
 export type Layer = 'system' | 'user' | 'project';
-export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent';
+export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent' | 'workflow';
 /** A resolved resource with its origin layer. */
 export interface ResolvedItem<T> {
     name: string;

package/dist/lib/resources/workflows.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Workflows resource handler.
+ *
+ * Workflows are directory bundles with a WORKFLOW.md containing YAML frontmatter.
+ * They optionally contain subagents/, skills/, and plugins/ subdirectories.
+ * Resolution order: project > user > system.
+ */
+import type { AgentId, ResolvedItem, ResourceHandler } from './types.js';
+export interface WorkflowItem {
+    name: string;
+    description: string;
+    model?: string;
+    subagentCount: number;
+}
+declare class WorkflowsHandlerImpl implements ResourceHandler<WorkflowItem> {
+    readonly kind: "workflow";
+    listAll(_agent: AgentId, cwd?: string): ResolvedItem<WorkflowItem>[];
+    resolve(_agent: AgentId, name: string, cwd?: string): ResolvedItem<WorkflowItem> | null;
+    sync(_agent: AgentId, _versionHome: string, _cwd?: string): void;
+    format(_agent: AgentId): 'md';
+    targetDir(_agent: AgentId): string;
+}
+export declare const WorkflowsHandler: WorkflowsHandlerImpl;
+export {};

package/dist/lib/resources/workflows.js

@@ -0,0 +1,110 @@
+/**
+ * Workflows resource handler.
+ *
+ * Workflows are directory bundles with a WORKFLOW.md containing YAML frontmatter.
+ * They optionally contain subagents/, skills/, and plugins/ subdirectories.
+ * Resolution order: project > user > system.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getProjectAgentsDir, getUserWorkflowsDir, getSystemWorkflowsDir, getEnabledExtraRepos, } from '../state.js';
+import { parseWorkflowFrontmatter, countWorkflowSubagents } from '../workflows.js';
+function getLayerDirs(cwd) {
+    const projectDir = getProjectAgentsDir(cwd);
+    const extraRepos = getEnabledExtraRepos();
+    return {
+        system: getSystemWorkflowsDir(),
+        user: getUserWorkflowsDir(),
+        project: projectDir ? path.join(projectDir, 'workflows') : null,
+        extra: extraRepos.map(e => path.join(e.dir, 'workflows')),
+    };
+}
+function listWorkflowsInDir(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true })
+            .filter(e => e.isDirectory() && !e.name.startsWith('.') &&
+            fs.existsSync(path.join(dir, e.name, 'WORKFLOW.md')))
+            .map(e => ({ name: e.name, path: path.join(dir, e.name) }));
+    }
+    catch {
+        return [];
+    }
+}
+class WorkflowsHandlerImpl {
+    kind = 'workflow';
+    listAll(_agent, cwd) {
+        const dirs = getLayerDirs(cwd);
+        const seen = new Set();
+        const results = [];
+        const layerDirs = [];
+        if (dirs.project)
+            layerDirs.push({ dir: dirs.project, layer: 'project' });
+        layerDirs.push({ dir: dirs.user, layer: 'user' });
+        layerDirs.push({ dir: dirs.system, layer: 'system' });
+        for (const extraDir of dirs.extra)
+            layerDirs.push({ dir: extraDir, layer: 'system' });
+        for (const { dir, layer } of layerDirs) {
+            for (const { name, path: workflowPath } of listWorkflowsInDir(dir)) {
+                if (seen.has(name))
+                    continue;
+                const fm = parseWorkflowFrontmatter(workflowPath);
+                if (!fm)
+                    continue;
+                seen.add(name);
+                results.push({
+                    name,
+                    item: {
+                        name: fm.name || name,
+                        description: fm.description,
+                        model: fm.model,
+                        subagentCount: countWorkflowSubagents(workflowPath),
+                    },
+                    layer,
+                    path: workflowPath,
+                });
+            }
+        }
+        return results.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    resolve(_agent, name, cwd) {
+        const dirs = getLayerDirs(cwd);
+        const searchDirs = [];
+        if (dirs.project)
+            searchDirs.push({ dir: dirs.project, layer: 'project' });
+        searchDirs.push({ dir: dirs.user, layer: 'user' });
+        searchDirs.push({ dir: dirs.system, layer: 'system' });
+        for (const extraDir of dirs.extra)
+            searchDirs.push({ dir: extraDir, layer: 'system' });
+        for (const { dir, layer } of searchDirs) {
+            const workflowPath = path.join(dir, name);
+            const fm = parseWorkflowFrontmatter(workflowPath);
+            if (fm) {
+                return {
+                    name,
+                    item: {
+                        name: fm.name || name,
+                        description: fm.description,
+                        model: fm.model,
+                        subagentCount: countWorkflowSubagents(workflowPath),
+                    },
+                    layer,
+                    path: workflowPath,
+                };
+            }
+        }
+        return null;
+    }
+    sync(_agent, _versionHome, _cwd) {
+        // Version-home copies are written by syncResourcesToVersion in versions.ts.
+        // exec.ts resolves workflows at run time from source dirs directly.
+    }
+    format(_agent) {
+        return 'md';
+    }
+    targetDir(_agent) {
+        return 'workflows';
+    }
+}
+export const WorkflowsHandler = new WorkflowsHandlerImpl();

package/dist/lib/resources.d.ts

@@ -11,7 +11,11 @@ export interface ResolvedResource {
     name: string;
     /** Absolute path to the resource file or directory. */
     path: string;
-    source: 'project' | 'user' | 'system';
+    /**
+     * Source layer: 'project' | 'user' | 'system' for built-in layers,
+     * or the alias name (e.g. 'rush') for extra repos registered in agents.yaml.
+     */
+    source: string;
 }
 /**
  * Resolve a single resource by kind + name using project > user > system precedence.
@@ -52,6 +56,7 @@ export interface AgentResources {
     mcp: McpResourceEntry[];
     memory: ResourceEntry[];
     hooks: ResourceEntry[];
+    workflows: ResourceEntry[];
 }
 /** Options for resource discovery. */
 export interface GetAgentResourcesOptions {

package/dist/lib/resources.js

@@ -11,6 +11,8 @@ import { listInstalledHooksWithScope } from './hooks.js';
 import { listInstalledInstructionsWithScope } from './rules/rules.js';
 import { getEffectiveHome } from './versions.js';
 import { listMcpServerConfigs } from './mcp.js';
+import { WorkflowsHandler } from './resources/workflows.js';
+import { WORKFLOW_CAPABLE_AGENTS } from './workflows.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';
 /**
  * Resolve a single resource by kind + name using project > user > system precedence.
@@ -26,7 +28,7 @@ export function resolveResource(kind, name, cwd) {
         ...(projectDir ? [[path.join(projectDir, kind), 'project']] : []),
         [path.join(getUserAgentsDir(), kind), 'user'],
         [path.join(getSystemAgentsDir(), kind), 'system'],
-        ...extraRepos.map((e) => [path.join(e.dir, kind), 'system']),
+        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias]),
     ];
     for (const [dir, source] of candidates) {
         if (!fs.existsSync(dir))
@@ -60,7 +62,7 @@ export function listResources(kind, cwd) {
         ...(projectDir ? [[path.join(projectDir, kind), 'project']] : []),
         [path.join(getUserAgentsDir(), kind), 'user'],
         [path.join(getSystemAgentsDir(), kind), 'system'],
-        ...extraRepos.map((e) => [path.join(e.dir, kind), 'system']),
+        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias]),
     ];
     for (const [dir, source] of roots) {
         if (!fs.existsSync(dir))
@@ -159,6 +161,13 @@ export function getAgentResources(agentId, options = {}) {
             hooks.push({ name: hook.name, path: hook.path, scope: hook.scope });
         }
     }
+    // Workflows (claude only)
+    const workflows = [];
+    if (WORKFLOW_CAPABLE_AGENTS.includes(agentId)) {
+        for (const w of WorkflowsHandler.listAll(agentId, cwd)) {
+            workflows.push({ name: w.name, path: w.path, scope: w.layer === 'project' ? 'project' : 'user' });
+        }
+    }
     return {
         agentId,
         commands,
@@ -167,6 +176,7 @@ export function getAgentResources(agentId, options = {}) {
         mcp,
         memory,
         hooks,
+        workflows,
     };
 }
 /**

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

@@ -151,16 +151,17 @@ export function getDB() {
     db.pragma('journal_mode = WAL');
     db.pragma('synchronous = NORMAL');
     db.pragma('temp_store = MEMORY');
-    // Wait up to 10s instead of failing immediately on SQLITE_BUSY. Multiple
-    // agents (CLIs, indexers, hooks) all open this DB concurrently; without a
-    // busy timeout, parallel writers throw "database is locked" the moment one
-    // holds the write lock. 10s is well above any realistic transaction here.
-    db.pragma('busy_timeout = 10000');
+    // 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);
@@ -181,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;
@@ -193,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;
@@ -367,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[]>;
 /**