chainlesschain 0.162.161 → 0.162.163

package/src/lib/plugin-runtime/capability-consent.js

@@ -0,0 +1,175 @@
+/**
+ * Plugin capability CONSENT (Phase 3 gap: capability declaration + re-consent).
+ *
+ * Complements version trust ([[trust.js]]): trust pins the exact CODE a plugin
+ * ships (re-consent on version bump); this pins the CAPABILITY SET the plugin is
+ * allowed to request (process / network / filesystem / mcp / monitor /
+ * credential). The two are orthogonal — a plugin can be trusted-to-run yet still
+ * WIDEN what it wants (add `network:*`, a new credential), which must re-prompt.
+ *
+ * Consent is keyed by the SET, not the version: once the user consents, later
+ * versions that keep the same (or a narrower) capability set stay consented; any
+ * WIDENING (a new grant) revokes consent until re-granted. This mirrors
+ * `consentRequiredForUpgrade` in [[capabilities.js]] exactly.
+ *
+ * Recorded in the USER data dir (never in the repo — a checked-in project file
+ * must not be able to pre-grant itself capabilities), keyed `<scope>:<name>` →
+ * { version, capabilities, consentedAt }. Pure over injected IO so unit tests
+ * never touch the real user-data dir.
+ */
+
+import fs from "fs";
+import path from "path";
+import { getElectronUserDataDir } from "../paths.js";
+import {
+  normalizeCapabilities,
+  diffCapabilities,
+  describeCapabilities,
+} from "./capabilities.js";
+
+export const _deps = {
+  existsSync: fs.existsSync,
+  readFileSync: fs.readFileSync,
+  writeFileSync: fs.writeFileSync,
+  mkdirSync: fs.mkdirSync,
+  now: () => new Date().toISOString(),
+  // Injectable so unit tests never touch the real user-data dir.
+  storePath: () =>
+    path.join(getElectronUserDataDir(), "plugin-capability-consent.json"),
+};
+
+function consentKey(scope, name) {
+  return `${scope}:${name}`;
+}
+
+export function loadConsentStore() {
+  try {
+    const p = _deps.storePath();
+    if (!_deps.existsSync(p)) return {};
+    const data = JSON.parse(_deps.readFileSync(p, "utf8"));
+    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+function saveConsentStore(store) {
+  const p = _deps.storePath();
+  _deps.mkdirSync(path.dirname(p), { recursive: true });
+  _deps.writeFileSync(p, JSON.stringify(store, null, 2), "utf8");
+}
+
+/**
+ * Coerce a capability set to the canonical shape diffCapabilities needs.
+ * `normalizeCapabilities` is NOT idempotent — it re-parses `filesystem`/
+ * `credential` through `toList`, so feeding it an already-normalized set (e.g.
+ * one read back from the store) corrupts those lists. Detect an already-
+ * canonical set and pass it through unchanged; only normalize raw input.
+ */
+function canonicalCaps(caps) {
+  if (
+    caps &&
+    typeof caps === "object" &&
+    caps.network &&
+    typeof caps.network === "object" &&
+    "domains" in caps.network &&
+    caps.filesystem &&
+    "roots" in caps.filesystem &&
+    caps.credential &&
+    "names" in caps.credential
+  ) {
+    return caps;
+  }
+  return normalizeCapabilities(caps);
+}
+
+/** True when a capability set grants nothing (all-deny) — nothing to consent. */
+export function capabilitiesAreEmpty(caps) {
+  return !diffCapabilities(null, canonicalCaps(caps)).widened;
+}
+
+/**
+ * PURE consent status: given a plugin's DECLARED capabilities and its stored
+ * consent entry, decide whether consent covers them. Re-consent is required on
+ * a first request or any WIDENING (new grant) — not on a version bump alone
+ * (trust handles versions).
+ *
+ * @param {object} declaredCaps  raw or normalized capabilities
+ * @param {object|null} entry    stored `{ version, capabilities }` (or null)
+ * @returns {{consented:boolean, reason:string, added:string[]}}
+ */
+export function capabilityConsentStatus(declaredCaps, entry) {
+  const declared = canonicalCaps(declaredCaps);
+  if (!diffCapabilities(null, declared).widened) {
+    return { consented: true, reason: "no capabilities declared", added: [] };
+  }
+  if (!entry) {
+    return {
+      consented: false,
+      reason: "capabilities never consented",
+      added: diffCapabilities(null, declared).added,
+    };
+  }
+  // Coerce the stored set to canonical too (raw hand-written entry, or an
+  // already-normalized one read from the store) before diffing.
+  const diff = diffCapabilities(canonicalCaps(entry.capabilities), declared);
+  if (diff.widened) {
+    return {
+      consented: false,
+      reason: "capabilities widened since last consent",
+      added: diff.added,
+    };
+  }
+  return {
+    consented: true,
+    reason: "consent covers declared capabilities",
+    added: [],
+  };
+}
+
+/** Load the store and report whether one plugin's declared caps are consented. */
+export function isPluginCapabilityConsented(plugin, declaredCaps) {
+  if (!plugin || !plugin.name) return false;
+  const entry = loadConsentStore()[consentKey(plugin.scope, plugin.name)];
+  return capabilityConsentStatus(declaredCaps, entry).consented;
+}
+
+/** Record consent for a plugin's currently-declared capability set. */
+export function consentPluginCapabilities(
+  name,
+  { scope = "project", version, capabilities } = {},
+) {
+  if (!version) throw new Error("consentPluginCapabilities requires a version");
+  const store = loadConsentStore();
+  store[consentKey(scope, name)] = {
+    version,
+    capabilities: canonicalCaps(capabilities),
+    consentedAt: _deps.now(),
+  };
+  saveConsentStore(store);
+  return { name, scope, version };
+}
+
+/** Revoke capability consent for a plugin at a scope. */
+export function revokeCapabilityConsent(name, { scope = "project" } = {}) {
+  const store = loadConsentStore();
+  const key = consentKey(scope, name);
+  const existed = Object.prototype.hasOwnProperty.call(store, key);
+  delete store[key];
+  saveConsentStore(store);
+  return { name, scope, removed: existed };
+}
+
+/** All consent entries (for `cc plugin consent --list`). */
+export function listCapabilityConsent() {
+  return Object.entries(loadConsentStore()).map(([key, v]) => {
+    const idx = key.indexOf(":");
+    return {
+      scope: key.slice(0, idx),
+      name: key.slice(idx + 1),
+      version: v?.version || null,
+      consentedAt: v?.consentedAt || null,
+      capabilities: describeCapabilities(v?.capabilities),
+    };
+  });
+}

package/src/lib/plugin-runtime/manifest.js

@@ -27,6 +27,11 @@
 import fs from "fs";
 import path from "path";
 import semver from "semver";
+import {
+  normalizeCapabilities,
+  normalizeOptionsSchema,
+  auditDeclaredCapabilities,
+} from "./capabilities.js";
 
 export const _deps = {
   existsSync: fs.existsSync,
@@ -73,6 +78,14 @@ export function parsePluginManifest(root) {
     scope: null,
     metadata: {},
     components: emptyComponents(),
+    // Declarative security contract (P1): the plugin's declared capabilities
+    // (manifest.permissions) + typed config schema (manifest.optionsSchema),
+    // normalized by capabilities.js. `capabilitiesDeclared` distinguishes a
+    // plugin that declared a permissions block (subject to the declared-vs-
+    // actual audit) from a legacy one that declared nothing (unrestricted).
+    capabilities: normalizeCapabilities(null),
+    capabilitiesDeclared: false,
+    optionsSchema: {},
     errors,
     warnings,
   };
@@ -165,6 +178,23 @@ export function parsePluginManifest(root) {
   c.bin = resolveBin(abs, manifest, safeResolve, warnings);
   c.settings = resolveSettings(abs, manifest, safeResolve);
 
+  // ── declared capabilities + options schema (P1) ──
+  const hasPermissions =
+    manifest.permissions &&
+    typeof manifest.permissions === "object" &&
+    !Array.isArray(manifest.permissions);
+  result.capabilities = normalizeCapabilities(manifest.permissions);
+  result.capabilitiesDeclared = Boolean(hasPermissions);
+  result.optionsSchema = normalizeOptionsSchema(manifest.optionsSchema);
+  // Declared-vs-actual audit runs ONLY when a permissions block is present — a
+  // legacy plugin that declares nothing is unrestricted by design, so it never
+  // gets these warnings (keeps existing manifests warning-free).
+  if (hasPermissions) {
+    for (const f of auditDeclaredCapabilities(result)) {
+      warnings.push(`capability: ${f.reason}`);
+    }
+  }
+
   result.ok = errors.length === 0;
   return result;
 }

package/src/lib/plugin-runtime/policy.js

@@ -25,6 +25,7 @@
 import { enforcePluginPolicy } from "../plugin-security.js";
 import { loadManagedSettings } from "../settings-loader.cjs";
 import { verifyInstalledSignature } from "./signature.js";
+import { isPluginCapabilityConsented } from "./capability-consent.js";
 
 // Managed settings are org-admin controlled and effectively static for a
 // session, and discoverPlugins is called by every collector — memoize the load
@@ -142,6 +143,67 @@ export function filterByManagedPolicy(plugins, managed) {
   return { kept, dropped };
 }
 
+/**
+ * Whether capability-consent must be ENFORCED at load time. The consent gate
+ * ([[capability-consent.js]]) already exists but was consulted only by `cc
+ * plugin consent`/`validate`/`doctor` — a plugin that declared capabilities and
+ * was never consented still loaded all six component types. Enforcement is
+ * OPT-IN (byte-identical default): an org sets `requirePluginCapabilityConsent`
+ * in managed settings, or a single user exports `CC_REQUIRE_PLUGIN_CONSENT=1`.
+ *
+ * @param {object|null} managed  managed settings
+ * @param {object} [env]         process env (injectable)
+ * @returns {boolean}
+ */
+export function capabilityConsentRequired(managed, env) {
+  const raw = (env || process.env).CC_REQUIRE_PLUGIN_CONSENT;
+  if (raw != null && /^(1|true|yes|on)$/i.test(String(raw).trim())) return true;
+  return (
+    managed?.requirePluginCapabilityConsent === true ||
+    managed?.requirePluginCapabilityConsent === "require"
+  );
+}
+
+/**
+ * Drop plugins that DECLARE capabilities but whose current capability SET has
+ * not been consented (first request or any widening). Fail-closed: a consent
+ * check that throws drops the plugin. Legacy plugins that declare no
+ * `permissions` block are UNAFFECTED — the same "未声明 legacy 不受限" rule the
+ * declaration audit uses. A plugin whose declared set is empty (all-deny) is
+ * auto-consented by `isPluginCapabilityConsented`, so it stays.
+ *
+ * @param {Array<{name, scope, manifest}>} plugins
+ * @returns {{ kept: Array, dropped: Array<{name, reason}> }}
+ */
+export function filterByCapabilityConsent(plugins) {
+  const kept = [];
+  const dropped = [];
+  for (const p of plugins) {
+    if (!p.manifest?.capabilitiesDeclared) {
+      kept.push(p); // legacy plugin, no declaration → not gated
+      continue;
+    }
+    let consented = false;
+    try {
+      consented = isPluginCapabilityConsented(
+        { name: p.name, scope: p.scope },
+        p.manifest.capabilities,
+      );
+    } catch {
+      consented = false; // fail closed
+    }
+    if (consented) {
+      kept.push(p);
+    } else {
+      dropped.push({
+        name: p.name,
+        reason: `capabilities not consented — run \`cc plugin consent ${p.name} --grant\``,
+      });
+    }
+  }
+  return { kept, dropped };
+}
+
 let _warnedDropped = new Set();
 
 /** One-time stderr warning naming plugins an org policy blocked from loading. */

package/src/lib/plugin-runtime/scopes.js

@@ -27,6 +27,8 @@ import { parsePluginManifest } from "./manifest.js";
 import {
   loadManagedPluginPolicy,
   filterByManagedPolicy,
+  filterByCapabilityConsent,
+  capabilityConsentRequired,
   warnDroppedOnce,
 } from "./policy.js";
 
@@ -160,10 +162,24 @@ export function discoverPlugins(opts = {}) {
     env: opts.env,
     managedSettingsFile: opts.managedSettingsFile,
   });
-  if (!managed) return all;
-  const { kept, dropped } = filterByManagedPolicy(all, managed);
-  if (dropped.length > 0) warnDroppedOnce(dropped);
-  return kept;
+  const consentGate = capabilityConsentRequired(managed, opts.env);
+  // Default (no managed policy AND consent enforcement off): byte-identical —
+  // return every discovered plugin, exactly as before.
+  if (!managed && !consentGate) return all;
+  let list = all;
+  if (managed) {
+    const { kept, dropped } = filterByManagedPolicy(list, managed);
+    if (dropped.length > 0) warnDroppedOnce(dropped);
+    list = kept;
+  }
+  // Capability-consent enforcement funnels through the SAME chokepoint, so an
+  // un-consented plugin loads NONE of its six component types (opt-in).
+  if (consentGate) {
+    const { kept, dropped } = filterByCapabilityConsent(list);
+    if (dropped.length > 0) warnDroppedOnce(dropped);
+    list = kept;
+  }
+  return list;
 }
 
 // ── internals ────────────────────────────────────────────────────────────

package/src/lib/project-instructions.js

@@ -477,4 +477,132 @@ export function loadProjectInstructionsBlock(opts = {}) {
   }
 }
 
