mixdog 0.9.37 → 0.9.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.37",
+  "version": "0.9.38",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",

package/scripts/dispatch-persist-recovery-test.mjs

@@ -0,0 +1,141 @@
+// Regression tests for recoverPending recovery bugs:
+//  (a) an entry must survive when notifyFn resolves false (not delivered) and
+//      only be removed after a confirmed (truthy) ack.
+//  (b) a scoped recovery that matches purely on clientHostPid must NOT stamp
+//      the reconnecting filter session's id onto another session's abort — it
+//      delivers to the true owner session, and leaves the entry persisted when
+//      there is no owner session to target.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  addPending,
+  recoverPending,
+} from '../src/runtime/agent/orchestrator/dispatch-persist.mjs';
+
+const FILE = 'pending-dispatches.json';
+
+function readMap(dir) {
+  try {
+    const raw = readFileSync(join(dir, FILE), 'utf8');
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch { return {}; }
+}
+
+async function waitFor(fn, { timeout = 3000, step = 20 } = {}) {
+  const deadline = Date.now() + timeout;
+  for (;;) {
+    if (fn()) return true;
+    if (Date.now() > deadline) return false;
+    await new Promise((r) => setTimeout(r, step));
+  }
+}
+
+function tmp() {
+  const dir = mkdtempSync(join(tmpdir(), 'dpersist-'));
+  return dir;
+}
+
+test('(a) only explicit false/0 keeps entry; undefined/void resolve deletes', async () => {
+  const dir = tmp();
+  try {
+    addPending(dir, 'h-a', 'recall', ['q'], 'sid-owner', 1111);
+    await waitFor(() => 'h-a' in readMap(dir));
+
+    // Explicit false → undelivered, entry MUST survive for retry.
+    recoverPending(dir, () => Promise.resolve(false), {});
+    await new Promise((r) => setTimeout(r, 200));
+    assert.ok('h-a' in readMap(dir), 'entry removed despite notifyFn=false');
+
+    // Explicit 0 → also undelivered, entry survives.
+    recoverPending(dir, () => Promise.resolve(0), {});
+    await new Promise((r) => setTimeout(r, 200));
+    assert.ok('h-a' in readMap(dir), 'entry removed despite notifyFn=0');
+
+    // undefined/void resolve from a delivered notifyFn → entry removed.
+    recoverPending(dir, () => Promise.resolve(undefined), {});
+    const gone = await waitFor(() => !('h-a' in readMap(dir)));
+    assert.ok(gone, 'entry not removed after undefined (delivered) resolve');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('(b) hostPid-only match delivers to true owner session, never the filter session', async () => {
+  const dir = tmp();
+  try {
+    addPending(dir, 'h-b', 'recall', ['q'], 'owner-A', 4242);
+    await waitFor(() => 'h-b' in readMap(dir));
+
+    let seen = null;
+    // Reconnect as a DIFFERENT session that only shares the host pid.
+    recoverPending(dir, (content, meta) => { seen = meta; return Promise.resolve(true); }, {
+      sessionId: 'session-B',
+      clientHostPid: 4242,
+    });
+    await waitFor(() => seen != null);
+    assert.equal(seen.caller_session_id, 'owner-A', 'stamped filter session instead of true owner');
+    assert.notEqual(seen.caller_session_id, 'session-B');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('(b) hostPid-only match with no owner session is left persisted, not injected', async () => {
+  const dir = tmp();
+  try {
+    addPending(dir, 'h-c', 'recall', ['q'], null, 5353);
+    await waitFor(() => 'h-c' in readMap(dir));
+
+    let called = false;
+    recoverPending(dir, () => { called = true; return Promise.resolve(true); }, {
+      sessionId: 'session-C',
+      clientHostPid: 5353,
+    });
+    await new Promise((r) => setTimeout(r, 250));
+    assert.equal(called, false, 'notifyFn fired for an entry with no owner session');
+    assert.ok('h-c' in readMap(dir), 'entry with no owner session was not left persisted');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('owner-session match still stamps the reconnecting session id', async () => {
+  const dir = tmp();
+  try {
+    addPending(dir, 'h-d', 'recall', ['q'], 'prior-sid', 6464);
+    await waitFor(() => 'h-d' in readMap(dir));
+
+    let seen = null;
+    recoverPending(dir, (content, meta) => { seen = meta; return Promise.resolve(true); }, {
+      sessionId: 'new-sid',
+      priorSessionId: 'prior-sid',
+      clientHostPid: 6464,
+    });
+    await waitFor(() => seen != null);
+    assert.equal(seen.caller_session_id, 'new-sid', 'owner match should stamp reconnecting session id');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('priorSessionId match with no current sessionId keeps the entry owner cid', async () => {
+  const dir = tmp();
+  try {
+    addPending(dir, 'h-e', 'recall', ['q'], 'prior-sid', 7575);
+    await waitFor(() => 'h-e' in readMap(dir));
+
+    let seen = null;
+    // priorSessionId matches the owner but no current sessionId is supplied →
+    // filterSid is null; must fall back to the entry's known owner cid.
+    recoverPending(dir, (content, meta) => { seen = meta; return Promise.resolve(true); }, {
+      priorSessionId: 'prior-sid',
+    });
+    await waitFor(() => seen != null);
+    assert.equal(seen.caller_session_id, 'prior-sid', 'dropped known owner cid when sessionId absent');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/scripts/explore-bench.mjs

@@ -6,13 +6,41 @@
 //   node scripts/explore-bench.mjs [roundLabel]
 // Fresh process per run = no in-memory result cache carryover.
 import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
 import { runExplore } from '../src/standalone/explore-tool.mjs';
 
 const ROUND = process.argv[2] || 'r0';
 const CWD = 'C:/Project/mixdog';
 
+// Anchor helpers: an anchor line carries a `path:line`. Strict quality =
+// expected token must land ON such a line (not merely somewhere in the text),
+// and anchors===0 is always a miss (except expectFail). Spot-accuracy verifies
+// the referenced file exists and the line number is within the file length.
+function anchorLinesOf(text) {
+  return text.split('\n').filter((l) => /:\d+/.test(l));
+}
+function checkAnchorLine(line, ctxTokens = []) {
+  const m = line.match(/([A-Za-z0-9_.\/\\-]+):(\d+)/);
+  if (!m) return null; // no parseable path:line
+  const p = m[1];
+  const ln = Number(m[2]);
+  const full = isAbsolute(p) ? p : join(CWD, p);
+  if (!existsSync(full)) return false;
+  try {
+    const fileLines = readFileSync(full, 'utf8').split('\n');
+    if (!(ln >= 1 && ln <= fileLines.length)) return false;
+    // Fabricated-line guard: the cited line's ±2 window must contain a
+    // query/expected token, so a plausible-but-wrong line number fails.
+    if (ctxTokens.length) {
+      // ±2 lines around the 1-based cited line (indices ln-3 .. ln+1 inclusive).
+      const win = fileLines.slice(Math.max(0, ln - 3), ln + 2).join('\n').toLowerCase();
+      if (!ctxTokens.some((t) => win.includes(t))) return false;
+    }
+    return true;
+  } catch { return false; }
+}
+
 // High-fanout timing attribution: emit lightweight per-iteration send_ms
 // loop rows (no verbose payload estimate) so we can split LLM send time
 // from tool time under the parallel round below. Trace-only; no behavior
@@ -68,6 +96,13 @@ const QUERIES = [
     q: 'where is the mixdog config json file path resolved (data dir)',
     expect: ['config', 'plugin-paths'],
   },
+  {
+    // path-only class: the correct answer is a verified file/dir location on
+    // disk; a bare path (no :line) is an allowed HIT for this query.
+    q: 'where does mixdog store background shell job stdout logs on disk',
+    expect: ['shell-jobs', 'shell-job-paths', 'getShellJobsDir', 'shellJobStdout'],
+    pathOnly: true,
+  },
   {
     q: 'GraphQL schema stitching resolver implementation', // not in this repo
     expectFail: true,
@@ -98,17 +133,38 @@ function readTraceSince(ts) {
 const t0 = Date.now();
 // Parallel round: all queries fire at once. Per-session trace attribution is
 // by session_id so counts stay correct; per-query ms includes queueing.
-const results = await Promise.all(QUERIES.map(async ({ q, expect, expectFail }) => {
+const results = await Promise.all(QUERIES.map(async ({ q, expect, expectFail, pathOnly }) => {
   const qt0 = Date.now();
   const res = await runExplore({ query: q, cwd: CWD }, { callerCwd: CWD });
   const text = res?.content?.[0]?.text || '';
-  const anchors = text.split('\n').filter((l) => /:\d+/.test(l)).length;
+  const aLines = anchorLinesOf(text);
+  const anchors = aLines.length;
   const failed = /EXPLORATION_FAILED/.test(text);
-  const lower = text.toLowerCase();
+  // Context tokens for the fabricated-line guard: expanded expected + query
+  // words, length>=4 to drop filler.
+  const ctxTokens = [
+    ...(expect || []).flatMap((e) => e.toLowerCase().split(/[^a-z0-9]+/)),
+    ...q.toLowerCase().split(/[^a-z0-9]+/),
+  ].filter((t) => t.length >= 4);
+  // Spot-check up to 2 anchors per query for file/line validity + line context.
+  let badAnchors = 0;
+  for (const l of aLines.slice(0, 2)) {
+    if (checkAnchorLine(l, ctxTokens) === false) badAnchors++;
+  }
+  const allLines = text.split('\n').filter((l) => l.trim());
+  // Strict hit: expected token must appear ON an anchor line (>=1 anchor). For
+  // the path-only class, an expected token on any verified path line HITs even
+  // without :line. expectFail wants EXPLORATION_FAILED with zero anchors.
   const hit = expectFail
     ? (failed && anchors === 0)
-    : (!failed && (expect || []).some((e) => lower.includes(e.toLowerCase())));
-  return { q: q.slice(0, 48), ms: Date.now() - qt0, anchors, failed, hit, bytes: text.length };
+    : pathOnly
+      ? (!failed && (expect || []).some(
+          (e) => allLines.some((l) => l.toLowerCase().includes(e.toLowerCase())),
+        ))
+      : (!failed && anchors > 0 && (expect || []).some(
+          (e) => aLines.some((l) => l.toLowerCase().includes(e.toLowerCase())),
+        ));
+  return { q: q.slice(0, 48), ms: Date.now() - qt0, anchors, failed, hit, badAnchors, bytes: text.length };
 }));
 
 // Identify explorer sessions from trace rows, then attribute both tool calls
@@ -145,9 +201,10 @@ const sendCount = [...sendBySession.values()].reduce((a, s) => a + s.sends, 0);
 
 console.log(`\n=== explore-bench round=${ROUND} ===`);
 for (const r of results) {
-  console.log(`  [${String(r.ms).padStart(6)}ms] ${r.hit ? 'HIT ' : 'MISS'} anchors=${r.anchors} failed=${r.failed} bytes=${r.bytes}  ${r.q}`);
+  console.log(`  [${String(r.ms).padStart(6)}ms] ${r.hit ? 'HIT ' : 'MISS'} anchors=${r.anchors} bad=${r.badAnchors} failed=${r.failed} bytes=${r.bytes}  ${r.q}`);
 }
-console.log(`  quality: ${results.filter((r) => r.hit).length}/${results.length} hits`);
+const badTotal = results.reduce((a, r) => a + r.badAnchors, 0);
+console.log(`  quality: ${results.filter((r) => r.hit).length}/${results.length} hits (strict)  bad-anchors=${badTotal}`);
 console.log(`  sessions=${bySession.size} toolcalls p50=${p50} max=${callCounts[callCounts.length - 1] ?? 0} total=${callCounts.reduce((a, b) => a + b, 0)}`);
 for (const [id, s] of bySession) console.log(`    ${id.slice(-8)}: ${s.tools.join(',')}`);
 const wallMs = Date.now() - t0;

package/scripts/explore-prompt-policy-test.mjs

@@ -13,9 +13,13 @@ test('explore per-query prompt leaves path policy to tool schemas', () => {
 
 test('grep glob find tool schemas carry unverified path policy', () => {
   const byName = Object.fromEntries(BUILTIN_TOOLS.map((tool) => [tool.name, tool]));
-  assert.match(byName.grep.description, /Unknown path\/name → find first/i);
+  // Conditional find-first: only genuinely guessed fragments route through
+  // find, and in the SAME turn — project root itself is a verified scope.
+  assert.match(byName.grep.description, /project root counts as verified/i);
+  assert.match(byName.grep.description, /guessed path fragment → find first, same turn/i);
   assert.match(byName.grep.description, /no path "\." \+ guessed src\/\*\*/i);
-  assert.match(byName.glob.description, /Unknown root\/name → find first/i);
+  assert.match(byName.glob.description, /project root is verified/i);
+  assert.match(byName.glob.description, /Guessed root\/name → find first, same turn/i);
   assert.match(byName.find.description, /verify roots before grep\/glob/i);
 });
 

package/scripts/notify-completion-mirror-test.mjs

@@ -0,0 +1,73 @@
+// notifyFnForSession must not double-inject a background-task completion. The
+// mirror skip is gated on an EXPLICIT model-visible-delivery ack
+// (modelVisibleDelivered), set ONLY by the TUI execution-ui path that injects
+// the completion body into the active loop — never on a generic truthy
+// onNotification return. So: delivered ack → mirror suppressed; headless /
+// display-only / API listener (no ack) → mirror kept as the sole delivery.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { shouldMirrorCompletionToPendingQueue } from '../src/session-runtime/runtime-core.mjs';
+
+// A terminal agent completion with a Result body — accepted by
+// shouldPersistModelVisibleToolCompletion.
+const completionText = 'Async agent task task_1 completed finished.\n\nResult:\n> ok';
+const completionMeta = { type: 'agent_task_result', execution_id: 'task_1', status: 'completed' };
+
+test('delivered-live completion: no pending mirror (explicit model-visible ack)', () => {
+  const mirror = shouldMirrorCompletionToPendingQueue({
+    callerSessionId: 'sess_live',
+    modelVisibleDelivered: true,
+    hasEnqueue: true,
+    text: completionText,
+    meta: completionMeta,
+  });
+  assert.equal(mirror, false, 'live twin already injected → mirror suppressed');
+});
+
+test('headless completion: pending mirror kept (no ack)', () => {
+  const mirror = shouldMirrorCompletionToPendingQueue({
+    callerSessionId: 'sess_headless',
+    modelVisibleDelivered: false,
+    hasEnqueue: true,
+    text: completionText,
+    meta: completionMeta,
+  });
+  assert.equal(mirror, true, 'no listener delivered → queue copy is the sole delivery');
+});
+
+test('display-only listener returning true (no ack): pending mirror kept', () => {
+  // A generic display/API listener consumes the event (would return true) but
+  // never injects the model-visible body, so it sets NO modelVisibleDelivered
+  // ack. The mirror must stay, or the model never sees the completion body.
+  const mirror = shouldMirrorCompletionToPendingQueue({
+    callerSessionId: 'sess_display_only',
+    modelVisibleDelivered: false,
+    hasEnqueue: true,
+    text: completionText,
+    meta: completionMeta,
+  });
+  assert.equal(mirror, true, 'generic handled===true is NOT an ack → mirror kept');
+});
+
+test('unhandled but non-terminal notification is never mirrored', () => {
+  const mirror = shouldMirrorCompletionToPendingQueue({
+    callerSessionId: 'sess_headless',
+    modelVisibleDelivered: false,
+    hasEnqueue: true,
+    text: 'still running...',
+    meta: { status: 'running' },
+  });
+  assert.equal(mirror, false, 'only persistable terminal completions mirror');
+});
+
+test('missing session id or enqueue capability never mirrors', () => {
+  assert.equal(shouldMirrorCompletionToPendingQueue({
+    callerSessionId: '', modelVisibleDelivered: false, hasEnqueue: true,
+    text: completionText, meta: completionMeta,
+  }), false, 'no caller session → nothing to mirror into');
+  assert.equal(shouldMirrorCompletionToPendingQueue({
+    callerSessionId: 'sess_headless', modelVisibleDelivered: false, hasEnqueue: false,
+    text: completionText, meta: completionMeta,
+  }), false, 'no enqueue capability → cannot mirror');
+});

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();