neurain 0.1.0-alpha.0

package/src/core/source_digest_gen.mjs

@@ -0,0 +1,311 @@
+// `source-digest` command (W-B). The manifest GENERATOR: scans the raw source
+// tree, fingerprints each file (reusing the prior sha when size+mtime are
+// unchanged), infers compile status, and scores high-value sources for deep
+// compile. Its only write is the source-digest manifest the engine read side
+// (source_digest.mjs) already consumes; dry by default, writes only with --write.
+// Faithful port of the vault neurain-source-digest tool, EXCEPT the path
+// sensitivity fallback, which uses the W-A label resolver + registry baseline
+// instead of the vault's hardcoded area-name regex (no vault identifiers leak
+// into the engine; on the reference vault the result is equivalent).
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, ensureDir, readText, relPath, timestamp, walkFiles } from './fs.mjs';
+import { recallConfig, vaultConfig } from './config.mjs';
+import { createSensitivityResolver } from './labels.mjs';
+import { loadAreaIntel } from './classify.mjs';
+import { atomicWriteJson } from './durable.mjs';
+import { readJsonSafe } from './vault_state.mjs';
+
+const TERMINAL_STATUSES = new Set(['compiled', 'flushed', 'archived', 'superseded']);
+const HIGH_VALUE_EXTS = new Set(['.pdf', '.docx', '.xlsx', '.xls', '.pptx', '.csv']);
+
+export async function sourceDigestCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  const recallCfg = recallConfig(root);
+  const intel = loadAreaIntel(root, vaultCfg);
+  const resolver = createSensitivityResolver(root, recallCfg);
+
+  const scope = String(args.scope || args.path || vaultCfg.raw_dir);
+  const manifestRel = String(args.manifest || vaultCfg.source_digest_manifest);
+  const write = Boolean(args.write || args.update);
+  const rehash = Boolean(args.rehash || args.full);
+  const top = Number(args.top || 20);
+  const now = timestamp();
+  const manifestAbs = path.join(root, manifestRel);
+  const previous = readJsonSafe(manifestAbs, null) || { version: 1, updated_at: '', files: {} };
+
+  const files = scanSourceFiles(root, scope, vaultCfg);
+  const nextFiles = {};
+  const newItems = [];
+  const changedItems = [];
+  const unchangedItems = [];
+  const highValueCandidates = [];
+  let reusedHashCount = 0;
+
+  for (const abs of files) {
+    const rel = relPath(root, abs);
+    const stat = fs.statSync(abs);
+    const previousEntry = (previous.files && previous.files[rel]) || null;
+    const canReuseHash =
+      !rehash &&
+      previousEntry &&
+      previousEntry.size_bytes === stat.size &&
+      previousEntry.mtime_ms === Math.round(stat.mtimeMs) &&
+      typeof previousEntry.sha256 === 'string';
+    if (canReuseHash) reusedHashCount += 1;
+    const sha = canReuseHash ? previousEntry.sha256 : sha256File(abs);
+    const rawMetadata = readRawMetadata(abs);
+    const sourceId = rawMetadata.source_id || inferSourceId(rel);
+    const envelope = sourceId ? readEnvelope(root, vaultCfg, sourceId) : null;
+    const text = isTextSource(abs) ? readText(abs, '').slice(0, 30000) : '';
+    const sensitivity = envelope?.sensitivity || rawMetadata.sensitivity || pathSensitivity(rel, text, resolver, intel, vaultCfg);
+    const compiledTo = inferCompiledTo(envelope, rawMetadata, previousEntry);
+    const status = inferStatus(envelope, previousEntry, rawMetadata, compiledTo);
+    const assessment = assessHighValue(rel, stat, sensitivity, text);
+    const entry = {
+      path: rel,
+      sha256: sha,
+      size_bytes: stat.size,
+      mtime_ms: Math.round(stat.mtimeMs),
+      source_id: sourceId,
+      source_type: envelope?.source_type || rawMetadata.source_type || inferSourceType(rel),
+      sensitivity,
+      status,
+      compiled_to: compiledTo,
+      first_seen: previousEntry?.first_seen || now,
+      last_seen: now,
+      last_changed: previousEntry?.sha256 && previousEntry.sha256 !== sha ? now : previousEntry?.last_changed || now,
+      high_value_score: assessment.score,
+      high_value_reasons: assessment.reasons,
+    };
+    nextFiles[rel] = entry;
+
+    if (!previousEntry) newItems.push(entry);
+    else if (previousEntry.sha256 !== sha) changedItems.push(entry);
+    else unchangedItems.push(entry);
+
+    if (!isCompiled(entry) && entry.high_value_score >= 2) highValueCandidates.push(entry);
+  }
+
+  const removed = Object.keys(previous.files || {}).filter((rel) => !nextFiles[rel]);
+  const nextManifest = {
+    version: 1,
+    updated_at: now,
+    scope,
+    generated_by: 'source_digest_gen.mjs',
+    policy: 'Tracks raw source fingerprints so unchanged files can be skipped and high-value sources can be selected for deep compile.',
+    files: nextFiles,
+  };
+
+  if (write) {
+    ensureDir(path.dirname(manifestAbs));
+    atomicWriteJson(manifestAbs, nextManifest);
+  }
+
+  const sortedHighValue = highValueCandidates
+    .sort((a, b) => b.high_value_score - a.high_value_score || b.size_bytes - a.size_bytes)
+    .slice(0, top)
+    .map(summarizeEntry);
+
+  const payload = {
+    ok: true,
+    command: 'source-digest',
+    durable_write: Boolean(write),
+    manifest: manifestRel,
+    scope,
+    write,
+    scanned_count: files.length,
+    reused_hash_count: reusedHashCount,
+    new_count: newItems.length,
+    changed_count: changedItems.length,
+    unchanged_count: unchangedItems.length,
+    removed_count: removed.length,
+    compiled_count: Object.values(nextFiles).filter(isCompiled).length,
+    uncompiled_count: Object.values(nextFiles).filter((entry) => !isCompiled(entry)).length,
+    high_value_candidate_count: highValueCandidates.length,
+    high_value_candidates: sortedHighValue,
+    removed: removed.slice(0, top),
+  };
+
+  if (args.json) return { json: true, payload };
+  return { text: render(payload) };
+}
+
+function scanSourceFiles(root, scope, vaultCfg) {
+  const scopeAbs = path.join(root, scope);
+  if (!fs.existsSync(scopeAbs)) return [];
+  return walkFiles(scopeAbs, { includeRaw: true, maxFiles: 200000 })
+    .filter((abs) => {
+      const rel = relPath(root, abs);
+      if (rel.startsWith(`${vaultCfg.raw_inbox_dir}/`)) return false;
+      if (rel.includes('/.git/') || rel.includes('/node_modules/')) return false;
+      if (rel.endsWith('.json') && rel.includes('/_inbox/')) return false;
+      return true;
+    })
+    .sort();
+}
+
+function sha256File(abs) {
+  return crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+}
+
+function isTextSource(abs) {
+  const ext = path.extname(abs).toLowerCase();
+  return ext === '.md' || ext === '.txt';
+}
+
+function inferSourceId(rel) {
+  const match = rel.match(/\b(raw-\d{8}-\d{3})\b/);
+  return match ? match[1] : '';
+}
+
+function readRawMetadata(abs) {
+  if (!isTextSource(abs)) return {};
+  const text = readText(abs, '').slice(0, 12000);
+  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return {};
+  return parseSimpleFrontmatter(fm[1]);
+}
+
+function parseSimpleFrontmatter(body) {
+  const meta = {};
+  let currentKey = '';
+  for (const rawLine of body.split(/\r?\n/)) {
+    const line = rawLine.trimEnd();
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const listMatch = line.match(/^\s+-\s*(.+)$/);
+    if (listMatch && currentKey) {
+      if (!Array.isArray(meta[currentKey])) meta[currentKey] = [];
+      meta[currentKey].push(cleanScalar(listMatch[1]));
+      continue;
+    }
+    const keyMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!keyMatch) continue;
+    currentKey = keyMatch[1];
+    const rawValue = keyMatch[2].trim();
+    if (!rawValue) meta[currentKey] = [];
+    else if (rawValue.startsWith('[') && rawValue.endsWith(']')) meta[currentKey] = rawValue.slice(1, -1).split(',').map(cleanScalar).filter(Boolean);
+    else meta[currentKey] = cleanScalar(rawValue);
+  }
+  return meta;
+}
+
+function cleanScalar(value) {
+  const text = String(value).trim();
+  if ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'"))) return text.slice(1, -1);
+  return text;
+}
+
+function readEnvelope(root, vaultCfg, sourceId) {
+  return readJsonSafe(path.join(root, `${vaultCfg.raw_inbox_dir}/${sourceId}.json`), null);
+}
+
+function inferSourceType(rel) {
+  if (rel.includes('/web/videos/')) return 'video';
+  if (rel.includes('/web/articles/')) return 'article';
+  if (rel.includes('/web/research/')) return 'paper';
+  if (rel.includes('/web/podcasts/')) return 'podcast';
+  if (rel.includes('/web/books/')) return 'book';
+  if (rel.includes('/files/')) return 'file';
+  if (rel.includes('/screenshots/')) return 'screenshot';
+  return 'raw';
+}
+
+// Path-based sensitivity fallback (only reached when neither the envelope nor the
+// file frontmatter sets sensitivity). Uses the W-A label resolver for the PRIVATE
+// decision (frontmatter + _area.md baseline + boundary path markers) and the
+// registry's per-area baseline for INTERNAL, plus generic business markers. No
+// hardcoded area names, so no vault identifier enters the engine.
+function pathSensitivity(rel, text, resolver, intel, vaultCfg) {
+  if (resolver.sensitivityFor(rel, text) === 'private') return 'private';
+  const areaMatch = rel.match(new RegExp(`^${vaultCfg.areas_dir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/([^/]+)/`));
+  if (areaMatch) {
+    const baseline = String((intel.sensitivity && intel.sensitivity[areaMatch[1]]) || '').toLowerCase();
+    if (/private/.test(baseline)) return 'private';
+    if (/internal/.test(baseline)) return 'internal';
+  }
+  if (/\b(internal|strategy|governance|partner|foundation|roadmap)\b/.test(rel.toLowerCase())) return 'internal';
+  return 'public';
+}
+
+function inferCompiledTo(envelope, rawMetadata, previousEntry) {
+  if (envelope?.compiled_to?.length) return envelope.compiled_to;
+  if (Array.isArray(rawMetadata.compiled_to) && rawMetadata.compiled_to.length) return rawMetadata.compiled_to;
+  if (typeof rawMetadata.compiled_to === 'string' && rawMetadata.compiled_to.trim()) return [rawMetadata.compiled_to.trim()];
+  return previousEntry?.compiled_to || [];
+}
+
+function normalizeStatus(status) {
+  return typeof status === 'string' ? status.trim().replace(/^["']|["']$/g, '') : '';
+}
+
+function inferStatus(envelope, previousEntry, rawMetadata, compiledTo) {
+  const envelopeStatus = normalizeStatus(envelope?.status);
+  const rawStatus = normalizeStatus(rawMetadata.status);
+  const rawIngestStatus = normalizeStatus(rawMetadata.ingest_status);
+  if (TERMINAL_STATUSES.has(envelopeStatus)) return envelopeStatus;
+  if (TERMINAL_STATUSES.has(rawIngestStatus)) return rawIngestStatus;
+  if (TERMINAL_STATUSES.has(rawStatus)) return rawStatus;
+  if ((compiledTo || []).length) return 'compiled';
+  if (envelopeStatus) return envelopeStatus;
+  if (rawIngestStatus && rawIngestStatus !== 'inbox') return rawIngestStatus;
+  if (rawStatus) return rawStatus;
+  return previousEntry?.status || 'discovered';
+}
+
+function isCompiled(entry) {
+  return TERMINAL_STATUSES.has(entry.status) || (entry.compiled_to || []).length > 0;
+}
+
+function assessHighValue(rel, stat, sensitivity, text) {
+  const reasons = [];
+  let score = 0;
+  const ext = path.extname(rel).toLowerCase();
+  const lowerPath = rel.toLowerCase();
+  if (HIGH_VALUE_EXTS.has(ext)) { score += 1; reasons.push(`structured or long-form source: ${ext}`); }
+  if (stat.size > 1_000_000) { score += 1; reasons.push('larger than 1MB'); }
+  if (stat.size > 10_000_000) { score += 1; reasons.push('larger than 10MB'); }
+  if (['private', 'internal'].includes(sensitivity)) { score += 1; reasons.push('sensitive or internal source'); }
+  const haystack = `${lowerPath}\n${text.toLowerCase()}`;
+  const patterns = [
+    ['investment', /investment|investor|valuation|revenue|model|dd|due diligence|term sheet|투자|밸류|매출|실사|텀시트/],
+    ['legal or contract', /contract|agreement|legal|license|tax|loan|real estate|계약|법무|세금|대출|부동산|등기/],
+    ['strategy or roadmap', /strategy|roadmap|milestone|checkpoint|current status|전략|로드맵|마일스톤|체크포인트|현황/],
+    ['health or family administration', /health|medical|family|parents|credentials|건강|의료|가족|부모|증명서/],
+  ];
+  for (const [label, regex] of patterns) {
+    if (regex.test(haystack)) { score += 1; reasons.push(label); }
+  }
+  if (text.length > 6000) { score += 1; reasons.push('long markdown source'); }
+  if (text.length > 20000) { score += 1; reasons.push('very long markdown source'); }
+  return { score, reasons: [...new Set(reasons)] };
+}
+
+function summarizeEntry(entry) {
+  return {
+    path: entry.path,
+    source_id: entry.source_id,
+    source_type: entry.source_type,
+    sensitivity: entry.sensitivity,
+    status: entry.status,
+    high_value_score: entry.high_value_score,
+    high_value_reasons: entry.high_value_reasons,
+    suggested_action: 'Deep Compile selected source before promoting official memory.',
+  };
+}
+
+function render(result) {
+  const lines = ['# Source Digest', ''];
+  lines.push(`- Manifest: ${result.manifest}`);
+  lines.push(`- Updated: ${result.write ? 'yes' : 'no, dry report only'}`);
+  lines.push(`- Scanned: ${result.scanned_count}`);
+  lines.push(`- Reused hashes (size+mtime unchanged): ${result.reused_hash_count}`);
+  lines.push(`- New: ${result.new_count}`);
+  lines.push(`- Changed: ${result.changed_count}`);
+  lines.push(`- Uncompiled: ${result.uncompiled_count}`);
+  lines.push(`- High-value candidates: ${result.high_value_candidate_count}`);
+  return lines.join('\n');
+}

package/src/core/stage.mjs

@@ -0,0 +1,105 @@
+// `stage` command + stageAndPromote primitive (W-B). The tool-enforced "a secret
+// never reaches canonical" guarantee: content is written to .neurain-staging
+// first (excluded from search/label walks), scanned fail-closed for secrets, and
+// ONLY promoted to its canonical target by an atomic rename if clean. On a high-
+// confidence hit it stays in staging (never indexed), the canonical target is
+// untouched, and the command exits 2. Every B4 durable canonical write routes
+// through here. Faithful port of the vault neurain-stage + wrap-intel
+// stageAndPromote.
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, ensureDir, readText, safeResolve, sha256, timestamp } from './fs.mjs';
+import { atomicWriteText, readJsonlRows } from './durable.mjs';
+import { isBlocking, scanSecrets, summarizeHits } from './secret_scan.mjs';
+
+export const STAGING_DIR = '.neurain-staging';
+export const PROMOTION_LEDGER = `${STAGING_DIR}/.promotions.jsonl`;
+const LEDGER_CAP = 5000;
+
+// Stage content, scan it, and atomically promote it to `relTarget` only if clean.
+// A blocking secret (unless allowSecret) leaves the content in staging and the
+// canonical target untouched.
+export function stageAndPromote(root, relTarget, content, { allowSecret = false } = {}) {
+  const safeRel = String(relTarget).replace(/^\/+/, '');
+  const stagedRel = `${STAGING_DIR}/${safeRel}`;
+  const stagedAbs = safeResolve(root, stagedRel);
+  atomicWriteText(stagedAbs, content); // land in excluded staging first
+
+  const hits = scanSecrets(content);
+  if (isBlocking(hits) && !allowSecret) {
+    return { promoted: false, blocked: 'secret', staged_path: stagedRel, canonical_path: safeRel, hits, summary: summarizeHits(hits) };
+  }
+
+  const canonAbs = safeResolve(root, safeRel);
+  ensureDir(path.dirname(canonAbs));
+  fs.renameSync(stagedAbs, canonAbs); // atomic promote (same filesystem under root)
+
+  // Record proof of promotion (content sha) so a later check can prove this
+  // canonical file was scanned before it reached the indexed tree.
+  const ledgerAbs = safeResolve(root, PROMOTION_LEDGER);
+  ensureDir(path.dirname(ledgerAbs));
+  fs.appendFileSync(ledgerAbs, `${JSON.stringify({ path: safeRel, sha256: sha256(content), promoted_at: timestamp() })}\n`);
+  try {
+    const rows = readJsonlRows(ledgerAbs);
+    if (rows.length > LEDGER_CAP) {
+      atomicWriteText(ledgerAbs, `${rows.slice(-Math.floor(LEDGER_CAP / 2)).map((r) => JSON.stringify(r)).join('\n')}\n`);
+    }
+  } catch { /* rotation is best-effort */ }
+  return { promoted: true, path: safeRel, hits, summary: summarizeHits(hits) };
+}
+
+// Did this canonical file's CURRENT content get promoted via staging (its sha is
+// in the ledger)? Direct writes that bypass the gate return false.
+export function wasStagedFile(root, relTarget) {
+  const safeRel = String(relTarget).replace(/^\/+/, '');
+  let content;
+  try { content = fs.readFileSync(safeResolve(root, safeRel), 'utf8'); } catch { return false; }
+  const sha = sha256(content);
+  const ledgerAbs = safeResolve(root, PROMOTION_LEDGER);
+  if (!fs.existsSync(ledgerAbs)) return false;
+  let rows = [];
+  try { rows = readJsonlRows(ledgerAbs); } catch { return false; }
+  return rows.some((r) => r && r.path === safeRel && r.sha256 === sha);
+}
+
+function readStageContent(args, root) {
+  if (typeof args.text === 'string') return args.text;
+  if (args.file) {
+    const target = path.isAbsolute(String(args.file)) ? String(args.file) : safeResolve(root, String(args.file));
+    return readText(target, '');
+  }
+  if (!process.stdin.isTTY) {
+    try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
+  }
+  return '';
+}
+
+export async function stageCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const target = String(args.target || '');
+  if (!target) {
+    process.exitCode = 1;
+    return done(args, { ok: false, command: 'stage', durable_write: false, error: 'Missing --target <relative path>.' });
+  }
+  const content = String(readStageContent(args, root) || '');
+  if (!content) {
+    process.exitCode = 1;
+    return done(args, { ok: false, command: 'stage', durable_write: false, error: 'Missing content. Pass --text, --file, or stdin.' });
+  }
+
+  const res = stageAndPromote(root, target, content, { allowSecret: Boolean(args['allow-secret']) });
+  process.exitCode = res.promoted ? 0 : 2;
+  return done(args, { ok: res.promoted, command: 'stage', durable_write: Boolean(res.promoted), ...res });
+}
+
+function done(args, payload) {
+  if (args.json) return { json: true, payload };
+  if (payload.error) return { text: `# Neurain Stage\n\n- ${payload.error}` };
+  if (payload.promoted) {
+    return { text: `✓ promoted to ${payload.path}${payload.hits.length ? ` (non-blocking notes: ${payload.summary})` : ''}` };
+  }
+  const lines = [`⛔ BLOCKED (secret): ${payload.summary}. Content held in ${payload.staged_path}; ${payload.canonical_path} NOT written.`];
+  for (const h of payload.hits) lines.push(`    [${h.confidence}] ${h.type}: ${h.sample}`);
+  lines.push('Redact the source, or pass --allow-secret for a verified false positive.');
+  return { text: lines.join('\n') };
+}

