create-walle 0.10.1 → 0.10.2

package/template/coding-task-manager/lib/transcript-archiver.js

@@ -1,17 +1,21 @@
 'use strict';
 
-// Session transcript archiving (design: session-transcript-storage-resume-from-database). Idle transcripts
-// of every provider are discovered from disk at archive time, compressed and verified, their originals
-// moved to the transcript trash, and the trash purged after a grace period; a unit can be restored from
-// the trash or from the archive. Runs only inside workers/transcript-archive-worker.js (or a test): it
-// does filesystem work and hashing, and reaches the manifest table only through an injected async
-// `store` (readRows / listByState / rowsForUnit / applyArchive / ctmSessionIds / ...), which the worker
-// forwards to the db-owner op `transcriptManifestOp`. Nothing here opens a database or reads process.env.
+// Session transcript archiving (design: transcript-never-removed-honest-resume-card-2026-10-24). Idle
+// transcripts of every provider are discovered from disk at archive time, compressed, verified and kept as
+// an ADDITIVE backup copy; a unit can be restored from the archive (or from a legacy trash entry). Runs only
+// inside workers/transcript-archive-worker.js (or a test): it does filesystem work and hashing, and reaches
+// the manifest table only through an injected async `store` (readRows / listByState / rowsForUnit /
+// applyArchive / ctmSessionIds / ...), which the worker forwards to the db-owner op `transcriptManifestOp`.
+// Nothing here opens a database or reads process.env.
 //
-// Rules this file keeps:
-//  - a file is never modified, and never deleted unless a verified archive of exactly that version exists
-//    (archiveUnit / purgeGraceExpired / scrub / recoverAtBoot, below); a failure at any step leaves the
-//    original where it is;
+// Rules this file keeps (user ruling 2026-10-24: "ctm should never ... remove transcript"):
+//  - an original under a provider transcript root is NEVER moved, renamed, truncated, modified or deleted
+//    by this file (D-1); the archiver only reads originals;
+//  - every byte CTM writes lands under <dataDir>/transcript-archive/<provider>/<sha[0:2]>/<sha256>.zst,
+//    with temp files under <dataDir>/transcript-archive/.incoming/ (D-3, D-4) -- never beside an original;
+//  - `archived` is terminal: the recorded version is in place, or the provider removed it and a verified
+//    copy of exactly that version exists (D-5). The states `original_trashed` and `cold` are read-only
+//    legacy values that no code path here writes any more;
 //  - nothing is copied or linked before a unit is archived: a transcript deleted from disk before then
 //    leaves no copy behind, and no manifest row either;
 //  - sha256 is computed by streaming, once, in the compress pass.
@@ -22,7 +26,6 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { getDataDir } = require('./data-dir');
 const { compressToFrames, verifyArchive, decodeFrame } = require('./transcript-archive-codec');
-const { trashSessionArtifacts, findTrashedTranscript } = require('./session-transcript-trash');
 const { RESTORED_GRACE_MS } = require('./transcript-source-identity');
 const { digestPassForMember } = require('./session-action-digest');
 const digestRunner = require('./transcript-digest-runner');
@@ -150,13 +153,13 @@ async function discoverClaudeUnits(opts = {}) {
 }
 
 // ---------------------------------------------------------------------------------------------------
-// WP-9: archive (D-16..D-19, D-22), grace purge, scrub (D-23) and boot recovery.
+// WP-1: archive (D-16..D-19, D-22), scrub (D-23) and boot recovery. No grace purge any more.
 //
-// A unit is archived only when EVERY member is eligible; nothing is deleted unless a verified archive
-// exists; a failure at any step leaves the original where it is. The order per member is
+// A unit is archived only when EVERY member is eligible; an original is never moved or deleted, at any
+// step: `archived` is the terminal state. The order per member is
 //   1 planned row -> 2 compress (one pass, also yields sha256) -> 3 fsync tmp -> 4 full decode verify ->
-//   5 re-stat the source -> 6 link tmp to its final name, unlink tmp, fsync dir -> 7 row `archived`
-// and once every member reached `archived`: 8 move the originals to the transcript trash -> `original_trashed`.
+//   5 re-stat the source -> 6 link tmp to its content-addressed name under the data dir, unlink tmp,
+//   fsync dir -> 7 row `archived`, and the original stays exactly where the provider put it.
 // Every manifest write goes through store.applyArchive.
 // ---------------------------------------------------------------------------------------------------
 
@@ -165,12 +168,15 @@ const IDLE_MS = 7 * DAY_MS; // D-18: every member's last write at least this lon
 const MIN_ARCHIVE_BYTES = 64 * 1024; // D-18: a unit whose members are all smaller is left alone
 const RESERVE_BYTES = 1 << 30; // D-18: free space >= 2 x expected archive + this
 const EXPECTED_RATIO = 8; // expected archive size = size / 8 (measured 88.0 GB -> 7.2 GB)
-const PURGE_GRACE_MS = 7 * DAY_MS;
 const SCRUB_MAX_BYTES = 2 * 1024 * 1024 * 1024;
-const ARCHIVE_SUBDIR = path.join('transcript-archive', 'claude');
+const ARCHIVE_ROOT_SUBDIR = 'transcript-archive';
+function archiveSubdirFor(provider) { return path.join(ARCHIVE_ROOT_SUBDIR, provider); }
+// Backward-compatible alias for readers that only ever knew the Claude layout (D-4/S-6).
+const ARCHIVE_SUBDIR = archiveSubdirFor('claude');
 const INCOMING_DIR = '.incoming';
 const TMP_RE = /\.zst\.tmp-\d+-\d+-\d+$/;
