chainlesschain 0.162.163 → 0.162.165

package/src/lib/hook-stats-store.cjs

@@ -0,0 +1,197 @@
+"use strict";
+
+/**
+ * hook-stats-store — a small, best-effort, cross-session RELIABILITY aggregate
+ * for async settings hooks, so `cc doctor` (a separate process) can surface
+ * hooks that have been slow, repeatedly failing, or circuit-broken. The gap's
+ * P2 "Doctor" wants "慢/熔断 Hook" health, but that state otherwise lives only
+ * in-memory in AsyncHookSupervisor for the life of one process.
+ *
+ * Design: the supervisor folds each completed hook run into an in-memory
+ * aggregate (bounded by the number of DISTINCT hooks, not runs) and persists it
+ * once on stopAll() — NOT per run — so there is no write amplification on the
+ * hook hot path. Persistence merges with whatever is already on disk, so counts
+ * accumulate across sessions. Reads/writes are best-effort (a corrupt/ío-failed
+ * file never blocks a hook or the agent).
+ *
+ * Pure aggregation (no clock/RNG/fs in the fold) so it's fully unit-testable;
+ * load/save take an injected fs. The default circuit threshold mirrors the
+ * doctor evaluator's `hookFailureThreshold`.
+ */
+
+const os = require("node:os");
+const path = require("node:path");
+const fsDefault = require("node:fs");
+
+const MAX_HOOKS = 200; // bound distinct-hook entries; drop least-recently-run
+const DEFAULT_CIRCUIT_THRESHOLD = 3;
+const CONFIG_DIR_NAME = ".chainlesschain";
+
+/** Stable per-hook id from its (event, command). */
+function hookKey(command, event) {
+  return `${event || "*"}::${String(command || "").trim()}`;
+}
+
+/** Default on-disk location (matches the ESM getHomeDir() layout). */
+function defaultHookStatsPath() {
+  return path.join(os.homedir(), CONFIG_DIR_NAME, "hook-stats.json");
+}
+
+/** Fresh empty aggregate map. */
+function emptyStats() {
+  return {};
+}
+
+/**
+ * Fold ONE completed run into the aggregate (mutates + returns `stats`). Pure:
+ * `now`/`ok`/`ms` are supplied by the caller. `consecutiveFailures` resets on
+ * any success — the circuit signal is "N failures in a row", not lifetime.
+ */
+function aggregateRun(stats, { command, event, ok, ms, now }) {
+  if (!stats || typeof stats !== "object") stats = {};
+  const id = hookKey(command, event);
+  const dur = Number.isFinite(Number(ms)) ? Number(ms) : 0;
+  const at = Number.isFinite(Number(now)) ? Number(now) : 0;
+  const e = stats[id] || {
+    id,
+    command: command || "",
+    event: event || null,
+    runs: 0,
+    failures: 0,
+    consecutiveFailures: 0,
+    lastFailureAt: null,
+    totalMs: 0,
+    maxMs: 0,
+    lastRunAt: 0,
+  };
+  e.runs += 1;
+  e.totalMs += dur;
+  if (dur > e.maxMs) e.maxMs = dur;
+  if (at > e.lastRunAt) e.lastRunAt = at;
+  if (ok === true) {
+    e.consecutiveFailures = 0;
+  } else {
+    e.failures += 1;
+    e.consecutiveFailures += 1;
+    e.lastFailureAt = at;
+  }
+  stats[id] = e;
+  boundStats(stats);
+  return stats;
+}
+
+/** Keep only the MAX_HOOKS most-recently-run entries. */
+function boundStats(stats) {
+  const keys = Object.keys(stats);
+  if (keys.length <= MAX_HOOKS) return stats;
+  keys
+    .sort((a, b) => (stats[a].lastRunAt || 0) - (stats[b].lastRunAt || 0))
+    .slice(0, keys.length - MAX_HOOKS)
+    .forEach((k) => delete stats[k]);
+  return stats;
+}
+
+/**
+ * Merge a session `delta` aggregate INTO a `base` aggregate (returns a new map).
+ * Counts add; maxMs/lastRunAt/lastFailureAt take the larger; the session's
+ * consecutiveFailures wins (it reflects the most recent streak).
+ */
+function mergeStats(base, delta) {
+  const out = {};
+  for (const src of [base, delta]) {
+    if (!src || typeof src !== "object") continue;
+    for (const [id, e] of Object.entries(src)) {
+      if (!e || typeof e !== "object") continue;
+      const cur = out[id];
+      if (!cur) {
+        out[id] = { ...e };
+        continue;
+      }
+      cur.runs += e.runs || 0;
+      cur.failures += e.failures || 0;
+      cur.totalMs += e.totalMs || 0;
+      cur.maxMs = Math.max(cur.maxMs || 0, e.maxMs || 0);
+      cur.lastRunAt = Math.max(cur.lastRunAt || 0, e.lastRunAt || 0);
+      cur.lastFailureAt =
+        Math.max(cur.lastFailureAt || 0, e.lastFailureAt || 0) || null;
+      // `delta` is applied second, so its streak (most recent) wins.
+      cur.consecutiveFailures =
+        e.consecutiveFailures ?? cur.consecutiveFailures;
+      cur.command = e.command || cur.command;
+      cur.event = e.event ?? cur.event;
+    }
+  }
+  return boundStats(out);
+}
+
+/**
+ * Shape the aggregate for the doctor `checkHooks` evaluator: id, lifetime
+ * failure count, average duration, and a derived circuit-open flag.
+ */
+function toCheckHooksInput(
+  stats,
+  { circuitThreshold = DEFAULT_CIRCUIT_THRESHOLD } = {},
+) {
+  if (!stats || typeof stats !== "object") return [];
+  return Object.values(stats).map((e) => ({
+    id: e.command || e.id,
+    event: e.event || null,
+    failures: e.failures || 0,
+    avgMs: e.runs > 0 ? e.totalMs / e.runs : 0,
+    circuitOpen: (e.consecutiveFailures || 0) >= circuitThreshold,
+  }));
+}
+
+/** Best-effort read of the on-disk aggregate (→ {} on missing/corrupt). */
+function loadHookStats(file = defaultHookStatsPath(), fs = fsDefault) {
+  try {
+    if (!fs.existsSync(file)) return {};
+    const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Best-effort atomic write (tmp + rename). Never throws. */
+function saveHookStats(stats, file = defaultHookStatsPath(), 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(stats), "utf-8");
+    fs.renameSync(tmp, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load the on-disk aggregate, fold in a session `delta`, and write it back.
+ * Best-effort end-to-end — the single call a supervisor makes on stopAll().
+ */
+function persistSessionStats(
+  delta,
+  file = defaultHookStatsPath(),
+  fs = fsDefault,
+) {
+  if (!delta || Object.keys(delta).length === 0) return false;
+  const merged = mergeStats(loadHookStats(file, fs), delta);
+  return saveHookStats(merged, file, fs);
+}
+
+module.exports = {
+  hookKey,
+  defaultHookStatsPath,
+  emptyStats,
+  aggregateRun,
+  mergeStats,
+  boundStats,
+  toCheckHooksInput,
+  loadHookStats,
+  saveHookStats,
+  persistSessionStats,
+  MAX_HOOKS,
+  DEFAULT_CIRCUIT_THRESHOLD,
+};

package/src/lib/idempotency.js

@@ -0,0 +1,109 @@
+/**
+ * Content-addressed idempotency — the P0-2 "Diff Apply 使用内容哈希/版本号" +
+ * "外部 API 优先使用 Provider Idempotency Key" primitives.
+ *
+ * All PURE (deterministic, no clock / RNG / I/O):
+ *
+ *  - `classifyEditReplay` — decide, from the CURRENT file content alone, whether
+ *    a literal edit still applies, has ALREADY landed (a resumed replay), or
+ *    genuinely conflicts. Lets a recovered worker skip an edit it already made
+ *    instead of double-applying it or erroring confusingly.
+ *  - `editIdempotencyKey` / `operationIdempotencyKey` — stable keys derived from
+ *    the operation and a canonicalized (order-independent) view of its args, so
+ *    a retry of the SAME effect yields the SAME key. An external provider that
+ *    honors `Idempotency-Key` then de-dupes a resumed replay; internally the key
+ *    tags each side-effect ledger op for duplicate detection.
+ */
+
+import { createHash } from "node:crypto";
+
+function sha256Hex(input) {
+  return createHash("sha256").update(String(input), "utf8").digest("hex");
+}
+
+/**
+ * Canonicalize a value so semantically-equal args hash identically regardless of
+ * key order. Arrays keep order (order is meaningful); object keys are sorted.
+ */
+function canonicalize(v) {
+  if (v == null) return null;
+  if (Array.isArray(v)) return v.map(canonicalize);
+  if (typeof v === "object") {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = canonicalize(v[k]);
+    return out;
+  }
+  return v;
+}
+
+/** Fate of an edit checked against the current on-disk content. */
+export const EDIT_REPLAY = Object.freeze({
+  APPLY: "apply", // old_string present — the edit still applies
+  ALREADY_APPLIED: "already_applied", // old gone, new present — idempotent no-op
+  CONFLICT: "conflict", // neither present — a genuine mismatch, surface it
+});
+
+/**
+ * Decide the fate of a literal (old→new) edit against CURRENT content — the
+ * content-addressed idempotency check. On a resumed replay the edit already
+ * landed, so `old_string` is gone and `new_string` is present → already_applied
+ * (skip, never double-apply). PURE.
+ *
+ * Deletions (`new_string === ""`) are deliberately NOT auto-detected as
+ * already-applied: "old absent + nothing to look for" is indistinguishable from
+ * "old never existed", so those keep surfacing as a conflict (the safe default).
+ *
+ * @param {{content:string, oldString:string, newString:string, replaceAll?:boolean}} p
+ * @returns {"apply"|"already_applied"|"conflict"}
+ */
+export function classifyEditReplay({ content, oldString, newString }) {
+  const text = String(content ?? "");
+  const oldS = String(oldString ?? "");
+  const newS = String(newString ?? "");
+  if (oldS && text.includes(oldS)) return EDIT_REPLAY.APPLY;
+  // old_string is absent. A present, non-empty new_string means the intended
+  // change is already in the file — the edit already happened.
+  if (newS && text.includes(newS)) return EDIT_REPLAY.ALREADY_APPLIED;
+  return EDIT_REPLAY.CONFLICT;
+}
+
+/** Stable idempotency key for a literal edit against a target file. */
+export function editIdempotencyKey({ path, oldString, newString, replaceAll }) {
+  return (
+    "edit_" +
+    sha256Hex(
+      JSON.stringify([
+        String(path || ""),
+        String(oldString ?? ""),
+        String(newString ?? ""),
+        replaceAll === true,
+      ]),
+    ).slice(0, 40)
+  );
+}
+
+/**
+ * Deterministic idempotency key for an external, irreversible operation — stable
+ * across retries so a provider honoring `Idempotency-Key` de-dupes a resumed
+ * replay, and so the side-effect ledger can spot a duplicated commit. Derived
+ * from the tool + a canonicalized view of its args; NO wall-clock / RNG so the
+ * SAME logical effect always maps to the SAME key.
+ *
+ * `scope` is optional namespacing (e.g. a session id); OMIT it when you want a
+ * pure retry of the same call to collide with its earlier attempt.
+ *
+ * @param {{tool:string, args?:object, scope?:string}} p
+ * @returns {string}
+ */
+export function operationIdempotencyKey({ tool, args, scope } = {}) {
+  return (
+    "op_" +
+    sha256Hex(
+      JSON.stringify([
+        String(tool || ""),
+        scope == null ? "" : String(scope),
+        canonicalize(args ?? null),
+      ]),
+    ).slice(0, 40)
+  );
+}

package/src/lib/jsonl-session-store.js

@@ -24,6 +24,7 @@ export {
   renameSession,
   pruneJsonlSessions,
   forkSession,
+  createBranchSession,
   sessionExists,
   getLastSessionId,
   migrateLegacySessions,

package/src/lib/lsp/__tests__/lsp-manager.test.js

@@ -257,6 +257,64 @@ describe("crash-loop restart guard", () => {
     expect(lastClient).not.toBe(quarantined);
     await mgr.disposeAll();
   });
+
+  describe("exponential restart backoff (opt-in)", () => {
+    it("computes exponential backoff per crash, capped, and 0 when disabled", () => {
+      const on = new LSPManager({
+        restartBackoffBaseMs: 1000,
+        restartBackoffMaxMs: 8000,
+      });
+      expect(on._restartBackoffMs(0)).toBe(0); // first start — no wait
+      expect(on._restartBackoffMs(1)).toBe(1000);
+      expect(on._restartBackoffMs(2)).toBe(2000);
+      expect(on._restartBackoffMs(3)).toBe(4000);
+      expect(on._restartBackoffMs(4)).toBe(8000);
+      expect(on._restartBackoffMs(5)).toBe(8000); // capped
+      // Disabled by default → always 0 (byte-identical immediate respawn).
+      const off = new LSPManager();
+      expect(off.restartBackoffBaseMs).toBe(0);
+      expect(off._restartBackoffMs(2)).toBe(0);
+    });
+
+    it("degrades (backing off) during the cooldown, then re-spawns once it elapses", async () => {
+      let t = 1000;
+      const mgr = new LSPManager({
+        maxRestarts: 5,
+        restartWindowMs: 60000,
+        restartBackoffBaseMs: 1000,
+        restartBackoffMaxMs: 8000,
+        now: () => t,
+      });
+      await mgr.ensureFor("/proj/src/a.ts"); // spawn #1
+      const first = lastClient;
+      crash(first); // 1 crash at t=1000
+      // Same tick → within the 1st-crash backoff (1000ms) → degrade, no respawn.
+      const backingOff = await mgr.ensureFor("/proj/src/a.ts");
+      expect(backingOff.unavailable).toBe(true);
+      expect(backingOff.backoff).toBe(true);
+      expect(backingOff.quarantined).toBeUndefined();
+      expect(backingOff.retryInMs).toBe(1000);
+      expect(lastClient).toBe(first); // did NOT spawn during cooldown
+      // Advance past the cooldown → a fresh spawn is allowed.
+      t += 1000;
+      const ready = await mgr.ensureFor("/proj/src/a.ts");
+      expect(ready.unavailable).toBeUndefined();
+      expect(lastClient).not.toBe(first);
+      await mgr.disposeAll();
+    });
+
+    it("does NOT back off by default — respawns a crashed server on the next request", async () => {
+      const mgr = new LSPManager({ maxRestarts: 3, now: () => 5000 });
+      await mgr.ensureFor("/proj/src/a.ts");
+      const first = lastClient;
+      crash(first);
+      // Same tick, backoff disabled → immediate fresh spawn (prior behaviour).
+      const ready = await mgr.ensureFor("/proj/src/a.ts");
+      expect(ready.unavailable).toBeUndefined();
+      expect(lastClient).not.toBe(first);
+      await mgr.disposeAll();
+    });
+  });
 });
 
 describe("diagnostics", () => {

package/src/lib/lsp/lsp-manager.js

@@ -33,6 +33,14 @@ export class LSPManager {
    * @param {number} [opts.restartWindowMs] sliding window for the crash count.
    *   A server that stays healthy for this long has its crash history pruned and
    *   can restart fresh. Default 30000.
+   * @param {number} [opts.restartBackoffBaseMs] exponential backoff BETWEEN
+   *   restart attempts: after the Nth recent crash the (N+1)th re-spawn waits
+   *   `base·2^(N-1)` (capped by `restartBackoffMaxMs`) before it is allowed,
+   *   spreading out a fast startup-crash loop instead of bursting `maxRestarts`
+   *   spawns back-to-back. Default 0 = OFF (byte-identical to the prior
+   *   immediate-respawn behaviour); opt-in pending evaluation.
+   * @param {number} [opts.restartBackoffMaxMs] cap for the exponential backoff.
+   *   Default 8000.
    * @param {() => number} [opts.now] injected clock (deterministic crash-loop tests)
    */
   constructor(opts = {}) {
@@ -65,6 +73,19 @@ export class LSPManager {
     this.restartWindowMs = Number.isFinite(opts.restartWindowMs)
       ? opts.restartWindowMs
       : 30000;
+    // Exponential backoff BETWEEN restart attempts (distinct from the quarantine
+    // cap above). Without it, a server that crashes on startup is re-spawned on
+    // the very next request — bursting `maxRestarts` spawns back-to-back in
+    // milliseconds before quarantine. When enabled, the (N+1)th spawn after N
+    // recent crashes waits `base·2^(N-1)` (capped), so a fast crash loop can't
+    // storm the process table. Default 0 = OFF → byte-identical to the prior
+    // immediate-respawn behaviour (opt-in pending evaluation).
+    this.restartBackoffBaseMs = Number.isFinite(opts.restartBackoffBaseMs)
+      ? Math.max(0, opts.restartBackoffBaseMs)
+      : 0;
+    this.restartBackoffMaxMs = Number.isFinite(opts.restartBackoffMaxMs)
+      ? opts.restartBackoffMaxMs
+      : 8000;
     this._now = typeof opts.now === "function" ? opts.now : () => Date.now();
     /** key → array of recent crash timestamps (survives entry re-spawn) */
     this._crashLog = new Map();
@@ -80,6 +101,18 @@ export class LSPManager {
     return pruned;
   }
 
+  /**
+   * Minimum delay before the next restart attempt given `crashCount` recent
+   * crashes: exponential `base·2^(crashCount-1)`, capped at `restartBackoffMaxMs`.
+   * Returns 0 when backoff is disabled (base 0) or `crashCount <= 0` (a first
+   * start). Deterministic (no jitter) so crash-loop tests stay reproducible.
+   */
+  _restartBackoffMs(crashCount) {
+    if (this.restartBackoffBaseMs <= 0 || crashCount <= 0) return 0;
+    const exp = this.restartBackoffBaseMs * 2 ** (crashCount - 1);
+    return Math.min(exp, this.restartBackoffMaxMs);
+  }
+
   /**
    * Ensure a server is running for `filePath` and the file is open. Returns
    * `{ client, uri, languageId }`, or `{ unavailable: true, reason }` when no
@@ -125,6 +158,29 @@ export class LSPManager {
           quarantined: true,
         };
       }
+      // Under the quarantine cap but recently crashed: when backoff is enabled,
+      // space out the re-spawn exponentially so a fast startup-crash loop doesn't
+      // storm the process table. The caller degrades to text search until the
+      // cooldown elapses — a transient state, distinct from quarantine.
+      if (crashes.length > 0) {
+        const backoffMs = this._restartBackoffMs(crashes.length);
+        if (backoffMs > 0) {
+          const lastCrash = crashes[crashes.length - 1];
+          const sinceLast = this._now() - lastCrash;
+          if (sinceLast < backoffMs) {
+            const retryInMs = backoffMs - sinceLast;
+            return {
+              unavailable: true,
+              reason:
+                `${resolved.id} restarting after a crash — backing off ` +
+                `~${Math.max(0, Math.round(retryInMs / 1000))}s ` +
+                `(attempt ${crashes.length + 1}/${this.maxRestarts})`,
+              backoff: true,
+              retryInMs,
+            };
+          }
+        }
+      }
       entry = await this._getOrStartServer(key, resolved, projectRoot);
     }