package/src/core/status.mjs

@@ -0,0 +1,175 @@
+// Read-only session status: boot summary, per-session detail, and an all-sessions
+// list. This is the data-driven core of the vault's session-status tool. It is
+// strictly read-only: it never advances the digest ack pointer and never runs
+// maintenance (--fix). The vault-product presentation layer (command menu,
+// decision guide, optimization lens, localized next-step copy) is intentionally
+// NOT hardcoded here so the engine stays generic; a vault shim composes that on
+// top of this data. lesson_review counts come from the engine's own lessons
+// registry, not the vault's lesson-intel.
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, exists } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+import { areaBriefPath, extractMarkdownSection, freshnessFor, loadSessionState, pendingQueueRows, readJsonl, readTextAt } from './vault_state.mjs';
+import { compileCandidateSummary } from './source_digest.mjs';
+import { computeDigest, renderDigest } from './digest.mjs';
+import { listLessons } from './lessons.mjs';
+
+function summarizeSession(root, vaultCfg, session, { staleDays, now }) {
+  const handoffRel = session.handoff_path || '';
+  const handoffText = readTextAt(root, handoffRel);
+  const areaBriefRel = session.area ? areaBriefPath(vaultCfg, session.area) : '';
+  const areaBriefText = areaBriefRel ? readTextAt(root, areaBriefRel) : '';
+  const pendingCount = pendingQueueRows(root, vaultCfg, { sessionId: session.session_id }).length;
+  const freshness = freshnessFor(session.last_pulse, staleDays, now);
+  return {
+    session_id: session.session_id,
+    area: session.area,
+    scope: session.scope,
+    status: session.status,
+    sensitivity: session.sensitivity,
+    last_pulse: session.last_pulse || '',
+    last_flush: session.last_flush || '',
+    ...freshness,
+    pending_count: pendingCount,
+    handoff_path: handoffRel,
+    handoff_exists: handoffRel ? exists(path.join(root, handoffRel)) : false,
+    handoff_lines: handoffText ? handoffText.split(/\r?\n/).length : 0,
+    area_brief_path: areaBriefRel,
+    area_brief_exists: areaBriefRel ? exists(path.join(root, areaBriefRel)) : false,
+    area_brief_latest_notes: extractMarkdownSection(areaBriefText, 'Latest Cross-Session Notes'),
+    current_focus: extractMarkdownSection(handoffText, 'Current Focus'),
+    next_suggested_action: extractMarkdownSection(handoffText, 'Next Suggested Action'),
+    read_first: session.read_first || [],
+  };
+}
+
+function lessonReview(root) {
+  let active = 0;
+  try { active = listLessons(root).length; } catch { active = 0; }
+  return { active_lessons: active, source: 'engine_lessons' };
+}
+
+function bootStatus(root, vaultCfg, state, { staleDays, now }) {
+  const sessions = Object.values(state.sessions || {}).map((s) => summarizeSession(root, vaultCfg, s, { staleDays, now }));
+  const queueRows = pendingQueueRows(root, vaultCfg);
+  const candidates = compileCandidateSummary(root, vaultCfg);
+  const freshnessSummary = sessions.reduce((acc, s) => { acc[s.freshness_status] = (acc[s.freshness_status] || 0) + 1; return acc; }, {});
+  const activeAreas = [...new Set(sessions.map((s) => s.area).filter(Boolean))].sort();
+  const staleSessions = sessions.filter((s) => s.freshness_status === 'stale');
+  const recentSessions = [...sessions]
+    .sort((a, b) => String(b.last_pulse || '').localeCompare(String(a.last_pulse || '')))
+    .slice(0, 5)
+    .map((s) => ({ session_id: s.session_id, area: s.area, freshness_status: s.freshness_status, last_pulse: s.last_pulse, pending_count: s.pending_count, area_brief_path: s.area_brief_path }));
+  const requiredFiles = vaultCfg.status_required_files.map((rel) => ({ path: rel, exists: exists(path.join(root, rel)) }));
+  return {
+    ok: requiredFiles.every((f) => f.exists),
+    command: 'status',
+    durable_write: false,
+    mode: 'boot_status',
+    required_files: requiredFiles,
+    updated_at: state.updated_at || '',
+    session_count: sessions.length,
+    active_areas: activeAreas,
+    freshness_summary: freshnessSummary,
+    total_pending_count: queueRows.length,
+    pending_requires_confirmation_count: queueRows.filter((r) => r.requires_user_decision || r.sensitivity === 'private' || r.flush_level === 'full').length,
+    compile_candidate_count: candidates.count,
+    compile_candidates: candidates.examples,
+    recent_sessions: recentSessions,
+    next_action: queueRows.length > 0
+      ? 'Review pending candidates before official memory changes.'
+      : candidates.count > 0
+      ? 'Review source candidates before deep reading.'
+      : 'Choose a session or area and continue work.',
+    stale_guidance: staleSessions.length
+      ? { count: staleSessions.length, action: 'Not an error. Resume those sessions, or consolidate only when closing them.', examples: staleSessions.slice(0, 3).map((s) => s.session_id) }
+      : null,
+    lesson_review: lessonReview(root),
+    health_maintenance: null,
+    health_maintenance_mode: 'read_only',
+    note: 'Read-only status. Maintenance (--fix) and the digest ack are vault-side until the session-state write surface migrates.',
+  };
+}
+
+export async function statusCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  const staleDays = Number(args['stale-days'] || 7);
+  const now = args.now !== undefined ? Number(args.now) : Date.now();
+  let state;
+  try {
+    state = loadSessionState(root, vaultCfg);
+  } catch (error) {
+    const payload = { ok: false, command: 'status', durable_write: false, error: error.message };
+    return args.json ? { json: true, payload } : { text: `# Neurain status\n\n- ERROR: ${error.message}` };
+  }
+  const sessionId = args['session-id'];
+
+  if (!sessionId && !args.all) {
+    const payload = bootStatus(root, vaultCfg, state, { staleDays, now });
+    if (args.json) return { json: true, payload };
+    return {
+      text: [
+        '# Neurain Status',
+        '',
+        `- OK: ${payload.ok ? 'yes' : 'needs attention'}`,
+        `- Sessions: ${payload.session_count} | Areas: ${payload.active_areas.join(', ') || 'none'}`,
+        `- Pending: ${payload.total_pending_count}${payload.pending_requires_confirmation_count ? ` (confirmation needed: ${payload.pending_requires_confirmation_count})` : ''}`,
+        payload.compile_candidate_count ? `- Compile candidates: ${payload.compile_candidate_count}` : '',
+        payload.stale_guidance ? `- Stale sessions: ${payload.stale_guidance.count} (not an error)` : '',
+        `- Next: ${payload.next_action}`,
+      ].filter(Boolean).join('\n'),
+    };
+  }
+
+  if (args.all) {
+    const sessions = Object.values(state.sessions || {}).map((s) => summarizeSession(root, vaultCfg, s, { staleDays, now }));
+    const payload = { ok: true, command: 'status', durable_write: false, mode: 'all', updated_at: state.updated_at || '', count: sessions.length, sessions };
+    if (args.json) return { json: true, payload };
+    return {
+      text: ['# Session Status', '', `- Sessions: ${payload.count}`, ...sessions.map((s) => `- ${s.session_id}: ${s.status}, freshness ${s.freshness_status}, pending ${s.pending_count}, handoff ${s.handoff_exists ? 'ok' : 'missing'}`)].join('\n'),
+    };
+  }
+
+  const session = state.sessions[String(sessionId)];
+  if (!session) {
+    process.stderr.write(`Unknown session_id: ${sessionId}\n`);
+    const payload = { ok: false, command: 'status', durable_write: false, error: `Unknown session_id: ${sessionId}` };
+    if (args.json) return { json: true, payload };
+    return { text: `# Session Status\n\n- Unknown session_id: ${sessionId}` };
+  }
+  const sinceLastVisit = computeDigest(root, session.session_id, { now, vaultCfg });
+  const payload = {
+    ok: true,
+    command: 'status',
+    durable_write: false,
+    mode: 'session',
+    ...summarizeSession(root, vaultCfg, session, { staleDays, now }),
+    queue_items: pendingQueueRows(root, vaultCfg, { sessionId: session.session_id }).map((row) => ({
+      source_id: row.source_id || '',
+      title: row.title || '',
+      flush_level: row.flush_level || '',
+      target_layer: row.target_layer || '',
+      target_path: row.target_path || '',
+      raw_path: row.raw_path || '',
+    })),
+    since_last_visit: sinceLastVisit,
+    lesson_review: lessonReview(root),
+  };
+  // The engine never acks; a vault shim acks after delivering the rendered text.
+  if (args.json) return { json: true, payload };
+  return {
+    text: [
+      '# Session Status',
+      '',
+      `- Session: ${payload.session_id}`,
+      `- Area: ${payload.area}`,
+      `- Pending: ${payload.pending_count}`,
+      `- Handoff: ${payload.handoff_exists ? payload.handoff_path : 'missing'}`,
+      `- Area brief: ${payload.area_brief_exists ? payload.area_brief_path : 'missing'}`,
+      `- Freshness: ${payload.freshness_message}`,
+      renderDigest(sinceLastVisit) ? `\n${renderDigest(sinceLastVisit)}` : '',
+    ].filter(Boolean).join('\n'),
+  };
+}