chainlesschain 0.162.162 → 0.162.164

package/src/lib/side-effect-ledger.js

@@ -0,0 +1,401 @@
+/**
+ * Side-effect ledger — crash-safe accounting of irreversible actions so a
+ * recovered worker never repeats a side-effect it already issued (P0
+ * state-machine slice: CLAUDE_CODE_CLI_INCREMENTAL_GAP_ANALYSIS_2026-07-12
+ * §"后台 Agent 状态机" — "副作用台账（prepared→started→committed|failed|unknown）
+ * 与崩溃恢复重放").
+ *
+ * The gap's acceptance is concrete: kill the worker/supervisor mid `file-write`,
+ * `git push`, or `package-install`, and after recovery the effect must not be
+ * applied twice. The classic bug is a blind retry — the process died AFTER
+ * `git push` reached the remote but BEFORE it recorded success, so a naive
+ * "resume the turn" pushes again.
+ *
+ * The fix is a two-phase record around every side-effect:
+ *
+ *   prepare(opId)  →  start(opId)  →  commit(opId) | fail(opId) | unknown(opId)
+ *
+ * and an HONEST recovery planner. The invariant: a `started`-but-not-settled op
+ * is INDETERMINATE — we cannot know if the effect landed — so unless the op is
+ * explicitly idempotent it must be INSPECTED by a human/verifier, never blindly
+ * redone. `prepared`-but-never-`started` ops are safe to redo (no effect issued
+ * yet); `committed` ops are skipped; cleanly `failed` ops redo only when the
+ * caller vouched they roll back atomically.
+ *
+ * Everything here is PURE (no timers, no I/O): the ledger is in-memory +
+ * serializable so a caller persists it alongside the session record. I/O lives
+ * in [[side-effect-ledger-store.js]].
+ */
+
+/** Lifecycle states of one side-effecting operation. */
+export const SIDE_EFFECT_STATE = Object.freeze({
+  PREPARED: "prepared", // intent recorded; nothing issued yet
+  STARTED: "started", // effect issued; outcome not yet known
+  COMMITTED: "committed", // effect confirmed applied
+  FAILED: "failed", // effect confirmed NOT applied (clean failure)
+  UNKNOWN: "unknown", // outcome indeterminate (e.g. crash mid-flight)
+});
+
+/** Recovery actions the reconciler emits for each unsettled op. */
+export const RECOVERY_ACTION = Object.freeze({
+  SKIP: "skip", // already committed — do nothing
+  REDO: "redo", // safe to run again (no effect issued, or idempotent)
+  INSPECT: "inspect", // indeterminate — verify before any repeat
+});
+
+/**
+ * Default idempotency for well-known side-effect kinds. Only actions that are
+ * naturally safe to re-run without duplicating an external effect are `true`.
+ * `file-write` is idempotent ONLY when a pre-write checkpoint exists (the write
+ * can be re-applied from the same source over a restored tree); a raw append
+ * has no such guarantee, so the default is conservative `false`.
+ */
+const KIND_IDEMPOTENT = new Map([
+  ["git-push", false],
+  ["package-install", false],
+  ["network-mutation", false],
+  ["payment", false],
+  ["file-write", false],
+  ["file-write-checkpointed", true],
+  ["read", true],
+  ["compute", true],
+]);
+
+/** Whether a kind is idempotent by default (unknown kinds → conservative false). */
+export function kindIsIdempotent(kind) {
+  return KIND_IDEMPOTENT.get(String(kind || "")) === true;
+}
+
+/** Trim a free-text descriptor to a short, log-safe key. */
+function shortKey(v) {
+  if (v == null) return null;
+  const s = String(v);
+  return s.length > 80 ? s.slice(0, 80) + "…" : s;
+}
+
+/**
+ * Classify one agent tool call into a side-effect kind for the ledger, or null
+ * when the tool issues no irreversible external effect (reads, searches, plain
+ * git status, etc.). PURE. Conservative by design — an opaque shell command is
+ * NON-idempotent so a mid-flight crash forces INSPECT rather than a blind
+ * replay (the P0-2 "started_unknown 风险操作默认 needs_input" invariant).
+ *
+ * Only the tools that can leave a durable external mark are recorded; read-only
+ * and purely-local-recoverable tools return null so a resumed session is not
+ * spammed with false "verify before replay" warnings.
+ *
+ * @param {string} toolName
+ * @param {object} [args]
+ * @returns {{kind:string, key:string|null}|null}
+ */
+export function classifyToolSideEffect(toolName, args = {}) {
+  const name = String(toolName || "");
+  const a = args && typeof args === "object" ? args : {};
+  switch (name) {
+    case "write_file":
+    case "notebook_edit":
+    case "edit_file":
+      return {
+        kind: "file-write",
+        key: shortKey(a.path || a.file || a.notebook_path),
+      };
+    case "edit_file_hashed":
+      // Hash-guarded: re-applying over an already-changed tree fails safely, so
+      // a replay cannot silently double-apply — idempotent-by-construction.
+      return {
+        kind: "file-write-checkpointed",
+        key: shortKey(a.path || a.file),
+      };
+    case "run_shell":
+    case "run_code":
+      // Opaque command: could be `npm publish`, `rm -rf`, or just `npm test`.
+      // We cannot tell, so fail-closed to a non-idempotent effect.
+      return { kind: "shell", key: shortKey(a.command || a.code) };
+    case "git": {
+      const cmd = String(a.command || "").trim();
+      const verb = cmd.split(/\s+/)[0] || "";
+      if (verb === "push") return { kind: "git-push", key: shortKey(cmd) };
+      // Every other git op (status/diff/commit/branch/fetch/pull/…) is either
+      // read-only or locally recoverable via git — not an irreversible effect.
+      return null;
+    }
+    case "publish_artifact":
+      return {
+        kind: "network-mutation",
+        key: shortKey(a.title || a.path || a.name),
+      };
+    case "schedule":
+      return {
+        kind: "network-mutation",
+        key: shortKey(a.name || a.cron || a.when),
+      };
+    case "notify":
+      return { kind: "network-mutation", key: shortKey(a.title || a.message) };
+    case "browser_act":
+      // A CDP action (click/type/submit) can mutate remote state.
+      return {
+        kind: "network-mutation",
+        key: shortKey(a.action || a.selector),
+      };
+    default:
+      return null;
+  }
+}
+
+function nowFrom(clock) {
+  return typeof clock === "function" ? Number(clock()) || 0 : 0;
+}
+
+/**
+ * The in-memory, serializable ledger. A caller records the two-phase lifecycle
+ * around each side-effect and, after a crash, hands the rebuilt ledger to
+ * `reconcileSideEffects` for a recovery plan.
+ *
+ * Timestamps are optional and only stamped when a `clock` is injected — keeping
+ * the ledger deterministic in tests (no `Date.now()`).
+ */
+export class SideEffectLedger {
+  constructor({ clock } = {}) {
+    this._ops = new Map();
+    this._order = [];
+    this._clock = clock || null;
+  }
+
+  _rec(opId) {
+    return this._ops.get(String(opId)) || null;
+  }
+
+  /**
+   * Record intent to perform a side-effect. Idempotent on opId (re-preparing an
+   * existing op is a no-op, so a retry loop can't reset a committed op).
+   *
+   * @param {string} opId  stable id (survives restart — e.g. `${turnId}:${seq}`)
+   * @param {{kind?:string, key?:string, idempotent?:boolean, meta?:object}} [info]
+   */
+  prepare(opId, info = {}) {
+    const id = String(opId);
+    if (this._ops.has(id)) return this;
+    const kind = info.kind == null ? null : String(info.kind);
+    this._ops.set(id, {
+      opId: id,
+      kind,
+      key: info.key == null ? null : String(info.key),
+      idempotent:
+        typeof info.idempotent === "boolean"
+          ? info.idempotent
+          : kindIsIdempotent(kind),
+      state: SIDE_EFFECT_STATE.PREPARED,
+      reason: null,
+      meta: info.meta && typeof info.meta === "object" ? { ...info.meta } : {},
+      preparedAt: nowFrom(this._clock),
+      settledAt: null,
+    });
+    this._order.push(id);
+    return this;
+  }
+
+  /** Mark the effect as ISSUED (outcome not yet known). Only from `prepared`. */
+  start(opId) {
+    return this._advance(opId, SIDE_EFFECT_STATE.STARTED, [
+      SIDE_EFFECT_STATE.PREPARED,
+    ]);
+  }
+
+  /** Confirm the effect applied. Only from `started`. */
+  commit(opId) {
+    return this._advance(
+      opId,
+      SIDE_EFFECT_STATE.COMMITTED,
+      [SIDE_EFFECT_STATE.STARTED],
+      { settle: true },
+    );
+  }
+
+  /** Confirm the effect did NOT apply (clean failure). Only from `started`. */
+  fail(opId, reason) {
+    return this._advance(
+      opId,
+      SIDE_EFFECT_STATE.FAILED,
+      [SIDE_EFFECT_STATE.STARTED],
+      { settle: true, reason },
+    );
+  }
+
+  /**
+   * Explicitly mark an op's outcome indeterminate. Accepts `prepared`/`started`
+   * (a recovery pass sweeping unsettled ops), never overrides a settled op.
+   */
+  unknown(opId, reason) {
+    return this._advance(
+      opId,
+      SIDE_EFFECT_STATE.UNKNOWN,
+      [SIDE_EFFECT_STATE.PREPARED, SIDE_EFFECT_STATE.STARTED],
+      { settle: true, reason },
+    );
+  }
+
+  _advance(opId, next, allowedFrom, { settle = false, reason } = {}) {
+    const rec = this._rec(opId);
+    if (!rec) return this;
+    if (!allowedFrom.includes(rec.state)) return this; // illegal transition → ignore
+    rec.state = next;
+    if (reason != null) rec.reason = String(reason);
+    if (settle) rec.settledAt = nowFrom(this._clock);
+    return this;
+  }
+
+  get(opId) {
+    const rec = this._rec(opId);
+    return rec ? { ...rec, meta: { ...rec.meta } } : null;
+  }
+
+  list() {
+    return this._order.map((id) => this.get(id));
+  }
+
+  /** Ops that never reached a terminal state — the recovery surface. */
+  unsettled() {
+    return this.list().filter(
+      (o) =>
+        o.state === SIDE_EFFECT_STATE.PREPARED ||
+        o.state === SIDE_EFFECT_STATE.STARTED,
+    );
+  }
+
+  toJSON() {
+    return { ops: this._order.map((id) => this.get(id)) };
+  }
+
+  static fromJSON(json, { clock } = {}) {
+    const ledger = new SideEffectLedger({ clock });
+    for (const o of json?.ops || []) {
+      if (!o || o.opId == null) continue;
+      const id = String(o.opId);
+      if (ledger._ops.has(id)) continue;
+      ledger._ops.set(id, {
+        opId: id,
+        kind: o.kind == null ? null : String(o.kind),
+        key: o.key == null ? null : String(o.key),
+        idempotent: o.idempotent === true,
+        state: Object.values(SIDE_EFFECT_STATE).includes(o.state)
+          ? o.state
+          : SIDE_EFFECT_STATE.UNKNOWN,
+        reason: o.reason == null ? null : String(o.reason),
+        meta: o.meta && typeof o.meta === "object" ? { ...o.meta } : {},
+        preparedAt: Number(o.preparedAt) || 0,
+        settledAt: o.settledAt == null ? null : Number(o.settledAt) || 0,
+      });
+      ledger._order.push(id);
+    }
+    return ledger;
+  }
+}
+
+/**
+ * Plan recovery for one op record (from SideEffectLedger.get()/list()). HONEST:
+ * an indeterminate `started` op is INSPECT unless it is explicitly idempotent.
+ *
+ * @param {object} op
+ * @returns {{opId:string, action:string, reason:string}}
+ */
+export function planOpRecovery(op) {
+  const opId = op?.opId ?? null;
+  switch (op?.state) {
+    case SIDE_EFFECT_STATE.COMMITTED:
+      return {
+        opId,
+        action: RECOVERY_ACTION.SKIP,
+        reason: "already committed",
+      };
+    case SIDE_EFFECT_STATE.PREPARED:
+      // Intent only — no external effect was issued, so a clean re-run is safe.
+      return {
+        opId,
+        action: RECOVERY_ACTION.REDO,
+        reason: "prepared but never started — no effect issued",
+      };
+    case SIDE_EFFECT_STATE.FAILED:
+      // A clean failure means the effect did not land; idempotent ops re-run.
+      return op.idempotent
+        ? {
+            opId,
+            action: RECOVERY_ACTION.REDO,
+            reason: "failed cleanly and idempotent — safe to retry",
+          }
+        : {
+            opId,
+            action: RECOVERY_ACTION.INSPECT,
+            reason: "failed — verify no partial effect before retrying",
+          };
+    case SIDE_EFFECT_STATE.STARTED:
+    case SIDE_EFFECT_STATE.UNKNOWN:
+    default:
+      // Crashed mid-flight: the effect MAY have landed. Only idempotent ops are
+      // safe to redo; everything else must be inspected, never blindly repeated.
+      return op?.idempotent
+        ? {
+            opId,
+            action: RECOVERY_ACTION.REDO,
+            reason: "indeterminate but idempotent — safe to re-run",
+          }
+        : {
+            opId,
+            action: RECOVERY_ACTION.INSPECT,
+            reason:
+              "started but not confirmed — effect may have applied; do not repeat blindly",
+          };
+  }
+}
+
+/**
+ * Count COMMITTED side-effects that share an idempotency key beyond the first —
+ * the "resume 后重复副作用 = 0" acceptance metric (P0-2 §11.2). A committed op's
+ * dedup key is `meta.idempotencyKey`; when absent it falls back to the (unique)
+ * `opId`, so un-keyed ops never register as duplicates. A correct resume never
+ * re-commits an already-committed effect, so this must stay `0`.
+ *
+ * @param {SideEffectLedger|{ops:Array}} ledger
+ * @returns {number}
+ */
+export function countDuplicateCommittedEffects(ledger) {
+  const ops =
+    ledger instanceof SideEffectLedger
+      ? ledger.list()
+      : Array.isArray(ledger?.ops)
+        ? ledger.ops
+        : [];
+  const seen = new Map();
+  let duplicates = 0;
+  for (const o of ops) {
+    if (o?.state !== SIDE_EFFECT_STATE.COMMITTED) continue;
+    const key = (o.meta && o.meta.idempotencyKey) || o.opId;
+    const n = (seen.get(key) || 0) + 1;
+    seen.set(key, n);
+    if (n > 1) duplicates++;
+  }
+  return duplicates;
+}
+
+/**
+ * Build a recovery plan for every op in a (crash-rebuilt) ledger.
+ *
+ * @param {SideEffectLedger|{ops:Array}} ledger
+ * @returns {{plans:Array, redo:string[], inspect:string[], skip:string[]}}
+ */
+export function reconcileSideEffects(ledger) {
+  const ops =
+    ledger instanceof SideEffectLedger
+      ? ledger.list()
+      : Array.isArray(ledger?.ops)
+        ? ledger.ops
+        : [];
+  const plans = ops.map((o) => planOpRecovery(o));
+  const bucket = (action) =>
+    plans.filter((p) => p.action === action).map((p) => p.opId);
+  return {
+    plans,
+    redo: bucket(RECOVERY_ACTION.REDO),
+    inspect: bucket(RECOVERY_ACTION.INSPECT),
+    skip: bucket(RECOVERY_ACTION.SKIP),
+  };
+}

