create-claude-cabinet 0.45.0 → 0.46.0

package/templates/scripts/watchtower-build-context.mjs

@@ -13,6 +13,7 @@
 import { readFileSync, readdirSync, existsSync, statSync, mkdirSync } from 'fs';
 import { join, resolve, basename } from 'path';
 import { currentCursor, resolveProjectIdentity } from './watchtower-lib.mjs';
+import { runAdvisoryPass } from './watchtower-advisories.mjs';
 
 const WATCHTOWER_DIR = process.env.WATCHTOWER_DIR
   || join(process.env.HOME, '.claude-cabinet', 'watchtower');
@@ -22,6 +23,18 @@ const STALENESS_THRESHOLD_MS = 24 * 60 * 60 * 1000; // 24 hours
 const RINGS_WARNING_THRESHOLD_MS = 48 * 60 * 60 * 1000; // 48 hours
 const PROJECT_STALENESS_DAYS = 7;
 
+// Section truncation priority — LOWER survives, HIGHER is dropped first.
+// `assembleSections` removes whole sections (never trims within one) in
+// descending priority order until the output fits MAX_OUTPUT_CHARS;
+// PRIORITY_NEVER is never dropped.
+const PRIORITY_NEVER = 0;    // summary — always kept
+const PRIORITY_KEEP = 1;     // threads, inbox, advisories — try hard to keep
+const PRIORITY_PROJECT = 2;  // per-project state
+const PRIORITY_DOMAIN = 3;   // injected domain files
+const PRIORITY_PATTERNS = 4; // enforcement patterns — nice-to-have, drop first
+
+const MAX_PATTERN_LINES = 5;
+
 // --- Argument parsing ---
 
 function parseArgs() {
@@ -183,6 +196,63 @@ function renderFocalZoom(threads, projectSlug) {
   return lines.join('\n');
 }
 
+// --- Enforcement patterns (.claude/memory/patterns/) ---
+
+// Pull the project-root patterns directory (NOT the ~/.claude/projects/<slug>/
+// memory tree) so captured enforcement lessons keep shaping behavior past
+// orient (act:202e5934). Index-line style only — name + one-line description,
+// budget-capped. A two-field line scan, NOT a YAML parser: there is no shared
+// frontmatter parser in templates/scripts/ and a full YAML parse trips on flow
+// sequences (see MEMORY.md lesson_parsefrontmatter_flow_sequences).
+function extractField(content, field) {
+  // Only look inside the leading --- frontmatter block.
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  const block = m ? m[1] : content;
+  for (const line of block.split('\n')) {
+    const fm = line.match(new RegExp(`^${field}:\\s*(.+)$`));
+    if (fm) return fm[1].trim().replace(/^["']|["']$/g, '');
+  }
+  return null;
+}
+
+function renderPatterns(projectPath) {
+  if (!projectPath) return null;
+  const patternsDir = join(projectPath, '.claude', 'memory', 'patterns');
+  if (!existsSync(patternsDir)) return null;
+
+  let files;
+  try {
+    files = readdirSync(patternsDir)
+      .filter(f => f.endsWith('.md') && !f.startsWith('_'))
+      .sort();
+  } catch {
+    return null;
+  }
+  if (files.length === 0) return null;
+
+  const lines = [];
+  for (const f of files.slice(0, MAX_PATTERN_LINES)) {
+    let name = null, desc = null;
+    try {
+      const content = safeReadFile(join(patternsDir, f));
+      if (content) {
+        name = extractField(content, 'name');
+        desc = extractField(content, 'description');
+      }
+    } catch {
+      // fall through to basename fallback
+    }
+    if (!name) name = f.replace(/\.md$/, '');
+    lines.push(desc ? `- ${name} — ${desc}` : `- ${name}`);
+  }
+  if (lines.length === 0) return null;
+
+  const more = files.length > MAX_PATTERN_LINES
+    ? `\n…and ${files.length - MAX_PATTERN_LINES} more`
+    : '';
+  return `--- Enforcement Patterns ---\n${lines.join('\n')}${more}`;
+}
+
 // --- Main ---
 
 function main() {
@@ -234,7 +304,7 @@ function main() {
   }
 
   // Summary is always included and never truncated
-  sections.push({ key: 'summary', content: summarySection, priority: 0 });
+  sections.push({ key: 'summary', content: summarySection, priority: PRIORITY_NEVER });
 
   // Step 3: If project has inject_domains, read each state/<domain>.md
   const domainSections = [];
@@ -246,7 +316,7 @@ function main() {
         domainSections.push({
           key: `domain:${domain}`,
           content: `--- ${domain} ---\n${domainContent.trim()}`,
-          priority: 3, // Truncated first
+          priority: PRIORITY_DOMAIN,
         });
       }
     }
@@ -264,7 +334,7 @@ function main() {
         sections.push({
           key: `project:${projectSlug}`,
           content: `--- Project: ${projectSlug} ---\n${projectStateContent.trim()}`,
-          priority: 2, // Truncated second (after domains)
+          priority: PRIORITY_PROJECT,
         });
       }
     }
@@ -278,7 +348,7 @@ function main() {
       sections.push({
         key: 'threads',
         content: focalZoom,
-        priority: 1,
+        priority: PRIORITY_KEEP,
       });
     }
   }
@@ -293,16 +363,44 @@ function main() {
     sections.push({
       key: 'queue',
       content: `--- Inbox ---\n${headline}\n${breakdown}`,
-      priority: 1,
+      priority: PRIORITY_KEEP,
     });
   }
 
+  // Step 6b: Enforcement patterns from the project-root patterns dir
+  const patternsSection = renderPatterns(projectPath);
+  if (patternsSection) {
+    sections.push({
+      key: 'patterns',
+      content: patternsSection,
+      priority: PRIORITY_PATTERNS,
+    });
+  }
+
+  // Step 6c: Environment advisories (LSP / Railway-MCP / hookify / briefing
+  // file / registry orphans) with per-project dismissal memory. The module
+  // owns all logic + I/O and never throws; the builder only renders. This is
+  // orient's advisory home now that orient is being retired (act:f9ea075d).
+  try {
+    const advisories = runAdvisoryPass({ projectPath });
+    if (advisories.length > 0) {
+      const body = advisories.map(a => `- ${a.action}`).join('\n');
+      sections.push({
+        key: 'advisories',
+        content: `--- Advisories ---\n${body}`,
+        priority: PRIORITY_KEEP,
+      });
+    }
+  } catch {
+    // never block session start on advisory rendering
+  }
+
   // Untracked project mode — if no project match, just add a note
   if (!projectSlug && projectPath) {
     sections.push({
       key: 'untracked',
       content: '(This project is not tracked by watchtower. Only global state is shown.)',
-      priority: 1,
+      priority: PRIORITY_KEEP,
     });
   }
 
@@ -322,16 +420,17 @@ function assembleSections(sections) {
   }
 
   // Need to truncate. Remove sections in reverse priority order (highest first).
-  // Priority 3 = domain files (truncated first)
-  // Priority 2 = project file (truncated second)
-  // Priority 0 = summary (never truncated)
-  // Priority 1 = queue/untracked (try to keep)
+  // PRIORITY_PATTERNS (4) = enforcement patterns (truncated first)
+  // PRIORITY_DOMAIN (3)   = domain files
+  // PRIORITY_PROJECT (2)  = project file
+  // PRIORITY_KEEP (1)     = threads/queue/advisories/untracked (try to keep)
+  // PRIORITY_NEVER (0)    = summary (never truncated)
 
   const sortedByTruncPriority = [...sections].sort((a, b) => b.priority - a.priority);
 
   let remaining = [...sections];
   for (const section of sortedByTruncPriority) {
-    if (section.priority === 0) break; // Never truncate summary
+    if (section.priority === PRIORITY_NEVER) break; // Never truncate summary
 
     const idx = remaining.findIndex(s => s.key === section.key);
     if (idx === -1) continue;

package/templates/scripts/watchtower-lib.mjs

@@ -6,7 +6,7 @@
 
 import {
   readFileSync, writeFileSync, existsSync,
-  mkdirSync, renameSync, realpathSync,
+  mkdirSync, renameSync, realpathSync, readdirSync,
 } from 'fs';
 import { join, dirname, basename, resolve as resolvePath } from 'path';
 import { homedir } from 'os';
@@ -68,6 +68,133 @@ export function slugify(text) {
   return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
 }
 
+// ---------------------------------------------------------------------------
+// flushFeedbackOutbox — deliver the GLOBAL cc-feedback outbox to the CC repo
+// ---------------------------------------------------------------------------
+// Ring 1 mechanical duty (act:6c3a4763). Ports orient's delivery algorithm:
+// read ~/.claude/cc-feedback-outbox.json, resolve the CC source repo via
+// cc-registry (the entry whose package.json name is create-claude-cabinet),
+// write each undelivered item's body to <cc>/feedback/{date}-{slug}.md with
+// a skip-if-exists guard against feedback/ AND feedback/resolved/ — a name
+// containing the slug, or a delivery-scheme name whose slug is a whole-token
+// prefix/subset of the new one, means a prior session already delivered or
+// resolved it — then atomically rewrite the outbox — [] on a clean pass, only the
+// failed items otherwise. Fail-safe: if the destination cannot be resolved,
+// the outbox is left untouched — an item is never dropped without a file
+// existing for it. Ring 1 is now the SOLE feedback-delivery owner: orient's
+// duplicate flush (incompatible {date}-{slug}-{seq}.md scheme) was retired
+// (act:d53ff509) once this duty was verified in the live runtime.
+
+const CC_PACKAGE_NAME = 'create-claude-cabinet';
+
+function resolveCcFeedbackDir(registryPath) {
+  if (!existsSync(registryPath)) return null;
+  let registry;
+  try {
+    registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+  } catch {
+    return null;
+  }
+  for (const proj of registry.projects || []) {
+    const pkgPath = join(proj.path || '', 'package.json');
+    if (!existsSync(pkgPath)) continue;
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      if (pkg.name === CC_PACKAGE_NAME) return join(proj.path, 'feedback');
+    } catch { /* unreadable package.json — not the CC repo */ }
+  }
+  return null;
+}
+
+function feedbackFileExists(feedbackDir, slug) {
+  for (const dir of [feedbackDir, join(feedbackDir, 'resolved')]) {
+    if (!existsSync(dir)) continue;
+    for (const name of readdirSync(dir)) {
+      if (name.includes(slug)) return true;
+      // Reverse direction (act:ca0aee25): a re-report under a LONGER title
+      // must still match its already-delivered shorter twin. Deliberately
+      // narrow — only delivery-scheme names ({date}-{slug}[-{seq}].md)
+      // carry slug semantics, and the existing slug must sit on whole
+      // dash-token boundaries inside the new one. Silent suppression of
+      // genuinely new feedback is worse than a duplicate delivery, so no
+      // substring fuzz and no participation by hand-named files.
+      const m = /^\d{4}-\d{2}-\d{2}-(.+?)(?:-\d+)?\.md$/.exec(name);
+      if (m && `-${slug}-`.includes(`-${m[1]}-`)) return true;
+    }
+  }
+  return false;
+}
+
+export function flushFeedbackOutbox(opts = {}) {
+  const outboxPath = opts.outboxPath
+    || join(homedir(), '.claude', 'cc-feedback-outbox.json');
+  const registryPath = opts.registryPath
+    || join(homedir(), '.claude', 'cc-registry.json');
+
+  const result = { status: 'ok', delivered: 0, skipped: 0, kept: 0, destination: null };
+
+  if (!existsSync(outboxPath)) {
+    result.status = 'no-outbox';
+    return result;
+  }
+
+  let outbox;
+  try {
+    outbox = JSON.parse(readFileSync(outboxPath, 'utf8'));
+  } catch {
+    // Malformed outbox: per orient's contract, warn and reset to [].
+    atomicWrite(outboxPath, '[]\n');
+    result.status = 'malformed-reset';
+    return result;
+  }
+
+  if (!Array.isArray(outbox) || outbox.length === 0) {
+    result.status = 'empty';
+    return result;
+  }
+
+  const undelivered = outbox.filter((item) => item && item.delivered !== true);
+  if (undelivered.length === 0) {
+    // Only stale delivered:true markers remain — don't accumulate them.
+    atomicWrite(outboxPath, '[]\n');
+    result.status = 'markers-cleared';
+    return result;
+  }
+
+  const feedbackDir = opts.destination || resolveCcFeedbackDir(registryPath);
+  if (!feedbackDir) {
+    // Cannot resolve where feedback lives. Leave the outbox untouched —
+    // never mark/drop an item without a delivered file existing for it.
+    result.status = 'no-destination';
+    result.kept = outbox.length;
+    return result;
+  }
+  result.destination = feedbackDir;
+
+  const failed = [];
+  for (const item of undelivered) {
+    try {
+      const slug = slugify(item.title || 'untitled') || 'untitled';
+      if (feedbackFileExists(feedbackDir, slug)) {
+        result.skipped++;
+        continue;
+      }
+      const date = item.date || new Date().toISOString().slice(0, 10);
+      if (!existsSync(feedbackDir)) mkdirSync(feedbackDir, { recursive: true });
+      writeFileSync(join(feedbackDir, `${date}-${slug}.md`), item.body || item.title || '');
+      result.delivered++;
+    } catch {
+      failed.push(item);
+    }
+  }
+
+  // Clean pass resets to []; otherwise keep only the failed items.
+  atomicWrite(outboxPath, JSON.stringify(failed, null, 2) + '\n');
+  result.kept = failed.length;
+  if (failed.length > 0) result.status = 'partial';
+  return result;
+}
+
 // ---------------------------------------------------------------------------
 // Thread cursor history (schema v2)
 // ---------------------------------------------------------------------------
@@ -236,6 +363,55 @@ export function preserveRing3LastSession(freshContent, existingContent) {
   return freshContent.slice(0, freshIdx) + preserved + '\n' + freshContent.slice(end);
 }
 
+// ---------------------------------------------------------------------------
+// writeProjectStatePreservingRing3 — race-safe project-state rebuild write
+// ---------------------------------------------------------------------------
+// preserveRing3LastSession is a pure merge; a raw read→merge→atomicWrite
+// around it has a read-then-write race: if Ring 3 writes its fresh Last
+// Session between Ring 1's snapshot read and the rename, the rebuild is
+// computed from a stale snapshot and silently drops the just-authored
+// summary until the NEXT session close. This helper closes that window
+// with a re-read check-and-retry: merge against a snapshot, re-read to
+// verify nothing changed underneath us, and only then write; on change,
+// re-merge against the fresh read (up to maxAttempts). If attempts are
+// exhausted (pathological churn), it merges against the FRESHEST read and
+// writes anyway — the rebuild is never skipped.
+//
+// Residual window: a write landing between the verify read and the rename
+// inside atomicWrite is still theoretically possible — microseconds wide,
+// down from the full merge-computation window. If it ever bites in
+// practice, the structural fix is the Ring 3 sidecar-file design (option c
+// in .claude/plans/watchtower-ring1-race-fix.md).
+//
+// opts._beforeVerifyHook is a TEST-ONLY injection seam, fired between the
+// merge and the verify re-read so tests can deterministically simulate a
+// concurrent Ring 3 write. Production callers must not pass it.
+//
+// Returns { written: true, attempts, exhausted? }.
+export function writeProjectStatePreservingRing3(statePath, freshContent, opts = {}) {
+  const maxAttempts = opts.maxAttempts ?? 3;
+  const read = () => (existsSync(statePath) ? readFileSync(statePath, 'utf8') : null);
+
+  let snapshot = read();
+  for (let i = 0; i < maxAttempts; i++) {
+    const merged = preserveRing3LastSession(freshContent, snapshot);
+    opts._beforeVerifyHook?.();
+    const verify = read();
+    if (verify !== snapshot) {
+      // Someone (Ring 3) wrote since our read — re-merge against it.
+      snapshot = verify;
+      continue;
+    }
+    atomicWrite(statePath, merged);
+    return { written: true, attempts: i + 1 };
+  }
+
+  // Attempts exhausted (pathological churn): merge against the freshest
+  // read and write anyway — never skip the rebuild.
+  atomicWrite(statePath, preserveRing3LastSession(freshContent, read()));
+  return { written: true, attempts: maxAttempts, exhausted: true };
+}
+
 // ---------------------------------------------------------------------------
 // resolveProjectIdentity — THE canonical "which project is this?" answer
 // ---------------------------------------------------------------------------

package/templates/scripts/watchtower-queue.mjs

@@ -4,7 +4,7 @@
 // All writes use atomic temp+rename per watchtower-contracts.md.
 // Queue uses directory listing, not index files (no-index convention).
 
-import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync, renameSync } from 'fs';
+import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync, renameSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { randomBytes } from 'crypto';
 
