mixdog 0.9.12 → 0.9.14

package/src/runtime/agent/orchestrator/stall-policy.mjs

@@ -193,6 +193,22 @@ export const PROVIDER_WS_INTER_CHUNK_TIMEOUT_MS = resolveTimeoutMs(
     { minMs: MIN_PROVIDER_TIMEOUT_MS, maxMs: STALL_ABORT_MS },
 );
 
+// First-MEANINGFUL-frame watchdog (WS). The inter-chunk timer resets on EVERY
+// received frame (keepalive/metadata/rate_limits keep the socket "alive"), so a
+// server that ACKs response.create with only keepalive/metadata frames — never
+// a response.created or a content/tool delta — resets provider idle forever and
+// the pre-response first-byte window never wins. This distinct timer is cleared
+// ONLY by a MEANINGFUL response event (response.created or the first content /
+// tool-arg delta); keepalive/metadata frames do NOT touch it. On expiry the
+// stream is treated as stalled (streamStalledError → existing retry/fallback).
+// Kept comfortably below the agent stall first-byte abort (300s default) so the
+// provider layer catches the wedge before the agent watchdog does. Env-tunable.
+export const PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS',
+    120_000,
+    { minMs: 10_000, maxMs: STALL_WARN_MS },
+);
+
 // First retry has a small floor (250ms) instead of 0ms: an immediate reissue on
 // a transient 5xx burst lets parallel workers thundering-herd the backend in
 // lockstep (jitter alone can't decluster a 0ms base). Subsequent steps keep the

package/src/runtime/channels/index.mjs