+function isDir(fs, p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Lazy subtree-instruction discovery (module 99 §5.3 "子目录指令按首次访问子树
+ * 懒加载"). Startup only loads the instruction chain from the project root DOWN
+ * to the cwd (see `findInstructionFiles`); a large monorepo's per-package
+ * `cc.md`/`CLAUDE.md`/`AGENTS.md` that sit BELOW the cwd are intentionally NOT
+ * injected up front — they cost tokens for subtrees a turn may never touch.
+ *
+ * This resolver answers "given a path a tool just accessed, which subtree
+ * instruction files should now be injected?" — the files in every directory
+ * strictly between `baseDir` (the already-loaded cwd) and the accessed path's
+ * directory, minus anything already loaded or excluded. Pure + deterministic;
+ * the tool-time injection itself is the caller's job.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot        excludes are matched relative to this
+ * @param {string} opts.baseDir         the startup cwd (its own file already loaded)
+ * @param {string} opts.accessedPath    a file/dir a tool touched (abs or rel to baseDir)
+ * @param {Set<string>|string[]} [opts.alreadyLoaded]  abs paths already injected
+ * @param {string[]} [opts.instructionExcludes]
+ * @returns {Array<{path:string, scope:"project", dir:string}>} shallowest-first
+ */
+export function resolveSubtreeInstructions(opts = {}) {
+  const { fs, path } = resolveDeps(opts);
+  const repoRoot = path.resolve(opts.repoRoot || opts.baseDir || process.cwd());
+  const baseDir = path.resolve(opts.baseDir || repoRoot);
+  const excludes = normalizeInstructionExcludes(opts.instructionExcludes);
+  const already =
+    opts.alreadyLoaded instanceof Set
+      ? opts.alreadyLoaded
+      : new Set((opts.alreadyLoaded || []).map((p) => path.resolve(p)));
+
+  if (!opts.accessedPath) return [];
+  // Resolve the accessed path to a directory inside the subtree. A not-yet-
+  // created file (about to be written) stats as neither file nor dir → treat it
+  // as a file and use its parent.
+  let target = path.resolve(baseDir, opts.accessedPath);
+  if (!isDir(fs, target)) target = path.dirname(target);
+
+  // Subtree instructions apply only to DESCENDANTS of baseDir (ancestors were
+  // loaded at startup). Reject a target that escapes baseDir or the repo.
+  const relFromBase = path.relative(baseDir, target);
+  if (
+    !relFromBase ||
+    relFromBase.startsWith("..") ||
+    path.isAbsolute(relFromBase)
+  ) {
+    return [];
+  }
+  const relFromRoot = path.relative(repoRoot, target);
+  if (relFromRoot.startsWith("..") || path.isAbsolute(relFromRoot)) return [];
+
+  // Directories strictly between baseDir (exclusive) and target (inclusive).
+  const dirs = [];
+  let dir = target;
+  while (dir !== baseDir) {
+    dirs.push(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // hit fs root without meeting baseDir
+    dir = parent;
+  }
+  dirs.reverse(); // shallowest first
+
+  const out = [];
+  for (const d of dirs) {
+    const file = firstExisting(fs, path, d, PROJECT_FILE_NAMES);
+    if (!file) continue;
+    const abs = path.resolve(file);
+    if (already.has(abs)) continue;
+    if (
+      excludes.length > 0 &&
+      pathIsExcluded(path.relative(repoRoot, abs), excludes)
+    ) {
+      continue;
+    }
+    out.push({ path: abs, scope: "project", dir: d });
+  }
+  return out;
+}
+
+/**
+ * Stateful companion to `resolveSubtreeInstructions`: tracks which subtree
+ * directories have already been injected across a session so a second access to
+ * the same subtree is a no-op. `onAccess(path)` returns ONLY the freshly
+ * discovered files. Fail-open (any error → []).
+ */
+export class SubtreeInstructionLoader {
+  constructor(opts = {}) {
+    const path = opts.deps?.path || pathDefault;
+    this._opts = opts;
+    this._loadedDirs = new Set();
+    this._loadedFiles = new Set(
+      (opts.alreadyLoaded || []).map((p) => path.resolve(p)),
+    );
+  }
+
+  /** @returns {Array<{path:string, scope:"project", dir:string}>} newly injected */
+  onAccess(accessedPath) {
+    try {
+      const found = resolveSubtreeInstructions({
+        ...this._opts,
+        accessedPath,
+        alreadyLoaded: this._loadedFiles,
+      });
+      const fresh = found.filter((f) => !this._loadedDirs.has(f.dir));
+      for (const f of fresh) {
+        this._loadedDirs.add(f.dir);
+        this._loadedFiles.add(f.path);
+      }
+      return fresh;
+    } catch {
+      return [];
+    }
+  }
+
+  /** Absolute paths injected so far (startup set + every onAccess discovery). */
+  loadedFiles() {
+    return [...this._loadedFiles];
+  }
+}
+
 export const _deps = { fs: fsDefault, path: pathDefault, os: osDefault };

package/src/lib/remote-approval-bridge.js

@@ -23,6 +23,10 @@
 
 import { randomBytes } from "crypto";
 import { WsRpcClient } from "./ws-rpc-client.js";
+import {
+  approvalFingerprintOk,
+  operationFingerprint,
+} from "./operation-fingerprint.js";
 import {
   buildDirectPairingUri,
   pickLanAddress,
@@ -113,6 +117,15 @@ export class RemoteApprovalBridge {
     const requestId = message.event.requestId || message.event.approvalId;
     const pending = requestId ? this._pending.get(requestId) : null;
     if (!pending) return;
+    // Confused-deputy guard: a resolve that carries an operation fingerprint
+    // must match the operation this ask published. A mismatch (stale card /
+    // replayed / swapped body) is rejected — the ask stays pending and fails
+    // closed on timeout. Absent fingerprint = legacy device, accepted.
+    if (
+      !approvalFingerprintOk(pending.fingerprint, message.event.fingerprint)
+    ) {
+      return;
+    }
     this._pending.delete(requestId);
     clearTimeout(pending.timer);
     const answer = message.event.answer ?? message.event.approved;
@@ -150,6 +163,7 @@ export class RemoteApprovalBridge {
     onRequestId = null,
   } = {}) {
     const requestId = `ra-${process.pid}-${++this._counter}-${randomBytes(4).toString("hex")}`;
+    const fingerprint = operationFingerprint({ tool, action, detail });
     if (onRequestId) {
       try {
         onRequestId(requestId);
@@ -171,6 +185,7 @@ export class RemoteApprovalBridge {
       if (typeof timer.unref === "function") timer.unref();
       this._pending.set(requestId, {
         timer,
+        fingerprint,
         resolve: (decision) => {
           this._publish({
             type: "permission.resolved",
@@ -187,6 +202,7 @@ export class RemoteApprovalBridge {
         tool: tool || null,
         action,
         detail,
+        fingerprint,
         askedAt: this._now(),
       });
     });

package/src/lib/repl-goal.js

@@ -0,0 +1,132 @@
+/**
+ * REPL `/goal <condition>` — a SESSION completion condition for interactive use.
+ *
+ * Three distinct "goal" concepts, kept separate on purpose:
+ *   - `cc goal`               → long-term, cross-session OKR (goal-store.js).
+ *   - headless --goal-condition → AUTO re-drives outer turns until met/exhausted.
+ *   - REPL `/goal <cond>`      → THIS: a human is present each turn, so it
+ *     EVALUATES + REPORTS after every turn whether the condition is met. It does
+ *     NOT auto-submit follow-ups (that autonomous loop belongs to headless, where
+ *     no human is watching) — the user decides whether to keep going.
+ *
+ * This is the pure, clock/dep-injected core over the already-tested
+ * goal-condition-engine.js; the agent-repl wiring is thin display + eval glue.
+ */
+
+import {
+  isDeterministicCondition,
+  runDeterministicCheck,
+  GoalConditionEngine,
+  GOAL_DECISION,
+} from "./goal-condition-engine.js";
+
+// Interactive sessions are human-paced, so the turn-count budget is generous —
+// it exists only as a backstop (the engine hard-caps at 100 regardless). The
+// meaningful signal in the REPL is met / not-yet-met, not budget exhaustion.
+export const REPL_GOAL_MAX_OUTER_TURNS = 100;
+
+/** Parse the `/goal` argument into an intent. Empty → status; a keyword → clear. */
+export function parseGoalCommand(arg) {
+  const s = String(arg ?? "").trim();
+  if (!s) return { action: "status" };
+  if (s === "clear" || s === "off" || s === "stop" || s === "drop")
+    return { action: "clear" };
+  return { action: "set", spec: s };
+}
+
+/**
+ * Create the REPL's session goal engine for a spec. Throws (via
+ * parseGoalCondition) on a malformed spec so the caller can report it.
+ */
+export function createReplGoal(spec, { now = () => 0 } = {}) {
+  return new GoalConditionEngine({
+    condition: spec,
+    budget: { maxOuterTurns: REPL_GOAL_MAX_OUTER_TURNS },
+    now,
+  });
+}
+
+/** Display lines shown when a goal is set. */
+export function renderGoalStart(engine) {
+  return [
+    `◎ goal set: ${engine.condition.source}`,
+    `  evaluated after each turn (≤ ${engine.budget.maxOuterTurns} turns); /goal clear to drop, /goal to check`,
+  ];
+}
+
+/** Display lines for `/goal` with no argument (status). */
+export function renderGoalStatus(engine) {
+  if (!engine)
+    return [
+      "No session goal. Set one with /goal <condition>",
+      "  e.g. /goal exit-zero:npm test · /goal file-exists:dist/app.js · /goal contains:ALL GREEN · /goal the tests pass",
+    ];
+  const s = engine.state;
+  return [
+    `◎ goal: ${engine.condition.source}`,
+    `  progress: outer turn ${s.outerTurns}/${engine.budget.maxOuterTurns}` +
+      (isDeterministicCondition(engine.condition)
+        ? ` (${engine.condition.kind} check)`
+        : " (model-judged)"),
+  ];
+}
+
+/** Verdict display lines for one evaluation's decision + events. */
+export function renderGoalVerdict(decision, events) {
+  const evaluated = (events || []).find((e) => e.type === "goal_evaluated");
+  if (decision === GOAL_DECISION.COMPLETE) {
+    const done = (events || []).find((e) => e.type === "goal_completed");
+    return [
+      `✔ goal met: ${done?.reason ?? evaluated?.reason ?? "condition met"}`,
+    ];
+  }
+  if (decision === GOAL_DECISION.EXHAUSTED) {
+    const ex = (events || []).find((e) => e.type === "goal_exhausted");
+    return [
+      `⛔ goal dropped — ${ex?.reason ?? "budget exhausted"}${ex?.limit ? ` (${ex.limit})` : ""}`,
+    ];
+  }
+  return [
+    `◎ goal not yet met: ${evaluated?.reason ?? "unmet"} · outer turn ${evaluated?.outerTurns ?? "?"}`,
+  ];
+}
+
+/**
+ * Evaluate the session goal against a completed turn's final text. Deterministic
+ * conditions run inline (contains/regex on the text; exit-zero/file-exists via
+ * injected `spawnSync`/`existsSync`); a model condition delegates to `judge`.
+ *
+ * @param {GoalConditionEngine} engine
+ * @param {string} finalText  the assistant's answer this turn
+ * @param {object} deps { cwd, spawnSync, existsSync, judge, tokens, costUsd }
+ *   judge(condition, {finalText}) => {met, reason, evidence}
+ * @returns {Promise<{decision, events, done, met}>}
+ */
+export async function evaluateReplGoalTurn(engine, finalText, deps = {}) {
+  engine.recordTurnUsage({ tokens: deps.tokens, costUsd: deps.costUsd });
+  const cond = engine.condition;
+  let evaluation;
+  if (isDeterministicCondition(cond)) {
+    evaluation = runDeterministicCheck(cond, {
+      lastOutput: finalText,
+      cwd: deps.cwd,
+      spawnSync: deps.spawnSync,
+      existsSync: deps.existsSync,
+    });
+  } else if (typeof deps.judge === "function") {
+    evaluation = await deps.judge(cond, { finalText });
+  } else {
+    evaluation = {
+      met: false,
+      reason: "no model judge available for this condition",
+      evidence: { kind: "model" },
+    };
+  }
+  const { decision, events } = engine.evaluate(evaluation);
+  return {
+    decision,
+    events,
+    done: engine.done,
+    met: decision === GOAL_DECISION.COMPLETE,
+  };
+}