package/src/lib/skill-loader.js

@@ -28,6 +28,7 @@ import { getElectronUserDataDir } from "./paths.js";
 import { findProjectRoot } from "./project-detector.js";
 import { findProjectRoot as findGitRoot } from "./project-instructions.js";
 import { parseSkillMcpServers } from "./skill-mcp.js";
+import { normalizeSkillPaths } from "./skill-path-scope.js";
 import { discoverPluginSkillLayers } from "./plugin-runtime/skills.js";
 import settingsLoader from "./settings-loader.cjs";
 
@@ -467,6 +468,10 @@ export class CLISkillLoader {
           executionMode: data.executionMode || null,
           cliDomain: data.cliDomain || null,
           cliVersionHash: data.cliVersionHash || null,
+          // Optional per-directory path-scope: when set, the skill is only
+          // surfaced/runnable under a matching subtree (large-monorepo lazy
+          // context). null (the default) = applies everywhere.
+          paths: normalizeSkillPaths(data),
           dirName: entry.name,
           hasHandler: fs.existsSync(path.join(skillDir, "handler.js")),
           body,
@@ -515,6 +520,33 @@ export class CLISkillLoader {
     return this._cache;
   }
 
+  /**
+   * Every skill found in every layer, WITHOUT dedup. loadAll() keeps only the
+   * winning copy per id (Map.set overwrite), so a skill id defined in more than
+   * one layer silently shadows — a caller (e.g. `cc doctor`) needs the full,
+   * un-deduped list to detect and report that. Same scan logic as loadAll, no
+   * override collapse.
+   * @returns {Array<{id:string, layer:string, skillDir:string}>}
+   */
+  listSkillLayerEntries(options = {}) {
+    if (allSkillsDisabled(options)) return [];
+    const dropBundled = bundledSkillsDisabled(options);
+    const out = [];
+    for (const { layer, path: layerPath, exists } of this.getLayerPaths()) {
+      if (!exists) continue;
+      if (dropBundled && (layer === "bundled" || layer === "cli-bundled"))
+        continue;
+      for (const skill of this._loadFromDir(layerPath, layer)) {
+        out.push({
+          id: skill.id,
+          layer: skill.source || layer,
+          skillDir: skill.skillDir,
+        });
+      }
+    }
+    return out;
+  }
+
   /**
    * Get resolved skills (uses cache if available)
    * @returns {object[]}

package/src/lib/skill-path-scope.js

@@ -0,0 +1,63 @@
+/**
+ * Per-directory skill path-scoping (P1 large-monorepo lazy context).
+ *
+ * A skill may declare a `paths:` (or `globs:` / `pathScope:`) frontmatter list
+ * so it is only surfaced when the agent is working under a matching subtree —
+ * e.g. a skill scoped to `packages/cli/**` should not clutter discovery or run
+ * when the agent is operating in `android-app/`. This keeps the on-demand skill
+ * surface small in a big monorepo.
+ *
+ * Pure (path math only; the matching semantics are reused from
+ * project-instructions.js's `ruleApplies`, the same prefix-overlap rule used for
+ * path-scoped `.claude/rules`). A skill with no `paths` applies everywhere, so a
+ * skill set with no path-scoped skills is filtered byte-for-byte unchanged.
+ */
+
+import path from "node:path";
+import { ruleApplies } from "./project-instructions.js";
+
+/**
+ * Normalize a skill's raw path-scope frontmatter (`paths` / `globs` /
+ * `pathScope`, string or array) into a non-empty string[] of globs, or null
+ * when the skill declares no scope (→ applies everywhere).
+ */
+export function normalizeSkillPaths(data) {
+  const raw = data?.paths ?? data?.globs ?? data?.pathScope ?? null;
+  if (raw == null) return null;
+  const list = (Array.isArray(raw) ? raw : [raw])
+    .map((g) => String(g == null ? "" : g).trim())
+    .filter(Boolean);
+  return list.length > 0 ? list : null;
+}
+
+/**
+ * The agent's cwd expressed relative to the project root, forward-slashed — the
+ * form `ruleApplies` expects (skill `paths` globs are project-root-relative,
+ * like rule globs). A cwd at (or outside) the root resolves to "" → every skill
+ * applies (never hide skills just because we can't locate the root).
+ */
+export function relCwdForCwd(cwd, root) {
+  if (!cwd || !root) return "";
+  let rel;
+  try {
+    rel = path.relative(root, cwd);
+  } catch {
+    return "";
+  }
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return "";
+  return rel.replace(/\\/g, "/");
+}
+
+/**
+ * Does a skill's path-scope apply when the agent runs at `relCwd`? A skill with
+ * no `paths` (null/empty) applies everywhere.
+ */
+export function skillAppliesToCwd(skill, relCwd) {
+  return ruleApplies(skill?.paths || [], relCwd);
+}
+
+/** Filter a skill list to those whose path-scope applies at `relCwd`. */
+export function filterSkillsByRelCwd(skills, relCwd) {
+  if (!Array.isArray(skills)) return skills;
+  return skills.filter((s) => skillAppliesToCwd(s, relCwd));
+}