chainlesschain 0.162.166 → 0.162.167

package/src/harness/session-mirror.js

@@ -26,10 +26,20 @@ import {
   readFileSync,
   writeFileSync,
   readdirSync,
+  unlinkSync,
 } from "node:fs";
+import {
+  scryptSync,
+  randomBytes,
+  createCipheriv,
+  createDecipheriv,
+} from "node:crypto";
 import { join, basename } from "node:path";
 import { isUnsafeSessionId } from "./jsonl-session-store.js";
 
+const CIPHER_VERSION = 1;
+const CIPHER_ALGO = "aes-256-gcm";
+
 /**
  * Build a mirror driver from config. `config.kind` selects the driver:
  *   { kind: "fs",   dir: "/mnt/backup/sessions" }
@@ -39,15 +49,193 @@ import { isUnsafeSessionId } from "./jsonl-session-store.js";
 export function createMirror(config = {}, deps = {}) {
   const kind = String(config.kind || config.type || "none").toLowerCase();
   if (!kind || kind === "none") return null;
+  let driver;
   if (kind === "fs" || kind === "dir" || kind === "directory") {
-    return createFsMirror(config, deps);
+    driver = createFsMirror(config, deps);
+  } else if (kind === "http" || kind === "api") {
+    driver = createHttpMirror(config, deps);
+  } else {
+    throw new Error(
+      `unknown session mirror kind "${kind}" (use fs | http, or wire an s3/webdav/redis driver)`,
+    );
   }
-  if (kind === "http" || kind === "api") {
-    return createHttpMirror(config, deps);
+  // When `encryption` (a passphrase) is configured, wrap the driver so bytes are
+  // AES-256-GCM encrypted at rest — the mirror target only ever holds ciphertext,
+  // and only the run-time passphrase can decrypt it. Absent → raw bytes (the
+  // prior behaviour, byte-for-byte).
+  const enc = config.encryption || config.encrypt;
+  if (enc && (enc.passphrase || enc.secret)) {
+    return wrapEncryptedMirror(driver, createMirrorCipher(enc, deps));
   }
-  throw new Error(
-    `unknown session mirror kind "${kind}" (use fs | http, or wire an s3/webdav/redis driver)`,
-  );
+  return driver;
+}
+
+/**
+ * Passphrase-based AES-256-GCM cipher for mirrored session bytes. scrypt derives
+ * a 256-bit key from the passphrase + a per-record random salt; a random 12-byte
+ * nonce and the GCM tag give confidentiality + integrity (a tampered ciphertext
+ * fails to decrypt). Each envelope is self-describing JSON — `{ v, alg, keyId,
+ * salt, nonce, tag, ct }`, all base64url — carrying `keyId` so key ROTATION can
+ * tell old ciphertext from new. No secret is ever stored; only the passphrase
+ * supplied at run time can read it. `randomBytes`/`scryptSync` are injectable so
+ * round-trips are unit-testable deterministically.
+ */
+export function createMirrorCipher(config = {}, deps = {}) {
+  const passphrase = config.passphrase || config.secret;
+  if (!passphrase) throw new Error("mirror encryption requires a `passphrase`");
+  const keyId = String(config.keyId || "default");
+  const _randomBytes = deps.randomBytes || randomBytes;
+  const _scrypt = deps.scryptSync || scryptSync;
+  const deriveKey = (salt) => _scrypt(String(passphrase), salt, 32);
+
+  return {
+    keyId,
+    encrypt(bytes) {
+      const salt = Buffer.from(_randomBytes(16));
+      const nonce = Buffer.from(_randomBytes(12));
+      const cipher = createCipheriv(CIPHER_ALGO, deriveKey(salt), nonce);
+      const ct = Buffer.concat([
+        cipher.update(Buffer.from(bytes, "utf-8")),
+        cipher.final(),
+      ]);
+      return JSON.stringify({
+        v: CIPHER_VERSION,
+        alg: CIPHER_ALGO,
+        keyId,
+        salt: salt.toString("base64url"),
+        nonce: nonce.toString("base64url"),
+        tag: cipher.getAuthTag().toString("base64url"),
+        ct: ct.toString("base64url"),
+      });
+    },
+    decrypt(envelope) {
+      let e;
+      try {
+        e = typeof envelope === "string" ? JSON.parse(envelope) : envelope;
+      } catch {
+        throw new Error("mirror ciphertext is not a valid envelope");
+      }
+      if (!e || e.v !== CIPHER_VERSION || e.alg !== CIPHER_ALGO) {
+        throw new Error("unsupported mirror ciphertext envelope");
+      }
+      const key = deriveKey(Buffer.from(e.salt, "base64url"));
+      const decipher = createDecipheriv(
+        CIPHER_ALGO,
+        key,
+        Buffer.from(e.nonce, "base64url"),
+      );
+      decipher.setAuthTag(Buffer.from(e.tag, "base64url"));
+      const pt = Buffer.concat([
+        decipher.update(Buffer.from(e.ct, "base64url")),
+        decipher.final(),
+      ]);
+      return pt.toString("utf-8");
+    },
+    /** Read an envelope's keyId without decrypting (rotation bookkeeping). */
+    envelopeKeyId(envelope) {
+      try {
+        const e =
+          typeof envelope === "string" ? JSON.parse(envelope) : envelope;
+        return e && e.keyId != null ? String(e.keyId) : null;
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Wrap a driver so push encrypts and pull decrypts transparently, keeping the
+ * raw driver reachable as `.raw` (key rotation drives the raw driver with two
+ * ciphers). list/delete pass through — ids stay plaintext in the target (they
+ * are random handles, not content).
+ */
+function wrapEncryptedMirror(driver, cipher) {
+  return {
+    ...driver,
+    encrypted: true,
+    keyId: cipher.keyId,
+    raw: driver,
+    cipher,
+    async push(id, bytes) {
+      const enc = cipher.encrypt(bytes);
+      const r = await driver.push(id, enc);
+      return {
+        ...r,
+        bytes: Buffer.byteLength(bytes),
+        storedBytes: Buffer.byteLength(enc),
+        encrypted: true,
+      };
+    },
+    async pull(id) {
+      const raw = await driver.pull(id);
+      return raw == null ? null : cipher.decrypt(raw);
+    },
+  };
+}
+
+/**
+ * RETENTION: delete every mirror entry whose id is NOT in `keep` — the mirror is
+ * one-way derived from the local store, so retention = "hold only what the local
+ * source still keeps" (e.g. the ids `cc session list` still returns). Best-effort
+ * per id; returns what was deleted vs kept.
+ */
+export async function pruneMirror(mirror, { keep = [] } = {}) {
+  if (!mirror || typeof mirror.list !== "function") {
+    return { deleted: [], kept: [] };
+  }
+  const keepSet = new Set((keep || []).map(String));
+  const ids = (await mirror.list()) || [];
+  const deleted = [];
+  for (const id of ids) {
+    if (keepSet.has(String(id))) continue;
+    try {
+      await mirror.delete(id);
+      deleted.push(id);
+    } catch {
+      /* best-effort — a failed delete must not abort the prune */
+    }
+  }
+  return { deleted, kept: ids.filter((i) => keepSet.has(String(i))) };
+}
+
+/**
+ * KEY ROTATION: re-encrypt every mirrored session from the `from` cipher to the
+ * `to` cipher, in place. Drives the RAW driver (pass `mirror.raw` for an
+ * encrypted mirror) so it reads/writes ciphertext directly. Entries already at
+ * `to.keyId` are skipped (idempotent re-runs); an entry that fails to decrypt
+ * with `from` is reported, not silently dropped.
+ */
+export async function rotateMirrorKey(driver, { from, to } = {}) {
+  if (!driver || !from || !to) {
+    throw new Error("rotateMirrorKey requires (driver, { from, to })");
+  }
+  const ids = (await driver.list()) || [];
+  const rotated = [];
+  const skipped = [];
+  const failed = [];
+  for (const id of ids) {
+    let raw;
+    try {
+      raw = await driver.pull(id);
+    } catch (e) {
+      failed.push({ id, error: e.message });
+      continue;
+    }
+    if (raw == null) continue;
+    if (from.envelopeKeyId(raw) === to.keyId) {
+      skipped.push(id);
+      continue;
+    }
+    try {
+      const plain = from.decrypt(raw);
+      await driver.push(id, to.encrypt(plain));
+      rotated.push(id);
+    } catch (e) {
+      failed.push({ id, error: e.message });
+    }
+  }
+  return { rotated, skipped, failed, keyId: to.keyId };
 }
 
 /** Directory mirror — the reference driver. */
@@ -59,6 +247,7 @@ export function createFsMirror(config = {}, deps = {}) {
   const _readFileSync = deps.readFileSync || readFileSync;
   const _writeFileSync = deps.writeFileSync || writeFileSync;
   const _readdirSync = deps.readdirSync || readdirSync;
+  const _unlinkSync = deps.unlinkSync || unlinkSync;
 
   const ensure = () => {
     if (!_existsSync(dir)) _mkdirSync(dir, { recursive: true });
@@ -88,6 +277,12 @@ export function createFsMirror(config = {}, deps = {}) {
         .filter((f) => f.endsWith(".jsonl"))
         .map((f) => basename(f, ".jsonl"));
     },
+    async delete(id) {
+      const f = fileFor(id);
+      if (!_existsSync(f)) return { id, deleted: false };
+      _unlinkSync(f);
+      return { id, deleted: true };
+    },
   };
 }
 
@@ -138,5 +333,16 @@ export function createHttpMirror(config = {}, deps = {}) {
         .map((x) => (typeof x === "string" ? x : x?.id))
         .filter(Boolean);
     },
+    async delete(id) {
+      const res = await doFetch(`${baseUrl}/sessions/${guard(id)}`, {
+        method: "DELETE",
+        headers: headers(),
+      });
+      // 404 = already gone → idempotent success, not an error.
+      if (!res.ok && res.status !== 404) {
+        throw new Error(`mirror DELETE ${id} → HTTP ${res.status}`);
+      }
+      return { id, deleted: res.ok };
+    },
   };
 }

package/src/lib/async-hook-queue.cjs

@@ -0,0 +1,288 @@
+"use strict";
+
+/**
+ * async-hook-queue — a small, best-effort, PERSISTENT queue for async settings
+ * hooks that opted into `asyncRewake: true` and finished in a FAILURE state.
+ *
+ * Why: AsyncHookSupervisor runs `async: true` hooks fire-and-forget and keeps
+ * their results ONLY in memory (`_results`/`_rewakes`). A rewake is the one
+ * actionable signal it produces — "a background check (e.g. `npm test`) failed,
+ * re-engage the agent with the error". If the process dies (crash, kill,
+ * hard exit) after the rewake was recorded but BEFORE the turn loop drained and
+ * surfaced it, that signal is silently lost: the next `--resume` of the same
+ * session has no idea a background check failed.
+ *
+ * This module gives the supervisor a durable place to park undrained rewakes,
+ * keyed by session id, so `--resume <id>` can recover them. The gap's P2 "Hooks"
+ * item calls for an "async hook 持久队列"; this is the reliability half of it
+ * (paired with the already-shipped `allowManagedHooksOnly`).
+ *
+ * Lifecycle (rewake-scoped on purpose — non-rewake results are informational and
+ * cheap to lose; rewakes are the failure signal worth surviving a crash):
+ *   record a rewake  → appendRewake()  (immediate write, survives even SIGKILL)
+ *   drain / surface  → removeRewakes() (consumed → no longer pending)
+ *   resume a session → takePending()   (load + clear that session's bucket)
+ *
+ * Design mirrors hook-stats-store.cjs: pure folds (no clock/RNG/fs inside), an
+ * injected fs for load/save, atomic tmp+rename writes, and per-session +
+ * per-session-count bounds so a runaway producer never grows the file without
+ * bound. Every path is best-effort — a corrupt/io-failed queue file must never
+ * block a hook or the agent.
+ */
+
+const os = require("node:os");
+const path = require("node:path");
+const fsDefault = require("node:fs");
+
+const CONFIG_DIR_NAME = ".chainlesschain";
+const MAX_RECORDS_PER_SESSION = 200; // drop oldest-recorded beyond this
+const MAX_SESSIONS = 100; // bound distinct session buckets
+const DEFAULT_STALE_MS = 7 * 24 * 60 * 60 * 1000; // prune buckets untouched >7d
+
+/** Default on-disk location (matches the ESM getHomeDir() layout). */
+function defaultAsyncHookQueuePath() {
+  return path.join(os.homedir(), CONFIG_DIR_NAME, "async-hook-queue.json");
+}
+
+/**
+ * Stable de-dupe key for one rewake record. Two records with the same
+ * (command, event, ts, ms, exitCode) are treated as the same pending item —
+ * enough to make removeRewakes() idempotent and appendRewake() not double-store
+ * a record that a caller replays. Pure, no hashing needed.
+ */
+function queueEntryKey(rec) {
+  if (!rec || typeof rec !== "object") return "";
+  return [
+    String(rec.command || ""),
+    String(rec.event || ""),
+    String(rec.ts ?? ""),
+    String(rec.ms ?? ""),
+    String(rec.exitCode ?? ""),
+  ].join("|");
+}
+
+/** Normalize a raw supervisor record into a compact stored rewake entry. */
+function normalizeRecord(rec) {
+  if (!rec || typeof rec !== "object") return null;
+  const command = String(rec.command || "").trim();
+  if (!command) return null;
+  return {
+    command,
+    event: rec.event ?? null,
+    exitCode: rec.exitCode ?? null,
+    error: rec.error ? String(rec.error) : null,
+    additionalContext: rec.additionalContext
+      ? String(rec.additionalContext)
+      : null,
+    blocked: !!rec.blocked,
+    ts: Number.isFinite(Number(rec.ts)) ? Number(rec.ts) : 0,
+    ms: Number.isFinite(Number(rec.ms)) ? Number(rec.ms) : 0,
+  };
+}
+
+/** Fresh empty queue. */
+function emptyQueue() {
+  return { sessions: {} };
+}
+
+/** Coerce an arbitrary parsed value into the queue shape. */
+function coerceQueue(parsed) {
+  if (
+    !parsed ||
+    typeof parsed !== "object" ||
+    typeof parsed.sessions !== "object" ||
+    !parsed.sessions
+  ) {
+    return emptyQueue();
+  }
+  return { sessions: parsed.sessions };
+}
+
+/**
+ * PURE fold: append `records` into `queue` under `sessionId` (mutates + returns
+ * `queue`). De-dupes by queueEntryKey, keeps the most-recent MAX_RECORDS_PER_
+ * SESSION, and stamps the bucket's `updatedAt` for stale pruning. `now` is
+ * supplied by the caller so the fold stays clock-free.
+ */
+function foldAppend(queue, sessionId, records, now) {
+  if (!queue || typeof queue !== "object") queue = emptyQueue();
+  if (!queue.sessions) queue.sessions = {};
+  const id = String(sessionId || "").trim();
+  if (!id) return queue;
+  const list = Array.isArray(records) ? records : [records];
+  const bucket = queue.sessions[id] || { records: [], updatedAt: 0 };
+  const seen = new Set(bucket.records.map(queueEntryKey));
+  for (const raw of list) {
+    const rec = normalizeRecord(raw);
+    if (!rec) continue;
+    const key = queueEntryKey(rec);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    bucket.records.push(rec);
+  }
+  // Never persist an empty bucket (all-invalid input, or nothing new for a
+  // session that had none) — it would just be dead weight in the file.
+  if (bucket.records.length === 0) return queue;
+  if (bucket.records.length > MAX_RECORDS_PER_SESSION) {
+    bucket.records = bucket.records.slice(
+      bucket.records.length - MAX_RECORDS_PER_SESSION,
+    );
+  }
+  bucket.updatedAt = Number.isFinite(Number(now))
+    ? Number(now)
+    : bucket.updatedAt;
+  queue.sessions[id] = bucket;
+  boundSessions(queue);
+  return queue;
+}
+
+/**
+ * PURE fold: remove `records` (by key) from `sessionId`'s bucket (mutates +
+ * returns `queue`). Empties → the bucket is deleted so the file self-cleans.
+ */
+function foldRemove(queue, sessionId, records) {
+  if (!queue || !queue.sessions) return queue || emptyQueue();
+  const id = String(sessionId || "").trim();
+  const bucket = queue.sessions[id];
+  if (!bucket) return queue;
+  const kill = new Set(
+    (Array.isArray(records) ? records : [records])
+      .map(normalizeRecord)
+      .filter(Boolean)
+      .map(queueEntryKey),
+  );
+  bucket.records = bucket.records.filter((r) => !kill.has(queueEntryKey(r)));
+  if (bucket.records.length === 0) delete queue.sessions[id];
+  return queue;
+}
+
+/** Keep only the MAX_SESSIONS most-recently-updated buckets. */
+function boundSessions(queue) {
+  if (!queue || !queue.sessions) return queue;
+  const ids = Object.keys(queue.sessions);
+  if (ids.length <= MAX_SESSIONS) return queue;
+  ids
+    .sort(
+      (a, b) =>
+        (queue.sessions[a].updatedAt || 0) - (queue.sessions[b].updatedAt || 0),
+    )
+    .slice(0, ids.length - MAX_SESSIONS)
+    .forEach((id) => delete queue.sessions[id]);
+  return queue;
+}
+
+/**
+ * PURE fold: drop buckets whose `updatedAt` is older than `now - staleMs`
+ * (mutates + returns `queue`). Guards the file against unbounded growth from
+ * sessions that were never resumed to drain their pending rewakes.
+ */
+function foldPruneStale(queue, now, staleMs = DEFAULT_STALE_MS) {
+  if (!queue || !queue.sessions) return queue || emptyQueue();
+  const cutoff = (Number.isFinite(Number(now)) ? Number(now) : 0) - staleMs;
+  for (const [id, bucket] of Object.entries(queue.sessions)) {
+    if (!bucket || (bucket.updatedAt || 0) < cutoff) delete queue.sessions[id];
+  }
+  return queue;
+}
+
+/** Best-effort read of the on-disk queue (→ empty on missing/corrupt). */
+function loadQueue(file = defaultAsyncHookQueuePath(), fs = fsDefault) {
+  try {
+    if (!fs.existsSync(file)) return emptyQueue();
+    return coerceQueue(JSON.parse(fs.readFileSync(file, "utf-8")));
+  } catch {
+    return emptyQueue();
+  }
+}
+
+/** Best-effort atomic write (tmp + rename). Never throws. */
+function saveQueue(queue, file = defaultAsyncHookQueuePath(), fs = fsDefault) {
+  try {
+    const dir = path.dirname(file);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(queue), "utf-8");
+    fs.renameSync(tmp, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Append one/more rewake records for `sessionId` and write back. Best-effort;
+ * returns true on a successful write. `now` defaults to Date.now() (the only
+ * non-pure entry point besides load/save).
+ */
+function appendRewake(
+  { sessionId, records, now } = {},
+  file = defaultAsyncHookQueuePath(),
+  fs = fsDefault,
+) {
+  const id = String(sessionId || "").trim();
+  if (!id || records == null) return false;
+  const at = Number.isFinite(Number(now)) ? Number(now) : Date.now();
+  const queue = foldAppend(loadQueue(file, fs), id, records, at);
+  return saveQueue(queue, file, fs);
+}
+
+/**
+ * Remove (mark consumed) rewake records for `sessionId` and write back.
+ * Best-effort; a no-op when nothing matches.
+ */
+function removeRewakes(
+  { sessionId, records } = {},
+  file = defaultAsyncHookQueuePath(),
+  fs = fsDefault,
+) {
+  const id = String(sessionId || "").trim();
+  if (!id || records == null) return false;
+  const queue = foldRemove(loadQueue(file, fs), id, records);
+  return saveQueue(queue, file, fs);
+}
+
+/**
+ * Load a session's pending rewakes AND clear its bucket (also prunes stale
+ * buckets while we hold the file). Returns the recovered records (possibly []).
+ * The single call a resuming runner makes on startup.
+ */
+function takePending(
+  { sessionId, now, staleMs } = {},
+  file = defaultAsyncHookQueuePath(),
+  fs = fsDefault,
+) {
+  const id = String(sessionId || "").trim();
+  if (!id) return [];
+  const at = Number.isFinite(Number(now)) ? Number(now) : Date.now();
+  let queue = loadQueue(file, fs);
+  const bucket = queue.sessions[id];
+  const recovered =
+    bucket && Array.isArray(bucket.records) ? bucket.records : [];
+  if (bucket) delete queue.sessions[id];
+  queue = foldPruneStale(queue, at, staleMs);
+  // Only rewrite if we actually changed something (recovered a bucket or the
+  // prune dropped one) — a pure read of an empty/unrelated queue leaves the
+  // file byte-unchanged.
+  if (recovered.length > 0 || bucket) saveQueue(queue, file, fs);
+  return recovered;
+}
+
+module.exports = {
+  defaultAsyncHookQueuePath,
+  queueEntryKey,
+  normalizeRecord,
+  emptyQueue,
+  coerceQueue,
+  foldAppend,
+  foldRemove,
+  foldPruneStale,
+  boundSessions,
+  loadQueue,
+  saveQueue,
+  appendRewake,
+  removeRewakes,
+  takePending,
+  MAX_RECORDS_PER_SESSION,
+  MAX_SESSIONS,
+  DEFAULT_STALE_MS,
+};

package/src/lib/async-hook-supervisor.cjs

@@ -73,6 +73,22 @@ class AsyncHookSupervisor {
         ? this._statsStore.defaultHookStatsPath()
         : null);
     this._statsFs = opts.statsFs || null; // injected fs for tests
+    // Persistent rewake queue (opt-in). A rewake — an async check that OPTED IN
+    // and finished in a FAILURE state — is the one actionable signal this
+    // supervisor produces, but it lives only in `_rewakes` until the turn loop
+    // drains it. If the process dies in that window the failure is lost. When a
+    // `sessionId` + `persistQueue` (or an explicit `queuePath`) are supplied,
+    // each rewake is durably parked keyed by session so `--resume` can recover
+    // it; it's removed again the moment the run drains it. Disabled (no writes,
+    // byte-unchanged) when either is absent — mirrors the stats-store opt-in.
+    this._queueStore = opts.queueStore || require("./async-hook-queue.cjs");
+    this._queueSessionId = opts.sessionId ? String(opts.sessionId) : null;
+    this._queuePath =
+      opts.queuePath ||
+      (opts.persistQueue === true
+        ? this._queueStore.defaultAsyncHookQueuePath()
+        : null);
+    this._queueFs = opts.queueFs || null; // injected fs for tests
     // The exit reaper is installed LAZILY (on first spawn), not in the ctor:
     // a supervisor that never dispatches a hook (or the many built in tests)
     // must not leave a permanent `process.once('exit')` listener behind —
@@ -359,6 +375,29 @@ class AsyncHookSupervisor {
     if (hook.asyncRewake && !rec.ok) {
       this._rewakes.push(rec);
       if (this._rewakes.length > RESULT_RING) this._rewakes.shift();
+      // Durably park it (opt-in) so a crash before the turn loop drains this
+      // rewake doesn't lose the failure signal. Immediate write, not deferred to
+      // stopAll — a rewake must survive even a hard exit that never runs stopAll.
+      this._persistRewake(rec);
+    }
+  }
+
+  /** True when a session id + queue location were both configured. */
+  _queueEnabled() {
+    return !!(this._queueSessionId && this._queuePath);
+  }
+
+  /** Best-effort durable append of one rewake record. Never throws. */
+  _persistRewake(rec) {
+    if (!this._queueEnabled()) return;
+    try {
+      this._queueStore.appendRewake(
+        { sessionId: this._queueSessionId, records: [rec], now: rec.ts },
+        this._queuePath,
+        this._queueFs || undefined,
+      );
+    } catch {
+      /* queue is best-effort */
     }
   }
 
@@ -377,6 +416,19 @@ class AsyncHookSupervisor {
   drainRewakes() {
     const r = this._rewakes;
     this._rewakes = [];
+    // The run has now consumed these rewakes (it will surface / re-engage on
+    // them), so they no longer need to survive a crash — drop the durable copies.
+    if (r.length > 0 && this._queueEnabled()) {
+      try {
+        this._queueStore.removeRewakes(
+          { sessionId: this._queueSessionId, records: r },
+          this._queuePath,
+          this._queueFs || undefined,
+        );
+      } catch {
+        /* queue is best-effort */
+      }
+    }
     return r;
   }