mixdog 0.9.37 → 0.9.39

package/scripts/routing-corpus.mjs

@@ -5,7 +5,7 @@
 // set by re-running --eval before/after (input constant, only rules change).
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, resolve } from 'node:path';
+import { basename, resolve, win32 } from 'node:path';
 import { resolvePluginData } from '../src/runtime/shared/plugin-paths.mjs';
 
 function argValue(name, fallback = null) {
@@ -64,7 +64,10 @@ function argsSummary(tool, args) {
   switch (tool) {
     case 'grep': return clip(Array.isArray(args.pattern) ? `[${args.pattern.length}]${args.pattern[0]}` : args.pattern);
     case 'read': return clip(basename(String(Array.isArray(args.path) ? args.path[0] : args.path || '')));
-    case 'code_graph': return clip(`${args.mode || '?'}:${args.symbol || args.file || ''}`);
+    case 'code_graph': {
+      const values = args.symbols || args.files || args.symbol || args.file || '';
+      return clip(`${args.mode || '?'}:${Array.isArray(values) ? `[${values.length}]${values[0] || ''}` : values}`);
+    }
     case 'explore': return arr(args.query);
     case 'find': return clip(args.query);
     case 'glob': return clip(Array.isArray(args.pattern) ? args.pattern[0] : args.pattern);
@@ -75,9 +78,119 @@ function argsSummary(tool, args) {
   }
 }
 
-function normGrep(args) {
-  const p = args?.pattern;
-  return String(Array.isArray(p) ? p.join('|') : (p ?? '')).trim().toLowerCase();
+function isMutation(tool) {
+  return ['apply_patch', 'edit', 'edit_many', 'write', 'shell'].includes(tool);
+}
+function failed(row) {
+  const kind = field(row, 'result_kind');
+  return /^(error|failed|failure|command-exit|timeout|permission)$/i.test(String(kind || ''));
+}
+function targetValues(tool, args) {
+  if (!args || typeof args !== 'object') return [];
+  let key = 'path';
+  if (tool === 'code_graph') {
+    const fileMode = ['overview', 'imports', 'dependents', 'related', 'impact'].includes(args.mode);
+    const symbolMode = ['find_symbol', 'symbol_search', 'search', 'references', 'callers', 'callees'].includes(args.mode);
+    key = fileMode || (args.mode === 'symbols' && (args.files != null || args.file != null))
+      ? (args.files != null ? 'files' : 'file')
+      : symbolMode || args.mode === 'symbols' ? (args.symbols != null ? 'symbols' : 'symbol') : 'file';
+  } else if (tool === 'grep' || tool === 'glob') key = 'pattern';
+  else if (tool === 'find' || tool === 'explore') key = 'query';
+  const value = args[key];
+  return Array.isArray(value) ? value : value == null ? [] : [value];
+}
+function batchFields(tool, args) {
+  if (tool === 'grep' || tool === 'glob') return ['pattern', 'path'];
+  if (tool === 'code_graph') {
+    const fileMode = ['overview', 'imports', 'dependents', 'related', 'impact'].includes(args?.mode);
+    const symbolMode = ['find_symbol', 'symbol_search', 'search', 'references', 'callers', 'callees'].includes(args?.mode);
+    if (symbolMode && args?.files == null && args?.file == null) return ['symbols', 'symbol'];
+    if (symbolMode) return [];
+    return [fileMode || args?.mode === 'symbols'
+      ? (args?.files != null ? 'files' : args?.file != null ? 'file' : args?.symbols != null ? 'symbols' : 'symbol')
+      : null].filter(Boolean);
+  }
+  return [tool === 'read' || tool === 'list' ? 'path' : tool === 'find' || tool === 'explore' ? 'query' : null].filter(Boolean);
+}
+function compatibleBatchCalls(tool, left, right) {
+  if (tool === 'read') {
+    const nonBatch = Object.keys({ ...left, ...right }).filter((key) => !['path', 'offset', 'limit'].includes(key));
+    return nonBatch.every((key) => JSON.stringify(left?.[key]) === JSON.stringify(right?.[key]));
+  }
+  const fields = batchFields(tool, left);
+  if (!fields.length) return false;
+  const differing = fields.filter((key) => JSON.stringify(left?.[key]) !== JSON.stringify(right?.[key]));
+  if (differing.length !== 1) return false;
+  const batchKey = differing[0];
+  if ((Array.isArray(left?.[batchKey]) && left[batchKey].length !== 1) || (Array.isArray(right?.[batchKey]) && right[batchKey].length !== 1)) return false;
+  return Object.keys({ ...left, ...right }).filter((key) => !fields.includes(key))
+    .every((key) => JSON.stringify(left?.[key]) === JSON.stringify(right?.[key]));
+}
+function readTargets(args) {
+  if (!args || typeof args !== 'object') return null;
+  const values = Array.isArray(args.path) ? args.path : [args.path];
+  return values.map((value) => {
+    if (typeof value === 'string') return { path: value, offset: args.offset ?? null, limit: args.limit ?? null };
+    if (value && typeof value === 'object' && typeof value.path === 'string') {
+      return { path: value.path, offset: value.offset ?? null, limit: value.limit ?? null };
+    }
+    return null;
+  }).filter(Boolean);
+}
+function batchSpec(tool, args, forcedField = null) {
+  if (!args || typeof args !== 'object') return null;
+  if (tool === 'code_graph') {
+    if (!['symbols', 'find_symbol', 'symbol_search', 'search', 'references', 'callers', 'callees', 'overview', 'imports', 'dependents', 'related', 'impact'].includes(args.mode)) return null;
+    const fileMode = ['overview', 'imports', 'dependents', 'related', 'impact'].includes(args.mode);
+    const symbolMode = ['find_symbol', 'symbol_search', 'search', 'references', 'callers', 'callees'].includes(args.mode);
+    if (symbolMode && (args.files != null || args.file != null)) return null;
+    const field = fileMode || (args.mode === 'symbols' && (args.files != null || args.file != null))
+      ? (args.files != null ? 'files' : 'file')
+      : (args.symbols != null ? 'symbols' : 'symbol');
+    return { field, values: targetValues(tool, args) };
+  }
+  const fieldName = forcedField || (tool === 'read' || tool === 'list' ? 'path' : tool === 'grep' || tool === 'glob' ? 'pattern' : tool === 'find' || tool === 'explore' ? 'query' : null);
+  if (!fieldName) return null;
+  const value = args[fieldName];
+  return { field: fieldName, values: Array.isArray(value) ? value : value == null ? [] : [value] };
+}
+function sameIterationBatchObservations(sequence) {
+  let found = false;
+  for (let i = 0; i < sequence.length; i += 1) {
+    const first = sequence[i];
+    if (isMutation(first.tool) || first.it == null) continue;
+    const group = [first];
+    for (let j = i + 1; j < sequence.length; j += 1) {
+      const next = sequence[j];
+      if (next.it !== first.it) break;
+      if (isMutation(next.tool)) break;
+      group.push(next);
+    }
+    for (const candidate of ['read', 'grep', 'find', 'glob', 'list', 'explore', 'code_graph']) {
+      if (candidate === 'read') {
+        const calls = group.filter((entry) => entry.tool === 'read' && !entry.failed).map((entry) => ({ entry, targets: readTargets(entry.rawArgs) })).filter(({ targets }) => targets?.length);
+        if (calls.some(({ entry, targets }, index) => calls.some(({ entry: other, targets: otherTargets }, otherIndex) => (
+          index < otherIndex
+          && compatibleBatchCalls('read', entry.rawArgs, other.rawArgs)
+          && targets.some((target) => otherTargets.some((otherTarget) => JSON.stringify(target) !== JSON.stringify(otherTarget)))
+        )))) found = true;
+        continue;
+      }
+      const firstArgs = group.find((entry) => entry.tool === candidate && !entry.failed)?.rawArgs;
+      for (const field of batchFields(candidate, firstArgs || {})) {
+        const calls = group.filter((entry) => entry.tool === candidate && !entry.failed).map((entry) => ({ entry, spec: batchSpec(candidate, entry.rawArgs, field) })).filter(({ spec }) => spec && spec.values.length === 1);
+        if (calls.length < 2) continue;
+        const distinct = new Set(calls.map(({ spec }) => JSON.stringify(spec.values[0])));
+        const compatiblePair = calls.some(({ entry, spec }, index) => calls.some(({ entry: other, spec: otherSpec }, otherIndex) => (
+          index < otherIndex
+          && JSON.stringify(spec.values[0]) !== JSON.stringify(otherSpec.values[0])
+          && compatibleBatchCalls(candidate, entry.rawArgs, other.rawArgs)
+        )));
+      if (distinct.size >= 2 && compatiblePair) found = true;
+      }
+    }
+  }
+  return found ? ['same_turn_batch_opportunity'] : [];
 }
 
 // shell used to INSPECT the filesystem (read/list/search/exists) instead of a
@@ -104,32 +217,98 @@ function buildCase(sid, toolRows) {
     const it = field(r, 'iteration');
     if (it != null) iters.add(it);
     const tool = field(r, 'tool_name') || '?';
-    sequence.push({ it: it ?? null, tool, args: argsSummary(tool, field(r, 'tool_args')), rawArgs: field(r, 'tool_args') });
+    const rawArgs = field(r, 'tool_args');
+    const summaryArgs = rawArgs;
+    sequence.push({
+      it: it ?? null,
+      tool,
+      args: argsSummary(tool, rawArgs),
+      rawArgs,
+      inspectArgs: summaryArgs,
+      argsHash: field(r, 'tool_args_hash'),
+      resultKind: field(r, 'result_kind'),
+      resultLines: Number(field(r, 'result_lines_est') || 0),
+      coverage: field(r, 'grep_coverage'),
+      cwd: field(r, 'cwd') || '',
+      failed: failed(r),
+    });
   }
-  // per-iteration tool counts for serial detection
-  const perIt = new Map();
-  for (const s of sequence) { if (s.it == null) continue; perIt.set(s.it, (perIt.get(s.it) || 0) + 1); }
-  const itOrder = [...perIt.keys()].sort((a, b) => a - b);
-  let longestSingleRun = 0, run = 0;
-  for (const it of itOrder) { if (perIt.get(it) === 1) { run += 1; longestSingleRun = Math.max(longestSingleRun, run); } else run = 0; }
-
   const names = sequence.map((s) => s.tool);
-  const hasAnchor = names.some((n) => n === 'grep' || n === 'code_graph' || n === 'find' || n === 'read');
-  const exploreCalls = sequence.filter((s) => s.tool === 'explore');
   const flags = [];
-  if (exploreCalls.length && hasAnchor) flags.push('explore_overuse');
-  if (exploreCalls.some((s) => Array.isArray(s.rawArgs?.query))) flags.push('explore_multiquery');
-  if (names[0] === 'explore') flags.push('explore_first');
-  if (sequence.some((s) => s.tool === 'code_graph' && s.rawArgs?.mode === 'find_symbol' && !s.rawArgs?.file)) flags.push('find_symbol_noscope');
-  if (longestSingleRun >= 4) flags.push('serial_single_tool');
-  // read fragmentation
-  const readCounts = new Map();
-  for (const s of sequence) { if (s.tool !== 'read') continue; const k = String(s.rawArgs?.path ?? s.args); readCounts.set(k, (readCounts.get(k) || 0) + 1); }
-  if ([...readCounts.values()].some((c) => c >= 3)) flags.push('read_fragmentation');
-  // grep retry
-  const grepCounts = new Map();
-  for (const s of sequence) { if (s.tool !== 'grep') continue; const k = normGrep(s.rawArgs); if (!k) continue; grepCounts.set(k, (grepCounts.get(k) || 0) + 1); }
-  if ([...grepCounts.values()].some((c) => c >= 2)) flags.push('grep_retry');
+  const observations = [];
+  if (sequence.some((s) => s.tool === 'code_graph' && s.rawArgs?.mode === 'find_symbol' && !s.rawArgs?.file && !s.rawArgs?.files)) flags.push('find_symbol_noscope');
+  // Exact duplicate requests are the only relookup signal available in tool
+  // traces. Do not infer waste from counts, roles, turns, or explore→inspection:
+  // exploration followed by inspection can be the intended route.
+  const seenRequests = new Set();
+  const readWindows = [];
+  let pendingContextGrep = null;
+  for (const s of sequence) {
+    if (isMutation(s.tool)) {
+      seenRequests.clear();
+      readWindows.length = 0;
+      pendingContextGrep = null;
+      continue;
+    }
+    if (s.failed) continue;
+    if (['grep', 'read'].includes(s.tool)) {
+      const key = s.argsHash ? `${s.tool}:${s.argsHash}` : null;
+      const duplicate = key && seenRequests.has(key);
+      if (duplicate) flags.push(`${s.tool}_relookup`);
+      if (key) seenRequests.add(key);
+      if (s.tool === 'read' && !duplicate) {
+        const normalize = (value, cwd) => {
+          const raw = String(value);
+          const base = String(cwd || process.cwd());
+          const winStyle = /^[A-Za-z]:[\\/]/.test(raw) || /^[A-Za-z]:[\\/]/.test(base) || raw.includes('\\');
+          const resolved = (winStyle ? win32.resolve(base, raw) : resolve(base, raw)).replace(/\\/g, '/');
+          return winStyle ? resolved.toLowerCase() : resolved;
+        };
+        const bounded = (offset, limit) => Number.isFinite(Number(offset)) && Number(offset) >= 0
+          && Number.isFinite(Number(limit)) && Number(limit) > 0;
+        for (const target of readTargets(s.rawArgs) || []) {
+          const start = bounded(target.offset, target.limit) ? Number(target.offset) : 0;
+          const end = bounded(target.offset, target.limit) ? start + Number(target.limit) : Infinity;
+          const path = normalize(target.path, s.cwd);
+          if (!flags.includes('read_overlap') && readWindows.some((prior) => prior.path === path && start < prior.end && prior.start < end)) flags.push('read_overlap');
+          readWindows.push({ path, start, end });
+        }
+      }
+    }
+    if (s.tool === 'grep' && Array.isArray(s.coverage) && s.coverage.length) {
+      pendingContextGrep = s;
+    } else if (s.tool === 'read' && pendingContextGrep) {
+      // Coverage is emitted by the trace formatter from actual path:line
+      // output. Missing/boundedness-unknown coverage intentionally stays
+      // unclassified; whole-file reads are a documented residual limitation.
+      const pathArg = s.rawArgs?.path;
+      const bounded = (offset, limit) => Number.isFinite(Number(offset)) && Number(offset) >= 0
+        && Number.isFinite(Number(limit)) && Number(limit) > 0;
+      const region = typeof pathArg === 'string' && bounded(s.rawArgs.offset, s.rawArgs.limit)
+        ? { path: pathArg, start: Number(s.rawArgs.offset) + 1, end: Number(s.rawArgs.offset) + Number(s.rawArgs.limit) }
+        : pathArg && typeof pathArg === 'object' && pathArg.path && bounded(pathArg.offset, pathArg.limit)
+          ? { path: pathArg.path, start: Number(pathArg.offset) + 1, end: Number(pathArg.offset) + Number(pathArg.limit) }
+          : null;
+      if (region) {
+      const normalize = (value, cwd) => {
+        const raw = String(value);
+        const base = String(cwd || process.cwd());
+        const winStyle = /^[A-Za-z]:[\\/]/.test(raw) || /^[A-Za-z]:[\\/]/.test(base) || raw.includes('\\');
+        const resolved = resolve(base, raw).replace(/\\/g, '/');
+        return winStyle ? resolved.toLowerCase() : resolved;
+      };
+        const wanted = normalize(region.path, s.cwd || pendingContextGrep.cwd);
+        const covered = new Set((pendingContextGrep.coverage || [])
+          .filter((item) => normalize(item.path, pendingContextGrep.cwd) === wanted)
+          .map((item) => Number(item.line)));
+        let complete = true;
+        for (let line = region.start; line <= region.end; line += 1) if (!covered.has(line)) { complete = false; break; }
+        if (complete) flags.push('grep_context_then_read');
+      }
+      pendingContextGrep = null;
+    }
+  }
+  observations.push(...sameIterationBatchObservations(sequence));
   // shell used for filesystem inspection instead of dedicated tools
   if (sequence.some((s) => s.tool === 'shell' && isShellInspect(s.rawArgs?.command))) flags.push('shell_inspect');
 
@@ -137,17 +316,17 @@ function buildCase(sid, toolRows) {
     session_id: sid,
     short_id: shortId(sid),
     agent, model,
-    turns: iters.size || itOrder.length,
+    turns: iters.size,
     tools: sequence.length,
     first_tool: names[0] || null,
-    longest_single_run: longestSingleRun,
     flags,
+    observations,
     max_ts: Math.max(...sorted.map((r) => Number(r.ts || 0))),
-    sequence: sequence.map((s) => ({ it: s.it, tool: s.tool, args: s.args })),
+    sequence: sequence.map((s) => ({ it: s.it, tool: s.tool, args: s.args, result_kind: s.resultKind, result_lines_est: s.resultLines, grep_coverage: s.coverage })),
   };
 }
 
-const FLAG_KEYS = ['explore_overuse', 'explore_multiquery', 'explore_first', 'find_symbol_noscope', 'serial_single_tool', 'read_fragmentation', 'grep_retry', 'shell_inspect'];
+const FLAG_KEYS = ['find_symbol_noscope', 'read_relookup', 'read_overlap', 'grep_relookup', 'grep_context_then_read', 'missed_array_batch', 'shell_inspect'];
 
 function buildCorpus(rows, { limit, sinceTs, agentFilter }) {
   let filtered = rows.filter((r) => r.kind === 'tool' && sessionId(r));

package/scripts/session-orphan-sweep-test.mjs

@@ -0,0 +1,83 @@
+/**
+ * session-orphan-sweep-test.mjs — proves the periodic sweep reclaims mature
+ * closed tombstones that exist ON DISK but are ABSENT from the summary index.
+ *
+ * Regression guard for the pre-fix bug where sweepStaleSessions iterated only
+ * listStoredSessionSummaries() rows, so on-disk session files missing from a
+ * stale index were never visited and their tombstones accumulated forever.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+test('mature closed on-disk orphan absent from summary index gets tombstone-swept', async () => {
+    const dataDir = mkdtempSync(join(tmpdir(), 'mixdog-orphan-sweep-'));
+    process.env.MIXDOG_DATA_DIR = dataDir;
+    try {
+        const store = await import('../src/runtime/agent/orchestrator/session/store.mjs');
+        const { sweepStaleSessions, _sessionSummary, _writeSummaryIndex } = store;
+
+        const sessionsDir = join(dataDir, 'sessions');
+        mkdirSync(sessionsDir, { recursive: true });
+
+        const now = Date.now();
+        const TWO_HOURS = 2 * 60 * 60 * 1000;
+        const ONE_HOUR = 60 * 60 * 1000;
+
+        // (1) An INDEXED, fresh, open agent session — present in the summary
+        //     index so the index is non-empty (blocking any rebuild) and must
+        //     survive the sweep.
+        const indexed = {
+            id: 'sess_indexed_keep',
+            closed: false,
+            status: 'idle',
+            owner: 'agent:test',
+            updatedAt: now,
+            createdAt: now,
+            lastHeartbeatAt: now,
+            messages: [],
+        };
+        writeFileSync(join(sessionsDir, `${indexed.id}.json`), JSON.stringify(indexed));
+
+        // (2) An ORPHAN closed+mature tombstone — on disk, NOT in the index,
+        //     closed >1h ago. Only reachable if the sweep reconciles the index
+        //     candidate set with a direct directory scan.
+        const orphan = {
+            id: 'sess_orphan_tombstone',
+            closed: true,
+            status: 'closed',
+            owner: 'agent:test',
+            updatedAt: now - TWO_HOURS,
+            createdAt: now - TWO_HOURS,
+            messages: [],
+        };
+        writeFileSync(join(sessionsDir, `${orphan.id}.json`), JSON.stringify(orphan));
+
+        // Index contains ONLY the indexed session — the orphan is absent.
+        const rows = _writeSummaryIndex([_sessionSummary(indexed)]);
+        assert.equal(rows.length, 1, 'index seeded with exactly one row');
+        assert.ok(!rows.some((r) => r.id === orphan.id), 'orphan is absent from the summary index');
+
+        // Tombstone-only pass (no idle sweep) with a 1h maturity threshold.
+        const result = sweepStaleSessions({ sweepIdle: false, tombstoneMaxAgeMs: ONE_HOUR });
+
+        assert.equal(result.tombstonesCleaned, 1, 'the orphan tombstone was reclaimed');
+        assert.ok(
+            result.tombstoneDetails.some((d) => d.id === orphan.id),
+            'sweep reports the orphan id among tombstone deletions',
+        );
+        assert.ok(
+            !existsSync(join(sessionsDir, `${orphan.id}.json`)),
+            'orphan session file was unlinked from disk',
+        );
+        assert.ok(
+            existsSync(join(sessionsDir, `${indexed.id}.json`)),
+            'fresh open indexed session was preserved',
+        );
+    } finally {
+        try { rmSync(dataDir, { recursive: true, force: true }); } catch { /* ignore */ }
+        delete process.env.MIXDOG_DATA_DIR;
+    }
+});