@@ -13,6 +13,23 @@ const WATCHTOWER_DIR = process.env.WATCHTOWER_DIR
 
 const QUEUE_DIR = join(WATCHTOWER_DIR, 'queue', 'items');
 
+// mux's dispatch queue (bin/mux `qa` verbs — the single desk-dispatch path,
+// carrying qa-handoffs AND routine dispatches). Descriptors are routing
+// convenience keyed <desk>/<item_id>.json (plus <desk>/in-flight/ once
+// drained); the inbox item is the durable record. Terminal exits here must
+// clear the matching descriptor or the two stores drift (act:796fe6dc —
+// resolved ghosts get re-offered by `mux qa drain`). The dir name is legacy.
+const MUX_QA_DIR = process.env.MUX_QA_DIR
+  || join(process.env.HOME, '.local', 'share', 'mux', 'qa-handoff');
+
+// Categories whose items are pushed to a desk via the mux dispatch queue.
+// Every terminal exit (resolve / dismiss / supersede / expire) on an item in
+// one of these categories clears its dispatch descriptor(s). Exported so
+// consumers (e.g. the /session-handoff epilogue drain) exclude dispatched
+// items by importing this set rather than re-listing categories in prose —
+// a hand-maintained copy would drift the moment a third category is added.
+export const DISPATCHED_CATEGORIES = new Set(['qa-handoff', 'routine']);
+
 // --- Helpers ---
 
 function ensureDir(dir) {
@@ -42,6 +59,27 @@ function generateId() {
   return 'dec-' + randomBytes(4).toString('hex');
 }
 
+// Best-effort removal of the mux dispatch-queue descriptor(s) for an item —
+// both the queued copy and the in-flight copy, across every desk dir (desk
+// names differ from project names, so we sweep rather than guess). Never
+// throws: a routing-cleanup failure must not block a gate exit. The ·N badge
+// is recomputed by mux on its next mutation/desk-open, so a deletion here is
+// picked up without tmux involvement.
+function clearDispatchEntries(item) {
+  try {
+    if (!existsSync(MUX_QA_DIR)) return;
+    for (const desk of readdirSync(MUX_QA_DIR, { withFileTypes: true })) {
+      if (!desk.isDirectory()) continue;
+      for (const sub of ['.', 'in-flight']) {
+        const fp = join(MUX_QA_DIR, desk.name, sub, `${item.id}.json`);
+        try {
+          if (existsSync(fp)) unlinkSync(fp);
+        } catch { /* best-effort per file */ }
+      }
+    }
+  } catch { /* best-effort overall */ }
+}
+
 // Urgency sort order: urgent < normal < low (urgent first)
 const URGENCY_ORDER = { urgent: 0, normal: 1, low: 2 };
 
@@ -57,6 +95,15 @@ const URGENCY_ORDER = { urgent: 0, normal: 1, low: 2 };
 // functions below only call into it.
 
 const QA_CATEGORY = 'qa-handoff';
+
+// Categories whose items carry a structural recipient gate: they may never be
+// included in a batch disposition — each leaves the queue only through its own
+// gate (per-item resolve with a validated verdict, or a typed per-item
+// dismissal). Distinct from DISPATCHED_CATEGORIES: 'routine' is dispatched but
+// NOT gated — stale routines are legal batch fodder. Future gated categories
+// join this set and inherit batch refusal for free.
+export const GATED_CATEGORIES = new Set([QA_CATEGORY]);
+
 const QA_TERMINAL_VERDICTS = ['runtime-verified', 'blocked'];
 // The parameterized token. Canonical form uses U+00B7 (·); input tolerates
 // common separator drift (-, –, —, *, •) because sessions retype labels.
@@ -326,6 +373,7 @@ export function resolveItem(id, { resolution, resolution_notes = null, resolutio
   item.resolution_type = resolution_type;
   item.resolution_notes = resolution_notes;
   atomicWrite(fp, item);
+  if (DISPATCHED_CATEGORIES.has(item.category)) clearDispatchEntries(item);
   return item;
 }
 
@@ -349,6 +397,7 @@ export function dismissItem(id, { notes = null, resolution_type = null } = {}) {
   item.resolution_type = resolution_type;
   item.resolution_notes = notes;
   atomicWrite(fp, item);
+  if (DISPATCHED_CATEGORIES.has(item.category)) clearDispatchEntries(item);
   return item;
 }
 
@@ -368,6 +417,7 @@ export function supersedeItem(id, { reason = null } = {}) {
   item.status = 'superseded';
   item.resolution_notes = reason;
   atomicWrite(fp, item);
+  if (DISPATCHED_CATEGORIES.has(item.category)) clearDispatchEntries(item);
   return item;
 }
 
@@ -386,9 +436,64 @@ export function expireItem(id) {
   item.status = 'expired';
   item.resolution_notes = 'Auto-expired by age policy';
   atomicWrite(fp, item);
+  if (DISPATCHED_CATEGORIES.has(item.category)) clearDispatchEntries(item);
   return item;
 }
 
+/**
+ * Apply ONE disposition to a batch of ungated items — the single bulk path,
+ * used by /briefing's batch dispositions and /inbox's bulk triage. A batch is one
+ * operator decision applied to many items, so the typed reason is REQUIRED:
+ * it lands on every item as its audit trail.
+ *
+ * All-or-nothing pre-validation: throws BEFORE any write when (a) any id is
+ * unknown, (b) any item is in a GATED_CATEGORIES category — gated items never
+ * batch; each goes through its own gate — or (c) the typed reason is absent.
+ * A batch that would hit a gate fails whole, never half-applies.
+ * Non-pending items are not an error (another session may have raced the
+ * disposition); they are skipped and reported.
+ * @param {string[]} ids
+ * @param {object} params
+ * @param {'dismiss'|'resolve'} params.disposition
+ * @param {string} params.resolution_type - typed reason (e.g. 'stale',
+ *   'noise', 'captured-to-memory', 'acted-on') — required
+ * @param {string} params.notes - plain-language reason — required
+ * @param {string} [params.resolution] - resolve batches: the resolution
+ *   value stamped on each item (defaults to resolution_type)
+ * @returns {{applied: string[], skipped_not_pending: string[]}}
+ */
+export function applyBatch(ids, { disposition, resolution_type, notes, resolution = null } = {}) {
+  if (!Array.isArray(ids) || ids.length === 0) {
+    throw new Error('applyBatch: ids must be a non-empty array');
+  }
+  if (disposition !== 'dismiss' && disposition !== 'resolve') {
+    throw new Error("applyBatch: disposition must be 'dismiss' or 'resolve'");
+  }
+  if (typeof resolution_type !== 'string' || !resolution_type.trim()
+      || typeof notes !== 'string' || !notes.trim()) {
+    throw new Error('applyBatch: a typed resolution_type AND notes are required — a batch is one decision applied to many items, and the reason lands on every one');
+  }
+  const items = ids.map((id) => {
+    const item = getItem(id);
+    if (!item) throw new Error(`applyBatch: unknown item ${id} — batches pre-validate whole; nothing was applied`);
+    return item;
+  });
+  const gated = items.filter((i) => GATED_CATEGORIES.has(i.category));
+  if (gated.length > 0) {
+    throw new Error(`applyBatch: ${gated.map((i) => `${i.id} (${i.category})`).join(', ')} carr${gated.length === 1 ? 'ies' : 'y'} a recipient gate — gated items never batch; handle each through its own gate. Nothing was applied`);
+  }
+  const applied = [];
+  const skipped_not_pending = [];
+  for (const item of items) {
+    const result = disposition === 'dismiss'
+      ? dismissItem(item.id, { notes, resolution_type })
+      : resolveItem(item.id, { resolution: resolution ?? resolution_type, resolution_notes: notes, resolution_type });
+    if (result) applied.push(item.id);
+    else skipped_not_pending.push(item.id);
+  }
+  return { applied, skipped_not_pending };
+}
+
 /**
  * List pending inbox items with optional filters.
  * @param {object} filters
@@ -425,6 +530,45 @@ export function listPending({ project, category, urgency, maxAge } = {}) {
   return items;
 }
 
+/**
+ * List inbox items across ALL statuses with optional filters — the single
+ * source for "read non-pending items". (Ring 2's private readAllQueueItems
+ * fork predates this helper; consolidating it is a separate-lane follow-up.)
+ * @param {object} filters
+ * @param {string} [filters.project] - exact match on item.project
+ * @param {string} [filters.category] - exact match on item.category
+ * @param {string[]} [filters.statuses] - keep items whose status is in the
+ *   array (omit = all statuses)
+ * @param {string} [filters.since] - ISO date; keep items whose
+ *   `resolved_at || filed_at` >= since (bounds corpus growth for dedup callers)
+ * @returns {Array} items sorted newest first by (resolved_at || filed_at)
+ */
+export function listItems({ project, category, statuses, since } = {}) {
+  if (!existsSync(QUEUE_DIR)) return [];
+  const sinceMs = since ? new Date(since).getTime() : null;
+  const entries = readdirSync(QUEUE_DIR, { withFileTypes: true });
+  const items = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+    try {
+      const item = readItem(join(QUEUE_DIR, entry.name));
+      if (project && item.project !== project) continue;
+      if (category && item.category !== category) continue;
+      if (Array.isArray(statuses) && !statuses.includes(item.status)) continue;
+      if (sinceMs != null) {
+        const ts = new Date(item.resolved_at || item.filed_at).getTime();
+        if (!(ts >= sinceMs)) continue;
+      }
+      items.push(item);
+    } catch {
+      // Skip unparseable items
+    }
+  }
+  items.sort((a, b) =>
+    new Date(b.resolved_at || b.filed_at) - new Date(a.resolved_at || a.filed_at));
+  return items;
+}
+
 /**
  * Get a single inbox item by id.
  * @param {string} id
@@ -490,6 +634,7 @@ export function runExpiry({ warnDays = 14, expireDays = 30 } = {}) {
       item.status = 'expired';
       item.resolution_notes = `Auto-expired after ${expireDays} days. If still relevant, re-file with updated context.`;
       atomicWrite(itemPath(item.id), item);
+      if (DISPATCHED_CATEGORIES.has(item.category)) clearDispatchEntries(item);
       expired.push(item);
     } else if (age >= warnMs) {
       warned.push(item);