@phnx-labs/agents-cli 1.20.74 → 1.20.76

package/dist/lib/session/db.js

@@ -13,7 +13,7 @@ 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 = 13;
+const SCHEMA_VERSION = 16;
 /**
  * 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`
@@ -99,6 +99,27 @@ CREATE TABLE IF NOT EXISTS scan_ledger (
   file_path TEXT PRIMARY KEY,
   file_mtime_ms INTEGER NOT NULL,
   file_size INTEGER NOT NULL,
+  scanned_at INTEGER NOT NULL,
+  -- Resumable-parse cursor + continuation (B-1). parser_state is a JSON
+  -- ClaudeParserState blob (offset + accumulator snapshot) so a scan can pick
+  -- up where the last one stopped; content_text caches the accumulated user
+  -- doc so detectTicket + FTS can rebuild on append without re-reading the file.
+  -- Written by B-2; B-1 only defines + round-trips them.
+  parser_state TEXT,
+  content_text TEXT
+);
+
+-- Tracks the mtime + entry-count of every LEAF directory that directly holds
+-- transcripts (a Claude project dir, a Gemini chats dir). A dir's mtime bumps
+-- on create/delete/rename of its entries but NOT on an in-place append, so a
+-- match here means the dir gained/lost/renamed no files: we can skip the
+-- readdir + per-file stat and serve unchanged files from the DB (append-safety
+-- is preserved by re-stat'ing only the "hot set" — see discover.ts). Keyed by
+-- canonicalLedgerKey, same as scan_ledger.
+CREATE TABLE IF NOT EXISTS dir_ledger (
+  dir_path TEXT PRIMARY KEY,
+  dir_mtime_ms INTEGER NOT NULL,
+  entry_count INTEGER NOT NULL,
   scanned_at INTEGER NOT NULL
 );
 `;
@@ -252,6 +273,49 @@ function migrateSchema(db, fromVersion) {
         db.exec(`UPDATE sessions SET origin = 'cli' WHERE origin IS NULL OR origin = ''`);
         db.exec(`DELETE FROM scan_ledger;`);
     }
+    if (fromVersion < 14) {
+        // v13 → v14: the discovery scan now short-circuits the readdir + per-file
+        // stat of leaf transcript dirs whose (mtime, entry_count) is unchanged,
+        // caching that snapshot in the new `dir_ledger` table. Create it, and clear
+        // scan_ledger so the first post-upgrade scan does a clean full walk — that
+        // walk seeds BOTH ledgers correctly, so a cold/empty dir_ledger degrades to
+        // today's full behavior.
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS dir_ledger (
+        dir_path TEXT PRIMARY KEY,
+        dir_mtime_ms INTEGER NOT NULL,
+        entry_count INTEGER NOT NULL,
+        scanned_at INTEGER NOT NULL
+      );
+      DELETE FROM scan_ledger;
+    `);
+    }
+    if (fromVersion < 15) {
+        // v14 → v15: the Claude scan becomes resumable (B-1). scan_ledger gains a
+        // `parser_state` continuation blob (offset + accumulator snapshot) and a
+        // `content_text` cache of the accumulated user doc. Add both columns, then
+        // clear scan_ledger so the first post-upgrade scan does a clean full walk
+        // that reseeds the cursor from byte 0.
+        const cols = db.prepare(`PRAGMA table_info(scan_ledger)`).all();
+        if (!cols.some(c => c.name === 'parser_state'))
+            db.exec(`ALTER TABLE scan_ledger ADD COLUMN parser_state TEXT`);
+        if (!cols.some(c => c.name === 'content_text'))
+            db.exec(`ALTER TABLE scan_ledger ADD COLUMN content_text TEXT`);
+        db.exec(`DELETE FROM scan_ledger;`);
+    }
+    if (fromVersion < 16) {
+        // v15 → v16: repair rows poisoned by the empty-shortId bug (now fixed at the
+        // source in deriveShortId). A session id that was only a known prefix — a bare
+        // `session_` dir, an id of exactly `api-` or `ses_` — derived to '' via
+        // `id.replace(prefix, '').slice(0, 8)`, passed the `short_id TEXT NOT NULL`
+        // column (empty string is not NULL), yet matched nothing in the
+        // `short_id LIKE ?` picker lookups. The parser no longer produces '', but
+        // existing rows don't self-heal: an empty short_id is not re-parsed unless its
+        // file changes, and an orphaned row (file gone) never re-parses at all. Repair
+        // in place — `substr(id, 1, 8)` is non-empty because `id` is the non-empty
+        // primary key — so every corrupt row becomes addressable. No rescan needed.
+        db.exec(`UPDATE sessions SET short_id = substr(id, 1, 8) WHERE short_id IS NULL OR short_id = ''`);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -310,6 +374,11 @@ export function closeDB() {
     if (dbInstance) {
         dbInstance.close();
         dbInstance = null;
+        // Closing the connection finalizes every prepared statement it owns. Drop
+        // the cached upsert/FTS statements too, so the next getDB() rebuilds them
+        // against the fresh connection instead of re-running a finalized statement
+        // (which throws "statement has been finalized" on the first upsert).
+        cachedStmts = {};
     }
 }
 // ---------------------------------------------------------------------------
@@ -440,6 +509,55 @@ export function getScanStampsForPaths(filePaths) {
     }
     return result;
 }
+/**
+ * Bulk-load the resumable-parse continuation (parser_state + content_text) plus
+ * the stamp for a set of file paths in a single chunked query. Mirrors
+ * {@link getScanStampsForPaths}: keys by canonical path and fans results back to
+ * every original alias so callers can `.get(filePath)` with the path they passed.
+ * The Claude incremental scan uses this to fetch each changed file's prior
+ * continuation without an N+1 of {@link getScanStampByPath}.
+ */
+export function getParserStatesForPaths(filePaths) {
+    const result = new Map();
+    if (filePaths.length === 0)
+        return result;
+    const db = getDB();
+    const canonicalToOriginals = new Map();
+    for (const fp of filePaths) {
+        const canonical = canonicalLedgerKey(fp);
+        const aliases = canonicalToOriginals.get(canonical);
+        if (aliases)
+            aliases.push(fp);
+        else
+            canonicalToOriginals.set(canonical, [fp]);
+    }
+    const canonicalKeys = [...canonicalToOriginals.keys()];
+    const CHUNK = 500;
+    for (let i = 0; i < canonicalKeys.length; i += CHUNK) {
+        const chunk = canonicalKeys.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => '?').join(',');
+        const rows = db
+            .prepare(`
+        SELECT file_path, file_mtime_ms, file_size, scanned_at, parser_state, content_text
+        FROM scan_ledger
+        WHERE file_path IN (${placeholders})
+      `)
+            .all(...chunk);
+        for (const row of rows) {
+            const state = {
+                parserState: row.parser_state,
+                contentText: row.content_text,
+                fileMtimeMs: row.file_mtime_ms,
+                fileSize: row.file_size,
+                scannedAt: row.scanned_at,
+            };
+            for (const original of canonicalToOriginals.get(row.file_path) || []) {
+                result.set(original, state);
+            }
+        }
+    }
+    return result;
+}
 /**
  * Record scan stamps for files we've looked at. Covers both files that produced
  * a session and files we looked at but chose not to index (e.g. malformed).
@@ -464,6 +582,73 @@ export function recordScans(entries) {
     });
     txn(entries);
 }
+/**
+ * Bulk-load the dir ledger for a set of leaf directories in a single SQL query.
+ * Mirrors {@link getScanStampsForPaths}: keys by canonical path (so a dir
+ * reachable via a symlinked version home and its realpath collapse to one row)
+ * and fans the result back out to every original alias so callers can
+ * `.get(dirPath)` with the path they passed in.
+ */
+export function getDirLedgerForPaths(dirs) {
+    const result = new Map();
+    if (dirs.length === 0)
+        return result;
+    const db = getDB();
+    const canonicalToOriginals = new Map();
+    for (const d of dirs) {
+        const canonical = canonicalLedgerKey(d);
+        const aliases = canonicalToOriginals.get(canonical);
+        if (aliases)
+            aliases.push(d);
+        else
+            canonicalToOriginals.set(canonical, [d]);
+    }
+    const canonicalKeys = [...canonicalToOriginals.keys()];
+    const CHUNK = 500;
+    for (let i = 0; i < canonicalKeys.length; i += CHUNK) {
+        const chunk = canonicalKeys.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => '?').join(',');
+        const rows = db
+            .prepare(`
+        SELECT dir_path, dir_mtime_ms, entry_count
+        FROM dir_ledger
+        WHERE dir_path IN (${placeholders})
+      `)
+            .all(...chunk);
+        for (const row of rows) {
+            const stamp = { dirMtimeMs: row.dir_mtime_ms, entryCount: row.entry_count };
+            for (const original of canonicalToOriginals.get(row.dir_path) || []) {
+                result.set(original, stamp);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Upsert dir-scan stamps. Recorded after a full readdir of a leaf transcript
+ * dir so the next scan can skip that dir when its (mtime, entry_count) is
+ * unchanged. Mirrors {@link recordScans}.
+ */
+export function recordDirScans(entries) {
+    if (entries.length === 0)
+        return;
+    const db = getDB();
+    const stmt = db.prepare(`
+    INSERT INTO dir_ledger (dir_path, dir_mtime_ms, entry_count, scanned_at)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(dir_path) DO UPDATE SET
+      dir_mtime_ms = excluded.dir_mtime_ms,
+      entry_count = excluded.entry_count,
+      scanned_at = excluded.scanned_at
+  `);
+    const now = Date.now();
+    const txn = db.transaction((items) => {
+        for (const { dirPath, dirMtimeMs, entryCount } of items) {
+            stmt.run(canonicalLedgerKey(dirPath), dirMtimeMs, entryCount, now);
+        }
+    });
+    txn(entries);
+}
 const upsertSessionStmt = (db) => db.prepare(`
   INSERT INTO sessions (
     id, short_id, agent, origin, routine_name, routine_run_id,
@@ -494,7 +679,15 @@ const upsertSessionStmt = (db) => db.prepare(`
     cwd = excluded.cwd,
     git_branch = excluded.git_branch,
     topic = excluded.topic,
-    label = excluded.label,
+    -- Never let an empty/placeholder incoming label clobber a good stored one.
+    -- A real incoming label (non-empty after trim) still wins; a blank one keeps
+    -- the label seeded by --name (seedLabelsFromNames) or refined by an agent
+    -- title / rename (syncLabels). A bare rescan carries no label, so it must
+    -- preserve, not erase, the good one already stored.
+    label = CASE
+      WHEN excluded.label IS NULL OR trim(excluded.label) = '' THEN sessions.label
+      ELSE excluded.label
+    END,
     message_count = excluded.message_count,
     token_count = excluded.token_count,
     output_tokens = excluded.output_tokens,
@@ -513,6 +706,10 @@ const upsertSessionStmt = (db) => db.prepare(`
 `);
 const deleteTextStmt = (db) => db.prepare(`DELETE FROM session_text WHERE session_id = ?`);
 const insertTextStmt = (db) => db.prepare(`INSERT INTO session_text (session_id, label, topic, project, content) VALUES (?, ?, ?, ?, ?)`);
+// Read back the label the upsert actually stored (which may be the preserved
+// one, not the incoming blank) so the FTS label column stays consistent with
+// sessions.label after a bare rescan.
+const readLabelStmt = (db) => db.prepare(`SELECT label FROM sessions WHERE id = ?`);
 let cachedStmts = {};
 function stmts(db) {
     if (!cachedStmts.upsert) {
@@ -520,17 +717,28 @@ function stmts(db) {
             upsert: upsertSessionStmt(db),
             delText: deleteTextStmt(db),
             insText: insertTextStmt(db),
+            readLabel: readLabelStmt(db),
         };
     }
     return cachedStmts;
 }
+/**
+ * Return the label stored for a session, as text for the FTS index (never NULL).
+ * Called inside the upsert transaction, AFTER the row upsert, so it reflects the
+ * preserve-non-empty-label rule in the ON CONFLICT clause rather than the raw
+ * incoming label.
+ */
+function storedFtsLabel(readLabel, id) {
+    const row = readLabel.get(id);
+    return row?.label ?? '';
+}
 /**
  * Upsert a session row and replace its FTS5 content in a single transaction.
  * `content` is the tokenizable user-prompt text; pass '' to leave the row unsearchable.
  */
 export function upsertSession(meta, content, scan) {
     const db = getDB();
-    const { upsert, delText, insText } = stmts(db);
+    const { upsert, delText, insText, readLabel } = stmts(db);
     const row = {
         id: meta.id,
         short_id: meta.shortId,
@@ -566,7 +774,10 @@ export function upsertSession(meta, content, scan) {
     const txn = db.transaction(() => {
         upsert.run(row);
         delText.run(meta.id);
-        insText.run(meta.id, meta.label ?? '', meta.topic ?? '', meta.project ?? '', content ?? '');
+        insText.run(meta.id, 
+        // Use the label the upsert actually stored (preserve-non-empty rule),
+        // not the raw incoming one, so FTS label ranking survives a bare rescan.
+        storedFtsLabel(readLabel, meta.id), meta.topic ?? '', meta.project ?? '', content ?? '');
     });
     txn();
 }
@@ -575,15 +786,22 @@ export function upsertSessionsBatch(entries) {
     if (entries.length === 0)
         return;
     const db = getDB();
-    const { upsert, delText, insText } = stmts(db);
+    const { upsert, delText, insText, readLabel } = stmts(db);
     const now = Date.now();
+    // Persist the Claude resumable-parse continuation (parser_state + content_text)
+    // alongside the stamp. On a full/incremental Claude parse the caller passes the
+    // serialized newState + accumulated user doc so the NEXT scan can resume from
+    // the persisted offset (B-2). Other scanners pass neither, leaving both columns
+    // NULL exactly as before — their ledger rows are unaffected.
     const ledger = db.prepare(`
-    INSERT INTO scan_ledger (file_path, file_mtime_ms, file_size, scanned_at)
-    VALUES (?, ?, ?, ?)
+    INSERT INTO scan_ledger (file_path, file_mtime_ms, file_size, scanned_at, parser_state, content_text)
+    VALUES (?, ?, ?, ?, ?, ?)
     ON CONFLICT(file_path) DO UPDATE SET
       file_mtime_ms = excluded.file_mtime_ms,
       file_size = excluded.file_size,
-      scanned_at = excluded.scanned_at
+      scanned_at = excluded.scanned_at,
+      parser_state = excluded.parser_state,
+      content_text = excluded.content_text
   `);
     // Build a lookup from canonical file path → entry, used inside the write
     // transaction to re-check the ledger AFTER acquiring the lock. When a
@@ -613,7 +831,7 @@ export function upsertSessionsBatch(entries) {
                 }
             }
         }
-        for (const { meta, content, scan } of items) {
+        for (const { meta, content, scan, parserState, contentText } of items) {
             if (alreadyIndexed.has(meta.id))
                 continue;
             // Per-row guard: one malformed session (e.g. a required field that resolves to
@@ -657,9 +875,12 @@ export function upsertSessionsBatch(entries) {
                     plan: meta.plan ?? null,
                 });
                 delText.run(meta.id);
-                insText.run(meta.id, meta.label ?? '', meta.topic ?? '', meta.project ?? '', content ?? '');
+                insText.run(meta.id, 
+                // Mirror upsertSession: index the label the upsert actually stored
+                // (preserve-non-empty rule), not the raw incoming one.
+                storedFtsLabel(readLabel, meta.id), meta.topic ?? '', meta.project ?? '', content ?? '');
                 if (scan && meta.filePath) {
-                    ledger.run(canonicalLedgerKey(meta.filePath), scan.fileMtimeMs, scan.fileSize, now);
+                    ledger.run(canonicalLedgerKey(meta.filePath), scan.fileMtimeMs, scan.fileSize, now, parserState ?? null, contentText ?? null);
                 }
             }
             catch (err) {
@@ -909,9 +1130,12 @@ function buildSessionWhere(options) {
         params.push(options.cwd);
     }
     if (options.cwdPrefix) {
-        // Stored cwd uses the host path separator (normalizeCwd → path.resolve), so
-        // the subdir wildcard must too — a hardcoded '/' never matches a Windows
-        // `C:\a\b` subpath and the listing comes back empty.
+        // A LOCAL stored cwd uses the host path separator (normalizeCwd runs
+        // path.normalize on it), so the subdir wildcard must too — a hardcoded '/'
+        // never matches a Windows `C:\a\b` subpath and the listing comes back empty.
+        // A cwd recorded on another machine keeps its own separators, so this
+        // wildcard does not match foreign subpaths; both sides go through
+        // normalizeCwd, so the exact `cwd = ?` comparison still holds for them.
         where.push('(cwd = ? OR cwd LIKE ?)');
         params.push(options.cwdPrefix, options.cwdPrefix + path.sep + '%');
     }

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

@@ -0,0 +1,30 @@
+/** A session's foreground/background presence. */
+export type Presence = 'attached' | 'background' | 'parked';
+export interface DetachRecord {
+    sessionId: string;
+    agent: string;
+    cwd?: string;
+    /** pid of the detached headless continuation `agents sessions detach` spawned. */
+    headlessPid: number;
+    /**
+     * Start-time fingerprint of {@link headlessPid} at spawn, so a liveness check
+     * survives PID reuse: the pid is only "our" continuation if it still occupies
+     * the process we launched. Null when the platform capture failed.
+     */
+    headlessStartTime: string | null;
+    detachedAtMs: number;
+}
+export declare function writeDetachRecord(rec: DetachRecord): void;
+export declare function readDetachRecord(sessionId: string): DetachRecord | undefined;
+export declare function clearDetachRecord(sessionId: string): void;
+export declare function listDetachRecords(): DetachRecord[];
+/** True while the recorded headless continuation is still the live process we spawned. */
+export declare function isHeadlessAlive(rec: DetachRecord): boolean;
+/**
+ * Presence for a session id from the detach store alone:
+ *   - no record            -> undefined (caller decides: `attached` for a live
+ *                             interactive row, nothing for cloud/team rows)
+ *   - record + pid alive    -> `background` (headless continuation running)
+ *   - record + pid exited   -> `parked` (the run finished; transcript is durable)
+ */
+export declare function presenceFromStore(sessionId: string): Presence | undefined;

package/dist/lib/session/detached.js

@@ -0,0 +1,92 @@
+/**
+ * Detached-session store — the record `agents sessions detach` writes and both
+ * `agents sessions attach` and the active-session scan read to know an agent is
+ * "backgrounded": running headless with no terminal, continuing its task
+ * unattended.
+ *
+ * One file per detached session under `~/.agents/.system/detached/<id>.json`.
+ * Presence is DERIVED, never asserted: a record only means "this session was
+ * detached to a headless continuation"; whether it is still `background`
+ * (that continuation is alive) or `parked` (it has exited) is decided live from
+ * the recorded pid + its start-time fingerprint. That keeps the store honest
+ * even across a crash that never ran `attach`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getSystemAgentsDir } from '../state.js';
+import { captureProcessStartTime } from '../pty-server.js';
+function detachedDir() {
+    return path.join(getSystemAgentsDir(), 'detached');
+}
+function recordPath(sessionId) {
+    return path.join(detachedDir(), `${sessionId}.json`);
+}
+export function writeDetachRecord(rec) {
+    fs.mkdirSync(detachedDir(), { recursive: true });
+    fs.writeFileSync(recordPath(rec.sessionId), JSON.stringify(rec, null, 2));
+}
+export function readDetachRecord(sessionId) {
+    try {
+        return JSON.parse(fs.readFileSync(recordPath(sessionId), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function clearDetachRecord(sessionId) {
+    try {
+        fs.rmSync(recordPath(sessionId));
+    }
+    catch {
+        /* already gone */
+    }
+}
+export function listDetachRecords() {
+    let names;
+    try {
+        names = fs.readdirSync(detachedDir());
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const rec = readDetachRecord(name.slice(0, -'.json'.length));
+        if (rec)
+            out.push(rec);
+    }
+    return out;
+}
+/** True while the recorded headless continuation is still the live process we spawned. */
+export function isHeadlessAlive(rec) {
+    if (!rec.headlessPid || rec.headlessPid <= 0)
+        return false;
+    try {
+        process.kill(rec.headlessPid, 0);
+    }
+    catch {
+        return false;
+    }
+    // Defeat PID reuse: if the pid now belongs to a different process, it is not ours.
+    if (rec.headlessStartTime !== null) {
+        const now = captureProcessStartTime(rec.headlessPid);
+        if (now !== null && now !== rec.headlessStartTime)
+            return false;
+    }
+    return true;
+}
+/**
+ * Presence for a session id from the detach store alone:
+ *   - no record            -> undefined (caller decides: `attached` for a live
+ *                             interactive row, nothing for cloud/team rows)
+ *   - record + pid alive    -> `background` (headless continuation running)
+ *   - record + pid exited   -> `parked` (the run finished; transcript is durable)
+ */
+export function presenceFromStore(sessionId) {
+    const rec = readDetachRecord(sessionId);
+    if (!rec)
+        return undefined;
+    return isHeadlessAlive(rec) ? 'background' : 'parked';
+}