-const RESTORABLE_DONE = new Set(['original_trashed', 'cold']);
+// D-5: read-only legacy states. Nothing in this file writes them any more; recovery (WP-2) reads them.
+const LEGACY_REMOVED_STATES = new Set(['original_trashed', 'cold']);
 const WORK_STATES = new Set(['archived']);
 // Rows no code writes any more (dev databases only): deleted at the start of a run, no file is touched.
 const LEGACY_STATES = ['pinned', 'survivor', 'lost'];
@@ -190,7 +196,8 @@ function _archiveContext(opts) {
   ctx.minBytes = Number.isFinite(Number(opts.minBytes)) && opts.minBytes !== undefined ? Number(opts.minBytes) : MIN_ARCHIVE_BYTES;
   ctx.reserveBytes = Number.isFinite(Number(opts.reserveBytes)) && opts.reserveBytes !== undefined ? Number(opts.reserveBytes) : RESERVE_BYTES;
   ctx.failpoint = typeof opts.failpoint === 'function' ? opts.failpoint : null;
-  ctx.archiveRoot = path.join(ctx.dataDir, ARCHIVE_SUBDIR);
+  ctx.archiveRoot = path.join(ctx.dataDir, ARCHIVE_ROOT_SUBDIR);
+  // D-5: the archiver never moves an original, so nothing here can trash or purge one.
   ctx.counters = { archived: 0, bytesIn: 0, bytesOut: 0, trashed: 0, purged: 0, verified: 0, corrupt: 0, skipped: {} };
   return ctx;
 }
@@ -212,11 +219,6 @@ async function _step(ctx, n, info) {
   }
 }
 
-function _rootsForTrash(ctx) {
-  const unset = (name) => path.join(ctx.dataDir, `.unset-root-${name}`);
-  return [ctx.projectsRoot, ctx.walleSessionsDir || unset('walle'), ctx.codexSessionsDir || unset('codex')];
-}
-
 function _under(root, p) {
   const rel = path.relative(root, p);
   return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel);
@@ -330,18 +332,15 @@ async function _publish(ctx, tmp, finalWanted, res, contentAddressed) {
   throw Object.assign(new Error('archive path is occupied by different bytes'), { code: 'archive_path_occupied' });
 }
 
+// D-4: every provider's archive object is content-addressed under CTM's data dir, never beside the source.
 function _finalPathFor(ctx, unit, member, res) {
-  if (unit.provider === 'claude') {
-    return path.join(ctx.archiveRoot, res.sha256.slice(0, 2), `${res.sha256}.zst`);
-  }
-  return `${member.sourcePath}.zst`;
+  return path.join(ctx.dataDir, archiveSubdirFor(unit.provider), res.sha256.slice(0, 2), `${res.sha256}.zst`);
 }
 
 function _tmpPathFor(ctx, unit, member) {
   tmpSeq += 1;
   const tag = `.zst.tmp-${process.pid}-${ctx.now()}-${tmpSeq}`;
-  if (unit.provider === 'claude') return path.join(ctx.archiveRoot, INCOMING_DIR, `${path.basename(member.sourcePath)}${tag}`);
-  return `${member.sourcePath}${tag}`;
+  return path.join(ctx.dataDir, ARCHIVE_ROOT_SUBDIR, INCOMING_DIR, `${path.basename(member.sourcePath)}${tag}`);
 }
 
 // Steps 1..7 for one member. Returns { row } (state archived) or { aborted: reason }.
