@twinsearth/w2m-dsh-plugin 1.9.11 → 1.9.12

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "twinsearth-w2m-dsh",
-  "version": "1.9.11",
+  "version": "1.9.12",
   "description": "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 12 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
   "license": "MIT",
   "keywords": [

package/src/plugin/joint-dev/plan-store.mjs

@@ -1,46 +1,108 @@
 /**
  * joint-dev 计划持久化与人工审批门（本地文件，0600）。
- * 未审批的计划禁止 dispatch；审批绑定 plan_sha256 与候选人。
+ *
+ * 安全不变量（v2 预置）：
+ *   · plan_sha256 必须由本模块重算，与文件内容不符即 PLAN_TAMPERED；
+ *   · planSha 必须是 64 位小写十六进制，禁止路径穿越；
+ *   · 审批绑定 plan_sha256 + approver + authority + 过期时间，approval_sha256 读回时重算；
+ *   · 未审批的计划禁止 dispatch（assertDispatchAllowed 是唯一入口）。
+ *
+ * 审批只由操作员 CLI/UI 写入，不暴露为 agent 工具。
  */
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 const sha256 = (text) => createHash('sha256').update(text, 'utf8').digest('hex');
+const PLAN_SHA = /^[0-9a-f]{64}$/;
+const DEFAULT_APPROVAL_TTL_MS = 24 * 60 * 60 * 1000;
+
 const planDir = (stateDir) => join(stateDir, 'joint-dev', 'plans');
 const approvalDir = (stateDir) => join(stateDir, 'joint-dev', 'approvals');
 
+/** Hash of the plan body WITHOUT plan_sha256 — the same rule buildPlan uses. */
+export function planHashOf(plan) {
+  if (plan === null || typeof plan !== 'object') return null;
+  const { plan_sha256: _ignored, ...canonical } = plan;
+  return sha256(JSON.stringify(canonical));
+}
+
+function readPlanFile(stateDir, planSha) {
+  if (!PLAN_SHA.test(String(planSha ?? ''))) return { ok: false, code: 'PLAN_SHA_INVALID' };
+  const path = join(planDir(stateDir), planSha + '.json');
+  if (!existsSync(path)) return { ok: false, code: 'PLAN_NOT_FOUND' };
+  let parsed;
+  try { parsed = JSON.parse(readFileSync(path, 'utf8')); } catch { return { ok: false, code: 'PLAN_UNREADABLE' }; }
+  const plan = parsed?.plan;
+  if (plan === null || typeof plan !== 'object') return { ok: false, code: 'PLAN_INVALID' };
+  const recomputed = planHashOf(plan);
+  if (recomputed !== plan.plan_sha256 || recomputed !== planSha) {
+    return { ok: false, code: 'PLAN_TAMPERED', detail: { declared: plan.plan_sha256, recomputed, path } };
+  }
+  return { ok: true, plan, path, saved_at: parsed.saved_at ?? null };
+}
+
 export function savePlan({ stateDir, plan, now = Date.now() }) {
-  if (typeof plan?.plan_sha256 !== 'string' || plan.plan_sha256.length !== 64) return { ok: false, code: 'PLAN_INVALID' };
+  if (plan === null || typeof plan !== 'object' || !PLAN_SHA.test(String(plan.plan_sha256 ?? ''))) {
+    return { ok: false, code: 'PLAN_INVALID' };
+  }
+  const recomputed = planHashOf(plan);
+  if (recomputed !== plan.plan_sha256) {
+    return { ok: false, code: 'PLAN_HASH_MISMATCH', detail: { declared: plan.plan_sha256, recomputed } };
+  }
   mkdirSync(planDir(stateDir), { recursive: true });
   const path = join(planDir(stateDir), plan.plan_sha256 + '.json');
   if (existsSync(path)) return { ok: true, path, reused: true };
-  writeFileSync(path, JSON.stringify({ plan, saved_at: new Date(now).toISOString() }, null, 2), { encoding: 'utf8', mode: 0o600 });
+  const tmp = path + '.tmp-' + process.pid;
+  writeFileSync(tmp, JSON.stringify({ plan, saved_at: new Date(now).toISOString() }, null, 2), { encoding: 'utf8', mode: 0o600 });
+  // rename is atomic on the same volume; a crash leaves only the tmp file behind.
+  renameSync(tmp, path);
   return { ok: true, path, reused: false };
 }
 
 export function loadPlan({ stateDir, planSha }) {
-  const path = join(planDir(stateDir), planSha + '.json');
-  if (!existsSync(path)) return { ok: false, code: 'PLAN_NOT_FOUND' };
-  return { ok: true, ...JSON.parse(readFileSync(path, 'utf8')), path };
+  const loaded = readPlanFile(stateDir, planSha);
+  if (loaded.ok !== true) return loaded;
+  return { ok: true, plan: loaded.plan, saved_at: loaded.saved_at, path: loaded.path };
+}
+
+export function listPlans({ stateDir, limit = 50 }) {
+  const dir = planDir(stateDir);
+  if (!existsSync(dir)) return { ok: true, plans: [], total: 0 };
+  const entries = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    const path = join(dir, name);
+    try {
+      const stat = statSync(path);
+      entries.push({ plan_sha256: name.slice(0, -5), saved_at_ms: stat.mtimeMs });
+    } catch { /* a vanished plan is simply absent */ }
+  }
+  entries.sort((a, b) => b.saved_at_ms - a.saved_at_ms);
+  return { ok: true, plans: entries.slice(0, Math.max(1, Math.min(200, limit))), total: entries.length };
 }
 
 /**
- * 人工审批。authority 建议 ≥70；审批只由操作员 CLI/UI 写入，不暴露给 agent 工具。
+ * 人工审批。authority 最低 70；TTL 默认 24h；过期/哈希不符/计划被替换时 dispatch 拒绝。
  */
