jules-orchestrator-kit 0.29.1 → 0.32.0

package/src/engine.mjs

@@ -2,15 +2,32 @@ import { loadConfig, parseYaml, normalizeScope } from "./config.mjs";
 import { checkScope, scanDiff, redactSecrets } from "./security.mjs";
 import { changedFiles, diffBytes, diffText, showFromOrigin, runCmd } from "./git.mjs";
 import { createProvider, ProviderRateLimitError, ProviderUnavailableError } from "./provider.mjs";
-import { withBudget, appendLedger, getQueueDir, ensureDir, rollbackBudgetReservation } from "./state.mjs";
+import { withBudget, appendLedger, getQueueDir, ensureDir, rollbackBudgetReservation, isConcurrencyGroupLocked } from "./state.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 { join } from "node:path";
+import { join, basename } from "node:path";
 import { createHash } from "node:crypto";
-import { appendTelemetry } from "./telemetry.mjs";
+import { appendTelemetry as appendTelemetryUnsafe } from "./telemetry.mjs";
 
-export { recordVerifyRun, readVerifyRuns, flakyVerdict, sanitizeUntrustedData };
+import { spawn } from "node:child_process";
+import { resolveAffectedTests } from "./dag-engine.mjs";
+import { recordRemediation, queryRemediations, harvestFailureRecord, hydrateMemory } from "./remediation.mjs";
+
+export { recordVerifyRun, readVerifyRuns, flakyVerdict, sanitizeUntrustedData, resolveAffectedTests, recordRemediation, queryRemediations, harvestFailureRecord, hydrateMemory, isConcurrencyGroupLocked };
+
+
+function appendTelemetry(root, kind, fields = {}) {
+  try {
+    return appendTelemetryUnsafe(root, kind, fields);
+  } catch (_) {
+    return null;
+  }
+}
+
+function isSafeQueueFileName(fileName) {
+  return typeof fileName === "string" && fileName.length > 0 && basename(fileName) === fileName && fileName !== "." && fileName !== "..";
+}
 
 /**
  * Validates whether a file in .agent/jules-queue/ is a task file.
@@ -128,8 +145,11 @@ export async function gate(opts = {}) {
       trustedScope = normalizeScope(parsed);
       if (parsed.verify || parsed.test_cmd || parsed.build_cmd) {
         trustedVerify = {
+          setup: parsed.verify?.setup || config.verify.setup,
           test: parsed.verify?.test || parsed.test_cmd || config.verify.test,
+          teardown: parsed.verify?.teardown || config.verify.teardown,
           build: parsed.verify?.build || parsed.build_cmd || config.verify.build,
+          timeoutMs: parsed.verify?.timeoutMs || parsed.verify?.timeout_ms || config.verify.timeoutMs,
         };
       }
     } catch (_) {}
@@ -201,34 +221,79 @@ export async function gate(opts = {}) {
   let flakyVerdictResult = null;
 
   if (testCmd) {
-    const startTime = Date.now();
-    const res = runCmd(testCmd, { cwd: root, ignoreError: true, env: testEnv });
-    const durationMs = Date.now() - startTime;
-    testResult = { ok: res.status === 0, status: res.status, stdout: res.stdout, stderr: res.stderr, command: testCmd };
-
-    const fingerprint = !testResult.ok ? fingerprintFailureState(testResult, root) : null;
-    recordVerifyRun(root, testCmd, testResult.ok, fingerprint, durationMs);
-
-    if (!testResult.ok) {
-      const runs = readVerifyRuns(root, testCmd);
-      flakyVerdictResult = flakyVerdict(runs);
-      if (flakyVerdictResult.verdict === "QUARANTINED") {
-        phases.push({ phase: "verify", ok: false, testResult, buildResult, flakyVerdict: flakyVerdictResult });
-        appendTelemetry(root, "gate_phase", { phase: "verify", ok: false, quarantined: true });
-        appendTelemetry(root, "gate_finished", { ok: false, code: 8 });
-        return { ok: false, code: 8, phases, flakyVerdict: flakyVerdictResult };
+    const setupCmd = trustedVerify.setup;
+    const teardownCmd = trustedVerify.teardown;
+    const verifyTimeout = trustedVerify.timeoutMs;
+
+    try {
+      if (setupCmd) {
+        const setupRes = runCmd(setupCmd, { cwd: root, ignoreError: true, env: testEnv, timeout: verifyTimeout });
+        if (setupRes.status !== 0) {
+          testResult = {
+            ok: false,
+            status: setupRes.status,
+            stdout: redactSecrets(setupRes.stdout || ""),
+            stderr: redactSecrets(setupRes.stderr || ""),
+            command: setupCmd,
+            phase: "setup",
+          };
+        }
+      }
+
+      if (testResult.ok) {
+        const startTime = Date.now();
+        const res = runCmd(testCmd, { cwd: root, ignoreError: true, env: testEnv, timeout: verifyTimeout });
+        const durationMs = Date.now() - startTime;
+        testResult = {
+          ok: res.status === 0,
+          status: res.status,
+          stdout: redactSecrets(res.stdout || ""),
+          stderr: redactSecrets(res.stderr || ""),
+          command: testCmd,
+        };
+
+        const fingerprint = !testResult.ok ? fingerprintFailureState(testResult, root) : null;
+        recordVerifyRun(root, testCmd, testResult.ok, fingerprint, durationMs);
+
+        if (!testResult.ok) {
+          const runs = readVerifyRuns(root, testCmd);
+          flakyVerdictResult = flakyVerdict(runs);
+          if (flakyVerdictResult.verdict === "QUARANTINED") {
+            phases.push({ phase: "verify", ok: false, testResult, buildResult, flakyVerdict: flakyVerdictResult });
+            appendTelemetry(root, "gate_phase", { phase: "verify", ok: false, quarantined: true });
+            appendTelemetry(root, "gate_finished", { ok: false, code: 8 });
+            return { ok: false, code: 8, phases, flakyVerdict: flakyVerdictResult };
+          }
+        }
+      }
+    } finally {
+      if (teardownCmd) {
+        try {
+          runCmd(teardownCmd, { cwd: root, ignoreError: true, env: testEnv });
+        } catch (_) {}
       }
     }
   }
 
   if (testResult.ok && buildCmd) {
     const res = runCmd(buildCmd, { cwd: root, ignoreError: true, env: testEnv });
-    buildResult = { ok: res.status === 0, status: res.status, stdout: res.stdout, stderr: res.stderr, command: buildCmd };
+    buildResult = {
+      ok: res.status === 0,
+      status: res.status,
+      stdout: redactSecrets(res.stdout || ""),
+      stderr: redactSecrets(res.stderr || ""),
+      command: buildCmd,
+    };
   }
 
-  const verifyOk = testResult.ok && buildResult.ok;
-  const failingCmd = !testResult.ok ? testResult : !buildResult.ok ? buildResult : null;
-  phases.push({ phase: "verify", ok: verifyOk, testResult, buildResult });
+  let serverResult = { ok: true, status: 0 };
+  if (testResult.ok && buildResult.ok && trustedVerify.server && trustedVerify.server.command) {
+    serverResult = await probeDevServer(trustedVerify.server, root);
+  }
+
+  const verifyOk = testResult.ok && buildResult.ok && serverResult.ok;
+  const failingCmd = !testResult.ok ? testResult : !buildResult.ok ? buildResult : !serverResult.ok ? serverResult : null;
+  phases.push({ phase: "verify", ok: verifyOk, testResult, buildResult, serverResult });
   appendTelemetry(root, "gate_phase", { phase: "verify", ok: verifyOk });
   if (progressBus && progressToken) {
     progressBus.reportProgress(progressToken, 100, 100, "Phase 4/4: Automated Test & Build Verification complete");
@@ -342,7 +407,7 @@ export async function repair(failure, opts = {}) {
       );
     } catch (err) {
       if (err instanceof ProviderRateLimitError || err instanceof ProviderUnavailableError) {
-        if (err.reservationId) {
+        if (err.reservationId && !err.budgetReservationRolledBack) {
           rollbackBudgetReservation(root, err.reservationId);
         }
         const retryAfterMs = err.retryAfterMs || 60000;
@@ -381,6 +446,12 @@ export async function repair(failure, opts = {}) {
     const gateRes = await gate({ root, config, fix: false, progressBus, progressToken });
     if (gateRes.ok) {
       breaker.reset();
+      recordRemediation(root, {
+        fingerprint: initialFingerprint,
+        symptom: currentFailure.stderr || currentFailure.message || "Failure resolved by OODA repair",
+        remediationHint: `Resolved on repair attempt #${n}`,
+        targetFiles: currentFailure.targetFiles || [],
+      });
       return { ok: true, attempts, finalStatus: "PASSED" };
     }
 
@@ -389,6 +460,12 @@ export async function repair(failure, opts = {}) {
 
     const check = breaker.observe(currentFingerprint);
     if (check.tripped) {
+      harvestFailureRecord(root, {
+        fingerprint: currentFingerprint,
+        symptom: currentFailure.stderr || currentFailure.message || "Deterministic Regression",
+        remediationHint: `Identical failure state fingerprint (${currentFingerprint}) observed during attempt #${n}`,
+        targetFiles: currentFailure.targetFiles || [],
+      });
       return {
         ok: false,
         attempts,
@@ -399,7 +476,15 @@ export async function repair(failure, opts = {}) {
     }
   }
 
+  harvestFailureRecord(root, {
+    fingerprint: initialFingerprint,
+    symptom: currentFailure.stderr || currentFailure.message || "OODA Repair Exhausted",
+    remediationHint: "OODA repair attempts exhausted without clean verification pass.",
+    targetFiles: currentFailure.targetFiles || [],
+  });
+
   return { ok: false, attempts, finalStatus: "OODA_EXHAUSTED" };
+
 }
 
 /**
@@ -473,7 +558,10 @@ Stderr:
 ${cleanStderr}`;
 }
 
-export async function dispatch(task, opts = {}) {
+export async function dispatch(task = {}, opts = {}) {
+  if (!task || typeof task !== "object") {
+    throw new TypeError("Dispatch task must be an object");
+  }
   const root = opts.config?._root || opts.root || process.cwd();
   const config = opts.config || loadConfig(root);
   const provider = createProvider(config.provider, config);
@@ -487,11 +575,15 @@ export async function dispatch(task, opts = {}) {
   // Redact secrets in prompt before dispatching
   const cleanPrompt = redactSecrets(task.prompt || "");
 
-  // Wire Prompt Guard & Envelope to wrap raw task arguments
+  // Wire Prompt Guard, Memory Hydration & Envelope to wrap raw task arguments
   const taskInstructions = task.taskInstructions || cleanPrompt || task.title || "Autonomous Task Execution";
   const untrustedData = Array.isArray(task.untrustedData) ? task.untrustedData : [];
   const systemPolicy = task.systemPolicy || config.systemPolicy || "";
-  const envelopedPrompt = buildAgentEnvelope(systemPolicy, taskInstructions, untrustedData);
+
+  const targetFiles = Array.isArray(task.targetFiles) ? task.targetFiles : (Array.isArray(task.referenced_paths) ? task.referenced_paths : []);
+  const learnedRemediations = task.learnedRemediations || hydrateMemory(root, { targetFiles, fingerprint: task.fingerprint || "" });
+
+  const envelopedPrompt = buildAgentEnvelope(systemPolicy, taskInstructions, untrustedData, { learnedRemediations });
 
   const cleanTask = { ...task, prompt: envelopedPrompt };
 
@@ -503,7 +595,7 @@ export async function dispatch(task, opts = {}) {
     );
   } catch (err) {
     if (err instanceof ProviderRateLimitError || err instanceof ProviderUnavailableError) {
-      if (err.reservationId) {
+      if (err.reservationId && !err.budgetReservationRolledBack) {
         rollbackBudgetReservation(root, err.reservationId);
       }
       const retryAfterMs = err.retryAfterMs || 60000;
@@ -534,7 +626,8 @@ export async function run(tasksOrOpts = {}, opts = {}) {
 
   const root = options.root || process.cwd();
   const config = options.config || loadConfig(root);
-  const concurrency = options.concurrency || config.limits.concurrency || 1;
+  const requestedConcurrency = Number(options.concurrency ?? config.limits.concurrency ?? 1);
+  const concurrency = Number.isInteger(requestedConcurrency) && requestedConcurrency > 0 ? requestedConcurrency : 1;
   const isDry = options.dryRun !== undefined ? options.dryRun : (process.env.JULES_DRY_RUN === "true" || process.env.JULES_DRY_RUN === "1");
   const queueDir = getQueueDir(root);
   const completedDir = join(queueDir, "completed");
@@ -553,15 +646,25 @@ export async function run(tasksOrOpts = {}, opts = {}) {
     const batch = filesToProcess.slice(i, i + concurrency);
     await Promise.all(
       batch.map(async (fileOrItem) => {
-        const fileName = typeof fileOrItem === "string" ? fileOrItem : fileOrItem.id || fileOrItem.file || fileOrItem.title || "task";
-        const srcPath = join(queueDir, fileName);
+        const fileName = typeof fileOrItem === "string" ? fileOrItem : fileOrItem?.id || fileOrItem?.file || fileOrItem?.title || "task";
         try {
+          if (!isSafeQueueFileName(fileName)) {
+            throw new Error(`Unsafe queue task path: ${fileName}`);
+          }
+          const srcPath = join(queueDir, fileName);
           let prompt = typeof fileOrItem === "object" && fileOrItem.prompt ? fileOrItem.prompt : "";
           let title = typeof fileOrItem === "object" && fileOrItem.title ? fileOrItem.title : fileName;
           if (!prompt && existsSync(srcPath)) {
             prompt = await fs.promises.readFile(srcPath, "utf-8");
           }
           const task = typeof fileOrItem === "object" ? { ...fileOrItem, title, prompt } : { title, prompt };
+
+          const groupName = task.concurrency_group || task.concurrencyGroup || "";
+          if (groupName && isConcurrencyGroupLocked(groupName, root, task.id || fileName)) {
+            results.push({ file: fileName, ok: false, status: "SKIPPED_CONCURRENCY_GROUP_LOCKED", reason: `Concurrency group '${groupName}' is active` });
+            return;
+          }
+
           const session = await dispatch(task, { root, config, dryRun: isDry });
 
           if (session && session.ok === false) {
@@ -569,6 +672,9 @@ export async function run(tasksOrOpts = {}, opts = {}) {
           } else {
             const dstPath = join(completedDir, fileName);
             if (existsSync(srcPath)) {
+              if (existsSync(dstPath)) {
+                throw new Error(`Completed task destination already exists: ${fileName}`);
+              }
               renameSync(srcPath, dstPath);
             }
             appendLedger({ event: "task_completed", file: fileName, session }, root);
@@ -581,5 +687,198 @@ export async function run(tasksOrOpts = {}, opts = {}) {
     );
   }
 
+
   return { processed: results.length, results };
 }
+
+/**
+ * Synthesizes a structured, evidence-backed PR description body for GitHub PR creation.
+ * @param {object} session - Session or dispatch result
+ * @param {object} gateResult - Gate evaluation result
+ * @param {object} [options]
+ * @returns {string} Markdown PR description body
+ */
+export function synthesizePrDescription(session = {}, gateResult = {}, options = {}) {
+  const sessionId = session.id || session.name || "jules-session";
+  const attemptsCount = session.attempts?.length || session._warmAttempts || 1;
+  const maxAttempts = options.maxAttempts || 3;
+  const durationMs = options.durationMs || session.durationMs || 0;
+  const durationSec = (durationMs / 1000).toFixed(1);
+  const isWarm = Boolean(session.resumed || session._warmResumed);
+
+  const phases = gateResult.phases || [];
+  const scopePhase = phases.find((p) => p.phase === "scope") || { ok: true, violations: [] };
+  const payloadPhase = phases.find((p) => p.phase === "payload") || { ok: true, bytes: 0, limitBytes: 76800 };
+  const secretPhase = phases.find((p) => p.phase === "secrets") || { ok: true, findings: [] };
+
+  const kbDiff = ((payloadPhase.bytes || 0) / 1024).toFixed(1);
+  const kbLimit = ((payloadPhase.limitBytes || 76800) / 1024).toFixed(0);
+
+  const modifiedFiles = options.modifiedFiles || [];
+  const affectedTests = resolveAffectedTests(modifiedFiles, options);
+
+  const prBody = `## 🚀 Autonomous Jules Agent Execution Evidence
+
+### ⏱️ OODA Verification Trace
+- **Session ID:** \`${sessionId}\`
+- **OODA Turns:** \`${attemptsCount}/${maxAttempts}\`
+- **Warm Resumption:** ${isWarm ? "✅ Active Context Stream" : "Cold Start"}
+- **Execution Latency:** \`${durationSec}s\`
+
+### 🛡️ Zero-Trust Security Audit Matrix
+- **Scope Guard:** ${scopePhase.ok ? "✅ PASS (0 protected path violations)" : "❌ FAIL"}
+- **Diff Payload Governor:** ${payloadPhase.ok ? `✅ PASS (${kbDiff} KB / ${kbLimit} KB limit)` : "❌ EXCEEDED"}
+- **Secret Scanner:** ${secretPhase.ok ? "✅ PASS (0 high-entropy leaks detected)" : "❌ LEAKS FOUND"}
+
+### 🧪 Terminal Verification Evidence
+\`\`\`text
+${options.testOutput || "All verification tests passed with Exit Code 0."}
+\`\`\`
+
+### 📂 AST Impact & Dependency Graph
+${
+  affectedTests === null
+    ? "- **Impact Scope:** ⚠️ Global contract change detected (`package.json`/`tsconfig`/`schema`). Full test suite executed."
+    : affectedTests.length > 0
+    ? `- **Affected Test Suites (${affectedTests.length}):**\n` + affectedTests.map((t) => `  - \`${t}\``).join("\n")
+    : "- **Impact Scope:** Isolated leaf implementation change."
+}
+
+---
+*Generated automatically by [jules-orchestrator-kit](https://github.com/FullThrottle83/jules-orchestrator-kit)*
+`;
+
+  return prBody;
+}
+
+/**
+ * Live Dev Server & SSR Hydration Smoke Prober.
+ * Spawns the server in a detached process group, polls the URL via globalThis.fetch,
+ * intercepts SSR hydration errors, and cleanly kills the process group in a finally block.
+ * @param {object} serverConfig
+ * @param {string} serverConfig.command
+ * @param {string} [serverConfig.url="http://localhost:3000"]
+ * @param {number} [serverConfig.timeoutMs=15000]
+ * @param {string} root
+ * @returns {Promise<object>} Probe result { ok: boolean, status: number, error: string, logs: string }
+ */
+export async function probeDevServer(serverConfig = {}, root = process.cwd()) {
+  if (!serverConfig || !serverConfig.command) {
+    return { ok: true, skipped: true, reason: "No server command configured" };
+  }
+
+  const cmd = serverConfig.command;
+  const url = serverConfig.url || "http://localhost:3000";
+  const timeoutMs = Number(serverConfig.timeoutMs || 15000);
+
+  const isWin = process.platform === "win32";
+  const shellBin = isWin ? (process.env.ComSpec || "cmd.exe") : "/bin/sh";
+  const shellArgs = isWin ? ["/d", "/s", "/c", cmd] : ["-c", cmd];
+
+  let child;
+  let stdoutLogs = "";
+  let stderrLogs = "";
+
+  try {
+    child = spawn(shellBin, shellArgs, {
+      cwd: root,
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: process.env,
+    });
+
+    if (child.stdout) {
+      child.stdout.on("data", (chunk) => {
+        stdoutLogs += chunk.toString("utf-8");
+      });
+    }
+    if (child.stderr) {
+      child.stderr.on("data", (chunk) => {
+        stderrLogs += chunk.toString("utf-8");
+      });
+    }
+
+    const startTime = Date.now();
+    let pollResponse = null;
+    let pollError = null;
+
+    while (Date.now() - startTime < timeoutMs) {
+      if (child.exitCode !== null) {
+        return {
+          ok: false,
+          status: child.exitCode,
+          error: `Dev server process exited prematurely with code ${child.exitCode}`,
+          logs: (stderrLogs || stdoutLogs).slice(-2000),
+        };
+      }
+
+      try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+        const bodyText = await res.text();
+        pollResponse = { status: res.status, bodyText, ok: res.ok };
+        break;
+      } catch (err) {
+        pollError = err;
+      }
+
+      await new Promise((r) => setTimeout(r, 400));
+    }
+
+    if (!pollResponse) {
+      return {
+        ok: false,
+        status: 504,
+        error: `Dev server probe timed out after ${timeoutMs}ms attempting to reach ${url}. ${pollError ? pollError.message : ""}`,
+        logs: (stderrLogs || stdoutLogs).slice(-2000),
+      };
+    }
+
+    const combinedLogs = (stderrLogs + "\n" + pollResponse.bodyText).toLowerCase();
+    const hydrationPanics = [
+      "hydration failed",
+      "text content did not match",
+      "unhandled runtime error",
+      "minified react error #418",
+      "minified react error #423",
+      "minified react error #425",
+    ];
+
+    const detectedPanic = hydrationPanics.find((panic) => combinedLogs.includes(panic));
+    if (detectedPanic) {
+      return {
+        ok: false,
+        status: 500,
+        error: `SSR Hydration Smoke Probe Failure: Detected '${detectedPanic}' error in server response or stderr.`,
+        logs: (stderrLogs || stdoutLogs).slice(-2000),
+      };
+    }
+
+    if (!pollResponse.ok) {
+      return {
+        ok: false,
+        status: pollResponse.status,
+        error: `Dev server responded with HTTP status ${pollResponse.status}`,
+        logs: (stderrLogs || stdoutLogs).slice(-2000),
+      };
+    }
+
+    return {
+      ok: true,
+      status: pollResponse.status,
+      url,
+      logs: stdoutLogs.slice(-500),
+    };
+  } finally {
+    if (child && child.pid) {
+      try {
+        if (isWin) {
+          spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+        } else {
+          process.kill(-child.pid, "SIGTERM");
+        }
+      } catch (_) {}
+    }
+  }
+}
+
+

package/src/envelope.mjs

@@ -2,7 +2,7 @@ import { git, runCmd, resolveBase } from "./git.mjs";
 import { checkScope } from "./security.mjs";
 import { normalizeScope } from "./config.mjs";
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { resolve, relative, isAbsolute } from "node:path";
 
 /**
  * Validates a Task Envelope before dispatch or during CI triage.
@@ -67,7 +67,12 @@ export function validateEnvelope(envelope = {}, opts = {}) {
   if (Array.isArray(envelope.referenced_paths)) {
     for (const relPath of envelope.referenced_paths) {
       if (typeof relPath !== "string") continue;
-      const absPath = join(root, relPath);
+      const absPath = resolve(root, relPath);
+      const rootRelative = relative(resolve(root), absPath);
+      if (isAbsolute(rootRelative) || rootRelative === ".." || rootRelative.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
+        errors.push(`Premise failure: referenced path '${relPath}' escapes repository root.`);
+        continue;
+      }
       let existsInGit = false;
       if (resolvedBase) {
         const catRes = runCmd(["git", "cat-file", "-e", `${resolvedBase}:${relPath}`], { cwd: root, ignoreError: true });
@@ -96,10 +101,35 @@ export function validateEnvelope(envelope = {}, opts = {}) {
     }
   }
 
+  // 6. Concurrency Group Check
+  if (envelope.concurrency_group !== undefined) {
+    if (typeof envelope.concurrency_group !== "string" || !envelope.concurrency_group.trim()) {
+      errors.push("concurrency_group must be a non-empty string when provided.");
+    }
+  }
+
   return {
+
     ok: errors.length === 0,
     code: errors.length === 0 ? 0 : 1,
     errors,
     warnings,
   };
 }
+
+/**
+ * Parse JSON metadata payload embedded in HTML comment JULES_TASK_ENVELOPE.
+ * @param {string} content
+ * @returns {Record<string, any> | null}
+ */
+export function parseEnvelopeHeader(content) {
+  if (!content) return null;
+  const match = String(content).match(/<!--\s*JULES_TASK_ENVELOPE:\s*({[\s\S]*?})\s*-->/);
+  if (!match) return null;
+  try {
+    return JSON.parse(match[1]);
+  } catch {
+    return null;
+  }
+}
+

package/src/execution_envelope.mjs

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { resolveRoot } from "./config.mjs";
 import { resolveBase } from "./git.mjs";
 import { classifyRiskTier } from "./risk.mjs";
+import { queryRemediations } from "./remediation.mjs";
 
 /**
  * Generates a SHA-256 hash of the execution envelope payload.
@@ -19,6 +20,7 @@ export function hashExecutionEnvelope(envelope) {
     riskTier: envelope.riskTier,
     budgetReservationId: envelope.budgetReservationId,
     capabilities: envelope.capabilities,
+    remediations: envelope.remediations || [],
     createdAt: envelope.createdAt,
   };
   const sortedKeys = Object.keys(rawPayload).sort();
@@ -45,11 +47,12 @@ export function freezeExecutionEnvelope(envelope) {
     }),
     verify: Object.freeze({ ...(envelope.verify || {}) }),
     capabilities: Object.freeze([...(envelope.capabilities || [])]),
+    remediations: Object.freeze([...(envelope.remediations || [])]),
   });
 }
 
 /**
- * Creates an immutable Capability-Bounded Execution Envelope (CBEE).
+ * Creates an immutable Capability-Bounded Execution Envelope (CBEE) with pre-flight remediation hydration.
  */
 export function createExecutionEnvelope(task = {}, opts = {}) {
   const root = opts.root || resolveRoot();
@@ -66,6 +69,9 @@ export function createExecutionEnvelope(task = {}, opts = {}) {
   const files = task.files || opts.files || [];
   const riskMeta = classifyRiskTier(files, { diffLines: opts.diffLines || 0 });
 
+  const taskFingerprint = task.fingerprint || opts.fingerprint || null;
+  const remediations = queryRemediations(root, { targetFiles: files, fingerprint: taskFingerprint, limit: 3 });
+
   const rawEnvelope = {
     id: envelopeId,
     taskId,
@@ -84,6 +90,7 @@ export function createExecutionEnvelope(task = {}, opts = {}) {
     riskTier: riskMeta.tier,
     budgetReservationId: opts.reservationId || null,
     capabilities: opts.capabilities || ["git:read", "git:diff", "test:run"],
+    remediations,
     createdAt: new Date().toISOString(),
   };
 
@@ -101,3 +108,4 @@ export function verifyExecutionEnvelope(envelope) {
   const expectedHash = hashExecutionEnvelope(envelope);
   return envelope.hash === expectedHash;
 }
+

package/src/git.mjs

@@ -131,6 +131,30 @@ export function git(args = [], opts = {}) {
   }
 }
 
+export function ensureBaseFetched(root = process.cwd(), baseRef = "main") {
+  try {
+    execFileSync("git", ["fetch", "origin", baseRef, "--depth=100"], {
+      cwd: root,
+      encoding: "utf-8",
+      shell: false,
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+    return true;
+  } catch (_) {
+    try {
+      execFileSync("git", ["fetch", "origin", baseRef, "--unshallow"], {
+        cwd: root,
+        encoding: "utf-8",
+        shell: false,
+        stdio: ["ignore", "ignore", "ignore"],
+      });
+      return true;
+    } catch (__) {
+      return false;
+    }
+  }
+}
+
 export function resolveBase(root = process.cwd(), baseRef = "main") {
   const candidates = [`origin/${baseRef}`, `refs/remotes/origin/${baseRef}`, baseRef];
   for (const ref of candidates) {
@@ -146,6 +170,23 @@ export function resolveBase(root = process.cwd(), baseRef = "main") {
       }
     } catch (_) {}
   }
+
+  ensureBaseFetched(root, baseRef);
+
+  for (const ref of candidates) {
+    try {
+      const res = execFileSync("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
+        cwd: root,
+        encoding: "utf-8",
+        shell: false,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      if (res && res.trim()) {
+        return res.trim();
+      }
+    } catch (_) {}
+  }
+
   throw new GateError(
     `Cannot resolve base reference "${baseRef}". Ensure base branch is fetched (e.g., fetch-depth: 0 in CI).`,
     { code: 1 }