@@ -70,6 +70,7 @@ const memoryClientModulePath = new URL("./lib/memory-client.mjs", import.meta.ur
 const {
   appendEntry: memoryAppendEntry,
   ingestTranscript: memoryIngestTranscript,
+  drainBuffer: memoryDrainBuffer,
 } = await import(memoryClientModulePath);
 // Zombie-Lead repro (2026-07-02): logCrash-then-survive left a worker alive
 // after an unhandled rejection whose async state was already corrupted
@@ -188,7 +189,19 @@ if (!_isWorkerMode) {
   // owner_lead_alive() sees a live owner and uses the full connect budget
   // instead of the 5s no-owner grace (fixes missing recap/core on restart).
   // backendReady intentionally omitted — readiness stays gated until connect.
-  refreshActiveInstance(INSTANCE_ID);
+  try {
+    refreshActiveInstance(INSTANCE_ID);
+  } catch (e) {
+    const code = e?.code;
+    const transient =
+      code === "EPERM" || code === "EBUSY" || code === "EACCES" || code === "ENOENT";
+    if (!transient) throw e;
+    try {
+      process.stderr.write(
+        `mixdog channels: refreshActiveInstance at startup failed (non-fatal, ${code}): ${e instanceof Error ? e.message : String(e)}\n`,
+      );
+    } catch {}
+  }
   startCliWorker();
 }
 const INSTRUCTIONS = "";
@@ -314,6 +327,10 @@ function applyTranscriptBinding(channelId, transcriptPath, options = {}) {
   const boundTranscriptPath = forwarder.transcriptPath || transcriptPath;
   forwarder.startWatch();
   void memoryIngestTranscript(boundTranscriptPath, { cwd: options.cwd });
+  // Opportunistic drain: an ingest that had to buffer (memory port not yet
+  // published) leaves entry-/ingest- files behind; kick the drainer so they
+  // replay as soon as the port appears, without waiting for the periodic tick.
+  void memoryDrainBuffer().catch(() => {});
   // onlyIfOwned: binds happen on the owned path, but discovery/poll loops
   // above can outlast an ownership handoff — never overwrite a newer owner.
   refreshActiveInstance(INSTANCE_ID, { channelId, transcriptPath: boundTranscriptPath }, { onlyIfOwned: true });
@@ -549,6 +566,7 @@ const ACTIVE_OWNER_STALE_MS = 1e4;
 let bindingReadyStatus = "pending";
 let _bindingReadyResolve;
 const bindingReady = new Promise((r) => { _bindingReadyResolve = r; });
+let _memoryDrainTimer = null;
 dropTrace("bindingReady.create", { status: bindingReadyStatus });
 // ── Bridge ownership snapshot + owner heartbeat ─────────────────────────────
 // Extracted → lib/owner-heartbeat.mjs. Owns its own heartbeat timer + last-note
@@ -723,6 +741,13 @@ async function startOwnedRuntime(options = {}) {
     return;
   }
   startOwnerHeartbeat();
+  // Periodic buffer drain: replays memory-buffer/entry-*/ingest-*.json once the
+  // memory service publishes its port. Idempotent + reentrancy-guarded inside
+  // drainBuffer(); unref'd so it never holds the worker open.
+  if (!_memoryDrainTimer) {
+    _memoryDrainTimer = setInterval(() => { void memoryDrainBuffer().catch(() => {}); }, 5e3);
+    _memoryDrainTimer.unref?.();
+  }
   // Re-check after each post-connect await so a stopOwnedRuntime() landing
   // mid-start cannot be overridden by the resuming start (scheduler/snapshot/
   // webhook/binding launches below would revive owner state after stop).
@@ -808,6 +833,7 @@ async function startOwnedRuntime(options = {}) {
     try { stopOwnerHeartbeat(); } catch {}
     try { releaseOwnedChannelLocks(INSTANCE_ID); } catch {}
     try { clearActiveInstance(INSTANCE_ID); } catch {}
+    if (_memoryDrainTimer) { clearInterval(_memoryDrainTimer); _memoryDrainTimer = null; }
   } finally {
     bridgeRuntimeStarting = false;
   }
@@ -837,6 +863,7 @@ async function stopOwnedRuntime(reason) {
   // file handle + timers for the rest of the process lifetime.
   try { forwarder.stopWatch(); } catch {}
   stopOwnerHeartbeat();
+  if (_memoryDrainTimer) { clearInterval(_memoryDrainTimer); _memoryDrainTimer = null; }
   scheduler.stop();
   stopSnapshotWriter();
   await stopWebhookAndEventRuntime();

package/src/runtime/channels/lib/memory-client.mjs

@@ -31,7 +31,7 @@ async function getMemoryPort() {
   }
 }
 
-async function memoryFetch(method, endpoint, body = null, timeoutMs = 10_000) {
+async function memoryFetch(method, endpoint, body = null, timeoutMs = 10_000, { throwOnError = false } = {}) {
   const port = await getMemoryPort()
   return new Promise((resolve, reject) => {
     if (!port) { reject(new Error('active-instance.json missing memory_port')); return }
@@ -49,8 +49,20 @@ async function memoryFetch(method, endpoint, body = null, timeoutMs = 10_000) {
       let data = ''
       res.on('data', chunk => { data += chunk })
       res.on('end', () => {
-        try { resolve(JSON.parse(data)) }
-        catch { resolve({ raw: data }) }
+        const status = res.statusCode || 0
+        let parsed
+        try { parsed = JSON.parse(data) }
+        catch { parsed = { raw: data } }
+        // Live callers keep lenient semantics (resolve on any response).
+        // Drain replay passes throwOnError so a non-2xx status or an
+        // {error} body is treated as a FAILED replay — the buffer file is
+        // then kept for retry instead of being unlinked (data-loss guard).
+        if (throwOnError && (status < 200 || status >= 300 || (parsed && parsed.error != null))) {
+          const detail = parsed && parsed.error != null ? String(parsed.error) : `HTTP ${status}`
+          reject(new Error(`memory replay rejected: ${detail}`))
+          return
+        }
+        resolve(parsed)
       })
     })
     req.on('error', reject)
@@ -61,6 +73,10 @@ async function memoryFetch(method, endpoint, body = null, timeoutMs = 10_000) {
 }
 
 const BUFFER_DIR = path.join(RUNTIME_ROOT, 'memory-buffer')
+const DEAD_DIR = path.join(BUFFER_DIR, 'dead')
+const MAX_DRAIN_ATTEMPTS = 5
+const MAX_BUFFER_FILES = 500
+let _draining = false
 
 function normalizeTs(ts) {
   if (typeof ts === 'number' && Number.isFinite(ts)) {
@@ -87,16 +103,8 @@ export async function appendEntry(data) {
     return await memoryFetch('POST', '/entry', payload, 3_000)
   } catch (e) {
     process.stderr.write(`[memory-client] appendEntry failed (${e.message}) — buffering\n`)
-    try {
-      fs.mkdirSync(BUFFER_DIR, { recursive: true })
-      const random = Math.random().toString(36).slice(2, 10)
-      const bufferPath = path.join(BUFFER_DIR, `entry-${Date.now()}-${random}.json`)
-      fs.writeFileSync(bufferPath, JSON.stringify(payload, null, 2))
-      return { ok: false, buffered: true, path: bufferPath }
-    } catch (bufErr) {
-      process.stderr.write(`[memory-client] Failed to buffer entry: ${bufErr.message}\n`)
-      return { ok: false }
-    }
+    const bufferPath = bufferToDisk('entry', payload)
+    return bufferPath ? { ok: false, buffered: true, path: bufferPath } : { ok: false }
   }
 }
 
@@ -104,8 +112,185 @@ export async function ingestTranscript(filePath, { cwd } = {}) {
   try {
     return await memoryFetch('POST', '/ingest-transcript', { filePath, ...(cwd ? { cwd } : {}) })
   } catch (e) {
-    process.stderr.write(`[memory-client] ingestTranscript failed: ${e.message}\n`)
-    return { ok: false }
+    process.stderr.write(`[memory-client] ingestTranscript failed (${e.message}) — buffering\n`)
+    // Dedupe by transcriptPath: replace any already-buffered ingest for the
+    // same file so a re-ingest storm cannot fan out to N buffer files.
+    const bufferPath = bufferToDisk('ingest', { filePath, ...(cwd ? { cwd } : {}) }, { dedupeKey: filePath })
+    return bufferPath ? { ok: false, buffered: true, path: bufferPath } : { ok: false }
+  }
+}
+
+// Persist a failed request so the drainer can replay it once the memory
+// service publishes its port. `kind` selects the replay endpoint on drain.
+// dedupeKey (ingest): if an existing kind-* file already carries the same
+// key, overwrite it in place instead of writing a new file — one buffered
+// ingest per transcriptPath. Enforces MAX_BUFFER_FILES (drop-oldest+warn).
+// Atomic write: stage to a unique tmp file in the SAME dir, then rename over
+// the target. rename() is atomic on a single filesystem, so a concurrent
+// reader/drainer never observes a half-written buffer file.
+function atomicWrite(targetPath, contents) {
+  const tmp = `${targetPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`
+  fs.writeFileSync(tmp, contents)
+  try { fs.renameSync(tmp, targetPath) }
+  catch (e) { try { fs.unlinkSync(tmp) } catch {}; throw e }
+}
+
+function bufferToDisk(kind, payload, { dedupeKey = null } = {}) {
+  try {
+    fs.mkdirSync(BUFFER_DIR, { recursive: true })
+    if (dedupeKey != null) {
+      let existing = []
+      try { existing = fs.readdirSync(BUFFER_DIR) } catch {}
+      for (const name of existing) {
+        if (!name.startsWith(`${kind}-`) || !name.endsWith('.json')) continue
+        const full = path.join(BUFFER_DIR, name)
+        try {
+          const prev = JSON.parse(fs.readFileSync(full, 'utf8'))
+          if (prev && prev.filePath === dedupeKey) {
+            // Atomic overwrite (tmp+rename); preserves the original (oldest)
+            // ordering slot without exposing a half-written file to a drainer.
+            atomicWrite(full, JSON.stringify(payload, null, 2))
+            return full
+          }
+        } catch {}
+      }
+    }
+    enforceBufferCap()
+    const random = Math.random().toString(36).slice(2, 10)
+    // Prefix carries the replay kind; timestamp prefix keeps oldest-first
+    // ordering under a lexicographic sort.
+    const bufferPath = path.join(BUFFER_DIR, `${kind}-${Date.now()}-${random}.json`)
+    atomicWrite(bufferPath, JSON.stringify(payload, null, 2))
+    return bufferPath
+  } catch (bufErr) {
+    process.stderr.write(`[memory-client] Failed to buffer ${kind}: ${bufErr.message}\n`)
+    return null
+  }
+}
+
+// Move a buffer file to memory-buffer/dead/ (quarantine, never silent-drop).
+// Returns true on success. On failure NEVER unlinks (no silent payload loss):
+// leaves the file in place and returns false so the caller skips it this pass.
+function moveToDead(name, reason) {
+  process.stderr.write(`[memory-client] quarantining ${name} to dead/ (${reason})\n`)
+  try {
+    fs.mkdirSync(DEAD_DIR, { recursive: true })
+    fs.renameSync(path.join(BUFFER_DIR, name), path.join(DEAD_DIR, name))
+    return true
+  } catch (e) {
+    process.stderr.write(`[memory-client] quarantine of ${name} failed (${e.message}) — leaving in place\n`)
+    return false
+  }
+}
+
+// Cap the buffer directory: when at/over MAX_BUFFER_FILES, quarantine oldest
+// files (lexicographic = ts-prefixed = oldest-first) to dead/ — never silently
+// destroy data (MED: cap must preserve for triage, same as poison path).
+function enforceBufferCap() {
+  let files
+  try {
+    files = fs.readdirSync(BUFFER_DIR)
+      .filter(f => (f.startsWith('entry-') || f.startsWith('ingest-')) && f.endsWith('.json'))
+      .sort()
+  } catch { return }
+  let over = files.length - (MAX_BUFFER_FILES - 1)
+  for (let i = 0; i < files.length && over > 0; i++, over--) {
+    moveToDead(files[i], `buffer cap ${MAX_BUFFER_FILES} exceeded — oldest`)
+  }
+}
+
+// Replay buffered entry-*/ingest-* files once the memory port is live.
+// Oldest-first (filename carries a ms timestamp), dedupe-safe (each file is
+// deleted only after a 2xx replay — memoryFetch(throwOnError) rejects on
+// non-2xx/{error}, so a rejected replay keeps the file for retry, no data
+// loss). Retry count is PERSISTED in the filename suffix (`.rN`) so process
+// restarts don't reset the poison cap; after MAX_DRAIN_ATTEMPTS the file is
+// MOVED to memory-buffer/dead/ (not deleted, not left blocking the queue).
+// Reentrancy-guarded.
+//
+// Attempt count lives in the name: `<kind>-<ts>-<rnd>.json` (attempt 0) or
+// `<kind>-<ts>-<rnd>.rN.json` (N prior failures). Parsed/rewritten via rename.
+function parseRetry(name) {
+  const m = name.match(/\.r(\d+)\.json$/)
+  return m ? Number(m[1]) : 0
+}
+function retryName(name, n) {
+  const base = name.replace(/\.r\d+\.json$/, '.json').replace(/\.json$/, '')
+  return `${base}.r${n}.json`
+}
+export async function drainBuffer() {
+  if (_draining) return { ok: true, skipped: 'in-progress' }
+  const port = await getMemoryPort()
+  if (!port) return { ok: false, reason: 'no-port' }
+  _draining = true
+  let drained = 0
+  let failed = 0
+  // Files that could not be advanced this pass (rename lock/EPERM). Skipped so
+  // an un-rewritable file can't wedge the oldest-first queue forever; retried
+  // on the next drain (their on-disk .rN is unchanged, so the cap still holds).
+  const skipThisPass = new Set()
+  try {
+    let files
+    try {
+      files = fs.readdirSync(BUFFER_DIR)
+    } catch { return { ok: true, drained: 0 } }
+    files = files
+      .filter(f => (f.startsWith('entry-') || f.startsWith('ingest-')) && f.endsWith('.json'))
+      .sort() // ts-prefixed name => oldest-first
+    for (const name of files) {
+      if (skipThisPass.has(name)) continue
+      const bufferPath = path.join(BUFFER_DIR, name)
+      let payload
+      try {
+        payload = JSON.parse(fs.readFileSync(bufferPath, 'utf8'))
+      } catch {
+        // Unparseable/corrupt buffer file — a partial write may be in flight,
+        // or it may be genuinely corrupt. Do NOT unlink (silent data loss):
+        // quarantine to dead/ for triage and move on. If the quarantine move
+        // itself fails, skip it for this pass so it can't block oldest-first.
+        if (!moveToDead(name, 'unparseable buffer file')) skipThisPass.add(name)
+        continue
+      }
+      const endpoint = name.startsWith('ingest-') ? '/ingest-transcript' : '/entry'
+      try {
+        // throwOnError: non-2xx status or an {error} body REJECTS, so the
+        // file is kept/aged for retry instead of unlinked (HIGH: data loss).
+        await memoryFetch('POST', endpoint, payload, 10_000, { throwOnError: true })
+        try { fs.unlinkSync(bufferPath) } catch {}
+        drained++
+      } catch (e) {
+        const attempts = parseRetry(name) + 1
+        failed++
+        if (attempts >= MAX_DRAIN_ATTEMPTS) {
+          // Quarantine, don't drop: move to dead/ so a poison record neither
+          // wedges the queue nor silently vanishes (recoverable for triage).
+          moveToDead(name, `${attempts} failed replays: ${e.message}`)
+        } else {
+          // Persist the incremented attempt count in the filename so a
+          // restart resumes the poison cap instead of resetting it. If the
+          // rename fails (EPERM/lock), leave the file as-is but skip it for
+          // THIS pass so it can't block the oldest-first queue forever — the
+          // next drain re-reads its (unchanged) .rN and retries.
+          try {
+            fs.renameSync(bufferPath, path.join(BUFFER_DIR, retryName(name, attempts)))
+          } catch {
+            // Rename lock/EPERM: don't break the whole pass on a file we
+            // couldn't even age — skip it and CONTINUE so later buffered
+            // files still drain. (Strict oldest-first yields to progress
+            // ONLY in this rename-failure case; a normal replay failure
+            // below still breaks, since the service is likely down.)
+            skipThisPass.add(name)
+            continue
+          }
+        }
+        // Stop the pass on first failure: the service is likely still down,
+        // so hammering the rest wastes timeouts. Next drain retries in order.
+        break
+      }
+    }
+  } finally {
+    _draining = false
   }
+  return { ok: failed === 0, drained, failed }
 }
 

package/src/runtime/memory/index.mjs

@@ -152,6 +152,17 @@ function touchDaemonIdleTimer(reason = 'activity') {
 function advertiseMemoryPort(boundPort, attempt = 0) {
   if (!Number.isFinite(boundPort) || boundPort <= 0) return
   _currentAdvertisedPort = boundPort
+  if (!_periodicAdvertiseInstalled) {
+    _periodicAdvertiseInstalled = true
+    _periodicAdvertiseTimer = setInterval(() => {
+      try {
+        if (_currentAdvertisedPort != null) {
+          advertiseMemoryPort(_currentAdvertisedPort)
+        }
+      } catch {}
+    }, 30_000)
+    _periodicAdvertiseTimer.unref?.()
+  }
   const dir = RUNTIME_ROOT
   const file = path.join(dir, 'active-instance.json')
   try {
@@ -177,17 +188,6 @@ function advertiseMemoryPort(boundPort, attempt = 0) {
       }
       return next
     }, { compact: true, fsyncDir: true, renameFallback: 'truncate' })
-    if (!_periodicAdvertiseInstalled) {
-      _periodicAdvertiseInstalled = true
-      _periodicAdvertiseTimer = setInterval(() => {
-        try {
-          if (_currentAdvertisedPort != null) {
-            advertiseMemoryPort(_currentAdvertisedPort)
-          }
-        } catch {}
-      }, 30_000)
-      _periodicAdvertiseTimer.unref?.()
-    }
   } catch (e) {
     const transient = e?.code === 'EPERM' || e?.code === 'EBUSY' || e?.code === 'EACCES'
     if (transient && attempt < 3) {
@@ -580,6 +580,7 @@ const _cycleScheduler = createCycleScheduler({
 const _startCycle1Run = _cycleScheduler.startCycle1Run
 const _awaitCycle1Run = _cycleScheduler.awaitCycle1Run
 const _finalizeCycle2Run = _cycleScheduler.finalizeCycle2Run
+const _finalizeCycle3Run = _cycleScheduler.finalizeCycle3Run
 
 // Transcript watcher lifecycle stays in the facade (owns _transcriptIngest);
 // the cycle tick loop start/stop is delegated to the scheduler.
@@ -769,6 +770,10 @@ async function _handleMemCycle3(args, config, signal) {
   }
   const result = await runCycle3(db, config || {}, DATA_DIR, c3Options)
   if (signal?.aborted) throw signal.reason ?? new Error('aborted')
+  // Stamp cycle3 success: the MCP path bypasses the scheduler's coalesced
+  // onCoalescedSuccess, so without this last_success_at stayed 0 despite
+  // successful runs.
+  await _finalizeCycle3Run(result)
   const parts = ['reviewed', 'kept', 'updated', 'merged', 'deleted']
     .map(k => `${k}=${result?.[k] || 0}`)
   if (result?.proposed) {
@@ -1523,11 +1528,11 @@ async function buildSessionCoreMemoryPayload(cwd) {
     ORDER BY score DESC, last_seen_at DESC
   `, projectId !== null ? [projectId] : [])).rows
   const commonRows = (await db.query(
-    `SELECT summary FROM core_entries WHERE project_id IS NULL ORDER BY id ASC`
+    `SELECT summary FROM core_entries WHERE project_id IS NULL AND (status IS NULL OR status = 'active') ORDER BY id ASC`
   )).rows
   const scopedRows = projectId !== null
     ? (await db.query(
-        `SELECT summary FROM core_entries WHERE project_id = $1 ORDER BY id ASC`,
+        `SELECT summary FROM core_entries WHERE project_id = $1 AND (status IS NULL OR status = 'active') ORDER BY id ASC`,
         [projectId]
       )).rows
     : []

package/src/runtime/memory/lib/core-memory-store.mjs

@@ -63,7 +63,9 @@ function throwIfAborted(signal) {
 async function _backfillNullEmbeddings(db, options = {}) {
   const signal = options?.signal
   throwIfAborted(signal)
-  const r = await db.query(`SELECT id, element, summary FROM core_entries WHERE embedding IS NULL`)
+  // Only refill live cores — archiveCore intentionally nulls the embedding to
+  // drop archived rows from recall; refilling them would resurrect them.
+  const r = await db.query(`SELECT id, element, summary FROM core_entries WHERE embedding IS NULL AND (status IS NULL OR status = 'active')`)
   if (r.rows.length === 0) return 0
   let filled = 0
   for (const row of r.rows) {
@@ -144,6 +146,7 @@ async function _findTopKCore(db, projectId, embedding, excludeId, { forUpdate =
     FROM core_entries
     WHERE embedding IS NOT NULL
       AND project_id IS NOT DISTINCT FROM $2
+      AND (status IS NULL OR status = 'active')
       ${exclusion}
     ORDER BY embedding <=> $1::halfvec
     LIMIT ${CORE_DEDUP_TOP_K}${forUpdate ? ' FOR UPDATE' : ''}`
@@ -188,15 +191,18 @@ async function _llmJudgeMerge(existing, incoming) {
 export async function listCore(dataDir, projectId = null) {
   const db = _getDb(dataDir)
   const cols = `id, element, summary, category, project_id, created_at, updated_at`
+  // Only live cores enter recall/review — archived (superseded) rows are
+  // retired but retained for audit. Legacy NULL status = active.
+  const live = `(status IS NULL OR status = 'active')`
   if (projectId === '*') {
-    const r = await db.query(`SELECT ${cols} FROM core_entries ORDER BY project_id NULLS FIRST, id ASC`)
+    const r = await db.query(`SELECT ${cols} FROM core_entries WHERE ${live} ORDER BY project_id NULLS FIRST, id ASC`)
     return r.rows
   }
   if (projectId === null) {
-    const r = await db.query(`SELECT ${cols} FROM core_entries WHERE project_id IS NULL ORDER BY id ASC`)
+    const r = await db.query(`SELECT ${cols} FROM core_entries WHERE project_id IS NULL AND ${live} ORDER BY id ASC`)
     return r.rows
   }
-  const r = await db.query(`SELECT ${cols} FROM core_entries WHERE project_id = $1 ORDER BY id ASC`, [projectId])
+  const r = await db.query(`SELECT ${cols} FROM core_entries WHERE project_id = $1 AND ${live} ORDER BY id ASC`, [projectId])
   return r.rows
 }
 
@@ -242,14 +248,37 @@ export async function addCore(dataDir, { element, summary, category }, projectId
     }
     let r
     try {
+      // Savepoint so a unique-collision doesn't abort the whole tx — we recover
+      // by reviving an archived row on the same connection below.
+      await client.query('SAVEPOINT ins')
       r = await client.query(
         `INSERT INTO core_entries(element, summary, category, project_id, embedding, created_at, updated_at)
          VALUES ($1, $2, $3, $4, $5::halfvec, $6, $7)
          RETURNING id, element, summary, category, project_id, created_at, updated_at`,
         [el, sm, cat, projectId, embedding ? embeddingToSql(embedding) : null, now, now],
       )
+      await client.query('RELEASE SAVEPOINT ins')
     } catch (err) {
       if (err.code === '23505') {
+        await client.query('ROLLBACK TO SAVEPOINT ins')
+        // Unique (project_id, element) collision. If the colliding row is an
+        // archived (superseded) row, the fact is being re-asserted → revive it
+        // in place: flip back to active, clear archived_at, overwrite content.
+        // Avoids a partial-index migration. An active collision is a genuine
+        // duplicate → surface the error.
+        const revived = await client.query(
+          `UPDATE core_entries
+           SET summary = $1, category = $2, embedding = $3::halfvec,
+               status = 'active', archived_at = NULL, updated_at = $4
+           WHERE project_id IS NOT DISTINCT FROM $5 AND element = $6
+             AND status = 'archived'
+           RETURNING id, element, summary, category, project_id, created_at, updated_at`,
+          [sm, cat, embedding ? embeddingToSql(embedding) : null, now, projectId, el],
+        )
+        if (revived.rows.length > 0) {
+          await client.query('COMMIT')
+          return { ...revived.rows[0], revived_from_archived: true }
+        }
         throw new Error(`core entry already exists: project=${projectId ?? 'COMMON'} element=${JSON.stringify(el.slice(0, 200))}`)
       }
       throw err
@@ -339,6 +368,80 @@ export async function deleteCore(dataDir, id) {
   return r.rows[0]
 }
 
+// Archive (retire without physical removal) a core entry whose fact was
+// superseded by a newer active fact. Non-destructive: flips status to
+// 'archived' + stamps archived_at so the row can be recovered/audited, and
+// drops it from the recall/review pool. Safe-by-default: unlike deleteCore this
+// is reversible and runs in conservative mode. Relies on the nullable status/
+// archived_at columns added in ensureCurrentSchemaExtensions (no migration
+// beyond those additive columns).
+//
+// Takes the same core:${project} advisory lock as addCore/editCore and
+// re-checks the row inside it, so a concurrent addCore merge/overwrite that
+// changed the fact after cycle3 read it is NOT clobbered. `expect` carries the
+// element/summary cycle3 reviewed; if the live row drifted from it the archive
+// is skipped (returns { skipped:true, reason:'content drift' }).
+export async function archiveCore(dataDir, id, expect = null) {
+  const numId = Number(id)
+  if (!Number.isInteger(numId) || numId <= 0) throw new Error('integer id > 0 required')
+  const db = _getDb(dataDir)
+  const now = Date.now()
+  const client = await checkedConnect(db._pool, 'memory')
+  try {
+    await client.query('BEGIN')
+    await client.query(`SET LOCAL lock_timeout = '5s'`)
+    // Lock ORDER must match addCore/editCore: advisory (pool) FIRST, then the
+    // row FOR UPDATE — otherwise same-row concurrency deadlocks. The advisory
+    // key needs project_id, so read it first WITHOUT a row lock (plain SELECT,
+    // no FOR UPDATE → acquires no row lock, can't invert ordering), take the
+    // pool advisory lock, THEN FOR UPDATE the row and re-validate under it.
+    const pre = (await client.query(
+      `SELECT project_id FROM core_entries WHERE id = $1`,
+      [numId],
+    )).rows[0]
+    if (!pre) throw new Error(`no entry with id=${numId}`)
+    const poolKey = `core:${pre.project_id == null ? 'COMMON' : pre.project_id}`
+    await client.query(`SELECT pg_advisory_xact_lock(hashtext($1))`, [poolKey])
+    // Now take the row lock under the pool lock and re-read — a concurrent
+    // addCore holding the same advisory lock may have merged/overwritten or
+    // moved the row's project_id between our pre-read and the lock.
+    const locked = (await client.query(
+      `SELECT id, element, summary, project_id, status FROM core_entries WHERE id = $1 FOR UPDATE`,
+      [numId],
+    )).rows[0]
+    if (!locked || !(locked.status == null || locked.status === 'active')) {
+      await client.query('ROLLBACK')
+      return { id: numId, skipped: true, reason: 'concurrently archived/removed' }
+    }
+    // If project_id moved pools between pre-read and lock, our advisory lock is
+    // on the wrong pool → bail rather than archive under a mismatched lock.
+    if ((locked.project_id ?? null) !== (pre.project_id ?? null)) {
+      await client.query('ROLLBACK')
+      return { id: numId, skipped: true, reason: 'pool changed under lock' }
+    }
+    if (expect && (String(expect.element ?? '') !== String(locked.element ?? '') ||
+                   String(expect.summary ?? '') !== String(locked.summary ?? ''))) {
+      await client.query('ROLLBACK')
+      return { id: numId, skipped: true, reason: 'content drift' }
+    }
+    const r = await client.query(
+      `UPDATE core_entries
+       SET status = 'archived', archived_at = $1, updated_at = $2, embedding = NULL
+       WHERE id = $3 AND (status IS NULL OR status = 'active')
+       RETURNING *`,
+      [now, now, numId],
+    )
+    await client.query('COMMIT')
+    if (r.rows.length === 0) return { id: numId, skipped: true, reason: 'concurrently archived/removed' }
+    return r.rows[0]
+  } catch (err) {
+    try { await client.query('ROLLBACK') } catch {}
+    throw err
+  } finally {
+    client.release()
+  }
+}
+
 // ─── Core-candidate promotion pipeline (proposal mode) ───────────────────────
 //
 // nominateCoreCandidates flags strong active entries as core-memory
@@ -446,6 +549,7 @@ export async function nominateCoreCandidates(dataDir, options = {}) {
            SELECT inner_c.embedding
            FROM core_entries inner_c
            WHERE inner_c.embedding IS NOT NULL
+            AND (inner_c.status IS NULL OR inner_c.status = 'active')
              AND (inner_c.project_id IS NULL OR inner_c.project_id IS NOT DISTINCT FROM e.project_id)
            ORDER BY inner_c.embedding <=> e.embedding
            LIMIT 1