@phnx-labs/agents-cli 1.20.50 → 1.20.51

package/dist/lib/hooks/cache.js

@@ -105,13 +105,19 @@ export function getHookShimPath(name) {
 /**
  * Generate (or refresh) the shim script for a hook. Idempotent — only writes
  * when the content differs from what's on disk. Returns the absolute shim path.
+ *
+ * A shim is generated when the hook opts into caching (`cache`) and/or declares
+ * `matches:` predicates. When `matches` is present the shim gates execution on
+ * those predicates before running the underlying script (see `renderShim`);
+ * when `cache` is absent the shim is a thin pass-through wrapper that only
+ * applies the gate and forwards stdin/stdout unchanged.
  */
 export function generateHookShim(args) {
     const shimsDir = args.paths?.shimsDir ?? getHookShimsDir();
     const cacheDir = args.paths?.cacheDir ?? getHookCacheDir();
     const logsDir = args.paths?.logsDir ?? getLogsDir();
     const shimPath = resolveContainedHookShimPath(shimsDir, args.name);
-    const content = renderShim(args.name, args.scriptPath, args.cache, { cacheDir, logsDir });
+    const content = renderShim(args.name, args.scriptPath, args.cache ?? null, args.matches, { cacheDir, logsDir });
     fs.mkdirSync(shimsDir, { recursive: true });
     let existing = null;
     if (fs.existsSync(shimPath)) {
@@ -132,24 +138,204 @@ export function generateHookShim(args) {
     }
     return shimPath;
 }
+/**
+ * The matches: gate, as a self-contained Python program run once per fire.
+ *
+ * Reads the hook's `matches:` block from $MATCHES_JSON and the event JSON from
+ * stdin, then prints `FIRE` or `SKIP`. A faithful port of `shouldFire()` in
+ * src/lib/hooks/match.ts — all declared predicates AND together, an empty block
+ * always fires, and the same ReDoS guard (`isSafeHookRegex`) rejects unsafe
+ * regexes to `SKIP`. Kept in double-quotes/apostrophe-free so it survives being
+ * embedded in a single-quoted `python -c '...'` argument in the shim. Behavioural
+ * parity with shouldFire() is pinned by a conformance test (match-parity.test.ts).
+ *
+ * On any exception it does NOT print SKIP — the shim treats a missing/garbled
+ * verdict as FIRE (fail-open), so a broken gate never silently disables a hook.
+ */
+const GATE_PY = `import json, os, re, subprocess, sys
+
+def arr(v):
+    if v is None:
+        return []
+    return v if isinstance(v, list) else [v]
+
+def max_group_depth(src):
+    depth = 0
+    mx = 0
+    escaped = False
+    in_class = False
+    for ch in src:
+        if escaped:
+            escaped = False
+            continue
+        if ch == chr(92):
+            escaped = True
+            continue
+        if ch == "[":
+            in_class = True
+            continue
+        if ch == "]":
+            in_class = False
+            continue
+        if in_class:
+            continue
+        if ch == "(":
+            depth += 1
+            if depth > mx:
+                mx = depth
+        elif ch == ")" and depth > 0:
+            depth -= 1
+    return mx
+
+_NESTED = re.compile(r"\\((?:\\?:)?[^)]*[*+][?+*{,\\d}]*[^)]*\\)\\s*(?:[+*]|\\{\\d*,?\\d*\\})")
+
+def is_safe(src):
+    if len(src) > 200:
+        return False
+    if max_group_depth(src) > 3:
+        return False
+    if _NESTED.search(src):
+        return False
+    return True
+
+def compile_rx(src):
+    if not is_safe(src):
+        return None
+    try:
+        return re.compile(src)
+    except re.error:
+        return None
+
+def find_root(start):
+    d = os.path.abspath(start)
+    while True:
+        if os.path.exists(os.path.join(d, ".git")):
+            return d
+        parent = os.path.dirname(d)
+        if parent == d:
+            return None
+        d = parent
+
+def git_dirty(cwd):
+    try:
+        out = subprocess.run(
+            ["git", "status", "--porcelain"],
+            cwd=cwd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+        )
+        return len(out.stdout.decode().strip()) > 0
+    except Exception:
+        return False
+
+def should_fire():
+    m = json.loads(os.environ.get("MATCHES_JSON") or "{}")
+    if not m:
+        return True
+    try:
+        inp = json.load(sys.stdin)
+    except Exception:
+        inp = {}
+    cwd = inp.get("cwd") or os.getcwd()
+
+    v = m.get("prompt_contains")
+    if v is not None:
+        if v not in (inp.get("prompt") or ""):
+            return False
+
+    v = m.get("prompt_matches")
+    if v is not None:
+        rx = compile_rx(v)
+        if rx is None or not rx.search(inp.get("prompt") or ""):
+            return False
+
+    v = m.get("tool_name")
+    if v is not None:
+        allowed = arr(v)
+        if allowed:
+            tn = inp.get("tool_name")
+            if not tn or tn not in allowed:
+                return False
+
+    v = m.get("tool_args_match")
+    if v is not None:
+        ta = inp.get("tool_args")
+        ser = ta if isinstance(ta, str) else json.dumps(ta if ta is not None else "", separators=(",", ":"))
+        rx = compile_rx(v)
+        if rx is None or not rx.search(ser):
+            return False
+
+    v = m.get("cwd_includes")
+    if v is not None:
+        needles = arr(v)
+        if needles and not any(n in cwd for n in needles):
+            return False
+
+    v = m.get("project_has")
+    if v is not None:
+        root = find_root(cwd)
+        if not root or not os.path.exists(os.path.join(root, v)):
+            return False
+
+    v = m.get("git_dirty")
+    if v is not None:
+        if bool(v) != git_dirty(cwd):
+            return False
+
+    return True
+
+print("FIRE" if should_fire() else "SKIP")
+`;
+/**
+ * Gate-only pass-through tail: no caching, just run the underlying script with
+ * stdin forwarded and stdout/exit code propagated, plus one timing log line.
+ * Used when a hook declares \`matches:\` but no \`cache:\`.
+ */
+const PASSTHROUGH_TAIL = `now_ns() { "$PY" -c 'import time; print(int(time.time()*1e9))'; }
+START_NS=$(now_ns)
+EXIT=0
+if printf '%s' "$STDIN_PAYLOAD" | "$SOURCE"; then
+  EXIT=0
+else
+  EXIT=$?
+fi
+END_NS=$(now_ns)
+MS=$(( (END_NS - START_NS) / 1000000 ))
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+LOG_FILE="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
+printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":%d,"cache":"%s","exit":%d}\\n' \\
+  "$TS" "$HOOK_NAME" "$MS" "none" "$EXIT" >>"$LOG_FILE" 2>/dev/null || true
+
+exit "$EXIT"`;
 /**
  * Render the bash shim. Bash 3.2-compatible (macOS default). Uses Python for
  * hashing + monotonic-ish nanosecond timing + portable mtime, resolved at
  * runtime (python3, then python) so a Windows Microsoft Store `python3` alias
  * stub — which exits non-zero without running — doesn't silently break caching.
+ *
+ * When `matches` is set, an early gate block evaluates the `matches:` predicates
+ * against the event JSON on stdin and exits 0 without running the script when
+ * they don't hold — this is the runtime enforcement of the documented `matches:`
+ * gating (mirrors `shouldFire()` in match.ts). When `cache` is null the shim is
+ * a gate-only pass-through: it forwards stdin to the script and its stdout back,
+ * with no cache read/write.
  */
-function renderShim(name, scriptPath, cache, paths) {
-    const ttl = typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0);
-    const key = cache.key ?? 'global';
-    const prefetch = cache.prefetch ?? 'none';
+function renderShim(name, scriptPath, cache, matches, paths) {
+    const ttl = cache ? (typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0)) : 0;
+    const key = cache?.key ?? 'global';
+    const prefetch = cache?.prefetch ?? 'none';
     const { cacheDir, logsDir } = paths;
+    const hasMatches = matches != null && Object.keys(matches).length > 0;
+    const matchesJson = hasMatches ? JSON.stringify(matches) : '';
     // sh-escape: wrap in single quotes, escape any embedded single quotes.
     const q = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+    const cacheHeader = cache
+        ? `# Cache: key=${key} ttl=${ttl}s prefetch=${prefetch}`
+        : `# Cache: none (gate-only pass-through)`;
+    const matchesHeader = hasMatches ? `\n# Matches: ${matchesJson}` : '';
     return `#!/usr/bin/env bash
 # GENERATED by agents-cli. Do not edit — re-run \`agents hooks sync\` to refresh.
 # Hook: ${name}
 # Source: ${scriptPath}
-# Cache: key=${key} ttl=${ttl}s prefetch=${prefetch}
+${cacheHeader}${matchesHeader}
 set -u
 
 HOOK_NAME=${q(name)}
@@ -159,6 +345,7 @@ LOGS_DIR=${q(logsDir)}
 TTL=${ttl}
 PREFETCH=${q(prefetch)}
 KEY_MODE=${q(key)}
+MATCHES_JSON=${q(matchesJson)}
 
 mkdir -p "$CACHE_DIR" "$LOGS_DIR"
 
@@ -178,7 +365,33 @@ done
 # Read stdin once (Claude/Codex/Gemini pass JSON on stdin to every hook).
 STDIN_PAYLOAD="$(cat || true)"
 
-# Portable sha1 — \`shasum\` is Perl, missing on minimal Linux images;
+# --- matches: gate (issue #744 / RUSH-1506) -------------------------------
+# Enforce the hook's declared \`matches:\` predicates at fire time. Mirrors
+# shouldFire() in src/lib/hooks/match.ts: all declared predicates AND together;
+# an empty/absent block always fires. When the predicates don't hold we exit 0
+# WITHOUT running the script (a skipped hook is not an error). Fail-open: any
+# gate-eval error runs the script, so a broken predicate can never silently
+# disable a safety hook (e.g. git-guard).
+if [ -n "$MATCHES_JSON" ]; then
+  _GATE="$(printf '%s' "$STDIN_PAYLOAD" | MATCHES_JSON="$MATCHES_JSON" "$PY" -c ${q(GATE_PY)} 2>/dev/null || printf FIRE)"
+  [ -z "$_GATE" ] && _GATE=FIRE
+  if [ "$_GATE" = SKIP ]; then
+    _TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    _LOG_FILE="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
+    printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":0,"cache":"skip","exit":0}\\n' \\
+      "$_TS" "$HOOK_NAME" >>"$_LOG_FILE" 2>/dev/null || true
+    exit 0
+  fi
+fi
+${cache ? CACHE_TAIL : PASSTHROUGH_TAIL}
+`;
+}
+/**
+ * Cache tail: the full cache lookup / stale-while-revalidate / timing machinery.
+ * Emitted only when the hook opts into \`cache:\`. (When only \`matches:\` is set,
+ * PASSTHROUGH_TAIL runs instead — no cache read/write.)
+ */
+const CACHE_TAIL = `# Portable sha1 — \`shasum\` is Perl, missing on minimal Linux images;
 # \`sha1sum\` is coreutils, missing on macOS. Truncate to 12 hex chars.
 sha1_12() { "$PY" -c 'import hashlib,sys; print(hashlib.sha1(sys.stdin.read().encode()).hexdigest()[:12])'; }
 
@@ -267,7 +480,6 @@ printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":%d,"cache":"%s","exit":%
 
 exit "$EXIT"
 `;
-}
 /**
  * Remove a hook's shim. Called by the registrar's garbage collection when a
  * hook is renamed/deleted or has its `cache:` field removed.

package/dist/lib/hooks.js

@@ -153,10 +153,12 @@ import { getHookShimsDir } from './state.js';
 /**
  * Resolve the command path to register for a hook.
  *
- * Returns either the raw script path (no `cache:` set, legacy behavior) or
- * the path to a generated caching/timing shim. The shim is written as a
- * side effect when `cache:` is configured. The agent-native settings file
- * gets the same shape either way — just a different command path.
+ * Returns either the raw script path (neither `cache:` nor `matches:` set,
+ * legacy behavior) or the path to a generated wrapper shim. The shim is written
+ * as a side effect when `cache:` and/or `matches:` is configured — it enforces
+ * the `matches:` gate at fire time and layers the caching/timing machinery when
+ * `cache:` is set. The agent-native settings file gets the same shape either
+ * way — just a different command path.
  */
 function resolveHookCommand(name, hookDef, resolveScript) {
     const scriptPath = resolveScript(hookDef.script);
@@ -165,13 +167,20 @@ function resolveHookCommand(name, hookDef, resolveScript) {
     if (!isValidHookShimName(name))
         return null;
     const cache = parseCacheConfig(hookDef.cache);
-    if (!cache) {
-        // No caching opted in — make sure a previously generated shim from an
-        // earlier `cache:` config is gone so the JSONL doesn't keep claiming hits.
+    const matches = hookDef.matches;
+    const hasMatches = matches != null && Object.keys(matches).length > 0;
+    if (!cache && !hasMatches) {
+        // No caching and no matches: gate opted in — make sure a previously
+        // generated shim from an earlier `cache:`/`matches:` config is gone so the
+        // JSONL doesn't keep claiming hits.
         removeHookShim(name);
         return toPortableCommand(scriptPath);
     }
-    return toPortableCommand(generateHookShim({ name, scriptPath, cache }));
+    // A shim is generated when the hook opts into caching and/or declares
+    // `matches:` predicates. The shim enforces the `matches:` gate at fire time
+    // (skipping the script when predicates don't hold) and, when `cache:` is set,
+    // layers the cache/timing machinery on top.
+    return toPortableCommand(generateHookShim({ name, scriptPath, cache, matches }));
 }
 /**
  * Extensions that are NEVER hooks — docs, configuration, plain data. A file

package/dist/lib/platform/exec.d.ts

@@ -14,7 +14,10 @@ export declare function needsWindowsShell(binary: string, platform?: NodeJS.Plat
  * Resolve an executable name to its absolute path via the OS PATH search, or
  * `null` if not found. On Windows `where` can return several lines (one per
  * PATHEXT match, e.g. `agents.cmd` and `agents.ps1`) — the first is the one the
- * shell would actually run, matching `which` semantics on POSIX.
+ * shell would actually run, matching `which` semantics on POSIX. stderr is
+ * dropped: a miss is an expected outcome here, and `where.exe` announces every
+ * miss on stderr ("INFO: Could not find files..."), which would otherwise leak
+ * into the caller's terminal once per probe.
  */
 export declare function findExecutable(name: string, platform?: NodeJS.Platform): string | null;
 /**

package/dist/lib/platform/exec.js

@@ -27,11 +27,17 @@ export function needsWindowsShell(binary, platform = process.platform) {
  * Resolve an executable name to its absolute path via the OS PATH search, or
  * `null` if not found. On Windows `where` can return several lines (one per
  * PATHEXT match, e.g. `agents.cmd` and `agents.ps1`) — the first is the one the
- * shell would actually run, matching `which` semantics on POSIX.
+ * shell would actually run, matching `which` semantics on POSIX. stderr is
+ * dropped: a miss is an expected outcome here, and `where.exe` announces every
+ * miss on stderr ("INFO: Could not find files..."), which would otherwise leak
+ * into the caller's terminal once per probe.
  */
 export function findExecutable(name, platform = process.platform) {
     try {
-        const out = execFileSync(whichCommand(platform), [name], { encoding: 'utf-8' });
+        const out = execFileSync(whichCommand(platform), [name], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
         const first = out.trim().split(/\r?\n/)[0]?.trim();
         return first || null;
     }

package/dist/lib/resources.d.ts

@@ -74,11 +74,3 @@ export interface GetAgentResourcesOptions {
  * This is the source of truth - not the tracking data in agents.yaml.
  */
 export declare function getAgentResources(agentId: AgentId, options?: GetAgentResourcesOptions): AgentResources;
-/**
- * Get resources for all agents.
- */
-export declare function getAllAgentResources(agentIds: AgentId[], options?: GetAgentResourcesOptions & {
-    cliStates?: Record<AgentId, {
-        installed: boolean;
-    }>;
-}): AgentResources[];

package/dist/lib/resources.js

@@ -180,13 +180,3 @@ export function getAgentResources(agentId, options = {}) {
         workflows,
     };
 }
-/**
- * Get resources for all agents.
- */
-export function getAllAgentResources(agentIds, options = {}) {
-    const { cliStates, ...restOptions } = options;
-    return agentIds.map((agentId) => {
-        const cliInstalled = cliStates?.[agentId]?.installed ?? true;
-        return getAgentResources(agentId, { ...restOptions, cliInstalled });
-    });
-}

package/dist/lib/runner.js

@@ -74,8 +74,16 @@ export function buildJobCommand(config, resolvedPrompt) {
         appendModelAndReasoning(cmd, config);
     }
     if (config.agent === 'codex') {
-        if (mode === 'edit') {
-            cmd.push('--dangerously-bypass-approvals-and-sandbox');
+        if (mode === 'plan') {
+            // The template defaults to workspace-write; plan means read-only.
+            const sbIndex = cmd.indexOf('--sandbox');
+            if (sbIndex !== -1)
+                cmd[sbIndex + 1] = 'read-only';
+        }
+        else if (mode === 'edit' || mode === 'auto') {
+            // Keep the workspace-write sandbox — no approval bypass; only skip drops
+            // the guardrails. Re-enable network, which workspace-write turns off.
+            cmd.push('-c', 'sandbox_workspace_write.network_access=true');
         }
         else if (mode === 'skip') {
             // Remove sandbox restriction, just --dangerously-bypass-approvals-and-sandbox

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

@@ -1,5 +1,5 @@
 import { type PidSessionEntry } from './pid-registry.js';
-import { type SessionActivity, type AwaitingReason, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
+import { type SessionActivity, type AwaitingReason, type StructuredQuestion, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
 import { type SessionProvenance } from './provenance.js';
 /**
  * Per-PID `lsof` probes run bounded and staggered rather than as one parallel
@@ -30,6 +30,16 @@ export interface ActiveSession {
     activity?: SessionActivity;
     /** Why the agent is waiting, when activity is waiting_input. */
     awaitingReason?: AwaitingReason;
+    /** The structured decision (question/plan/permission + options) the agent is waiting on. */
+    question?: StructuredQuestion;
+    /**
+     * Plan markdown from the last `ExitPlanMode` tool call. Present when the
+     * transcript ever entered plan-review; `awaitingReason === 'plan_review'`
+     * says whether it is still pending.
+     */
+    plan?: string;
+    /** Last few assistant turns (most-recent last), for at-a-glance context in the UI. */
+    tail?: string[];
     /** PR opened during the session. */
     pr?: DetectedPr;
     /** Worktree the session runs in. */

package/dist/lib/session/active.js

@@ -236,6 +236,9 @@ function applyState(base, state, fallbackFile) {
         status: statusFromActivity(state.activity),
         activity: state.activity,
         awaitingReason: state.awaitingReason,
+        question: state.question,
+        plan: state.plan,
+        tail: state.tail,
         // Prefer the live preview (latest turn); keep the first-prompt topic as a fallback.
         preview: state.preview ?? base.preview,
         pr: state.pr,

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

@@ -35,6 +35,7 @@ export interface SessionRow {
     pr_number: number | null;
     worktree_slug: string | null;
     ticket_id: string | null;
+    plan: string | null;
 }
 /** File stat snapshot used to detect changes between scan runs. */
 export interface ScanStamp {
@@ -199,10 +200,6 @@ export interface TopCostSession {
  * vanished, mirroring querySessions' liveness filter.
  */
 export declare function topSessionsByCost(n: number, options?: QueryOptions): TopCostSession[];
-/** Return the set of all file paths currently tracked in the sessions table. */
-export declare function getAllFilePaths(): Set<string>;
-/** Look up sessions by their source file paths. */
-export declare function getSessionsByFilePaths(paths: string[]): Map<string, SessionMeta>;
 /** Look up a single session by its unique ID. */
 export declare function getSessionById(id: string): SessionMeta | null;
 /**

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 = 10;
+const SCHEMA_VERSION = 11;
 /**
  * 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`
@@ -64,7 +64,8 @@ CREATE TABLE IF NOT EXISTS sessions (
   pr_url TEXT,
   pr_number INTEGER,
   worktree_slug TEXT,
-  ticket_id TEXT
+  ticket_id TEXT,
+  plan TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_sessions_timestamp ON sessions(timestamp DESC);
 CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd);
@@ -213,6 +214,16 @@ function migrateSchema(db, fromVersion) {
             db.exec(`ALTER TABLE sessions DROP COLUMN name`);
         }
     }
+    if (fromVersion < 11) {
+        // v10 → v11: the Claude scanner now captures the ExitPlanMode plan markdown
+        // at scan time so `agents sessions --json` can surface it without forcing
+        // consumers (the Factory NEEDS-YOU panel) to re-read raw JSONL. Additive
+        // column; rescan to backfill.
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some(c => c.name === 'plan'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN plan TEXT`);
+        db.exec(`DELETE FROM scan_ledger;`);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -429,13 +440,13 @@ const upsertSessionStmt = (db) => db.prepare(`
     project, cwd, git_branch, topic, label, message_count, token_count,
     cost_usd, duration_ms,
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin,
-    pr_url, pr_number, worktree_slug, ticket_id
+    pr_url, pr_number, worktree_slug, ticket_id, plan
   ) VALUES (
     @id, @short_id, @agent, @version, @account, @timestamp, @last_activity,
     @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
     @cost_usd, @duration_ms,
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin,
-    @pr_url, @pr_number, @worktree_slug, @ticket_id
+    @pr_url, @pr_number, @worktree_slug, @ticket_id, @plan
   )
   ON CONFLICT(id) DO UPDATE SET
     short_id = excluded.short_id,
@@ -461,7 +472,8 @@ const upsertSessionStmt = (db) => db.prepare(`
     pr_url = excluded.pr_url,
     pr_number = excluded.pr_number,
     worktree_slug = excluded.worktree_slug,
-    ticket_id = excluded.ticket_id
+    ticket_id = excluded.ticket_id,
+    plan = excluded.plan
 `);
 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 (?, ?, ?, ?, ?)`);
@@ -509,6 +521,7 @@ export function upsertSession(meta, content, scan) {
         pr_number: meta.prNumber ?? null,
         worktree_slug: meta.worktreeSlug ?? null,
         ticket_id: meta.ticketId ?? null,
+        plan: meta.plan ?? null,
     };
     const txn = db.transaction(() => {
         upsert.run(row);
@@ -597,6 +610,7 @@ export function upsertSessionsBatch(entries) {
                     pr_number: meta.prNumber ?? null,
                     worktree_slug: meta.worktreeSlug ?? null,
                     ticket_id: meta.ticketId ?? null,
+                    plan: meta.plan ?? null,
                 });
                 delText.run(meta.id);
                 insText.run(meta.id, meta.label ?? '', meta.topic ?? '', meta.project ?? '', content ?? '');
@@ -769,6 +783,7 @@ function rowToMeta(row) {
         prNumber: row.pr_number ?? undefined,
         worktreeSlug: row.worktree_slug ?? undefined,
         ticketId: row.ticket_id ?? undefined,
+        plan: row.plan ?? undefined,
     };
 }
 /**
@@ -954,26 +969,6 @@ export function topSessionsByCost(n, options = {}) {
         durationMs: r.duration_ms ?? 0,
     }));
 }
-/** Return the set of all file paths currently tracked in the sessions table. */
-export function getAllFilePaths() {
-    const db = getDB();
-    const rows = db.prepare(`SELECT file_path FROM sessions`).all();
-    return new Set(rows.map(r => r.file_path));
-}
-/** Look up sessions by their source file paths. */
-export function getSessionsByFilePaths(paths) {
-    if (paths.length === 0)
-        return new Map();
-    const db = getDB();
-    const placeholders = paths.map(() => '?').join(',');
-    const rows = db
-        .prepare(`SELECT * FROM sessions WHERE file_path IN (${placeholders})`)
-        .all(...paths);
-    const result = new Map();
-    for (const row of rows)
-        result.set(row.file_path, rowToMeta(row));
-    return result;
-}
 /** Look up a single session by its unique ID. */
 export function getSessionById(id) {
     const db = getDB();

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

@@ -68,6 +68,8 @@ interface ClaudeSessionScan {
     createdTickets?: string[];
     /** Team name this session SPAWNED via `agents teams create/add` (not team-of-origin). */
     spawnedTeam?: string;
+    /** Plan markdown from the last ExitPlanMode tool call (Claude sessions only). */
+    plan?: string;
 }
 /**
  * Discover sessions. Scans only files whose (mtime, size) have changed since
@@ -152,8 +154,6 @@ export declare function readCodexMeta(filePath: string, resolveAccount?: () => s
 } | null>;
 /** Stream a Claude JSONL file and extract scan-level metadata (timestamp, cwd, topic, tokens). */
 export declare function scanClaudeSession(filePath: string): Promise<ClaudeSessionScan>;
-/** Read up to maxLines non-empty lines from the beginning of a file. */
-export declare function readFirstLines(filePath: string, maxLines: number): Promise<string[]>;
 /** Parse a single Kimi session state.json file to extract session metadata. */
 export declare function readKimiMeta(filePath: string): {
     meta: SessionMeta;