avorelo 0.1.0

package/scripts/lib/reentry-memory-retrieval.js

@@ -0,0 +1,302 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_MAX_CANDIDATES = 5;
+const DEFAULT_MAX_AUTO_INJECT_TOKENS = 800;
+const DEFAULT_RETENTION_DAYS = 30;
+
+function computeAgeMs(createdAt) {
+  if (!createdAt) return Infinity;
+  const ts = Date.parse(createdAt);
+  if (!Number.isFinite(ts)) return Infinity;
+  return Date.now() - ts;
+}
+
+function fileExistsAndIsNewer(filePath, createdAt) {
+  try {
+    const stat = fs.statSync(filePath);
+    const itemTs = Date.parse(createdAt || 0);
+    return Number.isFinite(itemTs) && stat.mtimeMs > itemTs;
+  } catch {
+    return false;
+  }
+}
+
+function fileExists(filePath) {
+  try { fs.accessSync(filePath); return true; } catch { return false; }
+}
+
+function computeEffectiveStale(item, repoRoot, retentionDays) {
+  // Already marked stale — trust it
+  if (item.staleStatus === "stale") return "stale";
+
+  // Retention age check
+  const retentionMs = (retentionDays || DEFAULT_RETENTION_DAYS) * 24 * 60 * 60 * 1000;
+  const ageMs = computeAgeMs(item.createdAt);
+  if (ageMs > retentionMs) return "stale";
+  if (ageMs > retentionMs * 0.7) return "possibly_stale";
+
+  // File-based stale detection
+  const files = item.relatedFiles || [];
+  for (const rel of files) {
+    const abs = repoRoot ? path.join(repoRoot, rel) : rel;
+    // If file doesn't exist anymore → stale
+    if (!fileExists(abs) && !fileExists(rel)) return "stale";
+    // If file was modified after item was created → possibly_stale
+    if (fileExistsAndIsNewer(abs, item.createdAt) || fileExistsAndIsNewer(rel, item.createdAt)) {
+      return "possibly_stale";
+    }
+  }
+
+  return item.staleStatus || "fresh";
+}
+
+function scoreItem(item, context = {}) {
+  const {
+    relatedFiles = [],
+    relatedCommands = [],
+    errorText = "",
+    query = "",
+  } = context;
+
+  let score = 0;
+
+  // Confidence boost
+  if (item.confidence === "high") score += 30;
+  else if (item.confidence === "medium") score += 15;
+
+  // Risk penalty (higher risk → lower score for auto use)
+  if (item.riskLevel === "high") score -= 25;
+  else if (item.riskLevel === "medium") score -= 5;
+
+  // Stale penalty
+  const effectiveStale = item._effectiveStale || item.staleStatus || "fresh";
+  if (effectiveStale === "stale") score -= 50;
+  else if (effectiveStale === "possibly_stale") score -= 20;
+
+  // File match bonus
+  const itemFiles = new Set((item.relatedFiles || []).map((f) => f.toLowerCase()));
+  for (const f of relatedFiles) {
+    if (itemFiles.has(f.toLowerCase())) score += 25;
+    // Partial basename match
+    const base = path.basename(f).toLowerCase();
+    for (const itemFile of itemFiles) {
+      if (path.basename(itemFile) === base) score += 10;
+    }
+  }
+
+  // Command match bonus
+  const itemCmds = new Set((item.relatedCommands || []).map((c) => c.toLowerCase()));
+  for (const cmd of relatedCommands) {
+    if (itemCmds.has(cmd.toLowerCase())) score += 15;
+  }
+
+  // Error text exact match bonus
+  if (errorText && item.evidence) {
+    const normError = errorText.slice(0, 200).toLowerCase();
+    const normEvidence = (item.evidence || "").toLowerCase();
+    if (normEvidence.includes(normError) && normError.length > 10) score += 40;
+  }
+
+  // Keyword match bonus
+  if (query) {
+    const lower = query.toLowerCase();
+    if ((item.title || "").toLowerCase().includes(lower)) score += 20;
+    if ((item.summary || "").toLowerCase().includes(lower)) score += 10;
+  }
+
+  // Recency bonus (max 20 for very recent, fades over 7 days)
+  const ageMs = computeAgeMs(item.createdAt);
+  const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
+  const recencyBonus = Math.max(0, 20 * (1 - ageMs / sevenDaysMs));
+  score += recencyBonus;
+
+  // Type bonuses
+  if (item.type === "fix") score += 10;
+  if (item.type === "validation") score += 5;
+  if (item.type === "next_action") score += 8;
+
+  // Sensitive penalty
+  if (item.sensitive) score -= 15;
+
+  return score;
+}
+
+function buildMatchReason(item, context = {}) {
+  const reasons = [];
+  const { relatedFiles = [], relatedCommands = [], errorText = "", query = "" } = context;
+
+  const effectiveStale = item._effectiveStale || item.staleStatus || "fresh";
+  if (effectiveStale === "stale") reasons.push("stale memory");
+  if (effectiveStale === "possibly_stale") reasons.push("possibly stale");
+
+  const itemFiles = new Set((item.relatedFiles || []).map((f) => f.toLowerCase()));
+  for (const f of relatedFiles) {
+    if (itemFiles.has(f.toLowerCase())) {
+      reasons.push(`matched file: ${path.basename(f)}`);
+      break;
+    }
+  }
+
+  const itemCmds = new Set((item.relatedCommands || []).map((c) => c.toLowerCase()));
+  for (const cmd of relatedCommands) {
+    if (itemCmds.has(cmd.toLowerCase())) {
+      reasons.push(`matched command: ${cmd}`);
+      break;
+    }
+  }
+
+  if (errorText && item.evidence) {
+    const normError = errorText.slice(0, 200).toLowerCase();
+    if ((item.evidence || "").toLowerCase().includes(normError) && normError.length > 10) {
+      reasons.push("matched error text");
+    }
+  }
+
+  if (query && (item.title || "").toLowerCase().includes(query.toLowerCase())) {
+    reasons.push(`matched keyword: ${query.slice(0, 30)}`);
+  }
+
+  if (item.type === "next_action") reasons.push("previous session end state");
+  if (item.type === "fix") reasons.push("previous successful fix");
+  if (item.type === "failure") reasons.push("previous failed tool");
+  if (item.type === "validation") reasons.push("previous validation result");
+
+  return reasons.length ? reasons.join(", ") : "recent memory";
+}
+
+function rankCandidates(items, context, repoRoot, retentionDays) {
+  return items
+    .map((item) => {
+      const effectiveStale = computeEffectiveStale(item, repoRoot, retentionDays);
+      const enriched = { ...item, _effectiveStale: effectiveStale };
+      const score = scoreItem(enriched, context);
+      const matchReason = buildMatchReason(enriched, context);
+      return { item: enriched, score, matchReason };
+    })
+    .sort((a, b) => b.score - a.score);
+}
+
+function buildCandidates(store, context = {}, config = {}) {
+  const {
+    maxCandidates = DEFAULT_MAX_CANDIDATES,
+    maxAutoInjectTokens = DEFAULT_MAX_AUTO_INJECT_TOKENS,
+    mode = "suggest",
+    retentionDays = DEFAULT_RETENTION_DAYS,
+  } = config;
+
+  const { relatedFiles = [], relatedCommands = [], errorText = "", query = "" } = context;
+
+  const allItems = store.loadAll();
+  if (!allItems.length) {
+    return {
+      candidates: [],
+      autoInjected: [],
+      suggested: [],
+      estimatedTokens: 0,
+      totalItemCount: 0,
+    };
+  }
+
+  const ranked = rankCandidates(allItems, context, store.repoRoot, retentionDays);
+
+  // Take top N, filtering out items with very low scores
+  const topRanked = ranked
+    .filter((r) => r.score > -10)
+    .slice(0, Math.max(maxCandidates, 3));
+
+  const candidates = topRanked.map((r) => ({
+    id: r.item.id,
+    type: r.item.type,
+    title: r.item.title,
+    summary: r.item.summary,
+    confidence: r.item.confidence,
+    riskLevel: r.item.riskLevel,
+    staleStatus: r.item._effectiveStale || r.item.staleStatus,
+    sensitive: r.item.sensitive,
+    safeForAutoInject: r.item.safeForAutoInject,
+    tokenEstimate: r.item.tokenEstimate || 0,
+    matchReason: r.matchReason,
+    score: r.score,
+    createdAt: r.item.createdAt,
+    relatedFiles: r.item.relatedFiles || [],
+  }));
+
+  // Determine auto-inject: only in auto_safe mode, low risk, high confidence, fresh, not sensitive
+  let autoInjected = [];
+  let suggested = candidates;
+  let estimatedTokens = 0;
+
+  if (mode === "auto_safe") {
+    let tokenBudget = maxAutoInjectTokens;
+    const autoEligible = candidates.filter(
+      (c) =>
+        c.safeForAutoInject &&
+        !c.sensitive &&
+        c.staleStatus === "fresh" &&
+        c.riskLevel === "low" &&
+        c.confidence === "high"
+    );
+    for (const c of autoEligible) {
+      const cost = c.tokenEstimate || 0;
+      if (tokenBudget - cost >= 0) {
+        autoInjected.push(c);
+        tokenBudget -= cost;
+        estimatedTokens += cost;
+      }
+    }
+    const autoIds = new Set(autoInjected.map((c) => c.id));
+    suggested = candidates.filter((c) => !autoIds.has(c.id));
+  } else {
+    // suggest mode: estimate tokens for display
+    estimatedTokens = candidates.reduce((acc, c) => acc + (c.tokenEstimate || 0), 0);
+  }
+
+  return {
+    candidates,
+    autoInjected,
+    suggested,
+    estimatedTokens,
+    totalItemCount: allItems.length,
+  };
+}
+
+function formatCandidatesText(result, mode) {
+  if (!result || !result.candidates.length) return null;
+
+  const { candidates, autoInjected, suggested, estimatedTokens } = result;
+  const lines = ["Reentry Memory:"];
+  lines.push(`- ${candidates.length} relevant prior note${candidates.length !== 1 ? "s" : ""} found.`);
+
+  const highConf = candidates.filter((c) => c.confidence === "high" && c.type === "fix");
+  if (highConf.length > 0) {
+    lines.push(`- ${highConf.length} high-confidence fix candidate${highConf.length !== 1 ? "s" : ""}.`);
+  }
+
+  lines.push(`- ${autoInjected.length} auto-injected; ${suggested.length} suggested.`);
+  lines.push(`- Estimated context cost: ${estimatedTokens} tokens.`);
+
+  if (candidates.length > 0) {
+    const top = candidates[0];
+    const staleWarn = top.staleStatus !== "fresh" ? ` [${top.staleStatus}]` : "";
+    lines.push(
+      `- Top candidate: "${top.title.slice(0, 100)}" — ${top.confidence} confidence, ${top.staleStatus}, ${top.riskLevel} risk${staleWarn}.`
+    );
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  computeEffectiveStale,
+  scoreItem,
+  buildMatchReason,
+  rankCandidates,
+  buildCandidates,
+  formatCandidatesText,
+  DEFAULT_MAX_CANDIDATES,
+  DEFAULT_MAX_AUTO_INJECT_TOKENS,
+  DEFAULT_RETENTION_DAYS,
+};

package/scripts/lib/reentry-memory-status.js

@@ -0,0 +1,146 @@
+"use strict";
+
+const { ReentryMemoryStore } = require("./reentry-memory-store");
+const { buildCandidates, formatCandidatesText } = require("./reentry-memory-retrieval");
+
+const DEFAULT_CONFIG = {
+  enabled: true,
+  mode: "suggest",
+  maxCandidates: 5,
+  maxAutoInjectTokens: 800,
+  maxItemBytes: 8192,
+  retentionDays: 30,
+  captureSensitive: false,
+  showInStatus: true,
+};
+
+function normalizeMemoryConfig(raw) {
+  const cfg = { ...DEFAULT_CONFIG, ...(raw || {}) };
+  if (!["off", "suggest", "auto_safe"].includes(cfg.mode)) cfg.mode = "suggest";
+  cfg.enabled = cfg.enabled !== false;
+  cfg.captureSensitive = cfg.captureSensitive === true;
+  cfg.showInStatus = cfg.showInStatus !== false;
+  cfg.maxCandidates = Number.isFinite(Number(cfg.maxCandidates)) ? Math.max(1, Number(cfg.maxCandidates)) : 5;
+  cfg.maxAutoInjectTokens = Number.isFinite(Number(cfg.maxAutoInjectTokens)) ? Math.max(100, Number(cfg.maxAutoInjectTokens)) : 800;
+  cfg.maxItemBytes = Number.isFinite(Number(cfg.maxItemBytes)) ? Math.max(1024, Number(cfg.maxItemBytes)) : 8192;
+  cfg.retentionDays = Number.isFinite(Number(cfg.retentionDays)) ? Math.max(1, Number(cfg.retentionDays)) : 30;
+  return cfg;
+}
+
+function buildReentryMemoryStatus(cwd, rawMemoryConfig, context = {}) {
+  const memCfg = normalizeMemoryConfig(rawMemoryConfig);
+
+  const base = {
+    enabled: memCfg.enabled,
+    mode: memCfg.mode,
+    showInStatus: memCfg.showInStatus,
+    candidatesCount: 0,
+    autoInjectedCount: 0,
+    suggestedCount: 0,
+    estimatedTokens: 0,
+    topCandidates: [],
+    warnings: [],
+    storePath: ".claude/cco/state/reentry-memory.jsonl",
+  };
+
+  if (!memCfg.enabled || memCfg.mode === "off") {
+    return { ...base, enabled: false };
+  }
+
+  let store;
+  try {
+    store = new ReentryMemoryStore(cwd, {
+      maxItemBytes: memCfg.maxItemBytes,
+      maxItems: memCfg.maxCandidates * 20,
+    });
+  } catch {
+    return { ...base, warnings: ["memory store initialization failed"] };
+  }
+
+  let result;
+  try {
+    result = buildCandidates(store, context, {
+      maxCandidates: memCfg.maxCandidates,
+      maxAutoInjectTokens: memCfg.maxAutoInjectTokens,
+      mode: memCfg.mode,
+      retentionDays: memCfg.retentionDays,
+    });
+  } catch {
+    return { ...base, warnings: ["memory candidate retrieval failed"] };
+  }
+
+  const warnings = [];
+  const staleCount = result.candidates.filter((c) => c.staleStatus !== "fresh").length;
+  if (staleCount > 0) warnings.push(`${staleCount} candidate${staleCount !== 1 ? "s" : ""} may be stale`);
+
+  const sensitiveCount = result.candidates.filter((c) => c.sensitive).length;
+  if (sensitiveCount > 0) warnings.push(`${sensitiveCount} candidate${sensitiveCount !== 1 ? "s" : ""} marked sensitive (not auto-injected)`);
+
+  return {
+    enabled: true,
+    mode: memCfg.mode,
+    showInStatus: memCfg.showInStatus,
+    candidatesCount: result.candidates.length,
+    autoInjectedCount: result.autoInjected.length,
+    suggestedCount: result.suggested.length,
+    estimatedTokens: result.estimatedTokens,
+    topCandidates: result.candidates.slice(0, 3).map((c) => ({
+      id: c.id,
+      type: c.type,
+      title: c.title,
+      confidence: c.confidence,
+      riskLevel: c.riskLevel,
+      staleStatus: c.staleStatus,
+      sensitive: c.sensitive,
+      tokenEstimate: c.tokenEstimate,
+      matchReason: c.matchReason,
+    })),
+    warnings,
+    storePath: ".claude/cco/state/reentry-memory.jsonl",
+    totalStoredItems: result.totalItemCount,
+  };
+}
+
+function formatReentryMemoryText(memStatus) {
+  if (!memStatus || !memStatus.enabled || !memStatus.showInStatus || memStatus.mode === "off") {
+    return null;
+  }
+
+  if (memStatus.candidatesCount === 0) {
+    return null;
+  }
+
+  const lines = ["Reentry Memory:"];
+  lines.push(`- ${memStatus.candidatesCount} relevant prior note${memStatus.candidatesCount !== 1 ? "s" : ""} found.`);
+
+  const highConf = (memStatus.topCandidates || []).filter(
+    (c) => c.confidence === "high" && c.type === "fix"
+  );
+  if (highConf.length > 0) {
+    lines.push(`- ${highConf.length} high-confidence fix candidate${highConf.length !== 1 ? "s" : ""}.`);
+  }
+
+  lines.push(`- ${memStatus.autoInjectedCount} auto-injected; ${memStatus.suggestedCount} suggested.`);
+  lines.push(`- Estimated context cost: ${memStatus.estimatedTokens} tokens.`);
+
+  if (memStatus.topCandidates && memStatus.topCandidates.length > 0) {
+    const top = memStatus.topCandidates[0];
+    const staleWarn = top.staleStatus !== "fresh" ? ` [${top.staleStatus}]` : "";
+    lines.push(
+      `- Top candidate: "${top.title.slice(0, 100)}" — ${top.confidence} confidence, ${top.staleStatus}, ${top.riskLevel} risk${staleWarn}.`
+    );
+  }
+
+  if (memStatus.warnings && memStatus.warnings.length > 0) {
+    memStatus.warnings.forEach((w) => lines.push(`- Warning: ${w}`));
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  normalizeMemoryConfig,
+  buildReentryMemoryStatus,
+  formatReentryMemoryText,
+  DEFAULT_CONFIG,
+};

package/scripts/lib/reentry-memory-store.js

@@ -0,0 +1,178 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const MEMORY_REL = ".claude/cco/state/reentry-memory.jsonl";
+const DEFAULT_MAX_ITEM_BYTES = 8 * 1024;
+const DEFAULT_MAX_ITEMS = 500;
+
+const VALID_TYPES = new Set([
+  "decision", "fix", "failure", "validation",
+  "blocker", "file_change", "security_note", "config_note", "next_action",
+]);
+const VALID_CONFIDENCE = new Set(["low", "medium", "high"]);
+const VALID_RISK = new Set(["low", "medium", "high"]);
+const VALID_STALE = new Set(["fresh", "possibly_stale", "stale"]);
+
+function generateId() {
+  return crypto.randomUUID();
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function estimateTokens(texts) {
+  const combined = (Array.isArray(texts) ? texts : [texts]).join(" ");
+  return Math.ceil(Buffer.byteLength(String(combined || ""), "utf8") / 4);
+}
+
+function buildItem(partial) {
+  const now = nowIso();
+  return {
+    id: partial.id || generateId(),
+    createdAt: partial.createdAt || now,
+    updatedAt: partial.updatedAt || now,
+    repoRoot: partial.repoRoot || "",
+    sessionId: partial.sessionId || null,
+    runId: partial.runId || null,
+    sourceEventId: partial.sourceEventId || null,
+    sourceFile: partial.sourceFile || null,
+    sourceCommand: partial.sourceCommand || null,
+    type: partial.type || "failure",
+    title: String(partial.title || "").slice(0, 200),
+    summary: String(partial.summary || "").slice(0, 1000),
+    evidence: String(partial.evidence || "").slice(0, 2000),
+    relatedFiles: Array.isArray(partial.relatedFiles) ? partial.relatedFiles.slice(0, 20).map(String) : [],
+    relatedCommands: Array.isArray(partial.relatedCommands) ? partial.relatedCommands.slice(0, 10).map(String) : [],
+    confidence: VALID_CONFIDENCE.has(partial.confidence) ? partial.confidence : "low",
+    riskLevel: VALID_RISK.has(partial.riskLevel) ? partial.riskLevel : "medium",
+    staleStatus: VALID_STALE.has(partial.staleStatus) ? partial.staleStatus : "fresh",
+    sensitive: partial.sensitive === true,
+    safeForAutoInject: partial.safeForAutoInject === true,
+    tokenEstimate: Number.isFinite(partial.tokenEstimate)
+      ? partial.tokenEstimate
+      : estimateTokens([partial.title, partial.summary, partial.evidence]),
+    tags: Array.isArray(partial.tags) ? partial.tags.slice(0, 10).map(String) : [],
+  };
+}
+
+function validateItem(item) {
+  if (!item || typeof item !== "object") throw new Error("Memory item must be an object");
+  if (!item.title || typeof item.title !== "string" || !item.title.trim()) {
+    throw new Error("Memory item must have a non-empty title");
+  }
+  if (!VALID_TYPES.has(item.type)) throw new Error(`Invalid memory item type: ${item.type}`);
+  if (!VALID_CONFIDENCE.has(item.confidence)) throw new Error(`Invalid confidence: ${item.confidence}`);
+  if (!VALID_RISK.has(item.riskLevel)) throw new Error(`Invalid riskLevel: ${item.riskLevel}`);
+}
+
+class ReentryMemoryStore {
+  constructor(repoRoot, opts = {}) {
+    this.repoRoot = repoRoot;
+    this.filePath = path.join(repoRoot, MEMORY_REL);
+    this.maxItemBytes = Number.isFinite(opts.maxItemBytes) ? opts.maxItemBytes : DEFAULT_MAX_ITEM_BYTES;
+    this.maxItems = Number.isFinite(opts.maxItems) ? opts.maxItems : DEFAULT_MAX_ITEMS;
+  }
+
+  _ensureDir() {
+    fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+  }
+
+  append(partial) {
+    const item = buildItem({ ...partial, repoRoot: this.repoRoot });
+    validateItem(item);
+
+    const line = JSON.stringify(item) + "\n";
+    const bytes = Buffer.byteLength(line, "utf8");
+
+    if (bytes > this.maxItemBytes) {
+      const truncated = { ...item, evidence: item.evidence.slice(0, 300) + "...(truncated)" };
+      truncated.tokenEstimate = estimateTokens([truncated.title, truncated.summary, truncated.evidence]);
+      const tLine = JSON.stringify(truncated) + "\n";
+      if (Buffer.byteLength(tLine, "utf8") > this.maxItemBytes) {
+        return null;
+      }
+      this._ensureDir();
+      try {
+        fs.appendFileSync(this.filePath, tLine, "utf8");
+      } catch {
+        return null;
+      }
+      return truncated;
+    }
+
+    this._ensureDir();
+    try {
+      fs.appendFileSync(this.filePath, line, "utf8");
+    } catch {
+      return null;
+    }
+    return item;
+  }
+
+  loadAll() {
+    if (!fs.existsSync(this.filePath)) return [];
+    try {
+      const content = fs.readFileSync(this.filePath, "utf8");
+      const items = content
+        .split("\n")
+        .filter((line) => line.trim().length > 0)
+        .map((line) => {
+          try { return JSON.parse(line); } catch { return null; }
+        })
+        .filter(Boolean);
+      return items.slice(-this.maxItems);
+    } catch {
+      return [];
+    }
+  }
+
+  clear() {
+    if (fs.existsSync(this.filePath)) {
+      try { fs.unlinkSync(this.filePath); } catch {}
+    }
+  }
+
+  search(query) {
+    const items = this.loadAll();
+    if (!query || !query.trim()) return items;
+    const lower = query.toLowerCase();
+    return items.filter((item) =>
+      (item.title || "").toLowerCase().includes(lower) ||
+      (item.summary || "").toLowerCase().includes(lower) ||
+      (item.evidence || "").toLowerCase().includes(lower) ||
+      (item.relatedFiles || []).some((f) => f.toLowerCase().includes(lower)) ||
+      (item.relatedCommands || []).some((c) => c.toLowerCase().includes(lower)) ||
+      (item.tags || []).some((t) => t.toLowerCase().includes(lower))
+    );
+  }
+
+  hasDuplicate(sessionId, title, type) {
+    const items = this.loadAll();
+    return items.some(
+      (item) =>
+        item.sessionId === sessionId &&
+        item.type === type &&
+        item.title === title
+    );
+  }
+
+  storePath() {
+    return MEMORY_REL;
+  }
+}
+
+module.exports = {
+  ReentryMemoryStore,
+  buildItem,
+  validateItem,
+  estimateTokens,
+  VALID_TYPES,
+  VALID_CONFIDENCE,
+  VALID_RISK,
+  VALID_STALE,
+  MEMORY_REL,
+};

package/scripts/lib/reentry-state.js

@@ -0,0 +1,66 @@
+"use strict";
+
+const { safeReadJson, safeWriteJson } = require("./fsx");
+
+const REENTRY_STATE_PATH = ".claude/cco/state/reentry-state.json";
+const UNRESOLVED_RISK_TYPES = new Set([
+  "security_recovery",
+  "security_prerun_review",
+  "trust_review_required",
+  "risky_command_intervention",
+  "source_policy_intervention",
+  "team_policy_block",
+]);
+
+function normalizeText(value, fallback) {
+  const text = String(value || "").trim();
+  return text || fallback;
+}
+
+function normalizePath(value) {
+  if (value === null || value === undefined || value === "") return null;
+  return String(value);
+}
+
+function buildReentryStateV1(input = {}) {
+  return {
+    reentryStateVersion: 1,
+    lastInterventionType: normalizeText(input.lastInterventionType, "none"),
+    nextAction: normalizeText(input.nextAction, "Run /cco-status."),
+    unresolvedRisk: Boolean(input.unresolvedRisk),
+    primaryArtifactPath: normalizePath(input.primaryArtifactPath),
+    resumeHint: normalizeText(input.resumeHint, "Run /cco-status to continue."),
+  };
+}
+
+function unresolvedRiskFor(interventionType) {
+  return UNRESOLVED_RISK_TYPES.has(String(interventionType || "none"));
+}
+
+function writeReentryState(cwd, input = {}) {
+  const state = buildReentryStateV1({
+    lastInterventionType: input.lastInterventionType,
+    nextAction: input.nextAction,
+    unresolvedRisk:
+      typeof input.unresolvedRisk === "boolean"
+        ? input.unresolvedRisk
+        : unresolvedRiskFor(input.lastInterventionType),
+    primaryArtifactPath: input.primaryArtifactPath,
+    resumeHint: input.resumeHint,
+  });
+  safeWriteJson(cwd, REENTRY_STATE_PATH, state);
+  return { state, path: REENTRY_STATE_PATH };
+}
+
+function loadReentryState(cwd) {
+  const state = safeReadJson(cwd, REENTRY_STATE_PATH, null);
+  if (!state) return null;
+  return buildReentryStateV1(state);
+}
+
+module.exports = {
+  REENTRY_STATE_PATH,
+  buildReentryStateV1,
+  writeReentryState,
+  loadReentryState,
+};