package/scripts/session-sweep.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+/**
+ * session-sweep.mjs — DRY-RUN ONLY session-store retention reporter.
+ *
+ * Reports which session files a prune would reclaim WITHOUT touching disk:
+ * NO unlink, NO writes to session-summaries.json, NO mutation of store.mjs
+ * runtime behavior. It only reads.
+ *
+ * Reuses the real store helpers read-only:
+ *   - getPluginData()  → resolves the live data dir (…/.mixdog/data)
+ *   - summaryIndexPath()/listStoredSessionSummaries() → authoritative
+ *     per-session lifecycle rows (updatedAt/closed/status), avoiding a full
+ *     476MB JSON.parse of every session file.
+ *
+ * Candidate policy (conservative; keep everything else):
+ *   - closed/tombstoned sessions  (row.closed === true || status === 'closed')
+ *     ONLY when their closedAt/updatedAt is older than --min-closed-age-days
+ *     (default 7d) — a recently-closed session may still be resumed, so it is
+ *     kept until the gate elapses.
+ *   - OR sessions older than --max-age-days by updatedAt (default 30d)
+ * Thresholds are params:  --max-age-days=<n>  --min-closed-age-days=<n>  --now=<epochMs>
+ *
+ * This tool NEVER deletes. It only prints a report.
+ */
+import { existsSync, readdirSync, statSync } from 'fs';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { getPluginData } from '../src/runtime/agent/orchestrator/config.mjs';
+import {
+    summaryIndexPath,
+    listStoredSessionSummaries,
+} from '../src/runtime/agent/orchestrator/session/store.mjs';
+
+// ── Cheap top-level-only scalar scan ────────────────────────────────────────
+// Same depth-1 tokenizer idea as lifecycle-scan.mjs's scanTopLevelLifecycle
+// (bracket-depth + string-escape aware; the whole `messages` array is skipped
+// by depth counting, never parsed), extended to capture the lifecycle+age
+// scalars we classify on (closed/status/updatedAt/createdAt). This lets the
+// report read the AUTHORITATIVE per-file lifecycle without a full 476MB
+// JSON.parse and without depending on the (stale) summary index.
+const WANT = new Set(['closed', 'status', 'updatedAt', 'createdAt', 'closedAt']);
+function isWs(ch) { return ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r'; }
+function skipString(raw, i) {
+    const len = raw.length;
+    i++;
+    while (i < len) {
+        const ch = raw[i];
+        if (ch === '\\') { i += 2; continue; }
+        if (ch === '"') return i + 1;
+        i++;
+    }
+    return i;
+}
+function skipValue(raw, i) {
+    const len = raw.length;
+    const c = raw[i];
+    if (c === '"') return skipString(raw, i);
+    if (c === '{' || c === '[') {
+        let depth = 1; i++;
+        while (i < len && depth > 0) {
+            const ch = raw[i];
+            if (ch === '"') { i = skipString(raw, i); continue; }
+            if (ch === '{' || ch === '[') depth++;
+            else if (ch === '}' || ch === ']') depth--;
+            i++;
+        }
+        return i;
+    }
+    while (i < len && raw[i] !== ',' && raw[i] !== '}' && raw[i] !== ']' && !isWs(raw[i])) i++;
+    return i;
+}
+function scanTopLevelScalars(raw) {
+    const len = raw.length;
+    let i = 0;
+    while (i < len && isWs(raw[i])) i++;
+    if (raw[i] !== '{') return null;
+    i++;
+    const out = {};
+    while (i < len) {
+        while (i < len && isWs(raw[i])) i++;
+        if (i >= len) return out;
+        if (raw[i] === '}') return out;
+        if (raw[i] === ',') { i++; continue; }
+        if (raw[i] !== '"') return out;
+        const keyStart = i;
+        i = skipString(raw, i);
+        let key;
+        try { key = JSON.parse(raw.slice(keyStart, i)); } catch { return out; }
+        while (i < len && isWs(raw[i])) i++;
+        if (raw[i] !== ':') return out;
+        i++;
+        while (i < len && isWs(raw[i])) i++;
+        const valStart = i;
+        i = skipValue(raw, i);
+        if (WANT.has(key)) {
+            try { out[key] = JSON.parse(raw.slice(valStart, i)); } catch { /* ignore */ }
+        }
+    }
+    return out;
+}
+
+function parseArgs(argv) {
+    const out = { maxAgeDays: 30, minClosedAgeDays: 7, now: Date.now() };
+    for (const arg of argv) {
+        const m = /^--([^=]+)=(.*)$/.exec(arg);
+        if (!m) continue;
+        const [, key, val] = m;
+        if (key === 'max-age-days') out.maxAgeDays = Number(val);
+        else if (key === 'min-closed-age-days') out.minClosedAgeDays = Number(val);
+        else if (key === 'now') out.now = Number(val);
+    }
+    if (!Number.isFinite(out.maxAgeDays) || out.maxAgeDays < 0) out.maxAgeDays = 30;
+    if (!Number.isFinite(out.minClosedAgeDays) || out.minClosedAgeDays < 0) out.minClosedAgeDays = 7;
+    if (!Number.isFinite(out.now) || out.now <= 0) out.now = Date.now();
+    return out;
+}
+
+function fmtBytes(n) {
+    if (!Number.isFinite(n) || n <= 0) return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let i = 0;
+    let v = n;
+    while (v >= 1024 && i < units.length - 1) { v /= 1024; i += 1; }
+    return `${v.toFixed(i === 0 ? 0 : 2)} ${units[i]}`;
+}
+
+function fmtTs(ms) {
+    if (!Number.isFinite(ms) || ms <= 0) return 'n/a';
+    try { return new Date(ms).toISOString(); } catch { return String(ms); }
+}
+
+function main() {
+    const { maxAgeDays, minClosedAgeDays, now } = parseArgs(process.argv.slice(2));
+    const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
+    const minClosedAgeMs = minClosedAgeDays * 24 * 60 * 60 * 1000;
+
+    const dir = join(getPluginData(), 'sessions');
+    if (!existsSync(dir)) {
+        process.stdout.write(`[session-sweep] no sessions dir at ${dir}\n`);
+        return;
+    }
+
+    // Authoritative lifecycle rows (read-only). rebuildIfMissing:false so this
+    // report never triggers a summary-index write.
+    const rows = listStoredSessionSummaries({ rebuildIfMissing: false });
+    const rowById = new Map();
+    for (const r of rows) if (r?.id) rowById.set(r.id, r);
+
+    // Disk scan for sizes + mtime fallback. `.hb` sidecar bytes are attributed
+    // to their session so reclaimable bytes reflect the full on-disk footprint.
+    const files = readdirSync(dir);
+    const jsonFiles = files.filter((f) => f.endsWith('.json'));
+    const hbSizeById = new Map();
+    for (const f of files) {
+        if (!f.endsWith('.hb')) continue;
+        const id = f.slice(0, -3);
+        try { hbSizeById.set(id, statSync(join(dir, f)).size || 0); } catch { /* ignore */ }
+    }
+
+    let totalFiles = 0;
+    let totalBytes = 0;
+    const candidates = []; // { id, reason, updatedAt, bytes, inIndex }
+    let closedCount = 0;
+    let ageOnlyCount = 0;
+    let closedBytes = 0;
+    let ageOnlyBytes = 0;
+    let reclaimBytes = 0;
+    let scanFailFiles = 0;
+    let closedButFreshCount = 0; // closed, but within the min-closed-age gate → kept
+    let closedButFreshBytes = 0;
+    const fileIds = new Set();
+
+    for (const f of jsonFiles) {
+        const id = f.slice(0, -5);
+        fileIds.add(id);
+        const full = join(dir, f);
+        let size = 0;
+        let mtimeMs = 0;
+        try { const st = statSync(full); size = st.size || 0; mtimeMs = st.mtimeMs || 0; } catch { /* skip */ }
+        const hb = hbSizeById.get(id) || 0;
+        const bytes = size + hb;
+        totalFiles += 1;
+        totalBytes += bytes;
+
+        const row = rowById.get(id) || null;
+        // Authoritative per-file lifecycle via cheap top-level scan; the summary
+        // index is stale here (most on-disk files are unindexed), so the file
+        // itself — not the index — decides closed/age. Fall back to the index
+        // row, then to file mtime, only when the scan can't resolve a field.
+        let scan = null;
+        try { scan = scanTopLevelScalars(readFileSync(full, 'utf-8')); } catch { scan = null; }
+        if (!scan) scanFailFiles += 1;
+        const closedScan = scan && (scan.closed === true || scan.status === 'closed');
+        const closedRow = row && (row.closed === true || row.status === 'closed');
+        const closed = scan ? !!closedScan : !!closedRow;
+        let updatedAt = scan && Number(scan.updatedAt) > 0 ? Number(scan.updatedAt) : 0;
+        if (!updatedAt && row && Number(row.updatedAt) > 0) updatedAt = Number(row.updatedAt);
+        if (!updatedAt) updatedAt = mtimeMs;
+        const ageMs = now - updatedAt;
+        // Min-closed-age gate: a closed session only qualifies once its close
+        // timestamp (closedAt when present, else updatedAt — markSessionClosed
+        // sets updatedAt=Date.now() at tombstone time) is older than the gate.
+        // Recently-closed sessions may still be resumed, so keep them.
+        const closedAt = scan && Number(scan.closedAt) > 0 ? Number(scan.closedAt) : updatedAt;
+        const closedAge = now - closedAt;
+        const closedQualifies = closed
+            && (minClosedAgeMs <= 0
+                || (Number.isFinite(closedAt) && closedAt > 0 && closedAge > minClosedAgeMs));
+        const ageOnly = !closed && maxAgeMs > 0 && Number.isFinite(updatedAt) && updatedAt > 0 && ageMs > maxAgeMs;
+
+        if (closed && !closedQualifies) {
+            closedButFreshCount += 1;
+            closedButFreshBytes += bytes;
+        }
+        if (!closedQualifies && !ageOnly) continue; // keep
+
+        const reason = closedQualifies ? 'closed' : 'age';
+        candidates.push({ id, reason, updatedAt, bytes, inIndex: !!row });
+        reclaimBytes += bytes;
+        if (closedQualifies) { closedCount += 1; closedBytes += bytes; }
+        else { ageOnlyCount += 1; ageOnlyBytes += bytes; }
+    }
+
+    candidates.sort((a, b) => (a.updatedAt || 0) - (b.updatedAt || 0));
+    const oldest = candidates[0] || null;
+    const newest = candidates[candidates.length - 1] || null;
+    const dropRows = candidates.filter((c) => c.inIndex).length;
+    const remainFiles = totalFiles - candidates.length;
+    // Rows in the index whose session file is already gone from disk — a
+    // rebuild (scans existing files only) drops these regardless of retention.
+    const staleRows = rows.filter((r) => r?.id && !fileIds.has(r.id)).length;
+    // A real prune would delete candidate files then rebuild the index from the
+    // surviving files, so the post-rebuild index equals the surviving-file count
+    // (every remaining file gets a row, including currently-unindexed ones).
+    const rebuiltIndexRows = remainFiles;
+
+    const L = [];
+    L.push('══ session-sweep DRY-RUN report (NO files deleted, NO writes) ══');
+    L.push(`data dir            : ${dir}`);
+    L.push(`summary index       : ${summaryIndexPath()} (${rows.length} rows)`);
+    L.push(`now                 : ${fmtTs(now)}`);
+    L.push(`retention (age)     : > ${maxAgeDays} days by updatedAt`);
+    L.push(`retention (closed)  : (closed=true OR status='closed') AND closed > ${minClosedAgeDays}d ago`);
+    L.push('');
+    L.push(`total session files : ${totalFiles}  (${fmtBytes(totalBytes)})`);
+    L.push(`candidates (drop)   : ${candidates.length}  (${fmtBytes(reclaimBytes)} reclaimable)`);
+    L.push(`  ├─ closed         : ${closedCount}  (${fmtBytes(closedBytes)})`);
+    L.push(`  └─ age-only >${maxAgeDays}d   : ${ageOnlyCount}  (${fmtBytes(ageOnlyBytes)})`);
+    L.push(`kept: closed <${minClosedAgeDays}d : ${closedButFreshCount}  (${fmtBytes(closedButFreshBytes)}) — within min-closed-age gate`);
+    L.push(`would remain        : ${remainFiles} files  (${fmtBytes(totalBytes - reclaimBytes)})`);
+    L.push(`oldest candidate    : ${oldest ? `${oldest.id} @ ${fmtTs(oldest.updatedAt)} [${oldest.reason}]` : 'n/a'}`);
+    L.push(`newest candidate    : ${newest ? `${newest.id} @ ${fmtTs(newest.updatedAt)} [${newest.reason}]` : 'n/a'}`);
+    if (scanFailFiles > 0) L.push(`unparsable files    : ${scanFailFiles} (fell back to index/mtime)`);
+    L.push('');
+    L.push('── summary-index rebuild plan ──');
+    L.push(`index rows total    : ${rows.length}`);
+    L.push(`stale rows (no file): ${staleRows}  (already-deleted sessions; drop on rebuild)`);
+    L.push(`candidate rows drop : ${dropRows}  (candidate files that also have an index row)`);
+    L.push(`orphan candidates   : ${candidates.length - dropRows}  (candidate file present, no index row)`);
+    L.push(`index rows after    : ${rebuiltIndexRows}  (= surviving files; rebuild reindexes all remaining)`);
+    L.push('');
+    L.push('DRY-RUN ONLY — this tool performed no unlink and no disk writes.');
+    process.stdout.write(L.join('\n') + '\n');
+}
+
+main();