@@ -355,7 +354,7 @@ async function _archiveMember(ctx, unit, member, track) {
   await _step(ctx, 1, { member });
 
   const tmp = _tmpPathFor(ctx, unit, member);
-  if (unit.provider === 'claude') await ctx.fsp.mkdir(path.dirname(tmp), { recursive: true });
+  await ctx.fsp.mkdir(path.dirname(tmp), { recursive: true });
   track.tmp = tmp;
   const digest = digestPassForMember(unit, member, size); // D-24: the compress pass is also the digest pass
   let res;
@@ -368,7 +367,7 @@ async function _archiveMember(ctx, unit, member, track) {
   }
   await _step(ctx, 2, { member, tmp });
 
-  if (unit.provider !== 'claude') await ctx.fsp.utimes(tmp, st0.atime, st0.mtime); // Codex orders rollouts by mtime
+  if (unit.provider !== 'claude') await ctx.fsp.utimes(tmp, st0.atime, st0.mtime); // Codex orders rollouts by mtime (the archive copy only)
   await _fsyncFile(ctx, tmp);
   await _step(ctx, 3, { member, tmp });
 
@@ -382,13 +381,10 @@ async function _archiveMember(ctx, unit, member, track) {
     return { aborted: 'source_changed' };
   }
   await _step(ctx, 5, { member, tmp });
-  if (digest) await ctx.store.replaceDigest(member.sourcePath, digest.finish()); // fail closed: no digest, no trash
+  if (digest) await ctx.store.replaceDigest(member.sourcePath, digest.finish()); // fail closed: no digest, no archive
 
   const wanted = _finalPathFor(ctx, unit, member, res);
-  if (unit.provider !== 'claude' && member.row && member.row.archive_path === wanted && member.row.state === 'archived') {
-    await _unlinkIfPresent(ctx, wanted); // our own stale archive of an older version of this source
-  }
-  const final = await _publish(ctx, tmp, wanted, res, unit.provider === 'claude');
+  const final = await _publish(ctx, tmp, wanted, res, true);
   await _unlinkIfPresent(ctx, tmp);
   track.tmp = '';
   await _fsyncDir(ctx, path.dirname(final));
@@ -429,23 +425,6 @@ function _claudeProjectDir(ctx, members) {
   return path.join(ctx.projectsRoot, rel.split(path.sep)[0]);
 }
 
-// An `archived` row whose original is gone: the crash window between the trash move and step 8's row
-// write. Looks the original up in the trash manifests; '' when it cannot be proven to be there.
-async function _findInTrash(ctx, member, unitId) {
-  if (!ctx.trashRoot) return '';
-  const names = new Set([path.basename(member.sourcePath)]);
-  if (unitId) names.add(unitId);
-  for (const fileName of names) {
-    const hit = await findTrashedTranscript({ trashRoot: ctx.trashRoot, fileName, fs: ctx.fsp });
-    if (!hit) continue;
-    const src = member.sourcePath;
-    if (hit.originalPath !== src && !src.startsWith(hit.originalPath + path.sep)) continue;
-    const trashPath = hit.trashPath + src.slice(hit.originalPath.length);
-    if (await _statOrNull(ctx, trashPath)) return trashPath;
-  }
-  return '';
-}
-
 async function _loadMembers(ctx, unit) {
   if (unit.provider === 'claude') {
     // The members found on disk, joined with their manifest rows, plus the rows of the unit whose file is not
@@ -462,7 +441,7 @@ async function _loadMembers(ctx, unit) {
   return unit.members.map((m) => ({ ...m, row: rows.get(m.sourcePath) || null }));
 }
 
-// D-18 for one unit. Returns { skip } or { work: members still to be archived / trashed, total }.
+// D-18 for one unit. Returns { skip } or { work: members still to be archived, total }.
 async function _eligibility(ctx, unit, members) {
   if (!ctx.isPrimary) return { skip: 'not_primary' };
   if (ctx.live.has(String(unit.ctmSessionId)) || ctx.live.has(String(unit.unitId))) return { skip: 'live_session' };
@@ -471,8 +450,16 @@ async function _eligibility(ctx, unit, members) {
   const work = [];
   for (const member of members) {
     const state = member.row ? member.row.state : '';
-    if (RESTORABLE_DONE.has(state)) continue;
+    // D-5: a unit holding a legacy removed row is left entirely alone -- WP-2 restores it, never this file.
+    if (LEGACY_REMOVED_STATES.has(state)) return { skip: 'awaiting_recovery' };
     if (state && !WORK_STATES.has(state) && state !== 'planned') return { skip: 'unit_not_archivable' };
+    if (state === 'archived') {
+      const st = await _statOrNull(ctx, member.sourcePath);
+      if (!st) continue; // D-6: the provider removed it; the archive is the only copy and rung `restore` serves it
+      member.stat = st;
+      if (_sameSource(st, member.row)) continue; // D-5: the recorded version is in place -- done
+      // D-6: the original changed (resumed/appended) -- re-archive it and replace the row below.
+    }
     work.push(member);
   }
   if (!work.length) return { skip: 'already_archived' };
@@ -480,17 +467,13 @@ async function _eligibility(ctx, unit, members) {
   let large = false;
   const now = ctx.now();
   for (const member of work) {
-    const st = await _statOrNull(ctx, member.sourcePath);
-    if (!st) {
-      if (member.row && member.row.state === 'archived') { member.missing = true; continue; }
-      return { skip: 'member_missing' };
-    }
+    const st = member.stat || await _statOrNull(ctx, member.sourcePath);
+    if (!st) return { skip: 'member_missing' };
     if (now - _mtimeOf(st) < ctx.idleMs) return { skip: 'not_idle' };
     member.stat = st;
     total += Number(st.size);
     if (Number(st.size) >= ctx.minBytes) large = true;
   }
-  if (work.every((m) => m.missing)) return { work, total };
   if (!large) return { skip: 'too_small' };
   if (unit.provider === 'claude') {
     const projectDir = _claudeProjectDir(ctx, members);
@@ -499,7 +482,7 @@ async function _eligibility(ctx, unit, members) {
     const onDisk = await _enumerateClaudeUnit(ctx, projectDir, unit.unitId);
     if (onDisk.some((p) => !known.has(p))) return { skip: 'unit_changed' };
   }
-  const jsonl = work.filter((m) => !m.missing && /\.jsonl$/.test(m.sourcePath) && (m.memberKind === 'main' || m.memberKind === 'subagent'));
+  const jsonl = work.filter((m) => /\.jsonl$/.test(m.sourcePath) && (m.memberKind === 'main' || m.memberKind === 'subagent'));
   if (jsonl.length) {
     const cursors = await ctx.store.importCursors(jsonl.map((m) => m.sourcePath));
     for (const member of jsonl) {
@@ -508,93 +491,14 @@ async function _eligibility(ctx, unit, members) {
     }
   }
   if (typeof ctx.fsp.statfs === 'function') {
-    const probe = unit.provider === 'claude' ? ctx.dataDir : path.dirname(work[0].sourcePath);
-    const fsStat = await ctx.fsp.statfs(probe);
+    // D-4: the archive (and its temp) always lands on the data dir's filesystem, whatever the provider.
+    const fsStat = await ctx.fsp.statfs(ctx.dataDir);
     const free = Number(fsStat.bavail) * Number(fsStat.bsize);
     if (free < 2 * Math.ceil(total / EXPECTED_RATIO) + ctx.reserveBytes) return { skip: 'low_disk' };
   }
   return { work, total };
 }
 
-function _trashPathFor(entries, sourcePath) {
-  for (const entry of entries) {
-    if (entry.originalPath === sourcePath) return entry.trashPath;
-    if (sourcePath.startsWith(entry.originalPath + path.sep)) return entry.trashPath + sourcePath.slice(entry.originalPath.length);
-  }
-  return '';
-}
-
-// Step 8 for every member whose row is `archived` with the original still in place.
-async function _trashUnit(ctx, unit, members) {
-  const archived = [];
-  for (const member of members) {
-    if (member.row && member.row.state === 'archived' && await _statOrNull(ctx, member.sourcePath)) archived.push(member);
-  }
-  if (!archived.length) return { trashed: 0 };
-  // Nothing moves unless every original is exactly the version that was archived.
-  const changed = [];
-  for (const member of archived) {
-    if (!_sameSource(await _statOrNull(ctx, member.sourcePath), member.row)) changed.push(member);
-  }
-  if (changed.length) {
-    for (const member of changed) {
-      const change = _revertChange(ctx, unit, member);
-      await ctx.store.applyArchive(change);
-    }
-    _skip(ctx, 'source_changed');
-    return { trashed: 0, skipped: 'source_changed' };
-  }
-  const paths = [];
-  let unitDir = '';
-  if (unit.provider === 'claude') {
-    const projectDir = _claudeProjectDir(ctx, members);
-    const known = new Set(members.map((m) => m.sourcePath));
-    const onDisk = await _enumerateClaudeUnit(ctx, projectDir, unit.unitId);
-    if (onDisk.some((p) => !known.has(p))) {
-      _skip(ctx, 'unit_changed');
-      return { trashed: 0, skipped: 'unit_changed' };
-    }
-    const dir = path.join(projectDir, unit.unitId);
-    if (await _statOrNull(ctx, dir)) unitDir = dir;
-  }
-  const archivedPaths = new Set(archived.map((m) => m.sourcePath));
-  for (const member of archived) {
-    if (unitDir && member.sourcePath.startsWith(unitDir + path.sep)) continue; // moves with its directory
-    paths.push(member.sourcePath);
-  }
-  if (unitDir) {
-    const hasAnchor = [`${unit.unitId}.jsonl`, `${unit.unitId}.jsonl.bak`].some((n) => archivedPaths.has(path.join(path.dirname(unitDir), n)));
-    if (hasAnchor) paths.push(unitDir);
-    else for (const member of archived) if (member.sourcePath.startsWith(unitDir + path.sep)) paths.push(member.sourcePath);
-  }
-  const result = await trashSessionArtifacts({
-    paths,
-    roots: _rootsForTrash(ctx),
-    reason: 'archived',
-    ctmSessionId: unit.ctmSessionId || null,
-    isPrimary: true,
-    trashRoot: ctx.trashRoot,
-    fs: ctx.fsp,
-    now: () => new Date(ctx.now()),
-    warn: () => {},
-    error: (message) => ctx.stats.errors.push({ path: unit.unitId, code: String(message).slice(0, 200) }),
-  });
-  await _step(ctx, 8, { unit });
-  const now = ctx.now();
-  const upserts = [];
-  for (const member of archived) {
-    const trashPath = _trashPathFor(result.entries, member.sourcePath);
-    if (!trashPath) continue;
-    upserts.push({ ...member.row, state: 'original_trashed', trash_path: trashPath, state_changed_at_ms: now, last_error: '' });
-  }
-  if (upserts.length) await ctx.store.applyArchive({ upserts, deletes: [] });
-  if (upserts.length < archived.length) {
-    ctx.stats.errors.push({ path: unit.unitId, code: 'trash_incomplete' });
-  }
-  ctx.counters.trashed += upserts.length;
-  return { trashed: upserts.length };
-}
-
 async function _failMember(ctx, unit, track, err) {
   if (track.tmp) await _unlinkIfPresent(ctx, track.tmp).catch((cleanup) => ctx.stats.errors.push({ path: track.tmp, code: cleanup && cleanup.code }));
   if (track.member) {
@@ -604,30 +508,18 @@ async function _failMember(ctx, unit, track, err) {
 }
 
 /**
- * D-19. Archive one unit and move its originals to the trash. unit = { unitId, provider, ctmSessionId,
+ * D-19. Archive one unit as an additive backup. unit = { unitId, provider, ctmSessionId,
  * members: [{ sourcePath, memberKind }] } (Claude members come from the manifest rows of the unit).
- * @returns {{ archived: number, trashed: number, bytesIn: number, bytesOut: number, skipped: string, errors: object[] }}
+ * Originals are only ever read: no member is moved, modified or deleted.
+ * @returns {{ archived: number, bytesIn: number, bytesOut: number, skipped: string, errors: object[] }}
  */
 async function archiveUnit(unit, opts = {}) {
   const ctx = _archiveContext(opts);
-  const out = { archived: 0, trashed: 0, bytesIn: 0, bytesOut: 0, skipped: '', errors: [] };
+  const out = { archived: 0, bytesIn: 0, bytesOut: 0, skipped: '', errors: [] };
   const finish = () => { out.errors = ctx.stats.errors.splice(0); return out; };
   if (!ctx.isPrimary) { out.skipped = _skip(ctx, 'not_primary').skipped; return finish(); }
-  if (!ctx.trashRoot) throw new TypeError('transcript archiver: opts.trashRoot is required');
   const members = await _loadMembers(ctx, unit);
 
-  // A crash between the trash move and its row write: find the original in the trash and finish the row.
-  for (const member of members) {
-    if (!member.row || member.row.state !== 'archived') continue;
-    if (await _statOrNull(ctx, member.sourcePath)) continue;
-    const trashPath = await _findInTrash(ctx, member, unit.provider === 'claude' ? unit.unitId : '');
-    if (trashPath) {
-      member.row = { ...member.row, state: 'original_trashed', trash_path: trashPath, state_changed_at_ms: ctx.now(), last_error: '' };
-      await ctx.store.applyArchive({ upserts: [member.row], deletes: [] });
-      ctx.counters.trashed += 1;
-    }
-  }
-
   const eligible = await _eligibility(ctx, unit, members);
   if (eligible.skip) { out.skipped = _skip(ctx, eligible.skip).skipped; return finish(); }
 
@@ -635,7 +527,6 @@ async function archiveUnit(unit, opts = {}) {
   try {
     for (const member of eligible.work) {
       track.member = null;
-      if (member.missing) continue; // archived earlier, original already gone (trash lookup failed): nothing to do
       const row = member.row;
       if (row && row.state === 'archived' && _sameSource(member.stat, row) && await _statOrNull(ctx, row.archive_path)) continue; // finished earlier
       const result = await _archiveMember(ctx, unit, member, track);
@@ -650,9 +541,6 @@ async function archiveUnit(unit, opts = {}) {
       out.bytesIn += result.bytesIn;
       out.bytesOut += result.bytesOut;
     }
-    const trashed = await _trashUnit(ctx, unit, members);
-    out.trashed = trashed.trashed;
-    if (trashed.skipped) out.skipped = trashed.skipped;
   } catch (err) {
     if (err && err.failpoint) throw err;
     await _failMember(ctx, unit, track, err);
@@ -664,7 +552,7 @@ async function archiveUnit(unit, opts = {}) {
   return finish();
 }
 
-// ---- purge, scrub ------------------------------------------------------------------------------
+// ---- scrub --------------------------------------------------------------------------------------
 
 function _framesOf(row) {
   try {
@@ -711,44 +599,6 @@ async function _removeEmptyParents(ctx, start, stopAt) {
   }
 }
 
-// 7 days after the move: decode + hash the archive again; only then unlink the trash entry (-> `cold`). A failed verify sets `corrupt` and deletes nothing.
-async function purgeGraceExpired(opts = {}) {
-  const ctx = _archiveContext(opts);
-  const graceMs = Number.isFinite(Number(opts.graceMs)) && opts.graceMs !== undefined ? Number(opts.graceMs) : PURGE_GRACE_MS;
-  if (!ctx.isPrimary) { _skip(ctx, 'not_primary'); return { purged: 0, corrupt: 0, verified: 0, skipped: { not_primary: 1 }, errors: [] }; }
-  const out = { purged: 0, corrupt: 0, verified: 0, skipped: {}, errors: [] };
-  const rows = await ctx.store.listByState({
-    states: ['original_trashed'], olderThanMs: ctx.now() - graceMs, orderBy: 'changed', limit: Number(opts.limit) || 200,
-  });
-  const verify = _verifier(ctx);
-  for (const row of rows) {
-    try {
-      const verdict = await verify(row);
-      if (!verdict.ok) {
-        await ctx.store.applyArchive({ upserts: [{ ...row, state: 'corrupt', state_changed_at_ms: ctx.now(), last_error: `purge_${verdict.code}` }], deletes: [] });
-        out.corrupt += 1;
-        continue;
-      }
-      out.verified += 1;
-      if (row.trash_path && ctx.trashRoot && _under(ctx.trashRoot, row.trash_path)) {
-        await _unlinkIfPresent(ctx, row.trash_path);
-        await _removeEmptyParents(ctx, row.trash_path, ctx.trashRoot);
-      }
-      await ctx.store.applyArchive({
-        upserts: [{ ...row, state: 'cold', trash_path: '', pin_path: '', last_verified_at_ms: ctx.now(), state_changed_at_ms: ctx.now(), last_error: '' }],
-        deletes: [],
-      });
-      out.purged += 1;
-    } catch (err) {
-      out.errors.push({ path: row.source_path, code: (err && err.code) || String((err && err.message) || err) });
-    }
-  }
-  ctx.counters.purged += out.purged;
-  ctx.counters.verified += out.verified;
-  ctx.counters.corrupt += out.corrupt;
-  return out;
-}
-
 // D-23. Re-verify the least recently verified archives, up to `maxBytes` of archive bytes per run.
 async function scrub(opts = {}) {
   const ctx = _archiveContext(opts);
@@ -794,12 +644,13 @@ async function _removeTmpFiles(ctx, dir, out) {
 }
 
 /**
- * Removes `*.zst.tmp-*` leftovers in the archive dirs, deletes rows stuck in `planned`, and repairs
- * `archived` rows whose archive or original went missing. Never touches an original.
+ * Removes `*.zst.tmp-*` leftovers in the archive dirs, deletes rows stuck in `planned`, and repairs rows
+ * whose archive went missing (a row is only ever dropped or marked `corrupt`). Never touches an original:
+ * D-5, an `archived` row whose original is gone is done, not repaired.
  */
 async function recoverAtBoot(opts = {}) {
   const ctx = _archiveContext(opts);
-  const out = { tmpRemoved: 0, deleted: 0, archiveMissing: 0, trashRecovered: 0, errors: [] };
+  const out = { tmpRemoved: 0, deleted: 0, archiveMissing: 0, errors: [] };
   if (!ctx.isPrimary) return out;
   await _removeTmpFiles(ctx, ctx.archiveRoot, out);
   if (ctx.codexSessionsDir) await _removeTmpFiles(ctx, ctx.codexSessionsDir, out);
@@ -825,12 +676,6 @@ async function recoverAtBoot(opts = {}) {
         } else {
           await ctx.store.applyArchive({ upserts: [{ ...row, state: 'corrupt', state_changed_at_ms: now, last_error: 'archive_missing' }], deletes: [] });
         }
-      } else if (row.state === 'archived' && !source) {
-        const trashPath = await _findInTrash(ctx, { sourcePath: row.source_path }, row.provider === 'claude' ? row.unit_id : '');
-        if (trashPath) {
-          await ctx.store.applyArchive({ upserts: [{ ...row, state: 'original_trashed', trash_path: trashPath, state_changed_at_ms: now, last_error: '' }], deletes: [] });
-          out.trashRecovered += 1;
-        }
       }
     } catch (err) {
       out.errors.push({ path: row.source_path, code: (err && err.code) || String((err && err.message) || err) });
@@ -906,11 +751,11 @@ async function _retireRows(ctx) {
 }
 
 /**
- * One archive run (scheduler job transcript-archive): boot recovery (first run only), up to `maxUnits`
- * units archived oldest first, the grace purge, and a scrub when `scrub` is set. Every provider's units are
+ * One archive run (scheduler job transcript-archive): boot recovery (first run only), the D-7 recovery pass,
+ * up to `maxUnits` units archived oldest first, and a scrub when `scrub` is set. Every provider's units are
  * discovered from disk (Claude by project directory, Codex and Wall-E by path), resumable by the cursors
  * `claudeAfter` / `codexAfter` / `walleAfter`; a unit not idle for the threshold is skipped. Nothing runs
- * while the host is shedding load. Non-primary instances do nothing.
+ * while the host is shedding load. Non-primary instances do nothing. Originals are never moved or deleted.
  */
 async function runArchiveCycle(opts = {}) {
   const ctx = _archiveContext(opts);
@@ -919,16 +764,15 @@ async function runArchiveCycle(opts = {}) {
   if (opts.recover) result.recovered = await recoverAtBoot({ ...opts, _ctx: ctx });
   if (ctx.hostShedding) { _skip(ctx, 'host_shedding'); return result; }
   await _retireRows(ctx);
+  // D-7: put every original the pre-WP-1 archiver moved away back BEFORE discovery, so a unit restored here is
+  // never re-archived in the same run. Its unit budget is its own constant: the archive pass's `maxUnits`
+  // (20 per hour, lib/transcript-guard-job.js) must not throttle a recovery that has thousands of files to
+  // put back.
+  result.restoredOriginals = await restoreRemovedOriginals({ ...opts, _ctx: ctx, maxUnits: RESTORE_MAX_UNITS });
 
   const now = ctx.now();
   const maxUnits = Math.max(1, Number(opts.maxUnits) || 20);
   const byUnit = new Map();
-  // An `archived` row whose original is already gone (the crash window before the trash move) is finished from the row.
-  for (const row of await ctx.store.listByState({ states: ['archived'], mtimeBeforeMs: now - ctx.idleMs, orderBy: 'mtime', limit: 2000 })) {
-    if (row.provider !== 'claude') continue;
-    if (!byUnit.has(row.unit_id)) byUnit.set(row.unit_id, { unitId: row.unit_id, provider: 'claude', ctmSessionId: row.ctm_session_id, members: [], mtimeMs: row.source_mtime_ms });
-    byUnit.get(row.unit_id).members.push({ sourcePath: row.source_path, memberKind: row.member_kind });
-  }
   const found = await discoverClaudeUnits({ _ctx: ctx, afterPath: opts.claudeAfter || '', limit: opts.scanLimit });
   result.nextClaudeAfter = found.nextAfter;
   for (const unit of found.units) {
@@ -964,13 +808,11 @@ async function runArchiveCycle(opts = {}) {
     try {
       const r = await archiveUnit(unit, { ...opts, _ctx: ctx });
       result.errors.push(...r.errors);
-      if (r.archived > 0 || r.trashed > 0) archivedUnits += 1;
+      if (r.archived > 0) archivedUnits += 1;
     } catch (err) {
       result.errors.push({ path: unit.unitId, code: (err && err.code) || String((err && err.message) || err) });
     }
   }
-  const purge = await purgeGraceExpired({ ...opts, _ctx: ctx });
-  result.errors.push(...purge.errors);
   if (opts.scrub) {
     const scrubbed = await scrub({ ...opts, _ctx: ctx, maxBytes: opts.scrubMaxBytes });
     result.errors.push(...scrubbed.errors);
@@ -1106,7 +948,10 @@ async function _restoreMember(ctx, row) {
     if (!await _matchesRow(ctx, target, row)) throw _restoreError('target_exists');
   } else {
     ({ how, trashPath = '' } = await _placeMember(ctx, row));
-    await ctx.fsp.utimes(target, new Date(ctx.now()), new Date(ctx.now()));
+    // `now` (default) is today's behaviour; `recorded` puts the manifest's own source_mtime_ms back so a
+    // recovery pass can restore a file exactly as the provider last saw it.
+    const when = ctx.restoreMtime === 'recorded' ? new Date(Number(row.source_mtime_ms)) : new Date(ctx.now());
+    await ctx.fsp.utimes(target, when, when);
     await _fsyncDir(ctx, path.dirname(target));
   }
   const st = await ctx.fsp.stat(target); // number-valued, as the importer's own stat reports
@@ -1136,9 +981,12 @@ async function _restoreMember(ctx, row) {
 }
 
 /** D-20. Restore a unit (id, { unitId } or { sourcePath }); the store needs restampIdentity. Returns
- * { restored: [{path, how}], plain: [path], failed: [{path, code}], skipped } (`plain` = already in place). */
+ * { restored: [{path, how}], plain: [path], failed: [{path, code}], skipped } (`plain` = already in place).
+ * `opts.mtime` is `'now'` (default; the restored file is stamped with today's time) or `'recorded'` (the
+ * row's own source_mtime_ms is put back for both atime and mtime). */
 async function restoreUnit(unit, opts = {}) {
   const ctx = _archiveContext(opts);
+  ctx.restoreMtime = opts.mtime === 'recorded' ? 'recorded' : 'now';
   const out = { restored: [], plain: [], failed: [], skipped: '' };
   if (!ctx.isPrimary) { out.skipped = 'not_primary'; return out; }
   if (typeof ctx.store.restampIdentity !== 'function') throw new TypeError('transcript archiver: store.restampIdentity is required to restore');
@@ -1165,17 +1013,169 @@ async function restoreUnit(unit, opts = {}) {
   return out;
 }
 
+// ---------------------------------------------------------------------------------------------------
+// WP-2 / D-7 recovery: put every original the pre-WP-1 archiver moved away back to its `source_path`.
+// ---------------------------------------------------------------------------------------------------
+
+const RESTORE_FLOOR_BYTES = 10 * 1024 * 1024 * 1024; // D-7: never decode into the last bytes of a disk
+const RESTORE_MAX_DECODE_BYTES = 4 * 1024 * 1024 * 1024; // D-7: decoded bytes per call
+const RESTORE_MAX_UNITS = 200; // D-7: units per call (a trash link-back is cheap)
+
+// Free bytes on the filesystem that will hold the restored file. An absent directory is resolved to its
+// nearest existing ancestor: restoreUnit creates the directory (same filesystem, barring a mount point inside
+// it), so this is the space the decode actually has. null = nothing on the chain could be read.
+async function _freeBytesAt(ctx, dir) {
+  let probe = dir;
+  for (;;) {
+    try {
+      const st = await ctx.fsp.statfs(probe);
+      return Number(st.bavail) * Number(st.bsize);
+    } catch (err) {
+      if (!err || (err.code !== 'ENOENT' && err.code !== 'ENOTDIR')) throw err;
+    }
+    const up = path.dirname(probe);
+    if (up === probe) return null;
+    probe = up;
+  }
+}
+
+// D-9: `row.archive_path` is provably CTM's own legacy sibling copy of this original -- a `.jsonl.zst` beside
+// the source, outside the data dir, named exactly `<source_path>.zst`, holding the bytes the row recorded.
+async function _isOwnSiblingArchive(ctx, row) {
+  const p = String(row.archive_path || '');
+  if (!p.endsWith('.jsonl.zst') || p !== `${row.source_path}.zst`) return false;
+  if (_under(ctx.dataDir, p)) return false;
+  if (!row.archive_sha256 || !await _statOrNull(ctx, p)) return false;
+  try {
+    return (await _archiveFileSha(p)) === row.archive_sha256;
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return false; // expected: gone between the stat and the read
+    throw err;
+  }
+}
+
+// One unit through restoreUnit, with the counters D-7 reports and the D-9 sibling cleanup after a verified
+// restore. A failed member never changes another member's outcome.
+async function _recoverUnit(ctx, unitId, opts, out) {
+  let result;
+  try {
+    result = await restoreUnit({ unitId }, opts);
+  } catch (err) {
+    out.failed.push({ path: String(unitId), code: (err && err.code) || String((err && err.message) || err) });
+    return;
+  }
+  for (const failure of result.failed) {
+    if (failure.code === 'target_exists') out.targetExists.push(failure.path);
+    else out.failed.push(failure);
+  }
+  if (!result.restored.length) return;
+  out.restoredUnits += 1;
+  out.restoredFiles += result.restored.length;
+  const rows = new Map((await ctx.store.rowsForUnit(unitId)).map((r) => [r.source_path, r]));
+  for (const entry of result.restored) {
+    const row = rows.get(entry.path) || {};
+    if (entry.how === 'trash') out.linkedFromTrash += 1;
+    else if (entry.how === 'archive') out.decodedBytes += Number(row.size_bytes) || 0;
+  }
+  for (const entry of result.restored) {
+    const row = rows.get(entry.path);
+    if (!row || row.state !== 'hot') continue;
+    if (!await _isOwnSiblingArchive(ctx, row)) continue;
+    // D-9: the original is verified back in place, so CTM's own sibling copy has no job left. The row keeps
+    // running as a plain `hot` row; the next idle cycle re-archives the unit under D-4.
+    await _unlinkIfPresent(ctx, row.archive_path);
+    await ctx.store.applyArchive({
+      upserts: [{ ...row, archive_path: '', archive_bytes: 0, archive_sha256: '', frames_json: '[]' }],
+      deletes: [],
+    });
+  }
+}
+
+/**
+ * D-7. Put every original a pre-WP-1 archiver moved away back to its `source_path`, cheapest source first:
+ * trash entries are hard-linked back (no extra bytes at all), then `cold` units are decoded newest source
+ * first, while the free space left after the decode stays at or above `floorBytes` and the bytes decoded this
+ * call stay under `maxDecodeBytes`. An occupied `source_path` is reported in `targetExists` and left alone,
+ * with its row, its trash copy and its archive untouched. Primary only: a non-primary instance returns
+ * `skipped: 'not_primary'` without making a single filesystem call.
+ * @param {object} opts same context as runArchiveCycle (store, dataDir, trashRoot, isPrimary, fs, now, ...)
+ *   plus floorBytes / maxDecodeBytes / maxUnits.
+ * @returns {{ restoredUnits: number, restoredFiles: number, linkedFromTrash: number, decodedBytes: number,
+ *   deferredLowDisk: number, targetExists: string[], failed: {path: string, code: string}[], skipped: string }}
+ */
+async function restoreRemovedOriginals(opts = {}) {
+  const ctx = _archiveContext(opts);
+  const floorBytes = Number.isFinite(Number(opts.floorBytes)) && opts.floorBytes !== undefined ? Number(opts.floorBytes) : RESTORE_FLOOR_BYTES;
+  const maxDecodeBytes = Number.isFinite(Number(opts.maxDecodeBytes)) && opts.maxDecodeBytes !== undefined ? Number(opts.maxDecodeBytes) : RESTORE_MAX_DECODE_BYTES;
+  const maxUnits = Math.max(1, Number(opts.maxUnits) || RESTORE_MAX_UNITS);
+  const out = {
+    restoredUnits: 0, restoredFiles: 0, linkedFromTrash: 0, decodedBytes: 0, deferredLowDisk: 0,
+    targetExists: [], failed: [], skipped: '',
+  };
+  if (!ctx.isPrimary) { out.skipped = 'not_primary'; return out; }
+  const perUnit = { ...opts, _ctx: ctx, mtime: 'recorded' };
+  // Phase A (D-7): a unit with a trashed original, or a corrupt row that still names a trash copy. Cheapest
+  // first -- a link-back costs no bytes -- and oldest state change first.
+  const placed = new Set();
+  const phaseA = [];
+  for (const row of await ctx.store.listByState({ states: ['original_trashed', 'corrupt'], orderBy: 'changed', limit: 2000 })) {
+    if (row.state !== 'original_trashed' && !(row.state === 'corrupt' && row.trash_path)) continue;
+    if (placed.has(row.unit_id)) continue;
+    placed.add(row.unit_id);
+    phaseA.push(row.unit_id);
+  }
+  let done = 0;
+  for (const unitId of phaseA) {
+    if (done >= maxUnits) break;
+    done += 1;
+    await _recoverUnit(ctx, unitId, perUnit, out);
+  }
+  if (done >= maxUnits) return out;
+  // Phase B (D-7): units whose removed rows are all `cold`, newest source first, and only while the disk
+  // keeps `floorBytes` free and this call stays under `maxDecodeBytes`. The byte budget stops only a call
+  // that has already decoded something, so a single unit larger than the whole budget still runs -- alone --
+  // instead of breaking on every call and stalling every unit behind it (the phase B order is deterministic).
+  const phaseB = [];
+  for (const row of await ctx.store.listByState({ states: ['cold'], orderBy: 'mtime_desc', limit: 2000 })) {
+    if (placed.has(row.unit_id)) continue;
+    placed.add(row.unit_id);
+    phaseB.push(row.unit_id);
+  }
+  for (const unitId of phaseB) {
+    if (done >= maxUnits) break;
+    const rows = await ctx.store.rowsForUnit(unitId);
+    if (!rows.length) continue;
+    if (rows.some((r) => r.state === 'original_trashed' || (r.state === 'corrupt' && r.trash_path))) continue; // phase A's unit
+    let need = 0;
+    for (const row of rows) if (!await _statOrNull(ctx, row.source_path)) need += Number(row.size_bytes) || 0;
+    if (typeof ctx.fsp.statfs === 'function') {
+      const free = await _freeBytesAt(ctx, path.dirname(String(rows[0].source_path)));
+      if (free !== null && free - need < floorBytes) { out.deferredLowDisk += 1; break; }
+    }
+    if (out.decodedBytes > 0 && out.decodedBytes + need > maxDecodeBytes) break;
+    done += 1;
+    await _recoverUnit(ctx, unitId, perUnit, out);
+  }
+  return out;
+}
+
 module.exports = {
   ARCHIVE_SUBDIR,
+  ARCHIVE_ROOT_SUBDIR,
+  archiveSubdirFor,
+  LEGACY_REMOVED_STATES,
   IDLE_MS,
   MIN_ARCHIVE_BYTES,
+  RESTORE_FLOOR_BYTES,
+  RESTORE_MAX_DECODE_BYTES,
+  RESTORE_MAX_UNITS,
   discoverClaudeUnits,
   discoverFlatUnits,
   archiveUnit,
-  purgeGraceExpired,
   scrub,
   recoverAtBoot,
   runArchiveCycle, runDigestCycle,
   restoreUnit,
+  restoreRemovedOriginals,
   RESTORED_GRACE_MS,
 };