-export function approvePlan({ stateDir, planSha, approver, authority, note = '', now = Date.now() }) {
-  if (typeof planSha !== 'string' || planSha.length !== 64) return { ok: false, code: 'PLAN_SHA_INVALID' };
-  if (typeof approver !== 'string' || approver === '') return { ok: false, code: 'APPROVER_REQUIRED' };
+export function approvePlan({ stateDir, planSha, approver, authority, note = '', now = Date.now(), ttlMs = DEFAULT_APPROVAL_TTL_MS }) {
+  if (!PLAN_SHA.test(String(planSha ?? ''))) return { ok: false, code: 'PLAN_SHA_INVALID' };
+  if (typeof approver !== 'string' || approver.trim() === '') return { ok: false, code: 'APPROVER_REQUIRED' };
   if (!Number.isInteger(authority) || authority < 70) return { ok: false, code: 'APPROVAL_AUTHORITY_TOO_LOW', detail: { authority } };
-  if (!existsSync(join(planDir(stateDir), planSha + '.json'))) return { ok: false, code: 'PLAN_NOT_FOUND' };
+  if (!Number.isInteger(ttlMs) || ttlMs < 60_000 || ttlMs > 7 * 24 * 60 * 60 * 1000) {
+    return { ok: false, code: 'APPROVAL_TTL_INVALID', detail: { ttlMs } };
+  }
+  const loaded = readPlanFile(stateDir, planSha);
+  if (loaded.ok !== true) return loaded;
   mkdirSync(approvalDir(stateDir), { recursive: true });
   const body = {
-    v: 1,
+    v: 2,
     plan_sha256: planSha,
     approver,
     authority,
     note: String(note).slice(0, 200),
     approved_at: new Date(now).toISOString(),
+    expires_at: new Date(now + ttlMs).toISOString(),
   };
   const record = { ...body, approval_sha256: sha256(JSON.stringify(body)) };
   const path = join(approvalDir(stateDir), planSha + '.json');
@@ -48,19 +110,28 @@ export function approvePlan({ stateDir, planSha, approver, authority, note = '',
   return { ok: true, approval: record, path };
 }
 
-export function loadApproval({ stateDir, planSha }) {
+export function loadApproval({ stateDir, planSha, now = Date.now() }) {
+  if (!PLAN_SHA.test(String(planSha ?? ''))) return { ok: false, code: 'PLAN_SHA_INVALID' };
   const path = join(approvalDir(stateDir), planSha + '.json');
   if (!existsSync(path)) return { ok: false, code: 'APPROVAL_REQUIRED' };
-  const record = JSON.parse(readFileSync(path, 'utf8'));
-  if (record.plan_sha256 !== planSha) return { ok: false, code: 'APPROVAL_STALE' };
+  let record;
+  try { record = JSON.parse(readFileSync(path, 'utf8')); } catch { return { ok: false, code: 'APPROVAL_UNREADABLE' }; }
+  if (record?.plan_sha256 !== planSha) return { ok: false, code: 'APPROVAL_STALE' };
+  const { approval_sha256: declared, ...body } = record;
+  if (sha256(JSON.stringify(body)) !== declared) return { ok: false, code: 'APPROVAL_SIGNATURE_INVALID' };
+  if (!Number.isInteger(record.authority) || record.authority < 70) {
+    return { ok: false, code: 'APPROVAL_AUTHORITY_TOO_LOW', detail: { authority: record.authority } };
+  }
+  const expires = Date.parse(record.expires_at ?? '');
+  if (Number.isFinite(expires) && now > expires) return { ok: false, code: 'APPROVAL_EXPIRED', detail: { expires_at: record.expires_at } };
   return { ok: true, approval: record };
 }
 
-/** dispatch 前置门：计划必须存在且已审批。 */
-export function assertDispatchAllowed({ stateDir, planSha }) {
+/** dispatch 前置门：计划必须存在、未被篡改，且已审批、未过期。 */
+export function assertDispatchAllowed({ stateDir, planSha, now = Date.now() }) {
   const plan = loadPlan({ stateDir, planSha });
-  if (plan.ok !== true) return { ok: false, code: 'PLAN_NOT_FOUND' };
-  const approval = loadApproval({ stateDir, planSha });
-  if (approval.ok !== true) return { ok: false, code: 'APPROVAL_REQUIRED' };
+  if (plan.ok !== true) return { ok: false, code: plan.code ?? 'PLAN_NOT_FOUND' };
+  const approval = loadApproval({ stateDir, planSha, now });
+  if (approval.ok !== true) return { ok: false, code: approval.code ?? 'APPROVAL_REQUIRED' };
   return { ok: true, plan: plan.plan, approval: approval.approval };
 }

package/src/plugin/tools.mjs

@@ -283,7 +283,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '1.9.11';
+const PLUGIN_VERSION = '1.9.12';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -4249,6 +4249,7 @@ export async function apply(ctx, config = {}) {
       const originMachineId =
         typeof p2p.machineId === 'string' && p2p.machineId !== '' ? p2p.machineId : null;
 
+
       /**
        * v0.4.x: the punch this dispatch will use, published with the task so the executor can join
        * the same session instead of waiting to be reached. See {@link buildP2POfferBlock} for why the
@@ -4313,7 +4314,33 @@ export async function apply(ctx, config = {}) {
         p2p: p2pOffer,
       };
 
-      const result = await request({
+            // v2/S1: a narrowed dispatch is revalidated against the relay roster immediately before the
+      // POST, so a machine that went away after the composer selection is a named refusal rather
+      // than a task that expires with no executor.
+      const narrowedTo = selectionAppliedAs === 'executor_machine_id' || selectionAppliedAs === 'target_machines'
+        ? (selection?.machine_id ?? null)
+        : (executorMachineId ?? null);
+      if (narrowedTo !== null) {
+        // A roster read is a best-effort guard: if it fails, the relay itself still decides and the
+        // post-dispatch lease check below remains the authority on whether the narrowing held.
+        let preflight = null;
+        try {
+          preflight = await readFleet({ rabbitUrl: base, token, localMachineId: null, signal: exec?.signal, request });
+        } catch { preflight = null; }
+        if (preflight.ok === true) {
+          const listed = (preflight.devices ?? []).find((device) => device?.machine_id === narrowedTo);
+          const online = listed !== undefined && (listed.state === 'online' || listed.state === undefined);
+          if (!online) {
+            throw new W2MError(
+              'TARGET_UNAVAILABLE',
+              `TARGET_UNAVAILABLE: the target machine ${narrowedTo} is not online on the relay right now; nothing was dispatched and no other machine was chosen`,
+              { hint: 'pick another machine in the composer, or clear the selection to dispatch to the whole fleet' },
+            );
+          }
+        }
+      }
+
+const result = await request({
         rabbitUrl: base,
         token,
         signal: exec?.signal,
@@ -4346,7 +4373,29 @@ export async function apply(ctx, config = {}) {
         );
       }
 
-      /**
+      // v2/S1: the relay's own lease list is the proof that the narrowing was honoured. A lease on a
+      // machine that was not named means the dispatch widened (old relay ignoring the field, or a
+      // routing bug): cancel and refuse rather than let the wrong machines run.
+      if (narrowedTo !== null) {
+        const leases = Array.isArray(result.json?.leases) ? result.json.leases : [];
+        const executing = leases.filter((lease) => lease?.state !== 'observing');
+        const foreign = executing.filter((lease) => lease?.machine_id !== narrowedTo);
+        if (foreign.length > 0) {
+          const taskId = result.json?.task_id ?? null;
+          if (taskId !== null) {
+            try {
+              await request({ rabbitUrl: base, token, signal: exec?.signal, method: 'POST', pathname: '/v1/tasks/' + encodeURIComponent(taskId) + '/cancel', body: { reason: 'SELECTION_NOT_HONOURED' } });
+            } catch { /* the refusal below is still the answer */ }
+          }
+          throw new W2MError(
+            'SELECTION_NOT_HONOURED',
+            'SELECTION_NOT_HONOURED: this dispatch named ' + narrowedTo + ', but the relay leased ' + (foreign.map((lease) => lease.machine_id).join(', ') || 'no machine') + '; the task was cancelled',
+            { hint: 'upgrade the relay to a version that honours target_machines/executor_machine_id, or clear the selection' },
+          );
+        }
+      }
+
+/**
        * v0.4.0 §7: best-effort direct pushes, after the relay has the task.
        *
        * Order matters and is deliberate. The task exists on the relay *before* anything is punched,

package/src/relay/p0-projection.mjs

@@ -55,6 +55,23 @@ export function projectResultEnvelope(envelope) {
       dropped.push(field);
     }
   }
+  // NESTED: pipeline.stages[].command_argv and friends are content too. The top-level sweep above
+  // cannot see them, and a real ledger line carries exactly that shape.
+  const NESTED_CONTENT = [...CONTENT_FIELDS, 'changed_files'];
+  const walk = (value, path) => {
+    if (value === null || typeof value !== 'object') return;
+    if (Array.isArray(value)) { value.forEach((entry, index) => walk(entry, path + '[' + index + ']')); return; }
+    for (const key of Object.keys(value)) {
+      const keyPath = path === '' ? key : path + '.' + key;
+      if (NESTED_CONTENT.includes(key)) {
+        delete value[key];
+        dropped.push(keyPath);
+        continue;
+      }
+      walk(value[key], keyPath);
+    }
+  };
+  walk(projected, '');
   return { projected, dropped, argv_hash: argvHash };
 }
 
@@ -62,11 +79,16 @@ export function projectResultEnvelope(envelope) {
 export function projectLedgerLine(line) {
   let record;
   try { record = JSON.parse(line); } catch { return { changed: false, line }; }
-  const target = record?.result ?? record?.envelope;
-  if (target === null || typeof target !== 'object') return { changed: false, line };
-  const { projected, dropped } = projectResultEnvelope(target);
+  // Real ledger lines nest the envelope one level down: {type:'result.stored', result:{envelope:{...}}}.
+  // Handle that shape first, then the flat result, then a bare envelope record.
+  let holder = null;
+  if (record?.result && typeof record.result === 'object' && record.result.envelope && typeof record.result.envelope === 'object') holder = { parent: record.result, key: 'envelope' };
+  else if (record?.result && typeof record.result === 'object') holder = { parent: record, key: 'result' };
+  else if (record?.envelope && typeof record.envelope === 'object') holder = { parent: record, key: 'envelope' };
+  if (holder === null) return { changed: false, line };
+  const { projected, dropped } = projectResultEnvelope(holder.parent[holder.key]);
   if (dropped.length === 0) return { changed: false, line };
-  if (record.result !== undefined) record.result = projected; else record.envelope = projected;
+  holder.parent[holder.key] = projected;
   record.projection = { dropped, at: new Date().toISOString() };
   return { changed: true, line: JSON.stringify(record) };
 }

package/src/relay/purge-blobs.mjs

@@ -0,0 +1,137 @@
+/**
+ * Relay blob purge: retire the data-plane store that old relays (1.6.4) still accepted.
+ *
+ * Layout note (measured on a real relay): blobs live at `<state>/blobs/<aa>/<sha256>`, i.e. ONE
+ * level of fan-out directories, and `blob-sessions/` may hold in-flight chunks. The earlier
+ * scrubBlobs() only looked at the top level, which is why a dry run against a real state directory
+ * reported zero files while the relay was still holding megabytes.
+ *
+ * Rules:
+ *   - dry-run by default; `apply` is required to touch anything
+ *   - delete or quarantine (move outside the relay state tree); a manifest of what was removed is
+ *     written next to the quarantine so an audit can prove what existed
+ *   - after the purge the directory is re-listed; a non-empty result is `BLOBS_REAPPEARED`
+ *     (that means something is still writing, e.g. an old relay that was not retired first)
+ *   - stop the relay before applying: it keeps appending while running
+ */
+import {
+  existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join, relative } from 'node:path';
+
+export const PURGE_CODES = Object.freeze({
+  MISSING: 'BLOBS_MISSING',
+  NOT_A_DIR: 'BLOBS_NOT_A_DIR',
+  REAPPEARED: 'BLOBS_REAPPEARED',
+  QUARANTINE_FAILED: 'QUARANTINE_FAILED',
+});
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
+/** Recursively list blob files (and in-flight session dirs when asked). */
+export function listBlobs(blobDir, { includeSessions = true } = {}) {
+  if (!existsSync(blobDir)) return { ok: false, code: PURGE_CODES.MISSING, files: [] };
+  if (!statSync(blobDir).isDirectory()) return { ok: false, code: PURGE_CODES.NOT_A_DIR, files: [] };
+  const files = [];
+  const walk = (dir) => {
+    for (const name of readdirSync(dir)) {
+      const path = join(dir, name);
+      const stat = statSync(path);
+      if (stat.isDirectory()) {
+        const rel = relative(blobDir, path).split('\\').join('/');
+        if (!includeSessions && rel.startsWith('blob-sessions')) continue;
+        walk(path);
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      files.push({ rel: relative(blobDir, path).split('\\').join('/'), size: stat.size });
+    }
+  };
+  walk(blobDir);
+  files.sort((a, b) => a.rel.localeCompare(b.rel));
+  return { ok: true, files };
+}
+
+/** Prune empty directories under `dir`, leaving `dir` itself in place. */
+function pruneEmpty(dir) {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) {
+      pruneEmpty(path);
+      if (readdirSync(path).length === 0) rmdirSync(path);
+    }
+  }
+}
+
+/**
+ * Purge the blob store.
+ *
+ * @param {string} blobDir `<state>/blobs`
+ * @param {{apply?: boolean, quarantineDir?: string|null, now?: number, includeSessions?: boolean}} [options]
+ */
+export function purgeBlobs(blobDir, options = {}) {
+  const listed = listBlobs(blobDir, { includeSessions: options.includeSessions !== false });
+  if (listed.ok !== true) return { ok: false, ...listed, exists: false, count: 0, bytes: 0 };
+  const files = listed.files;
+  const bytes = files.reduce((sum, file) => sum + file.size, 0);
+  const base = {
+    ok: true,
+    dir: blobDir,
+    exists: true,
+    count: files.length,
+    bytes,
+    sample: files.slice(0, 5).map((file) => file.rel),
+  };
+  if (options.apply !== true) return { ...base, dry_run: true, removed: 0, quarantined: 0 };
+  if (files.length === 0) return { ...base, dry_run: false, removed: 0, quarantined: 0, remaining: 0 };
+
+  const now = Number.isInteger(options.now) ? options.now : Date.now();
+  let quarantine = null;
+  let manifest = null;
+  if (typeof options.quarantineDir === 'string' && options.quarantineDir !== '') {
+    quarantine = join(options.quarantineDir, 'purge-' + now);
+    try {
+      for (const file of files) {
+        const target = join(quarantine, file.rel);
+        mkdirSync(dirname(target), { recursive: true });
+        renameSync(join(blobDir, file.rel), target);
+      }
+      manifest = join(quarantine, 'manifest.json');
+      writeFileSync(
+        manifest,
+        JSON.stringify(
+          {
+            at: new Date(now).toISOString(),
+            source: blobDir,
+            count: files.length,
+            bytes,
+            files: files.map((file) => ({ rel: file.rel, size: file.size, sha256: sha256(readFileSync(join(quarantine, file.rel))) })),
+          },
+          null,
+          2,
+        ) + '\n',
+        'utf8',
+      );
+    } catch (error) {
+      return { ...base, ok: false, code: PURGE_CODES.QUARANTINE_FAILED, error: String(error) };
+    }
+  } else {
+    for (const file of files) unlinkSync(join(blobDir, file.rel));
+  }
+  pruneEmpty(blobDir);
+
+  const remaining = listBlobs(blobDir).files;
+  const result = {
+    ...base,
+    dry_run: false,
+    removed: quarantine === null ? files.length : 0,
+    quarantined: quarantine === null ? 0 : files.length,
+    quarantine,
+    manifest,
+    remaining: remaining.length,
+    remaining_bytes: remaining.reduce((sum, file) => sum + file.size, 0),
+  };
+  if (remaining.length > 0) return { ...result, ok: false, code: PURGE_CODES.REAPPEARED };
+  return result;
+}

package/src/relay/repair-ledger.mjs

@@ -0,0 +1,165 @@
+/**
+ * Relay ledger repair: quarantine corrupt JSONL lines and atomically rewrite the rest.
+ *
+ * The relay's ledger is append-only (`<state>/ledger.jsonl`, one JSON object per line). A crash
+ * during an append can leave a torn line, and `Persistence` reports it rather than guessing:
+ * `ledger_lines_skipped` and a `warn(ledger.jsonl, ...)` entry survive every restart. This tool is
+ * the operator half of that report.
+ *
+ * Rules (deliberately conservative):
+ *   - a line that `JSON.parse` rejects is NEVER repaired by guessing; it is moved to a quarantine
+ *     file byte for byte, so the operator can inspect what was lost
+ *   - dry-run is the default; writing needs `apply: true`
+ *   - the original is copied to `<file>.bak-<timestamp>` (mode 0600) before the atomic rename
+ *   - the read is bracketed by `stat`: if the relay appended while we were reading, the tool
+ *     refuses with `LEDGER_BUSY` instead of silently dropping the new line
+ */
+import {
+  chmodSync,
+  closeSync,
+  copyFileSync,
+  existsSync,
+  fsyncSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+
+export const LEDGER_REPAIR_CODES = Object.freeze({
+  MISSING: 'LEDGER_MISSING',
+  BUSY: 'LEDGER_BUSY',
+  NOT_A_FILE: 'LEDGER_NOT_A_FILE',
+  WRITE_FAILED: 'LEDGER_WRITE_FAILED',
+});
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
+/** Write bytes and fsync them, so a rename cannot publish a page the disk has not seen. */
+function writeDurable(file, data, mode) {
+  const fd = openSync(file, 'w', mode);
+  try {
+    writeSync(fd, data);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Inspect (and optionally repair) a ledger file.
+ *
+ * @param {string} file absolute or relative path to `ledger.jsonl`
+ * @param {{apply?: boolean, now?: number, quarantineDir?: string}} [options]
+ * @returns {object} report; `ok:false` carries one of {@link LEDGER_REPAIR_CODES}
+ */
+export function repairLedger(file, options = {}) {
+  if (typeof file !== 'string' || file === '') throw new TypeError('repairLedger: a file path is required');
+  if (!existsSync(file)) return { ok: false, code: LEDGER_REPAIR_CODES.MISSING, path: file };
+  const before = statSync(file);
+  if (!before.isFile()) return { ok: false, code: LEDGER_REPAIR_CODES.NOT_A_FILE, path: file };
+
+  const raw = readFileSync(file);
+  const afterRead = statSync(file);
+  if (afterRead.mtimeMs !== before.mtimeMs || afterRead.size !== before.size) {
+    return { ok: false, code: LEDGER_REPAIR_CODES.BUSY, path: file, size: before.size, size_now: afterRead.size };
+  }
+
+  const text = raw.toString('utf8');
+  const hasFinalNewline = text.endsWith('\n');
+  const lines = text.split('\n');
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+
+  const valid = [];
+  const invalid = [];
+  lines.forEach((line, index) => {
+    if (line.trim() === '') {
+      // A blank line carries no record; dropping it changes no replay outcome.
+      invalid.push({ line: index + 1, reason: 'EMPTY_LINE', raw: line });
+      return;
+    }
+    try {
+      JSON.parse(line);
+      valid.push(line);
+    } catch (error) {
+      invalid.push({ line: index + 1, reason: error instanceof Error ? error.message : String(error), raw: line });
+    }
+  });
+
+  const changed = invalid.length > 0;
+  const base = {
+    ok: true,
+    path: file,
+    bytes_before: raw.length,
+    sha256_before: sha256(raw),
+    total_lines: lines.length,
+    valid_lines: valid.length,
+    invalid_count: invalid.length,
+    invalid: invalid.map((entry) => ({ line: entry.line, reason: entry.reason })),
+    changed,
+  };
+  if (!changed) return { ...base, dry_run: options.apply !== true, written: false };
+  if (options.apply !== true) {
+    return {
+      ...base,
+      dry_run: true,
+      written: false,
+      note: 'dry run: pass apply:true (CLI --apply) to quarantine the invalid lines and rewrite the file',
+    };
+  }
+
+  const now = Number.isInteger(options.now) ? options.now : Date.now();
+  const backup = `${file}.bak-${now}`;
+  try {
+    copyFileSync(file, backup);
+    chmodSync(backup, 0o600);
+  } catch (error) {
+    return { ...base, dry_run: false, written: false, ok: false, code: LEDGER_REPAIR_CODES.WRITE_FAILED, error: String(error) };
+  }
+
+  const quarantineDir = options.quarantineDir ?? dirname(file);
+  const quarantine = join(quarantineDir, `ledger.corrupt-${now}.jsonl`);
+  try {
+    writeDurable(quarantine, Buffer.from(invalid.map((entry) => entry.raw).join('\n') + '\n', 'utf8'), 0o600);
+  } catch (error) {
+    return { ...base, dry_run: false, written: false, ok: false, code: LEDGER_REPAIR_CODES.WRITE_FAILED, error: String(error), backup };
+  }
+
+  const next = valid.length === 0 ? '' : valid.join('\n') + (hasFinalNewline ? '\n' : '');
+  const tmp = `${file}.repair-${now}.tmp`;
+  try {
+    writeDurable(tmp, Buffer.from(next, 'utf8'), 0o600);
+    renameSync(tmp, file);
+  } catch (error) {
+    try { if (existsSync(tmp)) unlinkSync(tmp); } catch { /* best effort */ }
+    return { ...base, dry_run: false, written: false, ok: false, code: LEDGER_REPAIR_CODES.WRITE_FAILED, error: String(error), backup, quarantine };
+  }
+
+  const written = readFileSync(file);
+  const reread = written.toString('utf8').split('\n').filter((line) => line.trim() !== '');
+  for (const line of reread) {
+    try { JSON.parse(line); } catch (error) {
+      return {
+        ...base, dry_run: false, written: true, backup, quarantine,
+        ok: false, code: LEDGER_REPAIR_CODES.WRITE_FAILED,
+        error: 'post-write verification failed: ' + (error instanceof Error ? error.message : String(error)),
+      };
+    }
+  }
+
+  return {
+    ...base,
+    dry_run: false,
+    written: true,
+    backup,
+    quarantine,
+    bytes_after: written.length,
+    sha256_after: sha256(written),
+    lines_after: reread.length,
+    verified: true,
+  };
+}

package/src/relay/scrub.mjs

@@ -8,25 +8,11 @@ import {
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 
+import { projectLedgerLine } from './p0-projection.mjs';
+
 export const LEDGER_CONTENT_FIELDS = ['stdout_head', 'stdout_tail', 'stderr_head', 'stderr_tail', 'command_argv', 'pipeline_hash_material', 'changed_files'];
 const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
 
-function projectLedgerLine(line) {
-  let record;
-  try { record = JSON.parse(line); } catch { return { changed: false, line }; }
-  const result = record?.result ?? record?.envelope ?? null;
-  if (result === null || typeof result !== 'object') return { changed: false, line };
-  let changed = false;
-  for (const field of LEDGER_CONTENT_FIELDS) {
-    if (field in result) { delete result[field]; changed = true; }
-  }
-  if ('patch_sha256' in result) { result.patch_sha256 = null; changed = true; }
-  if ('workspace' in result && typeof result.workspace === 'object' && result.workspace !== null) {
-    if ('changed_files' in result.workspace) { delete result.workspace.changed_files; changed = true; }
-    if ('patch_sha256' in result.workspace) { result.workspace.patch_sha256 = null; changed = true; }
-  }
-  return { changed, line: changed ? JSON.stringify(record) : line };
-}
 
 /** 清理 ledger：默认 dry-run；apply 时备份 .bak-<ts> 后原子替换。 */
 export function scrubLedger(ledgerPath, { dryRun = true, now = Date.now() } = {}) {
@@ -73,11 +59,15 @@ export function scanForContent(rootDir, markers = []) {
   const hits = [];
   const walk = (dir) => {
     for (const name of readdirSync(dir)) {
+      // Backups/temporaries are not live state: they hold the bytes the scrub just moved out.
+      if (/\.bak-|\.tmp-|\.corrupt-/.test(name)) continue;
       const path = join(dir, name);
       const stat = statSync(path);
       if (stat.isDirectory()) { walk(path); continue; }
       if (stat.size > 32 * 1024 * 1024) continue;
-      const text = readFileSync(path, 'utf8');
+      // The projection metadata names the dropped fields; scanning it for those names would report
+      // the scrub itself as a leak, so it is removed before the marker check.
+      const text = readFileSync(path, 'utf8').replace(/"projection"\s*:\s*\{[^{}]*\}/g, '');
       for (const field of LEDGER_CONTENT_FIELDS) {
         if (text.includes('"' + field + '"')) hits.push({ file: path, marker: field });
       }