jules-orchestrator-kit 0.74.0 → 0.75.0

package/src/bidi-guard.mjs

@@ -1,36 +1,211 @@
 /**
- * Trojan Source (CVE-2021-42574) BiDi override detection.
+ * Unicode security detection for diffs and source text.
+ *
+ * Covers Trojan Source BiDi overrides (CVE-2021-42574), invisible/zero-width
+ * obfuscation characters, Unicode Plane 14 tags, and mixed-script confusable
+ * identifiers (Latin mixed with vetted Cyrillic/Greek lookalikes).
  *
- * Split out of src/security.mjs (P05). A Unicode directional override can make
- * the line an agent reads differ from the line the parser executes, so the
- * check runs on every added line of every non-markdown file before anything
- * else looks at the diff.
+ * Split out of src/security.mjs (P05). A Unicode directional override — or an
+ * invisible filler mid-token — can make the line an agent reads differ from
+ * the line the parser executes, so these checks run on every added line of
+ * every non-markdown file before anything else looks at the diff.
+ *
+ * Zero third-party deps; Node ESM builtins + the shared confusable table from
+ * secret-scanner.mjs only.
  */
 
-export function checkTrojanSource(diffOrText = "", _options = {}) {
-  if (!diffOrText || typeof diffOrText !== "string") return { ok: true, violations: [] };
+import { CONFUSABLE_TO_ASCII } from "./secret-scanner.mjs";
 
-  const violations = [];
-  const bidiRegex = /[\u202A\u202B\u202C\u202D\u202E\u2066\u2067\u2068\u2069\u061C\u200E\u200F]/;
+/**
+ * BiDi directional controls — the CVE-2021-42574 Trojan Source set (12 chars).
+ * Exported so scanDiff can locate the offending line without duplicating the set.
+ */
+export const BIDI_CONTROL_REGEX =
+  /[\u202A\u202B\u202C\u202D\u202E\u2066\u2067\u2068\u2069\u061C\u200E\u200F]/;
+
+/**
+ * Invisible ZW / Hangul fillers used to obfuscate identifiers on added lines:
+ * U+00AD, U+200B–U+200D, U+2060–U+2064, U+FEFF, U+034F, U+3164, U+FFA0,
+ * U+115F, U+1160.
+ */
+export const INVISIBLE_OBFUSCATION_REGEX =
+  /[\u00AD\u200B-\u200D\u2060-\u2064\uFEFF\u034F\u3164\uFFA0\u115F\u1160]/;
+
+/** Unicode Plane 14 language tags U+E0000–U+E007F. */
+export const PLANE14_TAG_REGEX = /[\u{E0000}-\u{E007F}]/u;
+
+/**
+ * Cyrillic/Greek entries from the secret-scanner confusable table.
+ * Latin lookalikes outside those scripts (ſ, K) are intentionally excluded —
+ * they are not mixed-script substitutions.
+ */
+const MIXED_SCRIPT_CONFUSABLE_CHARS = [...CONFUSABLE_TO_ASCII.keys()].filter((ch) => {
+  const cp = ch.codePointAt(0);
+  return (cp >= 0x0370 && cp <= 0x03ff) || (cp >= 0x0400 && cp <= 0x04ff);
+});
 
+const CONFUSABLE_CLASS = MIXED_SCRIPT_CONFUSABLE_CHARS.map(
+  (ch) => `\\u${ch.codePointAt(0).toString(16).padStart(4, "0")}`,
+).join("");
+
+/** Identifier-like tokens built from ASCII id chars and vetted confusables. */
+export const MIXED_SCRIPT_TOKEN_REGEX = new RegExp(
+  `[A-Za-z0-9_${CONFUSABLE_CLASS}]+`,
+  "g",
+);
+
+const HAS_LATIN_ID = /[A-Za-z0-9_]/;
+const HAS_CONFUSABLE = new RegExp(`[${CONFUSABLE_CLASS}]`);
+
+/**
+ * True when a line contains an identifier token that mixes Latin [A-Za-z0-9_]
+ * with at least one Cyrillic/Greek confusable (e.g. Cyrillic i or a in an ASCII token).
+ * Pure Cyrillic / Greek / multilingual text without intra-token Latin mixing
+ * does not match.
+ *
+ * @param {string} line
+ * @returns {boolean}
+ */
+export function hasMixedScriptConfusable(line) {
+  if (!line || typeof line !== "string") return false;
+  MIXED_SCRIPT_TOKEN_REGEX.lastIndex = 0;
+  let match;
+  while ((match = MIXED_SCRIPT_TOKEN_REGEX.exec(line)) !== null) {
+    const token = match[0];
+    if (HAS_LATIN_ID.test(token) && HAS_CONFUSABLE.test(token)) return true;
+  }
+  return false;
+}
+
+/**
+ * Select the lines to scan: added lines of a unified diff, or every line of
+ * plain text.
+ *
+ * @param {string} diffOrText
+ * @returns {string[]}
+ */
+function targetLines(diffOrText) {
   const lines = diffOrText.split("\n");
-  // Only filter diff syntax if we actually start with typical diff headers
+  // Only filter diff syntax if we actually start with typical diff headers.
   // This avoids treating text containing "+++ b/" as a diff mistakenly.
-  const isDiff = diffOrText.startsWith("--- a/") || diffOrText.startsWith("+++ b/") || diffOrText.includes("\n+++ b/");
+  const isDiff =
+    diffOrText.startsWith("--- a/") ||
+    diffOrText.startsWith("+++ b/") ||
+    diffOrText.includes("\n+++ b/");
 
-  const targetLines = lines.filter((line) => {
+  return lines.filter((line) => {
     if (isDiff) {
       return line.startsWith("+") && !line.startsWith("+++");
     }
     return true;
   });
+}
 
-  for (const line of targetLines) {
-    if (bidiRegex.test(line)) {
-      violations.push({ reason: "Trojan Source BiDi override detected: contains invisible directional control characters (CVE-2021-42574)." });
+/**
+ * Trojan Source (CVE-2021-42574) BiDi override detection.
+ * Backward-compatible: returns `{ ok, violations }` and only reports BiDi
+ * controls. Broader Unicode checks live in {@link checkUnicodeSecurity}.
+ *
+ * @param {string} [diffOrText=""]
+ * @param {object} [_options={}]
+ * @returns {{ ok: boolean, violations: Array<{ reason: string }> }}
+ */
+export function checkTrojanSource(diffOrText = "", _options = {}) {
+  if (!diffOrText || typeof diffOrText !== "string") return { ok: true, violations: [] };
+
+  const violations = [];
+  for (const line of targetLines(diffOrText)) {
+    if (BIDI_CONTROL_REGEX.test(line)) {
+      violations.push({
+        reason:
+          "Trojan Source BiDi override detected: contains invisible directional control characters (CVE-2021-42574).",
+      });
       break; // One violation is enough for the file/diff block
     }
   }
 
   return { ok: violations.length === 0, violations };
 }
+
+/**
+ * Full Unicode security pass over a diff or plain text.
+ *
+ * Categories (at most one finding each):
+ *   - TROJAN_SOURCE_DETECTED — BiDi controls (CVE-2021-42574)
+ *   - UNICODE_OBFUSCATION_DETECTED — ZW/Hangul fillers or Plane 14 tags
+ *   - MIXED_SCRIPT_CONFUSABLE_DETECTED — Latin+confusable identifier tokens
+ *
+ * @param {string} [diffOrText=""]
+ * @param {object} [_options={}]
+ * @returns {{
+ *   ok: boolean,
+ *   violations: Array<{ reason: string, type: string }>
+ * }}
+ */
+export function checkUnicodeSecurity(diffOrText = "", _options = {}) {
+  if (!diffOrText || typeof diffOrText !== "string") return { ok: true, violations: [] };
+
+  const violations = [];
+  let sawBidi = false;
+  let sawObfuscation = false;
+  let sawMixed = false;
+
+  for (const line of targetLines(diffOrText)) {
+    if (!sawBidi && BIDI_CONTROL_REGEX.test(line)) {
+      sawBidi = true;
+      violations.push({
+        type: "TROJAN_SOURCE_DETECTED",
+        reason:
+          "Trojan Source BiDi override detected: contains invisible directional control characters (CVE-2021-42574).",
+      });
+    }
+    if (
+      !sawObfuscation &&
+      (INVISIBLE_OBFUSCATION_REGEX.test(line) || PLANE14_TAG_REGEX.test(line))
+    ) {
+      sawObfuscation = true;
+      violations.push({
+        type: "UNICODE_OBFUSCATION_DETECTED",
+        reason:
+          "Unicode obfuscation detected: invisible zero-width, Hangul filler, or Plane 14 tag characters on an added line.",
+      });
+    }
+    if (!sawMixed && hasMixedScriptConfusable(line)) {
+      sawMixed = true;
+      violations.push({
+        type: "MIXED_SCRIPT_CONFUSABLE_DETECTED",
+        reason:
+          "Mixed-script confusable identifier detected: Latin characters combined with Cyrillic/Greek lookalikes in one token.",
+      });
+    }
+    if (sawBidi && sawObfuscation && sawMixed) break;
+  }
+
+  return { ok: violations.length === 0, violations };
+}
+
+/**
+ * Locate the first added-line number that triggers a given Unicode finding type.
+ * Shared by scanDiff so it does not re-embed detection regexes.
+ *
+ * @param {Array<{ text: string, no: number|null }>} lines
+ * @param {string} type
+ * @returns {number|null}
+ */
+export function locateUnicodeFindingLine(lines, type) {
+  if (!Array.isArray(lines)) return null;
+  for (const l of lines) {
+    if (!l || typeof l.text !== "string") continue;
+    const text = l.text;
+    let hit = false;
+    if (type === "TROJAN_SOURCE_DETECTED") {
+      hit = BIDI_CONTROL_REGEX.test(text);
+    } else if (type === "UNICODE_OBFUSCATION_DETECTED") {
+      hit = INVISIBLE_OBFUSCATION_REGEX.test(text) || PLANE14_TAG_REGEX.test(text);
+    } else if (type === "MIXED_SCRIPT_CONFUSABLE_DETECTED") {
+      hit = hasMixedScriptConfusable(text);
+    }
+    if (hit) return l.no ?? null;
+  }
+  return null;
+}

package/src/config.mjs

@@ -34,7 +34,7 @@ const DEFAULTS = {
 // use: an identical exfiltration job placed in `.gitlab-ci.yml` was approved
 // where `.github/workflows/x.yml` was rejected. A safety gate that is only
 // safe on GitHub is not a safety gate.
-const CI_DEFINITIONS = [
+export const CI_DEFINITIONS = [
   ".github/**",
   ".gitlab-ci.yml",
   "**/.gitlab-ci.yml",
@@ -1019,9 +1019,11 @@ export function resolveTrustedPolicy(root = process.cwd(), baseRef = null, mode
 
   let trustedConfigRaw = null;
   let trustedJulesRaw = null;
+  let trustedProtectedRaw = null;
   try {
     trustedConfigRaw = showFromOrigin(root, base, ".agent/config.yml");
     trustedJulesRaw = showFromOrigin(root, base, ".agent/jules.yml");
+    trustedProtectedRaw = showFromOrigin(root, base, ".agent/protected-paths.json");
   } catch (_) {
     // If base branch cannot be resolved or show fails, let changedFiles report code 1
   }
@@ -1035,7 +1037,21 @@ export function resolveTrustedPolicy(root = process.cwd(), baseRef = null, mode
       if (raw) parsed = parseYaml(raw) || {};
     } catch (_) {}
 
+    let trustedProtectedPaths = [];
+    if (trustedProtectedRaw) {
+      try {
+        const parsedProtected = JSON.parse(trustedProtectedRaw);
+        if (Array.isArray(parsedProtected.protected)) {
+          trustedProtectedPaths = parsedProtected.protected.filter((p) => typeof p === "string" && p);
+        }
+      } catch (_) {}
+    }
+
     const trustedScope = normalizeScope(parsed);
+    if (trustedProtectedPaths.length > 0) {
+      trustedScope.protect = dedupe([...trustedScope.protect, ...trustedProtectedPaths]);
+      trustedScope.protectedPatterns = trustedProtectedPaths;
+    }
     const trustedDiffKb = Number(parsed.limits?.diff_kb || parsed.limits?.diffKb) || 75;
 
     const rawSetup = parsed.setup_cmd ?? parsed.verify?.setup;
@@ -1100,6 +1116,7 @@ export function resolveTrustedPolicy(root = process.cwd(), baseRef = null, mode
   // Inspect any proposed scaffold in this change (F06)
   let proposedConfig = null;
   let proposedJules = null;
+  let proposedProtectedPaths = [];
 
   try {
     if (mode === "committed") {
@@ -1107,11 +1124,29 @@ export function resolveTrustedPolicy(root = process.cwd(), baseRef = null, mode
       if (c) proposedConfig = parseYaml(c);
       const j = showFromOrigin(root, "HEAD", ".agent/jules.yml");
       if (j) proposedJules = parseYaml(j);
+      const p = showFromOrigin(root, "HEAD", ".agent/protected-paths.json");
+      if (p) {
+        try {
+          const parsedP = JSON.parse(p);
+          if (Array.isArray(parsedP.protected)) {
+            proposedProtectedPaths = parsedP.protected.filter((x) => typeof x === "string" && x);
+          }
+        } catch (_) {}
+      }
     } else {
       const configPath = join(root, ".agent/config.yml");
       if (existsSync(configPath)) proposedConfig = parseYaml(readFileSync(configPath, "utf-8"));
       const julesPath = join(root, ".agent/jules.yml");
       if (existsSync(julesPath)) proposedJules = parseYaml(readFileSync(julesPath, "utf-8"));
+      const protectedPath = join(root, ".agent/protected-paths.json");
+      if (existsSync(protectedPath)) {
+        try {
+          const parsedP = JSON.parse(readFileSync(protectedPath, "utf-8"));
+          if (Array.isArray(parsedP.protected)) {
+            proposedProtectedPaths = parsedP.protected.filter((x) => typeof x === "string" && x);
+          }
+        } catch (_) {}
+      }
     }
   } catch (_) {}
 
@@ -1182,6 +1217,10 @@ export function resolveTrustedPolicy(root = process.cwd(), baseRef = null, mode
 
   const stages = explicitStages ?? profilePlan?.stages ?? null;
   const trustedScope = normalizeScope(pConfig);
+  if (proposedProtectedPaths.length > 0) {
+    trustedScope.protect = dedupe([...trustedScope.protect, ...proposedProtectedPaths]);
+    trustedScope.protectedPatterns = proposedProtectedPaths;
+  }
   const trustedLimits = {
     diffKb: Number(pConfig.limits?.diff_kb || pConfig.limits?.diffKb) || 75,
   };

package/src/engine.mjs

@@ -1,4 +1,4 @@
-import { loadConfig, resolveTrustedPolicy } from "./config.mjs";
+import { loadConfig, resolveTrustedPolicy, normalizePath } from "./config.mjs";
 import { isTestPath } from "./test-paths.mjs";
 import { isPlaceholderTestScript, isSrcLayout } from "./stack-detector.mjs";
 import { checkCollectionFloor } from "./ops/test-collection.mjs";
@@ -10,9 +10,9 @@ import { withBudget, appendLedger, getQueueDir, ensureDir, rollbackBudgetReserva
 import { resolveDailyLimit, recordObservedCeiling, isDailyQuotaRejection, resolveAmbientIdentity } from "./budget.mjs";
 import { sanitizeUntrustedData, buildAgentEnvelope } from "./prompt-guard.mjs";
 import { recordVerifyRun, readVerifyRuns, flakyVerdict } from "./flaky-ledger.mjs";
-import fs, { readdirSync, readFileSync, renameSync, existsSync } from "node:fs";
+import fs, { readdirSync, readFileSync, writeFileSync, renameSync, existsSync } from "node:fs";
 import { join, basename } from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { appendTelemetryBestEffort as appendTelemetry } from "./telemetry.mjs";
 
 import { spawn } from "node:child_process";
@@ -207,6 +207,7 @@ export async function gate(opts = {}) {
       process.env.JULES_ALLOW_COMMAND_FILE_CHANGES === "1" ||
       process.env.AGENT_ALLOW_COMMAND_FILE_CHANGES === "true" ||
       process.env.AGENT_ALLOW_COMMAND_FILE_CHANGES === "1",
+    protectedPatterns: trustedScope.protectedPatterns,
   });
   // Report the violation against the link the change actually introduced, not
   // against a path the diff never names — the operator has to be able to find it.
@@ -336,8 +337,18 @@ export async function gate(opts = {}) {
   // failures stop reaching the exit code — the gate then sees exit 0 and
   // approves a change whose tests failed. src/perf.mjs already strips these for
   // the same reason; the gate, which is the one that decides, did not.
+  // Ambient PR waiver labels and HEAD_SHA must also be stripped so verification
+  // suites and child audits run hermetically without inherited waivers.
   for (const key of Object.keys(testEnv)) {
-    if (key.startsWith("NODE_TEST_") || key.startsWith("NODE_CHANNEL_")) delete testEnv[key];
+    if (
+      key.startsWith("NODE_TEST_") ||
+      key.startsWith("NODE_CHANNEL_") ||
+      key === "PR_LABELS" ||
+      key === "HEAD_SHA" ||
+      key.startsWith("JULES_ALLOW_")
+    ) {
+      delete testEnv[key];
+    }
   }
 
   let flakyVerdictResult = null;
@@ -815,12 +826,69 @@ export async function repair(failure, opts = {}) {
     threshold: 2,
   });
 
+  const repairId = `repair-${Date.now()}-${randomUUID().slice(0, 8)}`;
+  let repairDir = null;
+
   let currentFailure = failure;
   const initialFingerprint = fingerprintFailureState(currentFailure, root);
   breaker.observe(initialFingerprint);
   whackAMole.recordTestOutcome(currentFailure.stderr || currentFailure.message);
   let extraPromptDirective = null;
 
+  const persistFailedAttempt = (n, diff, diagnostics) => {
+    const relDir = normalizePath(join(".agent/state/repairs", repairId));
+    const absDir = join(root, relDir);
+    ensureDir(absDir);
+    const patchName = `attempt-${n}.patch`;
+    const diagName = `attempt-${n}-diagnostics.json`;
+    const patchRel = normalizePath(join(relDir, patchName));
+    const diagRel = normalizePath(join(relDir, diagName));
+    writeFileSync(join(absDir, patchName), redactSecrets(String(diff || "")), "utf-8");
+    const payload = {
+      ...diagnostics,
+      patchPath: patchRel,
+      diagnosticsPath: diagRel,
+    };
+    writeFileSync(join(absDir, diagName), JSON.stringify(payload, null, 2) + "\n", "utf-8");
+    repairDir = relDir;
+    return payload;
+  };
+
+  const captureAttemptDiff = () => {
+    try {
+      // Working-tree mode retains what the repair attempt left on disk; the
+      // default committed mode only shows the last commit and would hide
+      // uncommitted agent edits that operators need to review.
+      const base = config.baseBranch || config.base || "main";
+      return diffText(root, base, "working-tree") || "";
+    } catch (_) {
+      return "";
+    }
+  };
+
+  const buildGateDiagnostics = (gateRes) => {
+    const failingPhase = (gateRes.phases || []).find((p) => p && p.ok === false) || null;
+    const verifyPhase = (gateRes.phases || []).find((p) => p && p.phase === "verify") || null;
+    const failureInfo = verifyPhase?.failure || null;
+    const testResult = verifyPhase?.testResult || null;
+    const stderr = failureInfo?.stderr || testResult?.stderr || gateRes.error || "";
+    const stdout = failureInfo?.stdout || testResult?.stdout || "";
+    return {
+      code: gateRes.code ?? null,
+      phase: failingPhase?.phase || "verify",
+      command: failureInfo?.command || testResult?.command || null,
+      exitCode: failureInfo?.exitCode ?? testResult?.status ?? null,
+      stderr: redactSecrets(String(stderr).slice(0, 8000)),
+      stdout: redactSecrets(String(stdout).slice(0, 4000)),
+      messages: Array.isArray(failureInfo?.diagnostics) ? failureInfo.diagnostics.map((d) => redactSecrets(String(d))) : [],
+      error: redactSecrets(
+        String(gateRes.error || failureInfo?.stderr || testResult?.stderr || "Gate re-verification failed")
+          .split("\n")[0]
+          .slice(0, 500)
+      ),
+    };
+  };
+
   for (let n = 1; n <= maxRetries; n++) {
     if (progressBus && progressToken) {
       progressBus.reportProgress(progressToken, Math.round((n / maxRetries) * 100), 100, `OODA Repair attempt ${n}/${maxRetries}`);
@@ -847,7 +915,14 @@ export async function repair(failure, opts = {}) {
         const retryAfterMs = err.retryAfterMs || 60000;
         const backoffSec = Math.ceil(retryAfterMs / 1000);
         console.warn(`[PROVIDER_INFRASTRUCTURE_FAILURE] ${err.name}: ${err.message}. Recommended backoff: ${backoffSec}s.`);
-        attempts.push({ n, ok: false, error: err.message, providerError: true, retryAfterMs });
+        attempts.push({
+          n,
+          ok: false,
+          phase: "dispatch",
+          error: err.message,
+          providerError: true,
+          retryAfterMs,
+        });
         appendTelemetry(root, "ooda_repair_attempt", { attempt: n, ok: false, error: err.message, providerError: true });
         return {
           ok: false,
@@ -856,9 +931,10 @@ export async function repair(failure, opts = {}) {
           error: err.message,
           retryAfterMs,
           providerError: true,
+          repairDir,
         };
       }
-      attempts.push({ n, ok: false, error: err.message });
+      attempts.push({ n, ok: false, phase: "dispatch", error: err.message });
       appendTelemetry(root, "ooda_repair_attempt", { attempt: n, ok: false, error: err.message });
       break;
     }
@@ -898,17 +974,21 @@ export async function repair(failure, opts = {}) {
       }
     }
 
-    attempts.push({
-      n,
-      session,
-      ok: true,
-      poll: pollVerdict ? { status: pollVerdict.status, terminal: pollVerdict.terminal } : null,
-    });
-    appendTelemetry(root, "ooda_repair_attempt", { attempt: n, ok: true });
+    const poll = pollVerdict ? { status: pollVerdict.status, terminal: pollVerdict.terminal } : null;
 
     // Re-verify after repair attempt
     const gateRes = await gate({ root, config, fix: false, progressBus, progressToken });
+    const attemptDiff = captureAttemptDiff();
     if (gateRes.ok) {
+      attempts.push({
+        n,
+        session,
+        ok: true,
+        verified: true,
+        diff: attemptDiff,
+        poll,
+      });
+      appendTelemetry(root, "ooda_repair_attempt", { attempt: n, ok: true, verified: true });
       breaker.reset();
       whackAMole.reset();
       recordRemediation(root, {
@@ -917,9 +997,27 @@ export async function repair(failure, opts = {}) {
         remediationHint: `Resolved on repair attempt #${n}`,
         targetFiles: currentFailure.targetFiles || [],
       });
-      return { ok: true, attempts, finalStatus: "PASSED" };
+      return { ok: true, attempts, finalStatus: "PASSED", repairDir };
     }
 
+    const diagnostics = persistFailedAttempt(n, attemptDiff, buildGateDiagnostics(gateRes));
+    attempts.push({
+      n,
+      session,
+      ok: false,
+      verified: false,
+      diff: attemptDiff,
+      diagnostics,
+      poll,
+    });
+    appendTelemetry(root, "ooda_repair_attempt", {
+      attempt: n,
+      ok: false,
+      verified: false,
+      code: gateRes.code ?? null,
+      phase: diagnostics.phase,
+    });
+
     currentFailure = gateRes.phases.find((p) => p.phase === "verify")?.testResult || failure;
     const currentFingerprint = fingerprintFailureState(currentFailure, root);
 
@@ -943,6 +1041,7 @@ export async function repair(failure, opts = {}) {
         finalStatus: "DETERMINISTIC_REGRESSION",
         reason: `Identical failure state fingerprint (${currentFingerprint}) observed during attempt #${n}`,
         fingerprint: currentFingerprint,
+        repairDir,
       };
     }
   }
@@ -963,39 +1062,66 @@ export async function repair(failure, opts = {}) {
     });
   } catch (_) {}
 
-  return { ok: false, attempts, finalStatus: "OODA_EXHAUSTED" };
+  return { ok: false, attempts, finalStatus: "OODA_EXHAUSTED", repairDir };
 
 }
 
 /**
- * Polls an async provider for terminal session state (COMPLETED / FAILED) before re-verification.
- */
-/**
- * Evaluates whether a task's verification oracle or goal is already satisfied on the current working tree.
- * Prevents redundant session dispatch and API budget burning.
+ * A passing generic test suite does not prove that a requested feature exists.
+ * Only an explicit goal-specific check may suppress dispatch. This is advisory:
+ * the supplied command must return 0 exactly when the requested state exists.
  */
 export async function checkTaskPremise(task = {}, opts = {}) {
   const root = opts.config?._root || opts.root || process.cwd();
-  const verifyCmd = task.verifyCmd || task.verify;
-  if (!verifyCmd) {
-    return { satisfied: false, reason: "No verification oracle specified for pre-flight premise check." };
+  const goalCheck = task.goalCheck ?? opts.goalCheck;
+  const evidence = { revision: null, goalCheckSha256: null, exitCode: null, durationMs: null };
+  const unknown = (reasonCode, reason) => ({ satisfied: false, status: "UNKNOWN", reasonCode, reason, evidence });
+  if (typeof goalCheck !== "string" || !goalCheck.trim()) {
+    return unknown("NO_GOAL_CHECK", "No explicit goal-specific check supplied; a passing verification suite is not proof that the task is complete.");
   }
-
-  const { runVerificationProbe } = await import("./wizard-oracle.mjs");
-  const probe = await runVerificationProbe(verifyCmd, root, { timeoutMs: opts.timeoutMs || 30_000 });
-  if (probe.ok) {
-    return {
-      satisfied: true,
-      reason: `Verification oracle '${verifyCmd}' already passes cleanly with exit code 0 on base branch.`,
-      durationMs: probe.durationMs,
-    };
+  const command = goalCheck.trim();
+  evidence.goalCheckSha256 = sha256(command);
+  if (isPlaceholderTestScript(command)) {
+    return unknown("PLACEHOLDER_GOAL_CHECK", "Goal check is a no-op or incapable of establishing the requested state.");
+  }
+  const genericCommands = [
+    task.verifyCmd, task.verify,
+    opts.config?.verify?.test, opts.config?.verify?.unit,
+    opts.config?.verify?.lint, opts.config?.verify?.build,
+  ].filter((value) => typeof value === "string").map((value) => value.trim());
+  if (genericCommands.includes(command)) {
+    return unknown("GENERIC_VERIFY_IS_NOT_GOAL_PROOF", "Goal check matches the generic verification command; provide a separate objective-specific condition.");
   }
 
-  return {
-    satisfied: false,
-    reason: `Verification oracle '${verifyCmd}' failed (exit ${probe.code}), proving task need.`,
-    durationMs: probe.durationMs,
+  // The check runs against the working tree. A clean tree and stable HEAD are
+  // prerequisites for attributing a successful result to a committed revision.
+  const snapshot = () => {
+    try {
+      const head = runCmd(["git", "rev-parse", "HEAD"], { cwd: root, ignoreError: true, timeout: 5000 });
+      const state = runCmd(["git", "status", "--porcelain", "--untracked-files=all"], { cwd: root, ignoreError: true, timeout: 5000 });
+      if (head.status !== 0 || state.status !== 0 || !/^[0-9a-f]{40,64}$/.test(head.stdout.trim())) return null;
+      return { revision: head.stdout.trim(), clean: !state.stdout.trim() };
+    } catch (_) {
+      return null;
+    }
   };
+  const before = snapshot();
+  if (!before) return unknown("GIT_STATE_UNAVAILABLE", "Cannot establish the Git revision and working-tree state.");
+  evidence.revision = before.revision;
+  if (!before.clean) return unknown("DIRTY_WORKTREE", "The working tree is not clean; goal proof cannot be attributed to the committed revision.");
+
+  const { runVerificationProbe } = await import("./wizard-oracle.mjs");
+  const probe = await runVerificationProbe(command, root, { timeoutMs: opts.timeoutMs || 30_000 });
+  evidence.exitCode = probe.code;
+  evidence.durationMs = probe.durationMs;
+  const after = snapshot();
+  if (!after || after.revision !== before.revision || !after.clean) {
+    return unknown("GIT_STATE_CHANGED", "The goal check changed the repository state or revision; its result cannot justify skipping dispatch.");
+  }
+  if (!probe.ok) {
+    return { satisfied: false, status: "NOT_PROVEN", reasonCode: "GOAL_CHECK_NOT_SATISFIED", reason: "The goal-specific check did not establish the requested state.", evidence };
+  }
+  return { satisfied: true, status: "PROVEN", reasonCode: "GOAL_CHECK_SATISFIED", reason: "Explicit goal-specific check passed on an unchanged, clean Git revision.", evidence };
 }
 
 /**
@@ -1181,17 +1307,28 @@ export async function dispatch(task = {}, opts = {}) {
     throw new Error(`Task prompt exceeds maximum payload limit of ${config.limits.promptKb} KB`);
   }
 
-  // Pre-flight idempotency premise check
-  if (opts.checkPremise || task.checkPremise) {
-    const premise = await checkTaskPremise(task, { root, config });
-    if (premise.satisfied) {
-      return {
-        id: "premise-already-satisfied",
-        status: "ALREADY_SATISFIED",
-        skipped: true,
-        reason: premise.reason,
-      };
-    }
+  // Record both positive and negative decisions. A generic green test suite
+  // must never be mistaken for proof that a requested task is complete.
+  const premiseRequested = Boolean(opts.checkPremise || task.checkPremise);
+  const premise = premiseRequested
+    ? (opts.dryRun
+        ? { satisfied: false, reasonCode: "DRY_RUN", reason: "Preview does not execute the goal check.", evidence: { revision: null, goalCheckSha256: null, exitCode: null, durationMs: null } }
+        : await checkTaskPremise(task, { root, config }))
+    : { satisfied: false, reasonCode: "PREMISE_CHECK_NOT_REQUESTED", evidence: null };
+  appendTelemetry(root, "dispatch_decision", {
+    taskId: task.id || task.taskId || null,
+    decision: premise.satisfied ? "SKIP" : "DISPATCH",
+    reasonCode: premise.reasonCode,
+    evidence: premise.evidence,
+  });
+  if (premise.satisfied) {
+    return {
+      id: "premise-already-satisfied",
+      status: "ALREADY_SATISFIED",
+      skipped: true,
+      reason: premise.reason,
+      evidence: premise.evidence,
+    };
   }
 
   // Redact secrets in prompt before dispatching