feat: add durable lifecycle and deterministic rollout selection

src/lib/cli/register-commands.ts

@@ -140,9 +140,10 @@ export function registerCommands(program: Command): void {
 
   program
     .command("forget")
-    .description("Delete matching memory entries")
+    .description("Delete or archive matching memory entries")
     .argument("<query>", "Search query used to find memory entries")
     .option("--scope <scope>", "Specific scope to target, or all")
+    .option("--archive", "Move matching entries into archive instead of deleting them")
     .action(withStdout(async (query, options) => runForget(query, options)));
 
   program

src/lib/commands/forget.ts

@@ -4,20 +4,23 @@ import type { MemoryScope } from "../types.js";
 interface ForgetOptions {
   cwd?: string;
   scope?: MemoryScope | "all";
+  archive?: boolean;
 }
 
 export async function runForget(
   query: string,
   options: ForgetOptions = {}
 ): Promise<string> {
   const runtime = await buildRuntimeContext(options.cwd);
-  const deleted = await runtime.syncService.memoryStore.forget(options.scope ?? "all", query);
+  const deleted = await runtime.syncService.memoryStore.forget(options.scope ?? "all", query, {
+    archive: options.archive
+  });
   if (deleted.length === 0) {
     return `No memory entries matched "${query}".`;
   }
 
   return [
-    `Deleted ${deleted.length} memory entr${deleted.length === 1 ? "y" : "ies"}:`,
+    `${options.archive ? "Archived" : "Deleted"} ${deleted.length} memory entr${deleted.length === 1 ? "y" : "ies"}:`,
     ...deleted.map((entry) => `- ${entry.scope}/${entry.topic}/${entry.id}: ${entry.summary}`)
   ].join("\n");
 }

src/lib/commands/memory.ts

@@ -35,6 +35,7 @@ function formatPendingSyncRecovery(record: SyncRecoveryRecord, recoveryPath: str
     `- Rollout: ${record.rolloutPath}`,
     `- Session: ${record.sessionId ?? "unknown"}`,
     `- Status: ${record.status} (${record.appliedCount} operation${record.appliedCount === 1 ? "" : "s"})`,
+    `- No-op: ${record.noopOperationCount ?? 0}`,
     `- Suppressed: ${record.suppressedOperationCount ?? 0}`,
     `- Audit entry written: ${record.auditEntryWritten}`,
     `- Failure: ${record.failureMessage}`
@@ -62,6 +63,7 @@ function syncAuditSignature(entry: MemorySyncAuditEntry): string {
     actualExtractorMode: entry.actualExtractorMode,
     actualExtractorName: entry.actualExtractorName,
     appliedCount: entry.appliedCount,
+    noopOperationCount: entry.noopOperationCount ?? 0,
     suppressedOperationCount: entry.suppressedOperationCount ?? 0,
     scopesTouched: entry.scopesTouched,
     conflicts: entry.conflicts ?? [],
@@ -131,7 +133,14 @@ export async function runMemory(options: MemoryOptions = {}): Promise<string> {
     ? await runtime.syncService.memoryStore.readRecentSyncAuditEntries(recentCount * 2)
     : [];
   const recentSyncAudit = recentSyncAuditPreviewEntries.slice(0, recentCount);
-  const pendingSyncRecovery = await runtime.syncService.memoryStore.readSyncRecoveryRecord();
+  let pendingSyncRecovery = null;
+  try {
+    pendingSyncRecovery = await runtime.syncService.memoryStore.readSyncRecoveryRecord();
+  } catch (error) {
+    runtime.loadedConfig.warnings.push(
+      `Sync recovery record could not be read: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
   const startupFilesByScope = {
     global: startup.sourceFiles.filter(
       (filePath) => filePath === runtime.syncService.memoryStore.getMemoryFile("global")

src/lib/commands/remember.ts

@@ -19,7 +19,7 @@ export async function runRemember(
   const details = options.detail?.length ? options.detail : [text];
   const id = slugify(text);
 
-  await runtime.syncService.memoryStore.remember(
+  const record = await runtime.syncService.memoryStore.remember(
     scope,
     topic,
     id,
@@ -28,5 +28,9 @@ export async function runRemember(
     "Manual remember request."
   );
 
+  if (record?.lifecycleAction === "noop") {
+    return `Memory ${scope}/${topic}/${id} is already up to date.`;
+  }
+
   return `Saved memory to ${scope}/${topic} with id ${id}.`;
 }

src/lib/commands/wrapper.ts

@@ -4,7 +4,7 @@ import { persistSessionContinuity } from "../domain/session-continuity-persisten
 import {
   listRolloutFiles,
   parseRolloutEvidence,
-  readRolloutMeta
+  selectLatestPrimaryRolloutFromCandidates
 } from "../domain/rollout.js";
 import { compileSessionContinuity } from "../domain/session-continuity.js";
 import { readCodexBaseInstructions } from "../runtime/codex-config.js";
@@ -16,18 +16,6 @@ import { WrapperRuntimeInjector } from "../runtime/wrapper-injector.js";
 const sessionSource = new RolloutSessionSource();
 const runtimeInjector = new WrapperRuntimeInjector();
 
-async function selectLatestPrimaryRollout(candidates: string[]): Promise<string | null> {
-  const metas = await Promise.all(candidates.map((candidate) => readRolloutMeta(candidate)));
-  for (let index = candidates.length - 1; index >= 0; index -= 1) {
-    if (metas[index]?.isSubagent === true) {
-      continue;
-    }
-    return candidates[index] ?? null;
-  }
-
-  return null;
-}
-
 async function syncRecentRollouts(
   cwd: string,
   before: string[],
@@ -100,7 +88,7 @@ async function saveSessionContinuity(
     startedAtMs,
     endedAtMs
   );
-  const rolloutPath = await selectLatestPrimaryRollout(candidates);
+  const rolloutPath = await selectLatestPrimaryRolloutFromCandidates(candidates);
   if (!rolloutPath) {
     return null;
   }

src/lib/domain/memory-lifecycle.ts

@@ -0,0 +1,109 @@
+import type {
+  MemoryEntry,
+  MemoryHistoryRecordState,
+  MemoryLifecycleAction,
+  MemoryRecordState,
+  MemoryRef,
+  MemoryScope
+} from "../types.js";
+
+const allowedScopes = new Set<MemoryScope>(["global", "project", "project-local"]);
+const allowedStates = new Set<MemoryRecordState>(["active", "archived"]);
+const allowedHistoryStates = new Set<MemoryHistoryRecordState>(["active", "archived", "deleted"]);
+
+export function buildMemoryRef(
+  scope: MemoryScope,
+  state: MemoryRecordState,
+  topic: string,
+  id: string
+): string {
+  return `${scope}:${state}:${topic}:${id}`;
+}
+
+export function parseMemoryRef(ref: string): MemoryRef | null {
+  const [scope, state, topic, ...idParts] = ref.split(":");
+  const id = idParts.join(":");
+  if (
+    !scope ||
+    !state ||
+    !topic ||
+    idParts.length === 0 ||
+    id.length === 0 ||
+    !allowedScopes.has(scope as MemoryScope) ||
+    !allowedStates.has(state as MemoryRecordState)
+  ) {
+    return null;
+  }
+
+  return {
+    ref,
+    scope: scope as MemoryScope,
+    state: state as MemoryRecordState,
+    topic,
+    id
+  };
+}
+
+export function assertValidMemoryRef(ref: string): MemoryRef {
+  const parsed = parseMemoryRef(ref);
+  if (!parsed) {
+    throw new Error(
+      `Invalid memory ref "${ref}". Expected format <scope>:<state>:<topic>:<id>.`
+    );
+  }
+
+  return parsed;
+}
+
+export function isMemoryHistoryRecordState(value: unknown): value is MemoryHistoryRecordState {
+  return typeof value === "string" && allowedHistoryStates.has(value as MemoryHistoryRecordState);
+}
+
+function normalizeString(value: string | undefined): string {
+  return (value ?? "").trim();
+}
+
+function normalizeStringArray(values: readonly string[]): string[] {
+  return values
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+export function areEquivalentMemoryEntries(left: MemoryEntry, right: MemoryEntry): boolean {
+  return (
+    normalizeString(left.summary) === normalizeString(right.summary) &&
+    JSON.stringify(normalizeStringArray(left.details)) ===
+      JSON.stringify(normalizeStringArray(right.details)) &&
+    JSON.stringify(normalizeStringArray(left.sources)) ===
+      JSON.stringify(normalizeStringArray(right.sources)) &&
+    normalizeString(left.reason) === normalizeString(right.reason)
+  );
+}
+
+export function classifyUpsertLifecycle(
+  existingActive: MemoryEntry | null,
+  existingArchived: MemoryEntry | null,
+  nextEntry: MemoryEntry
+): Extract<MemoryLifecycleAction, "add" | "update" | "noop"> {
+  if (existingActive && areEquivalentMemoryEntries(existingActive, nextEntry)) {
+    return "noop";
+  }
+
+  return existingActive || existingArchived ? "update" : "add";
+}
+
+export function nextHistoryStateForLifecycle(
+  action: MemoryLifecycleAction
+): MemoryHistoryRecordState | undefined {
+  switch (action) {
+    case "add":
+    case "update":
+      return "active";
+    case "archive":
+      return "archived";
+    case "delete":
+      return "deleted";
+    case "noop":
+      return undefined;
+  }
+}