chainlesschain 0.162.161 → 0.162.163

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

@@ -0,0 +1,296 @@
+/**
+ * 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;
+}
+
+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",
+          };
+  }
+}
+
+/**
+ * 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/sub-agent-context.js

@@ -45,8 +45,10 @@ export class SubAgentContext {
    * @param {number} [options.maxIterations] - Iteration limit (fallback if no budget)
    * @param {import('./iteration-budget.js').IterationBudget} [options.iterationBudget] - Shared iteration budget (takes priority over maxIterations)
    * @param {number} [options.tokenBudget] - Optional token budget
-   * @param {object} [options.db] - Database instance
+   * @param {object} [options.db] - Database instance (memory recall source)
    * @param {object} [options.permanentMemory] - Permanent memory instance
+   * @param {boolean} [options.memoryEnabled=true] - When false, the child's
+   *   context engine suppresses hierarchical-memory recall (contract memory:false)
    * @param {object} [options.llmOptions] - LLM provider/model/key options
    * @param {string} [options.cwd] - Working directory
    * @param {boolean} [options.useWorktree] - Force worktree isolation (overrides flag)
@@ -77,6 +79,14 @@ export class SubAgentContext {
     // Shared run-wide TOTAL-sub-agent counter (one object across the whole tree)
     // so this sub-agent's own spawns draw from the same breadth pool.
     this.subAgentBudget = options.subAgentBudget || null;
+    // This context's EFFECTIVE subagent contract — the ceiling handed to its OWN
+    // nested spawns (threaded into the loop options so a nested spawn_sub_agent
+    // reads it as ctx.subAgentContract).
+    this.subAgentContract = options.subAgentContract || null;
+    // Skill capability INTERSECT: null = unrestricted; a list (possibly empty)
+    // restricts run_skill/list_skills in this context's loop to those skills.
+    this.skillAllowlist =
+      options.skillAllowlist != null ? options.skillAllowlist : null;
     this.cwd = options.cwd || process.cwd();
     this.status = "active";
     this.result = null;
@@ -93,10 +103,17 @@ export class SubAgentContext {
     // Independent message history — never shared with parent
     this.messages = [];
 
-    // Independent context engine — does not inherit parent's compaction/errors
+    // Independent context engine — does not inherit parent's compaction/errors.
+    // Memory recall is gated by the subagent contract: the spawn passes a `db`
+    // and memoryEnabled:true only when the resolved contract grants memory
+    // (context:fork from a memory-bearing parent, or explicit memory:true).
+    // Default (silent-`fresh`→memory:false) → no db + memoryEnabled:false → no
+    // recall, which is today's byte-identical behavior for a plain sub-agent.
+    this._memoryEnabled = options.memoryEnabled !== false;
     this.contextEngine = new CLIContextEngineering({
       db: options.db || null,
       permanentMemory: options.permanentMemory || null,
+      memoryEnabled: this._memoryEnabled,
       scope: {
         taskId: this.id,
         role: this.role,
@@ -145,6 +162,22 @@ export class SubAgentContext {
         : {};
     this._mcpClient = options.mcpClient || null;
 
+    // Inherited settings hooks (Pre/PostToolUse) for this child loop. null =
+    // no hooks (the spawn default). The spawn path passes the parent's hooks
+    // filtered by the contract's `hooks` allow-list; forwarded into agentLoop.
+    this._settingsHooks = options.settingsHooks || null;
+
+    // permissionMode confirmer for this child loop. null = no confirmer (the
+    // spawn default → the child denies ask/sensitive-file/git gates). The spawn
+    // sets this only for the autopilot (bypassPermissions) ALLOW confirmer.
+    this._permissionConfirm = options.permissionConfirm || null;
+
+    // permissionMode ApprovalGate for this child loop. null = ungated (the spawn
+    // default). The spawn sets a dedicated confirmer-less gate (seeded with the
+    // mode's tier) for the strict/trusted tiers so run_shell/browser_act are
+    // gated headlessly (CONFIRM→no-confirmer→DENY).
+    this._approvalGate = options.approvalGate || null;
+
     // Build isolated system prompt
     const basePrompt = buildSystemPrompt(this.cwd);
     const profilePrompt = this._profile?.systemPrompt
@@ -176,9 +209,25 @@ export class SubAgentContext {
       );
     }
 
-    // If worktree isolation is enabled, wrap execution in isolated worktree
-    if (this._useWorktree && isGitRepo(this._repoDir)) {
-      return this._runInWorktree(userPrompt, loopOptions);
+    // If worktree isolation is enabled, wrap execution in isolated worktree.
+    if (this._useWorktree) {
+      if (isGitRepo(this._repoDir)) {
+        return this._runInWorktree(userPrompt, loopOptions);
+      }
+      // FAIL CLOSED: isolation was explicitly requested but this is not a git
+      // repo. Never silently fall back to the parent checkout — refuse.
+      this.status = "failed";
+      this.completedAt = new Date().toISOString();
+      this.result = {
+        summary:
+          "Worktree isolation was requested but the working directory is not a git repository — refusing to run in the parent checkout.",
+        artifacts: [],
+        tokenCount: this._tokenCount,
+        toolsUsed: [...new Set(this._toolsUsed)],
+        iterationCount: this._iterationCount,
+        isolationError: true,
+      };
+      return this.result;
     }
 
     return this._runCore(userPrompt, loopOptions);
@@ -270,6 +319,10 @@ export class SubAgentContext {
       // Shared total-sub-agent counter so a nested spawn_sub_agent draws from
       // (and is bounded by) the run's single breadth pool.
       subAgentBudget: this.subAgentBudget,
+      // This context's effective contract = the ceiling for its nested spawns.
+      subAgentContract: this.subAgentContract,
+      // Skill allow-list restricting run_skill/list_skills in this loop.
+      skillAllowlist: this.skillAllowlist,
       ...loopOptions,
     };
     if (this.iterationBudget) {
@@ -298,6 +351,22 @@ export class SubAgentContext {
     if (this._mcpClient) {
       options.mcpClient = this._mcpClient;
     }
+    // Inherited Pre/PostToolUse hooks (spawn passes the parent's, filtered by
+    // the contract's `hooks` allow-list). Only set when non-null so a plain
+    // sub-agent keeps its no-hooks default.
+    if (this._settingsHooks) {
+      options.settingsHooks = this._settingsHooks;
+    }
+    // permissionMode confirmer (spawn sets it only for bypassPermissions). Only
+    // forward when present so a plain sub-agent keeps its implicit-deny default.
+    if (this._permissionConfirm) {
+      options.permissionConfirm = this._permissionConfirm;
+    }
+    // permissionMode ApprovalGate (spawn sets it for strict/trusted tiers). Only
+    // forward when present so a plain sub-agent stays ungated (byte-identical).
+    if (this._approvalGate) {
+      options.approvalGate = this._approvalGate;
+    }
 
     try {
       // Use a separate messages array for the agent loop