jules-orchestrator-kit 0.38.2 → 0.41.0

package/src/config.mjs

@@ -155,6 +155,12 @@ export function normalizeScope(parsed = {}) {
  */
 export function parseYaml(src) {
   if (!src || typeof src !== "string") return Object.create(null);
+  const trimmedSrc = src.trim();
+  if (trimmedSrc.startsWith("{") && trimmedSrc.endsWith("}")) {
+    try {
+      return JSON.parse(trimmedSrc);
+    } catch (_) {}
+  }
   const root = Object.create(null);
   const stack = [{ indent: -1, node: root }];
   const lines = src.split("\n");
@@ -174,13 +180,44 @@ export function parseYaml(src) {
     const top = stack[stack.length - 1];
 
     if (trimmed.startsWith("- ")) {
+      const itemBody = trimmed.slice(2).trim();
+      const colonIdx = itemBody.indexOf(":");
+      if (colonIdx > 0 && !itemBody.startsWith('"') && !itemBody.startsWith("'") && !itemBody.startsWith("[")) {
+        const itemKey = itemBody.slice(0, colonIdx).trim();
+        const itemVal = itemBody.slice(colonIdx + 1).trim();
+        if (BLOCKED_KEYS.has(itemKey)) {
+          throw new ConfigError(`Illegal prototype key "${itemKey}" detected in configuration`);
+        }
+        const obj = Object.create(null);
+        if (itemVal.startsWith("[") && itemVal.endsWith("]")) {
+          obj[itemKey] = itemVal
+            .slice(1, -1)
+            .split(",")
+            .map((s) => coerce(s.trim()))
+            .filter((s) => s !== "");
+        } else if (itemVal !== "") {
+          obj[itemKey] = coerce(itemVal);
+        }
+
+        if (top.key && top.parent) {
+          if (!Array.isArray(top.parent[top.key])) {
+            top.parent[top.key] = [];
+          }
+          top.parent[top.key].push(obj);
+        } else if (Array.isArray(top.node)) {
+          top.node.push(obj);
+        }
+        stack.push({ indent, node: obj, isArrayItem: true });
+        continue;
+      }
+
       if (top.key && top.parent) {
         if (!Array.isArray(top.parent[top.key])) {
           top.parent[top.key] = [];
         }
-        top.parent[top.key].push(coerce(trimmed.slice(2).trim()));
+        top.parent[top.key].push(coerce(itemBody));
       } else if (Array.isArray(top.node)) {
-        top.node.push(coerce(trimmed.slice(2).trim()));
+        top.node.push(coerce(itemBody));
       }
       continue;
     }
@@ -357,8 +394,21 @@ export const TIER_PRESETS = {
 /** Tier names that correspond to real vendor plans, in ascending order. */
 export const VENDOR_TIERS = ["free", "pro", "ultra"];
 
-/** The tier used when a config names one that does not exist. */
-export const FALLBACK_TIER = "ultra";
+/**
+ * The tier assumed when a repository states none, or names one that does not exist.
+ *
+ * `free` rather than `ultra`, because this is a guess about someone else's
+ * billing account and the two directions fail very differently. Guessing low
+ * costs a Pro or Ultra operator some throughput until they set `tier:` — a
+ * number they see in `agentctl doctor` and can raise in one line. Guessing high
+ * hands a Free account a 15-worker swarm and a 300-task allowance it does not
+ * have, so the first real run dispatches into `FAILED_PRECONDITION` quota
+ * rejections, which is also the worst possible first impression of the kit.
+ *
+ * The learned-ceiling logic in src/budget.mjs corrects upward from observation;
+ * nothing corrects downward from an over-generous assumption.
+ */
+export const FALLBACK_TIER = "free";
 
 /**
  * Escalation reasons that bypass the Silence Governor and alert immediately.
@@ -406,8 +456,8 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
   const verifyTimeoutMs = parsed.verify?.timeoutMs ?? parsed.verify?.timeout_ms ?? 60000;
   const autoVerify = resolveVerify(root);
 
-  const rawTier = String(process.env.JULES_TIER || parsed.tier || "ultra").toLowerCase();
-  const activeTier = TIER_PRESETS[rawTier] ? rawTier : "ultra";
+  const rawTier = String(process.env.JULES_TIER || parsed.tier || FALLBACK_TIER).toLowerCase();
+  const activeTier = TIER_PRESETS[rawTier] ? rawTier : FALLBACK_TIER;
   const tierLimits = TIER_PRESETS[activeTier];
 
   const envDailyTasks = process.env.JULES_DAILY_BUDGET !== undefined && Number.isFinite(Number(process.env.JULES_DAILY_BUDGET)) ? Number(process.env.JULES_DAILY_BUDGET) : null;
@@ -470,6 +520,18 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
       discordWebhookUrl: parsed.notifications?.discord_webhook_url || parsed.notifications?.discordWebhookUrl || "",
     },
     scope: normalizeScope(parsed),
+    // Project-specific risk paths. These extend the builtin lists in risk.mjs
+    // rather than replacing them; see resolveRiskPatterns() for why. This is
+    // where a repository declares the directories that are dangerous *for it* —
+    // billing, tax rates, pricing, smart contracts — which cannot be guessed
+    // from the stack and must not be shipped as someone else's defaults.
+    risk: {
+      restricted: Array.isArray(parsed.risk?.restricted) ? parsed.risk.restricted : [],
+      consequential: Array.isArray(parsed.risk?.consequential) ? parsed.risk.consequential : [],
+      maxRoutineDiffLines: Number.isFinite(Number(parsed.risk?.max_routine_diff_lines ?? parsed.risk?.maxRoutineDiffLines))
+        ? Number(parsed.risk.max_routine_diff_lines ?? parsed.risk.maxRoutineDiffLines)
+        : 400,
+    },
     limits: {
       ...DEFAULTS.limits,
       ...tierLimits,
@@ -494,6 +556,7 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     runner: parsed.runner || DEFAULTS.runner,
     branchPrefix: parsed.branch_prefix || parsed.branchPrefix || DEFAULTS.branchPrefix,
     baseBranch: parsed.base_branch || parsed.baseBranch || DEFAULTS.baseBranch,
+    source: parsed.source || process.env.JULES_REPO || "",
     julesApiKeys: Array.from(new Set([
       (process.env.JULES_API_KEY || "").trim(),
       ...(process.env.JULES_API_KEYS || process.env.JULES_API_KEY_SECONDARY || "").split(",").map((k) => k.trim()),

package/src/dag-engine.mjs

@@ -493,6 +493,8 @@ export async function executeQueueDag(root = process.cwd(), options = {}) {
     let role = undefined;
     let tier = undefined;
 
+    let targetFiles = [];
+
     // Check envelope header
     const match = content.match(/<!--\s*JULES_TASK_ENVELOPE:\s*({[\s\S]*?})\s*-->/);
     if (match) {
@@ -502,6 +504,8 @@ export async function executeQueueDag(root = process.cwd(), options = {}) {
         if (meta.title) title = meta.title;
         if (meta.role) role = meta.role;
         if (meta.tier) tier = meta.tier;
+        if (Array.isArray(meta.targetFiles)) targetFiles = meta.targetFiles;
+        else if (Array.isArray(meta.referenced_paths)) targetFiles = meta.referenced_paths;
         if (Array.isArray(meta.dependsOn)) dependsOn = meta.dependsOn;
         else if (typeof meta.dependsOn === "string") dependsOn = meta.dependsOn.split(",").map((s) => s.trim()).filter(Boolean);
       } catch (_) {}
@@ -513,12 +517,29 @@ export async function executeQueueDag(root = process.cwd(), options = {}) {
         if (parsed.prompt) prompt = parsed.prompt;
         if (parsed.role) role = parsed.role;
         if (parsed.tier) tier = parsed.tier;
+        if (Array.isArray(parsed.targetFiles)) targetFiles = parsed.targetFiles;
+        else if (Array.isArray(parsed.referenced_paths)) targetFiles = parsed.referenced_paths;
         if (Array.isArray(parsed.dependsOn)) dependsOn = parsed.dependsOn;
         else if (typeof parsed.dependsOn === "string") dependsOn = parsed.dependsOn.split(",").map((s) => s.trim()).filter(Boolean);
       } catch (_) {}
     }
 
-    taskMap.set(taskId, { file, fullPath, taskId, title, prompt, role, tier, dependsOn });
+    taskMap.set(taskId, { file, fullPath, taskId, title, prompt, role, tier, dependsOn, targetFiles });
+  }
+
+  // Auto-serialize concurrent tasks that touch overlapping target files to prevent git merge conflicts
+  const fileToLastTaskId = new Map();
+  for (const [taskId, t] of taskMap.entries()) {
+    for (const rawPath of t.targetFiles || []) {
+      const norm = String(rawPath).replace(/\\/g, "/");
+      if (fileToLastTaskId.has(norm)) {
+        const priorTaskId = fileToLastTaskId.get(norm);
+        if (priorTaskId !== taskId && !t.dependsOn.includes(priorTaskId)) {
+          t.dependsOn.push(priorTaskId);
+        }
+      }
+      fileToLastTaskId.set(norm, taskId);
+    }
   }
 
   // Register each task with its dependencies that are part of this queue run

package/src/engine.mjs

@@ -4,7 +4,7 @@ import { changedFiles, diffBytes, diffText, showFromOrigin, runCmd } from "./git
 import { createProvider, ProviderRateLimitError, ProviderUnavailableError } from "./provider.mjs";
 import { resolveRoutedProvider } from "./router.mjs";
 import { withBudget, appendLedger, getQueueDir, ensureDir, rollbackBudgetReservation, isConcurrencyGroupLocked, checkDailyBudget } from "./state.mjs";
-import { resolveDailyLimit, recordObservedCeiling, isDailyQuotaRejection } from "./budget.mjs";
+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";
@@ -18,12 +18,14 @@ import { recordRemediation, queryRemediations, harvestFailureRecord, hydrateMemo
 import { hydratePrompt, harvestFailure } from "./memory.mjs";
 import { resolveRolePrompt } from "./role-resolver.mjs";
 
+import { runAssertion } from "./assertions.mjs";
 import {
   computeDirectoryHash,
   generateEvidenceManifest,
   writeEvidenceManifest,
   verifyEvidenceManifest,
   generateEvidenceMarkdown,
+  exportJsonReport,
   sha256,
 } from "./evidence.mjs";
 
@@ -47,6 +49,8 @@ export {
   writeEvidenceManifest,
   verifyEvidenceManifest,
   generateEvidenceMarkdown,
+  exportJsonReport,
+  runAssertion,
 };
 
 
@@ -296,34 +300,60 @@ export async function gate(opts = {}) {
 
   try {
     for (const stage of stagesToRun) {
-      if (!stage.cmd) continue;
-      const startTime = Date.now();
-      const stageEnv = stage.networkAccess === "forbidden" || trustedVerify.policy?.offline
-        ? { ...testEnv, JULES_SANDBOX_OFFLINE: "1" }
-        : testEnv;
+      const isAssertion = Boolean(
+        stage.assert ||
+        (stage.type && String(stage.type).startsWith("assert:")) ||
+        (stage.kind && String(stage.kind).startsWith("assert:"))
+      );
+      if (!stage.cmd && !isAssertion) continue;
 
-      const res = runCmd(stage.cmd, { cwd: root, ignoreError: true, env: stageEnv, timeout: stage.timeoutMs || verifyTimeout });
-      const durationMs = Date.now() - startTime;
-      const stdoutRedacted = redactSecrets(res.stdout || "");
-      const stderrRedacted = redactSecrets(res.stderr || "");
-      const stageOk = res.status === 0;
+      const startTime = Date.now();
+      let res;
+      let durationMs;
+      let stdoutRedacted;
+      let stderrRedacted;
+      let stageOk;
+      let assertDiagnostics = [];
+      let assertMetrics = {};
+
+      if (isAssertion) {
+        const assertRes = runAssertion(stage, root);
+        durationMs = assertRes.metrics?.durationMs ?? (Date.now() - startTime);
+        stdoutRedacted = assertRes.stdout || "";
+        stderrRedacted = assertRes.stderr || "";
+        stageOk = assertRes.ok;
+        assertDiagnostics = assertRes.diagnostics || [];
+        assertMetrics = assertRes.metrics || {};
+        res = { status: assertRes.status, stdout: stdoutRedacted, stderr: stderrRedacted };
+      } else {
+        const stageEnv = stage.networkAccess === "forbidden" || trustedVerify.policy?.offline
+          ? { ...testEnv, JULES_SANDBOX_OFFLINE: "1" }
+          : testEnv;
+
+        res = runCmd(stage.cmd, { cwd: root, ignoreError: true, env: stageEnv, timeout: stage.timeoutMs || verifyTimeout });
+        durationMs = Date.now() - startTime;
+        stdoutRedacted = redactSecrets(res.stdout || "");
+        stderrRedacted = redactSecrets(res.stderr || "");
+        stageOk = res.status === 0;
+      }
 
       executionRecords.push({
-        id: stage.id || stage.kind,
-        kind: stage.kind,
-        cmd: stage.cmd,
+        id: stage.id || stage.kind || (isAssertion ? `assert:${stage.assert}` : "stage"),
+        kind: stage.kind || (isAssertion ? "assert" : "test"),
+        cmd: stage.cmd || `assert:${stage.assert || stage.type || stage.kind}`,
         exitCode: res.status,
         durationMs,
-        networkAccess: stage.networkAccess || "allow",
+        networkAccess: isAssertion ? "offline" : (stage.networkAccess || "allow"),
         stdoutHash: "sha256:" + sha256(stdoutRedacted),
         stderrHash: "sha256:" + sha256(stderrRedacted),
+        ...(isAssertion ? { assert: stage.assert || stage.type || stage.kind, diagnostics: assertDiagnostics, metrics: assertMetrics } : {}),
       });
 
       if (stage.kind === "test" || stage.kind === "unit") {
         testResult = { ok: stageOk, status: res.status, stdout: stdoutRedacted, stderr: stderrRedacted, command: stage.cmd };
         const fingerprint = !stageOk ? fingerprintFailureState(testResult, root) : null;
-        recordVerifyRun(root, stage.cmd, stageOk, fingerprint, durationMs);
-        if (!stageOk) {
+        if (stage.cmd) recordVerifyRun(root, stage.cmd, stageOk, fingerprint, durationMs);
+        if (!stageOk && stage.cmd) {
           const runs = readVerifyRuns(root, stage.cmd);
           flakyVerdictResult = flakyVerdict(runs);
           if (flakyVerdictResult.verdict === "QUARANTINED") {
@@ -343,8 +373,11 @@ export async function gate(opts = {}) {
           status: res.status,
           stdout: stdoutRedacted,
           stderr: stderrRedacted,
-          command: stage.cmd,
-          phase: stage.kind,
+          command: stage.cmd || `assert:${stage.assert || stage.type || stage.kind}`,
+          phase: stage.kind || (isAssertion ? "assert" : "stage"),
+          stageId: stage.id || (isAssertion ? `assert:${stage.assert || stage.type || stage.kind}` : stage.kind),
+          diagnostics: assertDiagnostics,
+          metrics: assertMetrics,
         };
         break;
       }
@@ -378,8 +411,11 @@ export async function gate(opts = {}) {
     }
   }
 
+  const verifyOk = !failingCmd && !testTampered;
+
   // Generate & persist Evidence Manifest
   const evidenceManifest = generateEvidenceManifest(root, {
+    taskId: opts.taskId,
     preTestHash,
     executionRecords,
     secretScanOk: secretResult.ok,
@@ -387,6 +423,10 @@ export async function gate(opts = {}) {
     maxDiffKb: config.limits.diffKb || 75,
     protectedScopeOk: scopeResult.ok,
     repository: config.provider || "jules",
+    failedStage: failingCmd?.stageId || failingCmd?.phase || null,
+    diagnostics: failingCmd?.diagnostics?.length ? failingCmd.diagnostics : (failingCmd?.stderr ? [failingCmd.stderr] : []),
+    metrics: failingCmd?.metrics || {},
+    ok: verifyOk,
   });
   if (testTampered) {
     evidenceManifest.testIntegrity.tamperDetected = true;
@@ -396,7 +436,13 @@ export async function gate(opts = {}) {
     evidencePath = writeEvidenceManifest(root, evidenceManifest);
   } catch (_) {}
 
-  const verifyOk = !failingCmd && !testTampered;
+  // Export structured JSON report if requested
+  const jsonReportPath = opts.jsonReport || opts.jsonReportPath || process.env.JULES_JSON_REPORT || null;
+  if (jsonReportPath) {
+    try {
+      exportJsonReport(evidenceManifest, jsonReportPath);
+    } catch (_) {}
+  }
   phases.push({
     phase: "verify",
     ok: verifyOk,
@@ -526,7 +572,8 @@ export async function repair(failure, opts = {}) {
             { root, dryRun: opts.dryRun }
           ),
         root,
-        config.limits.dailyTasks
+        config.limits.dailyTasks,
+        { author: opts.author ? resolveAmbientIdentity(opts.author) : "ooda-repair-bot" }
       );
     } catch (err) {
       if (err instanceof ProviderRateLimitError || err instanceof ProviderUnavailableError) {
@@ -622,10 +669,48 @@ export async function repair(failure, opts = {}) {
 /**
  * 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.
+ */
+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 { 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,
+    };
+  }
+
+  return {
+    satisfied: false,
+    reason: `Verification oracle '${verifyCmd}' failed (exit ${probe.code}), proving task need.`,
+    durationMs: probe.durationMs,
+  };
+}
+
+/**
+ * Polls the provider until the session terminates in COMPLETED, FAILED, or reaches timeout.
+ */
 export async function pollSessionState(provider, session, opts = {}) {
   if (!session || !session.id) return { status: "COMPLETED" };
   const initialStatus = String(session.status || session.state || "").toUpperCase();
-  if (initialStatus === "COMPLETED" || initialStatus === "FAILED" || opts.dryRun || session.id === "dry-run-session-id") {
+  if (
+    initialStatus === "COMPLETED" ||
+    initialStatus === "FAILED" ||
+    opts.dryRun ||
+    session.id === "dry-run-session-id" ||
+    session.id.startsWith("mock-") ||
+    session.id.startsWith("dry-run-")
+  ) {
     return { status: initialStatus || "COMPLETED" };
   }
 
@@ -650,6 +735,17 @@ export async function pollSessionState(provider, session, opts = {}) {
 
     if (currentSession) {
       const status = String(currentSession.status || currentSession.state || "").toUpperCase();
+      if (
+        (status === "AWAITING_PLAN_APPROVAL" || status === "PENDING_APPROVAL") &&
+        (opts.autoApprovePlan || opts.autoApprove || session.autoApprovePlan)
+      ) {
+        if (provider && typeof provider.approvePlan === "function") {
+          try {
+            await provider.approvePlan(session.id, opts);
+          } catch (_) {}
+        }
+      }
+
       if (status === "COMPLETED" || status === "FAILED") {
         return { ...currentSession, status };
       }
@@ -717,6 +813,19 @@ 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,
+      };
+    }
+  }
+
   // Redact secrets in prompt before dispatching
   let cleanPrompt = redactSecrets(task.prompt || "");
 
@@ -765,9 +874,10 @@ export async function dispatch(task = {}, opts = {}) {
     // consume one of the operator's finite daily task slots. Reserving here also
     // made every `npm test` burn real budget, which eventually exhausted the
     // ledger and turned the suite red for reasons unrelated to any code change.
+    const author = resolveAmbientIdentity(task.author || opts.author || null);
     const session = opts.dryRun
       ? await runDispatch()
-      : await withBudget(runDispatch, root, budget.limit, { enforce: budget.certain });
+      : await withBudget(runDispatch, root, budget.limit, { enforce: budget.certain, author });
     return classification ? { ...session, _routeTier: classification.tier, _routeReason: classification.reason } : session;
   } catch (err) {
     // A refusal for daily quota is the only authoritative statement of the

package/src/evidence.mjs

@@ -156,6 +156,11 @@ export function computeEvidenceHash(manifest) {
     testIntegrity: manifest.testIntegrity,
     executionRecords: manifest.executionRecords,
     securityChecks: manifest.securityChecks,
+    ...(manifest.status ? { status: manifest.status } : {}),
+    ...(manifest.failedStage ? { failedStage: manifest.failedStage } : {}),
+    ...(manifest.diagnostics && manifest.diagnostics.length > 0 ? { diagnostics: manifest.diagnostics } : {}),
+    ...(manifest.metrics && Object.keys(manifest.metrics).length > 0 ? { metrics: manifest.metrics } : {}),
+    ...(manifest.summary && Object.keys(manifest.summary).length > 0 ? { summary: manifest.summary } : {}),
   });
   return "sha256:" + sha256(canonicalPayload);
 }
@@ -242,11 +247,18 @@ export function generateEvidenceManifest(root = process.cwd(), options = {}) {
   const promptHash = taskPrompt ? "sha256:" + sha256(taskPrompt) : "sha256:empty";
   const promptExcerpt = taskPrompt ? taskPrompt.slice(0, 140).replace(/[\r\n]+/g, " ") : "";
 
+  const diagnostics = Array.isArray(options.diagnostics) ? options.diagnostics : [];
+  const metrics = options.metrics || {};
+  const status = options.status || (options.ok === false || tamperDetected || diagnostics.length > 0 ? "failed" : "passed");
+  const failedStage = options.failedStage || options.failedStep || null;
+
   // Base manifest
   const baseManifest = {
     schema: "agentctl/evidence-manifest-v1",
     manifestId,
     generatedAt,
+    status,
+    ...(failedStage ? { failedStage } : {}),
     intent: {
       taskId: options.taskId || options.task?.id || "local-task",
       title: options.title || options.task?.title || "Verification Run",
@@ -273,6 +285,8 @@ export function generateEvidenceManifest(root = process.cwd(), options = {}) {
       maxDiffKb: options.maxDiffKb || 75,
       protectedScopeOk: options.protectedScopeOk ?? true,
     },
+    ...(diagnostics.length > 0 ? { diagnostics } : {}),
+    ...(Object.keys(metrics).length > 0 ? { metrics } : {}),
   };
 
   const evidenceHash = computeEvidenceHash(baseManifest);
@@ -307,9 +321,70 @@ export function writeEvidenceManifest(root, manifest, customPath = null) {
     writeFileAtomically(latestPath, JSON.stringify(manifest, null, 2));
   } catch (_) {}
 
+  // Written at a custom path means the caller owns the location and its
+  // lifetime; only the kit's own directory is ours to rotate.
+  if (!customPath) {
+    pruneEvidenceManifests(root);
+  }
+
   return targetPath;
 }
 
+/**
+ * How many evidence manifests to keep.
+ *
+ * Two are written per verified task, so this is roughly the last hundred runs.
+ * Checkpoints (10) and handovers (20) already rotate; evidence and telemetry
+ * did not, and a fortnight of ordinary use left 305 files and 2.6 MB in a
+ * directory nothing ever read past the newest few. Unbounded growth inside
+ * `.agent/` is not just disk: `getLedgerPathsInWindow` and the doctor checks
+ * walk these directories, so every dispatch slowly pays for every run before it.
+ */
+export const EVIDENCE_RETENTION = 200;
+
+/**
+ * Removes the oldest evidence manifests beyond the retention limit.
+ *
+ * Ordered by the timestamp embedded in the manifest id rather than by mtime:
+ * a `git checkout` or an rsync rewrites mtimes and would otherwise make the
+ * pruner delete the newest evidence it has.
+ *
+ * @param {string} root
+ * @param {number} [retention=EVIDENCE_RETENTION]
+ * @returns {{ pruned: number, kept: number }}
+ */
+export function pruneEvidenceManifests(root, retention = EVIDENCE_RETENTION) {
+  const evidenceDir = join(root, ".agent", "evidence");
+  if (!existsSync(evidenceDir)) return { pruned: 0, kept: 0 };
+
+  let entries;
+  try {
+    entries = readdirSync(evidenceDir);
+  } catch (_) {
+    return { pruned: 0, kept: 0 };
+  }
+
+  const manifests = entries
+    .filter((f) => f.startsWith("EVD-") && f.endsWith(".json"))
+    .map((f) => {
+      const match = /^EVD-(\d+)-/.exec(f);
+      return { file: f, ts: match ? Number(match[1]) : 0 };
+    })
+    .sort((a, b) => b.ts - a.ts);
+
+  if (manifests.length <= retention) return { pruned: 0, kept: manifests.length };
+
+  let pruned = 0;
+  for (const { file } of manifests.slice(retention)) {
+    try {
+      unlinkSync(join(evidenceDir, file));
+      pruned++;
+    } catch (_) {}
+  }
+
+  return { pruned, kept: retention };
+}
+
 /**
  * Loads and validates an evidence manifest from disk.
  * @param {string} root
@@ -402,6 +477,32 @@ export function verifyEvidenceManifest(root = process.cwd(), manifestOrPath = "m
   return { ok: true, manifestId: manifest.manifestId, evidenceHash: manifest.evidenceHash };
 }
 
+/**
+ * Exports a structured, machine-readable JSON report optimized for agent consumption.
+ * @param {object} manifest
+ * @param {string} [customPath]
+ * @returns {object}
+ */
+export function exportJsonReport(manifest, customPath = null) {
+  const report = {
+    schema: manifest.schema || "agentctl/evidence-manifest-v1",
+    manifestId: manifest.manifestId,
+    generatedAt: manifest.generatedAt,
+    status: manifest.status || (manifest.testIntegrity?.tamperDetected ? "failed" : "passed"),
+    failedStage: manifest.failedStage || null,
+    metrics: manifest.metrics || {},
+    diagnostics: manifest.diagnostics || [],
+    executionRecords: manifest.executionRecords || [],
+    evidenceHash: manifest.evidenceHash,
+  };
+
+  if (customPath) {
+    writeFileAtomically(customPath, JSON.stringify(report, null, 2));
+  }
+
+  return report;
+}
+
 /**
  * Renders PR-ready Markdown evidence section.
  * @param {object} manifest
@@ -422,12 +523,20 @@ export function generateEvidenceMarkdown(manifest) {
 
   if (Array.isArray(manifest.executionRecords) && manifest.executionRecords.length > 0) {
     lines.push("", "#### Executed Verification Stages");
-    lines.push("| Stage | Command | Policy | Exit Code | Duration |");
+    lines.push("| Stage | Command / Assertion | Policy | Exit Code | Duration |");
     lines.push("| :--- | :--- | :---: | :---: | :---: |");
     for (const rec of manifest.executionRecords) {
       const statusIcon = rec.exitCode === 0 ? "✅" : "❌";
       const policyStr = rec.networkAccess === "forbidden" ? "🔒 Offline" : rec.networkAccess === "read-only" ? "📖 Read-Only" : "🌐 Online";
-      lines.push(`| \`${rec.id || rec.kind}\` | \`${rec.cmd}\` | ${policyStr} | ${statusIcon} \`${rec.exitCode}\` | \`${rec.durationMs || 0}ms\` |`);
+      const cmdOrAssert = rec.assert ? `\`assert:${rec.assert}\`` : `\`${rec.cmd}\``;
+      lines.push(`| \`${rec.id || rec.kind}\` | ${cmdOrAssert} | ${policyStr} | ${statusIcon} \`${rec.exitCode}\` | \`${rec.durationMs || 0}ms\` |`);
+    }
+  }
+
+  if (Array.isArray(manifest.diagnostics) && manifest.diagnostics.length > 0) {
+    lines.push("", "#### ⚠️ Diagnostic Findings");
+    for (const diag of manifest.diagnostics) {
+      lines.push(`- ${diag}`);
     }
   }
 

package/src/execution-envelope.mjs

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { resolveRoot } from "./config.mjs";
+import { resolveRoot, loadConfig } from "./config.mjs";
 import { resolveBase } from "./git.mjs";
 import { classifyRiskTier } from "./risk.mjs";
 import { queryRemediations } from "./remediation.mjs";
@@ -62,12 +62,28 @@ export function createExecutionEnvelope(task = {}, opts = {}) {
   const taskId = task.id || opts.taskId || `task-${Date.now()}`;
   const envelopeId = `env-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
 
-  const denyPaths = opts.forbiddenPaths || task.forbiddenPaths || [".github/**", "package-lock.json", "pnpm-lock.yaml"];
-  const allowPaths = opts.allowPaths || task.allowPaths || [];
-  const protectPaths = opts.protectPaths || task.protectPaths || ["package.json", "tsconfig.json", "AGENTS.md"];
+  // The repository's own resolved scope and verification commands, not a set of
+  // Node literals. `loadConfig` merges BUILTIN_DENY/BUILTIN_PROTECT (which are
+  // already polyglot — Cargo.toml, go.mod, pyproject.toml, composer.json) with
+  // whatever `.agent/config.yml` adds, and `resolveVerify` runs the stack
+  // detector. Hardcoding `npm test` here meant the envelope handed a Rust or
+  // Python repo a command that could not run, in the very structure whose job
+  // is to be the authoritative record of what the agent was allowed to do.
+  let config = opts.config;
+  if (!config) {
+    try {
+      config = loadConfig(root);
+    } catch (_) {
+      config = {};
+    }
+  }
+
+  const denyPaths = opts.forbiddenPaths || task.forbiddenPaths || config.scope?.deny || [];
+  const allowPaths = opts.allowPaths || task.allowPaths || config.scope?.allow || [];
+  const protectPaths = opts.protectPaths || task.protectPaths || config.scope?.protect || [];
 
   const files = task.files || opts.files || [];
-  const riskMeta = classifyRiskTier(files, { diffLines: opts.diffLines || 0 });
+  const riskMeta = classifyRiskTier(files, { diffLines: opts.diffLines || 0, config });
 
   const taskFingerprint = task.fingerprint || opts.fingerprint || null;
   const remediations = queryRemediations(root, { targetFiles: files, fingerprint: taskFingerprint, limit: 3 });
@@ -84,8 +100,8 @@ export function createExecutionEnvelope(task = {}, opts = {}) {
       protect: protectPaths,
     },
     verify: {
-      testCmd: opts.testCmd || task.testCmd || "npm test",
-      buildCmd: opts.buildCmd || task.buildCmd || "npm run build",
+      testCmd: opts.testCmd || task.testCmd || config.verify?.test || "",
+      buildCmd: opts.buildCmd || task.buildCmd || config.verify?.build || "",
     },
     riskTier: riskMeta.tier,
     budgetReservationId: opts.reservationId || null,

package/src/flaky-ledger.mjs

@@ -245,7 +245,10 @@ export function clearFlakyLedger(root = resolveRoot(), testCmd = null) {
  */
 export function synthesizeFlakyHealingTask(quarantinedItem, options = {}) {
   const item = typeof quarantinedItem === "string" ? { testCmd: quarantinedItem, oscillation: 0.5, fails: 3, passes: 3, n: 6 } : quarantinedItem;
-  const testCmd = item.testCmd || "npm test";
+  // The quarantined entry carries the command that actually oscillated; the
+  // config's resolved test command is the fallback. `npm test` was neither, and
+  // in a non-Node repo it produced a healing task that could not run.
+  const testCmd = item.testCmd || options.testCmd || options.config?.verify?.test || "";
   const oscillationPct = Math.round((item.oscillation || 0.4) * 100);
   const role = options.role || "janitor";
   const slug = String(testCmd).replace(/[^a-zA-Z0-9]/g, "-").replace(/-+/g, "-").slice(0, 20).toLowerCase();