@try-works/dsh-memory 0.1.19 → 0.1.21

package/src/capture.js

@@ -1,242 +1,242 @@
-// Incremental, summarized capture: sessionQuery events -> dated summary sections.
-//
-// Capture is O(new events), not O(session): a lastSeq watermark in state/sessions.json
-// means each pass summarizes only what arrived since the previous one. Raw message
-// bodies never reach the digest file - a digest holds a bounded metadata header plus
-// the summarizer's durable bullets (or a deterministic fallback when no model is
-// available). Tool mechanics are reduced to a count.
-import { createHash } from 'node:crypto'
-import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { projectDigest, classifyJunk, extractCandidates, renderDigestHeader, totalToolCalls, dateOf } from './digest.js'
-import { summarizeSession, renderSummarySection } from './summarize.js'
-import { advance, fail, isSettled, readQueue, REASONS, seed, STATES } from './queue.js'
-
-/** Digest file format. A stored state with a different value forces a full re-capture. */
-export const DIGEST_FORMAT = 2
-
-export function digestPath(root, id) { return join(root, 'digests', id + '.md') }
-
-export function readDigestText(root, id) {
-  try { return readFileSync(digestPath(root, id), 'utf8') } catch { return '' }
-}
-
-/** Log position of an event: its own seq when present, else its index in the log. */
-function seqOf(event, index) {
-  return typeof event?.seq === 'number' ? event.seq : index
-}
-
-export function digestHash(digest) {
-  return createHash('sha256')
-    .update(digest.sessionId + '|' + digest.eventCount + '|' + digest.userTexts.join('\n') + '|' + digest.assistantTexts.join('\n'))
-    .digest('hex')
-}
-
-/**
- * Capture one session incrementally.
- * @param store - memory store.
- * @param services - { sessionQuery, llm? }; llm(prompt) summarizes, omit for deterministic notes.
- * @param session - the live session (id + header).
- * @param options - capture budgets (see defaults.js).
- * @returns {Promise<{sessionId: string, tier: string, changed: boolean, fresh: number, summarySource: string, bullets: number}>}
- */
-/** Does the queue already track this candidate? */
-function queueHas(root, id) { return readQueue(root).has(id) }
-
-export async function captureSession(store, services, session, options = {}) {
-  const cfg = {
-    maxUserTurns: 60, maxAssistantGists: 40, maxMessageChars: 600,
-    maxGoalChars: 200, maxCheckpoints: 4, maxBytes: 40000,
-    maxBullets: 16, maxBulletChars: 2000, summaryMinSignalChars: 400,
-    now: () => new Date().toISOString(),
-    ...options,
-  }
-  let events = []
-  try {
-    const snapshot = await services?.sessionQuery?.readSession(session.id)
-    events = snapshot?.events ?? []
-  } catch { events = [] }
-
-  // Read the queue entry directly. The previous record shape is a projection over the queue, so
-  // asking for it here meant projecting every candidate to answer a question about one.
-  const prevEntry = readQueue(store.root).get(session.id)
-  const prev = {
-    digestFormat: prevEntry?.detail?.digestFormat,
-    lastSeq: prevEntry?.detail?.lastSeq,
-    summaryAttempts: prevEntry?.attempts,
-  }
-  const formatChanged = prev.digestFormat !== DIGEST_FORMAT
-  const watermark = (!formatChanged && typeof prev.lastSeq === 'number') ? prev.lastSeq : -1
-  const fresh = events.filter((event, index) => seqOf(event, index) > watermark)
-  const logEnd = events.length === 0 ? watermark : seqOf(events[events.length - 1], events.length - 1)
-  // The watermark advances only over material that was actually CONSUMED. A trivial ping is
-  // dropped outright, but a thin delta is provisional: it is below the signal floor now and may
-  // not be later, so it stays in the window and accumulates with the next delta. Advancing past
-  // it would skip that text forever, which is how content quietly disappeared.
-  // Material is CONSUMED only when it was actually dealt with: summarized, or deliberately
-  // concluded to hold nothing durable. A thin delta accumulates, and a FAILED summary keeps its
-  // material so the retry has something to retry - consuming it would leave the retry with no
-  // input, which is a silent no-op dressed up as a retry. After the cap the failure is accepted
-  // and the window advances, so a permanently broken session cannot block progress forever.
-  // A thin delta is a DELIBERATE skip, so it counts as dealt with; only a FAILURE is re-presented.
-  const consumes = (failed, givingUp) => !failed || givingUp
-
-  // Tier is decided once, on the first capture, from the whole session; later passes
-  // reuse it so a long session is never re-projected wholesale.
-  const tier = prev.tier ?? classifyJunk(projectDigest({
-    sessionId: session.id, createdAt: session.header?.createdAt, cwd: session.header?.cwd,
-  }, events))
-
-  if (fresh.length === 0) {
-    return { sessionId: session.id, tier, changed: false, fresh: 0, summarySource: 'none', bullets: 0 }
-  }
-
-  const freshDigest = projectDigest({
-    sessionId: session.id, createdAt: session.header?.createdAt, cwd: session.header?.cwd,
-  }, fresh)
-  const toolCallCount = (prev.toolCallCount ?? 0) + totalToolCalls(freshDigest.toolTally)
-  const meta = {
-    sessionId: session.id,
-    title: freshDigest.title || prev.title || session.header?.title || '',
-    createdAt: session.header?.createdAt,
-    cwd: session.header?.cwd,
-    date: dateOf(session.header?.createdAt),
-    eventCount: events.length,
-    toolCallCount,
-    capturedAt: cfg.now(),
-  }
-
-  mkdirSync(join(store.root, 'digests'), { recursive: true })
-  const path = digestPath(store.root, session.id)
-  if (!existsSync(path) || formatChanged) writeFileSync(path, renderDigestHeader(meta) + '\n', 'utf8')
-
-  // Signal check: how much NEW material would a summary actually see? Counting the FILTERED
-  // candidates, not raw events, so a burst of tool noise cannot masquerade as content.
-  const candidateSet = tier === "trivial" ? undefined : extractCandidates(freshDigest, cfg)
-  const signalChars = candidateSet
-    ? candidateSet.userTurns.reduce((n, text) => n + text.length, 0)
-      + candidateSet.assistantGists.reduce((n, text) => n + text.length, 0)
-    : 0
-  const enoughSignal = signalChars >= (cfg.summaryMinSignalChars ?? 0)
-
-  // A ping has nothing durable to find, and a thin delta is not worth a model call either.
-  const summary = tier === "trivial"
-    ? { bullets: [], source: "skipped" }
-    : (enoughSignal
-      ? await summarizeSession(services?.llm, candidateSet, { date: meta.date }, cfg)
-      : { bullets: [], source: "thin" })
-  if (summary.bullets.length > 0) {
-    appendFileSync(path, '\n' + renderSummarySection(summary.bullets, { stamp: meta.capturedAt, source: summary.source }), 'utf8')
-  }
-
-  // SETTLED versus FAILED. Nothing durable written is only a conclusion when the model SAID
-  // so (NO_DURABLE_CONTENT), or when the session was never worth a call at all. An empty or
-  // unparseable reply is a FAILURE: it stays pending so the next pass retries it. A failed
-  // summary is retried at most summaryMaxAttempts times before it is laid to rest as failed
-  // instead of being retried forever.
-  // SETTLED versus FAILED. Nothing durable written is only a conclusion when the model SAID so
-  // (NO_DURABLE_CONTENT), or when the session was never worth a call at all. An empty or
-  // unparseable reply is a FAILURE, and a failure is retried rather than settled.
-  //
-  // This writes TRANSITIONS now, not flags. The state IS the answer to what happened, so no
-  // reader has to derive it: a deliberate skip, a defect and a finished job are three states,
-  // not three combinations of a timestamp, a source string and a counter.
-  const summaryFailed = summary.bullets.length === 0
-    && (summary.reason === 'empty-reply' || summary.reason === 'unparseable' || summary.reason === 'error')
-  const giveUp = summaryFailed && (Number(prev.summaryAttempts ?? 0) + 1) >= (cfg.summaryMaxAttempts ?? 2)
-  // The watermark advances only over material that was DEALT WITH. A failure keeps its material
-  // so the retry has something to retry; a deliberate skip consumes it.
-  const consumed = !summaryFailed || giveUp
-  const detail = {
-    tier,
-    title: meta.title,
-    capturedAt: meta.capturedAt,
-    digestFormat: DIGEST_FORMAT,
-    lastSeq: consumed ? logEnd : watermark,
-    digestHash: digestHash(freshDigest),
-    eventCount: events.length,
-    toolCallCount,
-  };
-  // Which state this pass produced, and why. A stopping state always carries a reason, because
-  // a decision and a defect must be told apart by a reader who was not here.
-  let outcome;
-  if (tier !== 'content') outcome = { state: STATES.SKIPPED, reason: REASONS.TRIVIAL };
-  else if (summary.source === 'thin') outcome = { state: STATES.SKIPPED, reason: REASONS.THIN };
-  else if (summary.bullets.length > 0) outcome = { state: STATES.SUMMARIZED };
-  else if (summary.reason === REASONS.NO_DURABLE) outcome = { state: STATES.SKIPPED, reason: REASONS.NO_DURABLE };
-  else if (summaryFailed) {
-    outcome = {
-      state: STATES.FAILED,
-      reason: summary.reason === 'error' ? REASONS.CALL_FAILED : summary.reason,
-      error: summary.error,
-    };
-  } else outcome = { state: STATES.SKIPPED, reason: REASONS.UNCLASSIFIED };
-
-  // A new candidate is seeded PENDING and then walks the real path. Recording the intermediate
-  // steps is not ceremony: the summarization genuinely ran, and a failure that appears straight
-  // from pending would describe something that never happened.
-  if (!queueHas(store.root, session.id)) seed(store.root, session.id, STATES.PENDING, { detail });
-  advance(store.root, session.id, STATES.SUMMARIZING, { detail });
-  if (outcome.state === STATES.FAILED) {
-    // fail() schedules the next attempt and enforces the cap itself, so a caller cannot leave
-    // a candidate failed forever by forgetting to check it.
-    fail(store.root, session.id, { reason: outcome.reason, error: outcome.error });
-  } else {
-    advance(store.root, session.id, outcome.state, { reason: outcome.reason, attempts: 0, detail });
-  }
-  // A successful summary clears the attempt budget: the failure is behind it.
-  if (outcome.state === STATES.SUMMARIZED) advance(store.root, session.id, STATES.SUMMARIZED, { attempts: 0, detail });
-  return {
-    sessionId: session.id, tier, changed: true, fresh: fresh.length,
-    summarySource: summary.source, bullets: summary.bullets.length,
-  }
-}
-
-/**
- * Prune captured digests. Digests are raw session material and gitignored, but one file per
- * session accumulates forever. Only digests that have already been consolidated AND are beyond
- * the newest `keep` are removed: a pending digest is the only copy of work not yet in the store.
- * @returns {{removed: number, kept: number, pending: number}}
- */
-export function pruneDigests(store, options = {}) {
-  const keep = options.keep ?? 50
-  // A digest may only be removed when the work is DEALT WITH: while a candidate is waiting, its
-  // digest is the only copy of material that is not in the store yet.
-  const entries = [...readQueue(store.root).values()]
-    .map((entry) => ({
-      id: entry.id,
-      settled: isSettled(entry),
-      mtime: statSafe(digestPath(store.root, entry.id)),
-      capturedAt: Date.parse(String(entry.detail?.capturedAt ?? '')) || 0,
-    }))
-    // "Newest" must not depend on file mtime alone: several digests written in the same tick
-    // are otherwise indistinguishable, and a same-instant test (or a fast machine) would prune
-    // the wrong one. capturedAt is the record of when the session was captured; mtime breaks
-    // ties when records are missing it.
-    .sort((a, b) => (b.capturedAt - a.capturedAt) || ((b.mtime ?? 0) - (a.mtime ?? 0)))
-  let removed = 0
-  let pending = 0
-  for (const [index, item] of entries.entries()) {
-    if (!item.settled) { pending += 1; continue }
-    if (index < keep) continue
-    try {
-      rmSync(digestPath(store.root, item.id))
-      removed += 1
-    } catch {}
-  }
-  return { removed, kept: Math.max(0, entries.length - removed - pending), pending }
-}
-
-/** Modification time of a file, or undefined when it is absent. */
-function statSafe(file) {
-  try { return statSync(file).mtimeMs } catch { return undefined }
-}
-/** Sessions captured but not yet consolidated (oldest-first is handled by the caller). */
-export function pendingDigests(store) {
-  // Waiting work, which is exactly what the queue calls PENDING or SUMMARIZED - the same set the
-  // cadence treats as work. Neither a failure on its backoff nor an orphan belongs here: those are
-  // different actions, and folding them in is what made 78 orphans look like 78 retries.
-  return [...readQueue(store.root).values()]
-    .filter((entry) => entry.state === STATES.PENDING || entry.state === STATES.SUMMARIZED)
-    .map((entry) => ({ id: entry.id, tier: entry.detail?.tier, digestHash: entry.detail?.digestHash }))
-}
+// Incremental, summarized capture: sessionQuery events -> dated summary sections.
+//
+// Capture is O(new events), not O(session): a lastSeq watermark in state/sessions.json
+// means each pass summarizes only what arrived since the previous one. Raw message
+// bodies never reach the digest file - a digest holds a bounded metadata header plus
+// the summarizer's durable bullets (or a deterministic fallback when no model is
+// available). Tool mechanics are reduced to a count.
+import { createHash } from 'node:crypto'
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { projectDigest, classifyJunk, extractCandidates, renderDigestHeader, totalToolCalls, dateOf } from './digest.js'
+import { summarizeSession, renderSummarySection } from './summarize.js'
+import { advance, fail, isSettled, readQueue, REASONS, seed, STATES } from './queue.js'
+
+/** Digest file format. A stored state with a different value forces a full re-capture. */
+export const DIGEST_FORMAT = 2
+
+export function digestPath(root, id) { return join(root, 'digests', id + '.md') }
+
+export function readDigestText(root, id) {
+  try { return readFileSync(digestPath(root, id), 'utf8') } catch { return '' }
+}
+
+/** Log position of an event: its own seq when present, else its index in the log. */
+function seqOf(event, index) {
+  return typeof event?.seq === 'number' ? event.seq : index
+}
+
+export function digestHash(digest) {
+  return createHash('sha256')
+    .update(digest.sessionId + '|' + digest.eventCount + '|' + digest.userTexts.join('\n') + '|' + digest.assistantTexts.join('\n'))
+    .digest('hex')
+}
+
+/**
+ * Capture one session incrementally.
+ * @param store - memory store.
+ * @param services - { sessionQuery, llm? }; llm(prompt) summarizes, omit for deterministic notes.
+ * @param session - the live session (id + header).
+ * @param options - capture budgets (see defaults.js).
+ * @returns {Promise<{sessionId: string, tier: string, changed: boolean, fresh: number, summarySource: string, bullets: number}>}
+ */
+/** Does the queue already track this candidate? */
+function queueHas(root, id) { return readQueue(root).has(id) }
+
+export async function captureSession(store, services, session, options = {}) {
+  const cfg = {
+    maxUserTurns: 60, maxAssistantGists: 40, maxMessageChars: 600,
+    maxGoalChars: 200, maxCheckpoints: 4, maxBytes: 40000,
+    maxBullets: 16, maxBulletChars: 2000, summaryMinSignalChars: 400,
+    now: () => new Date().toISOString(),
+    ...options,
+  }
+  let events = []
+  try {
+    const snapshot = await services?.sessionQuery?.readSession(session.id)
+    events = snapshot?.events ?? []
+  } catch { events = [] }
+
+  // Read the queue entry directly. The previous record shape is a projection over the queue, so
+  // asking for it here meant projecting every candidate to answer a question about one.
+  const prevEntry = readQueue(store.root).get(session.id)
+  const prev = {
+    digestFormat: prevEntry?.detail?.digestFormat,
+    lastSeq: prevEntry?.detail?.lastSeq,
+    summaryAttempts: prevEntry?.attempts,
+  }
+  const formatChanged = prev.digestFormat !== DIGEST_FORMAT
+  const watermark = (!formatChanged && typeof prev.lastSeq === 'number') ? prev.lastSeq : -1
+  const fresh = events.filter((event, index) => seqOf(event, index) > watermark)
+  const logEnd = events.length === 0 ? watermark : seqOf(events[events.length - 1], events.length - 1)
+  // The watermark advances only over material that was actually CONSUMED. A trivial ping is
+  // dropped outright, but a thin delta is provisional: it is below the signal floor now and may
+  // not be later, so it stays in the window and accumulates with the next delta. Advancing past
+  // it would skip that text forever, which is how content quietly disappeared.
+  // Material is CONSUMED only when it was actually dealt with: summarized, or deliberately
+  // concluded to hold nothing durable. A thin delta accumulates, and a FAILED summary keeps its
+  // material so the retry has something to retry - consuming it would leave the retry with no
+  // input, which is a silent no-op dressed up as a retry. After the cap the failure is accepted
+  // and the window advances, so a permanently broken session cannot block progress forever.
+  // A thin delta is a DELIBERATE skip, so it counts as dealt with; only a FAILURE is re-presented.
+  const consumes = (failed, givingUp) => !failed || givingUp
+
+  // Tier is decided once, on the first capture, from the whole session; later passes
+  // reuse it so a long session is never re-projected wholesale.
+  const tier = prev.tier ?? classifyJunk(projectDigest({
+    sessionId: session.id, createdAt: session.header?.createdAt, cwd: session.header?.cwd,
+  }, events))
+
+  if (fresh.length === 0) {
+    return { sessionId: session.id, tier, changed: false, fresh: 0, summarySource: 'none', bullets: 0 }
+  }
+
+  const freshDigest = projectDigest({
+    sessionId: session.id, createdAt: session.header?.createdAt, cwd: session.header?.cwd,
+  }, fresh)
+  const toolCallCount = (prev.toolCallCount ?? 0) + totalToolCalls(freshDigest.toolTally)
+  const meta = {
+    sessionId: session.id,
+    title: freshDigest.title || prev.title || session.header?.title || '',
+    createdAt: session.header?.createdAt,
+    cwd: session.header?.cwd,
+    date: dateOf(session.header?.createdAt),
+    eventCount: events.length,
+    toolCallCount,
+    capturedAt: cfg.now(),
+  }
+
+  mkdirSync(join(store.root, 'digests'), { recursive: true })
+  const path = digestPath(store.root, session.id)
+  if (!existsSync(path) || formatChanged) writeFileSync(path, renderDigestHeader(meta) + '\n', 'utf8')
+
+  // Signal check: how much NEW material would a summary actually see? Counting the FILTERED
+  // candidates, not raw events, so a burst of tool noise cannot masquerade as content.
+  const candidateSet = tier === "trivial" ? undefined : extractCandidates(freshDigest, cfg)
+  const signalChars = candidateSet
+    ? candidateSet.userTurns.reduce((n, text) => n + text.length, 0)
+      + candidateSet.assistantGists.reduce((n, text) => n + text.length, 0)
+    : 0
+  const enoughSignal = signalChars >= (cfg.summaryMinSignalChars ?? 0)
+
+  // A ping has nothing durable to find, and a thin delta is not worth a model call either.
+  const summary = tier === "trivial"
+    ? { bullets: [], source: "skipped" }
+    : (enoughSignal
+      ? await summarizeSession(services?.llm, candidateSet, { date: meta.date }, cfg)
+      : { bullets: [], source: "thin" })
+  if (summary.bullets.length > 0) {
+    appendFileSync(path, '\n' + renderSummarySection(summary.bullets, { stamp: meta.capturedAt, source: summary.source }), 'utf8')
+  }
+
+  // SETTLED versus FAILED. Nothing durable written is only a conclusion when the model SAID
+  // so (NO_DURABLE_CONTENT), or when the session was never worth a call at all. An empty or
+  // unparseable reply is a FAILURE: it stays pending so the next pass retries it. A failed
+  // summary is retried at most summaryMaxAttempts times before it is laid to rest as failed
+  // instead of being retried forever.
+  // SETTLED versus FAILED. Nothing durable written is only a conclusion when the model SAID so
+  // (NO_DURABLE_CONTENT), or when the session was never worth a call at all. An empty or
+  // unparseable reply is a FAILURE, and a failure is retried rather than settled.
+  //
+  // This writes TRANSITIONS now, not flags. The state IS the answer to what happened, so no
+  // reader has to derive it: a deliberate skip, a defect and a finished job are three states,
+  // not three combinations of a timestamp, a source string and a counter.
+  const summaryFailed = summary.bullets.length === 0
+    && (summary.reason === 'empty-reply' || summary.reason === 'unparseable' || summary.reason === 'error')
+  const giveUp = summaryFailed && (Number(prev.summaryAttempts ?? 0) + 1) >= (cfg.summaryMaxAttempts ?? 2)
+  // The watermark advances only over material that was DEALT WITH. A failure keeps its material
+  // so the retry has something to retry; a deliberate skip consumes it.
+  const consumed = !summaryFailed || giveUp
+  const detail = {
+    tier,
+    title: meta.title,
+    capturedAt: meta.capturedAt,
+    digestFormat: DIGEST_FORMAT,
+    lastSeq: consumed ? logEnd : watermark,
+    digestHash: digestHash(freshDigest),
+    eventCount: events.length,
+    toolCallCount,
+  };
+  // Which state this pass produced, and why. A stopping state always carries a reason, because
+  // a decision and a defect must be told apart by a reader who was not here.
+  let outcome;
+  if (tier !== 'content') outcome = { state: STATES.SKIPPED, reason: REASONS.TRIVIAL };
+  else if (summary.source === 'thin') outcome = { state: STATES.SKIPPED, reason: REASONS.THIN };
+  else if (summary.bullets.length > 0) outcome = { state: STATES.SUMMARIZED };
+  else if (summary.reason === REASONS.NO_DURABLE) outcome = { state: STATES.SKIPPED, reason: REASONS.NO_DURABLE };
+  else if (summaryFailed) {
+    outcome = {
+      state: STATES.FAILED,
+      reason: summary.reason === 'error' ? REASONS.CALL_FAILED : summary.reason,
+      error: summary.error,
+    };
+  } else outcome = { state: STATES.SKIPPED, reason: REASONS.UNCLASSIFIED };
+
+  // A new candidate is seeded PENDING and then walks the real path. Recording the intermediate
+  // steps is not ceremony: the summarization genuinely ran, and a failure that appears straight
+  // from pending would describe something that never happened.
+  if (!queueHas(store.root, session.id)) seed(store.root, session.id, STATES.PENDING, { detail });
+  advance(store.root, session.id, STATES.SUMMARIZING, { detail });
+  if (outcome.state === STATES.FAILED) {
+    // fail() schedules the next attempt and enforces the cap itself, so a caller cannot leave
+    // a candidate failed forever by forgetting to check it.
+    fail(store.root, session.id, { reason: outcome.reason, error: outcome.error });
+  } else {
+    advance(store.root, session.id, outcome.state, { reason: outcome.reason, attempts: 0, detail });
+  }
+  // A successful summary clears the attempt budget: the failure is behind it.
+  if (outcome.state === STATES.SUMMARIZED) advance(store.root, session.id, STATES.SUMMARIZED, { attempts: 0, detail });
+  return {
+    sessionId: session.id, tier, changed: true, fresh: fresh.length,
+    summarySource: summary.source, bullets: summary.bullets.length,
+  }
+}
+
+/**
+ * Prune captured digests. Digests are raw session material and gitignored, but one file per
+ * session accumulates forever. Only digests that have already been consolidated AND are beyond
+ * the newest `keep` are removed: a pending digest is the only copy of work not yet in the store.
+ * @returns {{removed: number, kept: number, pending: number}}
+ */
+export function pruneDigests(store, options = {}) {
+  const keep = options.keep ?? 50
+  // A digest may only be removed when the work is DEALT WITH: while a candidate is waiting, its
+  // digest is the only copy of material that is not in the store yet.
+  const entries = [...readQueue(store.root).values()]
+    .map((entry) => ({
+      id: entry.id,
+      settled: isSettled(entry),
+      mtime: statSafe(digestPath(store.root, entry.id)),
+      capturedAt: Date.parse(String(entry.detail?.capturedAt ?? '')) || 0,
+    }))
+    // "Newest" must not depend on file mtime alone: several digests written in the same tick
+    // are otherwise indistinguishable, and a same-instant test (or a fast machine) would prune
+    // the wrong one. capturedAt is the record of when the session was captured; mtime breaks
+    // ties when records are missing it.
+    .sort((a, b) => (b.capturedAt - a.capturedAt) || ((b.mtime ?? 0) - (a.mtime ?? 0)))
+  let removed = 0
+  let pending = 0
+  for (const [index, item] of entries.entries()) {
+    if (!item.settled) { pending += 1; continue }
+    if (index < keep) continue
+    try {
+      rmSync(digestPath(store.root, item.id))
+      removed += 1
+    } catch {}
+  }
+  return { removed, kept: Math.max(0, entries.length - removed - pending), pending }
+}
+
+/** Modification time of a file, or undefined when it is absent. */
+function statSafe(file) {
+  try { return statSync(file).mtimeMs } catch { return undefined }
+}
+/** Sessions captured but not yet consolidated (oldest-first is handled by the caller). */
+export function pendingDigests(store) {
+  // Waiting work, which is exactly what the queue calls PENDING or SUMMARIZED - the same set the
+  // cadence treats as work. Neither a failure on its backoff nor an orphan belongs here: those are
+  // different actions, and folding them in is what made 78 orphans look like 78 retries.
+  return [...readQueue(store.root).values()]
+    .filter((entry) => entry.state === STATES.PENDING || entry.state === STATES.SUMMARIZED)
+    .map((entry) => ({ id: entry.id, tier: entry.detail?.tier, digestHash: entry.detail?.digestHash }))
+}