jules-orchestrator-kit 0.42.0 → 0.52.0

package/src/security.mjs

@@ -1,7 +1,7 @@
 import { openSync, writeSync, fsyncSync, closeSync, renameSync, realpathSync, existsSync, lstatSync, unlinkSync } from "node:fs";
 import { dirname, join, basename } from "node:path";
 import { randomBytes } from "node:crypto";
-import { canonicalizePath } from "./config.mjs";
+import { canonicalizePath, isWindowsAbsolutePath } from "./config.mjs";
 import { detectCrossPackageBoundaryViolations } from "./stack-detector.mjs";
 
 export const HIGH_CONFIDENCE_PATTERNS = [
@@ -208,34 +208,118 @@ export function anonymizePii(text) {
  * @param {string} globPattern
  * @param {{ caseInsensitive?: boolean }} [opts]
  */
+/**
+ * Matches one `/`-free glob segment against one `/`-free path segment.
+ *
+ * Only `*` (zero or more characters) and `?` (exactly one) are special; every
+ * other character — including regex metacharacters like `(`, `+`, `.`, `[` —
+ * is matched literally, preserving the escaping behaviour the old regex
+ * translation had. A segment that is exactly `*` keeps its historical one-or-
+ * more semantics, so `*` cannot match an empty segment.
+ *
+ * Implemented with the classic greedy-star wildcard algorithm rather than a
+ * compiled regex: a segment like `*a*a*a*a*a*a*b` translated to
+ * `^[^/]*a[^/]*a…$` and backtracked exponentially on a long run of `a`s, so
+ * this path must never build a regex. The algorithm scans each character a
+ * bounded number of times and cannot blow up the way the regex could.
+ *
+ * @param {string} str
+ * @param {string} pattern
+ * @param {boolean} [caseInsensitive]
+ * @returns {boolean}
+ */
+function matchGlobSegment(str, pattern, caseInsensitive = false) {
+  if (pattern === "*") return str.length > 0;
+
+  let s = caseInsensitive ? str.toLowerCase() : str;
+  let p = caseInsensitive ? pattern.toLowerCase() : pattern;
+
+  let si = 0;
+  let pi = 0;
+  let star = -1;
+  let matchIdx = 0;
+
+  while (si < s.length) {
+    if (pi < p.length && (p[pi] === "?" || p[pi] === s[si])) {
+      si++;
+      pi++;
+    } else if (pi < p.length && p[pi] === "*") {
+      star = pi;
+      matchIdx = si;
+      pi++;
+    } else if (star !== -1) {
+      pi = star + 1;
+      matchIdx++;
+      si = matchIdx;
+    } else {
+      return false;
+    }
+  }
+
+  while (pi < p.length && p[pi] === "*") pi++;
+  return pi === p.length;
+}
+
+/**
+ * Linear-time glob matcher over `/`-split segments.
+ *
+ * `**` matches zero or more whole segments; every other pattern segment
+ * matches exactly one path segment via `matchGlobSegment`. This is a
+ * bottom-up dynamic program with a rolling array: O(n·m) time and O(m) memory
+ * for n path and m pattern segments, and it builds no regex at all.
+ *
+ * The previous implementation translated `**` into overlapping dot-star and
+ * start-anchored `(?: … |^)` alternations (`SEC-01`). Anchored against `$`, a
+ * pattern like `*a*a*a*a*a*a*a*a*b` or a chain of globstars caused catastrophic
+ * backtracking — the match time grew exponentially with input length and a
+ * hostile deny rule or file list could stall the dispatch gate. The DP
+ * replaces every one of those constructs with a bounded scan.
+ *
+ * @param {string[]} pathSegs
+ * @param {string[]} patSegs
+ * @param {boolean} [caseInsensitive]
+ * @returns {boolean}
+ */
+function matchGlobSegments(pathSegs, patSegs, caseInsensitive = false) {
+  const n = pathSegs.length;
+  const m = patSegs.length;
+
+  // next[j] answers "does pathSegs[i+1..] match patSegs[j..]?". Seeded for the
+  // empty-path row (i = n): only true when every remaining pattern segment is
+  // `**`, since those are the only segments that can match zero path segments.
+  let next = new Array(m + 1).fill(false);
+  next[m] = true;
+  for (let j = m - 1; j >= 0; j--) {
+    next[j] = patSegs[j] === "**" && next[j + 1];
+  }
+
+  for (let i = n - 1; i >= 0; i--) {
+    const cur = new Array(m + 1).fill(false);
+    // cur[m] stays false: a path segment remains but the pattern is exhausted.
+    for (let j = m - 1; j >= 0; j--) {
+      if (patSegs[j] === "**") {
+        // Consume this segment and keep `**` (next[j]), or match zero segments
+        // and move on (cur[j + 1]).
+        cur[j] = next[j] || cur[j + 1];
+      } else if (matchGlobSegment(pathSegs[i], patSegs[j], caseInsensitive)) {
+        cur[j] = next[j + 1];
+      }
+    }
+    next = cur;
+  }
+
+  return next[0];
+}
+
 export function matchesGlob(filePath, globPattern, opts = {}) {
   if (!filePath || !globPattern) return false;
   const file = canonicalizePath(filePath);
   const pattern = canonicalizePath(globPattern);
-  const flags = opts.caseInsensitive ? "i" : "";
-
-  if (opts.caseInsensitive ? file.toLowerCase() === pattern.toLowerCase() : file === pattern) return true;
+  const caseInsensitive = Boolean(opts.caseInsensitive);
 
-  const parts = pattern.split("/");
-  const regexParts = parts.map((part) => {
-    if (part === "**") return "___GLOBSTAR___";
-    if (part === "*") return "[^/]+";
-    const escaped = part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    return escaped.replace(/\\\*/g, "[^/]*").replace(/\\\?/g, ".");
-  });
+  if (caseInsensitive ? file.toLowerCase() === pattern.toLowerCase() : file === pattern) return true;
 
-  let regexStr = regexParts.join("/");
-  regexStr = regexStr
-    .replace(/^___GLOBSTAR___\//g, "(?:.*/|^)")
-    .replace(/\/___GLOBSTAR___$/g, "(?:/.*|$)")
-    .replace(/\/___GLOBSTAR___\//g, "(?:/|/.+/|/)")
-    .replace(/___GLOBSTAR___/g, ".*");
-
-  try {
-    return new RegExp(`^${regexStr}$`, flags).test(file);
-  } catch (_) {
-    return false;
-  }
+  return matchGlobSegments(file.split("/"), pattern.split("/"), caseInsensitive);
 }
 
 export function isForbiddenPath(filePath, config = {}) {
@@ -256,8 +340,19 @@ export function checkScope(files = [], scope = {}, opts = {}) {
     const file = canonicalizePath(rawFile);
 
     // A path that climbs out of the repository root can never be legitimate and
-    // must not be silently pattern-matched against repo-relative rules.
-    if (file === ".." || file.startsWith("../") || file.startsWith("/")) {
+    // must not be silently pattern-matched against repo-relative rules. This
+    // covers every spelling: POSIX absolute (`/etc/passwd`) and traversal
+    // (`../`, `..`), Windows drive-qualified and drive-relative (`C:\...`,
+    // `C:/...`, `C:foo`), and UNC (`\\server\share`, `//server/share`). The raw
+    // spelling is checked as well as the canonical one, because canonicalisation
+    // folds a leading `//` UNC into `/` and the check must fail on both.
+    if (
+      file === ".." ||
+      file.startsWith("../") ||
+      file.startsWith("/") ||
+      isWindowsAbsolutePath(rawFile) ||
+      isWindowsAbsolutePath(file)
+    ) {
       violations.push({ file, reason: "Path escapes the repository root", rule: "deny", pattern: "<traversal>" });
       continue;
     }
@@ -393,6 +488,59 @@ export function checkCrossPackageImports(diffOrText = "", root = process.cwd(),
 // regex without changing how the value renders, copies, or authenticates.
 const INVISIBLE_CHARS = /[\u00AD\u200B-\u200F\u2028\u2029\u202A-\u202E\u2060-\u2064\uFEFF]/g;
 
+// Unicode lookalikes that NFKD does NOT decompose. Full-width and other
+// compatibility forms are handled by String#normalize("NFKD") below; these are
+// the Cyrillic/Greek/Latin homoglyphs that survive NFKD because they are
+// distinct code points with no compatibility decomposition. A credential
+// scanner without this table can be defeated by a single substituted glyph,
+// e.g. `ghp_` spelled with Cyrillic `р`.
+const CONFUSABLE_TO_ASCII = new Map([
+  // Cyrillic
+  ["А", "A"], ["В", "B"], ["Е", "E"], ["К", "K"], ["М", "M"], ["Н", "H"],
+  ["О", "O"], ["Р", "P"], ["С", "C"], ["Т", "T"], ["У", "Y"], ["Х", "X"],
+  ["а", "a"], ["е", "e"], ["о", "o"], ["р", "p"], ["с", "c"], ["у", "y"],
+  ["х", "x"], ["і", "i"], ["ј", "j"], ["ѕ", "s"],
+  // Greek
+  ["Α", "A"], ["Β", "B"], ["Ε", "E"], ["Ζ", "Z"], ["Η", "H"], ["Ι", "I"],
+  ["Κ", "K"], ["Μ", "M"], ["Ν", "N"], ["Ο", "O"], ["Ρ", "P"], ["Τ", "T"],
+  ["Υ", "Y"], ["Χ", "X"], ["ο", "o"], ["ι", "i"], ["ν", "v"], ["υ", "u"],
+  ["ρ", "p"], ["τ", "t"], ["χ", "x"],
+  // Other Unicode lookalikes
+  ["ſ", "s"], // U+017F LATIN SMALL LETTER LONG S
+  ["K", "K"], // U+212A KELVIN SIGN
+]);
+
+/**
+ * Reduces the confusable spellings a credential can hide behind to plain
+ * ASCII before the secret patterns run (`SEC-04`).
+ *
+ *   1. NFKD decomposes full-width and other compatibility forms
+ *      (`ｇｈｐ＿…` → `ghp_…`).
+ *   2. Combining marks the decomposition may leave behind are stripped
+ *      (`e\u0301` → `e`).
+ *   3. The curated lookalike table maps Cyrillic/Greek/Latin homoglyphs that
+ *      NFKD cannot see through to their ASCII target.
+ *
+ * This is the zero-dependency subset of Unicode TR39 confusable handling; the
+ * full confusables data table is intentionally omitted so the kit keeps
+ * shipping with no runtime dependencies.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function normalizeSecretText(str) {
+  if (!str || typeof str !== "string") return str;
+  let out = str;
+  try {
+    out = out.normalize("NFKD");
+  } catch (_) {}
+  out = out.replace(/[\u0300-\u036f]/g, "");
+  for (const [from, to] of CONFUSABLE_TO_ASCII) {
+    out = out.split(from).join(to);
+  }
+  return out;
+}
+
 // A credential split across a source-level string concatenation is invisible to
 // a line-oriented scanner. This is not only an evasion technique — formatters
 // wrap long string literals exactly this way, so it also happens by accident.
@@ -442,9 +590,14 @@ function secretScanVariants(addedLines) {
 
   const hexDecoded = tryHexDecodeTokens(dejoined);
   const pctDecoded = tryPercentDecode(dejoined);
+  // Confusable / NFKD normalisation runs over both the raw text and the
+  // concatenation-collapsed text, so a credential that is both split across a
+  // source-level join AND spelled with homoglyphs still surfaces.
+  const confusable = normalizeSecretText(stripped);
+  const confusableDejoined = normalizeSecretText(dejoined);
 
   return {
-    all: [...new Set([addedLines, stripped, dejoined, hexDecoded, pctDecoded])],
+    all: [...new Set([addedLines, stripped, dejoined, hexDecoded, pctDecoded, confusable, confusableDejoined])],
     normalized: dejoined,
   };
 }
@@ -600,7 +753,7 @@ function splitDiffByFile(diffText) {
   };
 
   for (const line of diffText.split("\n")) {
-    if (line.startsWith("+++")) {
+    if ((line.startsWith("+++ ") || line.startsWith("+++ b/") || line.startsWith("+++ /dev/null")) && !line.startsWith("++++")) {
       const name = line.slice(3).split("\t")[0].trim().replace(/^b\//, "");
       select(name && name !== "/dev/null" ? name : null);
       lineNo = null;
@@ -673,6 +826,104 @@ function locateFindingLine(lines, type) {
   return null;
 }
 
+/**
+ * Detects test file assertion tampering, weakening, or test skips.
+ *
+ * @param {string} diffOrText - Unified git diff
+ * @param {Object} [options]
+ * @param {boolean} [options.allowTestModifications=false]
+ * @returns {{ ok: boolean, violations: Array<{ file: string, type: string, line?: number, reason: string }> }}
+ */
+export function checkTestTampering(diffOrText = "", options = {}) {
+  if (!diffOrText || typeof diffOrText !== "string") return { ok: true, violations: [] };
+  if (options.allowTestModifications === true) return { ok: true, violations: [] };
+
+  const violations = [];
+  const lines = diffOrText.split("\n");
+  let currentFile = null;
+  let currentLineNo = null;
+
+  const isTestFile = (f) => {
+    if (!f) return false;
+    const n = f.replace(/\\/g, "/").toLowerCase();
+    return (
+      n.includes(".test.") ||
+      n.includes(".spec.") ||
+      n.includes("_test.") ||
+      n.includes("/test/") ||
+      n.includes("/tests/") ||
+      n.includes("/__tests__/")
+    );
+  };
+
+  const SKIP_INJECTIONS = [
+    { pattern: /\b(?:it|test|describe|context)\.skip\s*\(/i, desc: "Injected test skip (.skip())" },
+    { pattern: /\b(?:xit|xtest|xdescribe)\s*\(/i, desc: "Injected disabled test (xit/xtest/xdescribe)" },
+    { pattern: /@pytest\.mark\.skip/i, desc: "Injected Pytest skip decorator (@pytest.mark.skip)" },
+    { pattern: /\bt\.Skip\s*\(/i, desc: "Injected Go test skip (t.Skip())" },
+    { pattern: /#\[ignore\]/i, desc: "Injected Rust test ignore attribute (#[ignore])" },
+    { pattern: /\/\/\s*@ts-ignore/i, desc: "Injected TypeScript ignore comment (// @ts-ignore)" },
+    { pattern: /\/\/\s*@ts-nocheck/i, desc: "Injected TypeScript nocheck directive (// @ts-nocheck)" },
+  ];
+
+  const COMMENTED_ASSERTION = /^\+\s*(?:\/\/|\/\*)\s*(?:expect\(|assert\.|assert\(|t\.expect|t\.assert)/i;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if ((line.startsWith("+++ ") || line.startsWith("+++ b/") || line.startsWith("+++ /dev/null")) && !line.startsWith("++++")) {
+      const target = line.slice(3).split("\t")[0].trim().replace(/^b\//, "");
+      currentFile = target && target !== "/dev/null" ? target : null;
+      currentLineNo = null;
+      continue;
+    }
+
+    const hunkMatch = /^@@ -\d+(?:,\d+)? \+(\d+)/.exec(line);
+    if (hunkMatch) {
+      currentLineNo = Number(hunkMatch[1]);
+      continue;
+    }
+
+    if (!currentFile || !isTestFile(currentFile)) {
+      continue;
+    }
+
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      const addedText = line.slice(1);
+
+      // Check skip injections
+      for (const skipRule of SKIP_INJECTIONS) {
+        if (skipRule.pattern.test(addedText)) {
+          violations.push({
+            file: currentFile,
+            line: currentLineNo,
+            type: "TEST_SKIP_INJECTION",
+            reason: `Test Tamper Guard: ${skipRule.desc} found in ${currentFile}${currentLineNo ? `:${currentLineNo}` : ""}`,
+          });
+        }
+      }
+
+      // Check commented-out assertions
+      if (COMMENTED_ASSERTION.test(line)) {
+        violations.push({
+          file: currentFile,
+          line: currentLineNo,
+          type: "COMMENTED_ASSERTION",
+          reason: `Test Tamper Guard: Commented-out test assertion detected in ${currentFile}${currentLineNo ? `:${currentLineNo}` : ""}`,
+        });
+      }
+
+      if (currentLineNo !== null) currentLineNo++;
+    } else if (currentLineNo !== null && !line.startsWith("-") && !line.startsWith("\\")) {
+      currentLineNo++;
+    }
+  }
+
+  return {
+    ok: violations.length === 0,
+    violations,
+  };
+}
+
 export function scanDiff(diffTextStr = "", options = {}) {
   if (!diffTextStr) return { ok: true, findings: [] };
 
@@ -727,8 +978,15 @@ export function scanDiff(diffTextStr = "", options = {}) {
     }
   }
 
+  const tamperingRes = checkTestTampering(diffTextStr, options);
+  if (!tamperingRes.ok) {
+    for (const v of tamperingRes.violations) {
+      findings.push({ severity: "CRITICAL", type: "TEST_TAMPERING_DETECTED", file: v.file ?? null, line: v.line ?? null, description: v.reason });
+    }
+  }
+
   return {
-    ok: secretsOk && edgeRes.ok && crossPkgRes.ok,
+    ok: secretsOk && edgeRes.ok && crossPkgRes.ok && tamperingRes.ok,
     findings,
   };
 }

package/src/session-ops.mjs

@@ -0,0 +1,312 @@
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createProvider } from "./provider.mjs";
+import { loadConfig, resolveRoot } from "./config.mjs";
+import { redactSecrets } from "./security.mjs";
+
+/**
+ * Parses human-readable duration strings (e.g. "7d", "24h", "30m", "60s") into milliseconds.
+ *
+ * @param {string|number} duration
+ * @returns {number} Milliseconds
+ */
+export function parseAgeDuration(duration) {
+  if (typeof duration === "number" && Number.isFinite(duration)) return duration;
+  if (!duration || typeof duration !== "string") return 0;
+  const match = duration.trim().match(/^(\d+(?:\.\d+)?)\s*([smhdw])$/i);
+  if (!match) {
+    const num = Number(duration);
+    return Number.isFinite(num) ? num : 0;
+  }
+  const val = parseFloat(match[1]);
+  const unit = match[2].toLowerCase();
+  switch (unit) {
+    case "s": return val * 1000;
+    case "m": return val * 60 * 1000;
+    case "h": return val * 60 * 60 * 1000;
+    case "d": return val * 24 * 60 * 60 * 1000;
+    case "w": return val * 7 * 24 * 60 * 60 * 1000;
+    default: return 0;
+  }
+}
+
+/**
+ * Extracts git diff patch, PR details, and modified files from a Jules session.
+ *
+ * @param {string} sessionId
+ * @param {object} opts
+ * @returns {Promise<{ ok: boolean, id: string, patch: string, pr: object|null, files: string[], error?: string }>}
+ */
+export async function extractSessionPatch(sessionId, opts = {}) {
+  if (!sessionId || typeof sessionId !== "string") {
+    throw new TypeError("extractSessionPatch requires a valid sessionId string");
+  }
+  const root = opts.root || resolveRoot();
+  const config = opts.config || loadConfig(root);
+  const provider = opts.provider || createProvider(config.provider || "jules", config);
+
+  const session = await provider.getSession(sessionId, opts);
+  const activitiesRes = await provider.listActivities(sessionId, opts).catch(() => ({ activities: [] }));
+  const activities = activitiesRes.activities || [];
+
+  let patch = "";
+  let pr = null;
+  const files = new Set();
+
+  // 1. Inspect session outputs
+  const outputs = session?.raw?.outputs || session?.outputs || [];
+  for (const out of outputs) {
+    if (out.pullRequest) {
+      pr = out.pullRequest;
+    }
+    if (out.gitPatch || out.patch || out.diff) {
+      patch = out.gitPatch || out.patch || out.diff;
+    }
+  }
+
+  // 2. Inspect activity artifacts and logs if patch wasn't in top-level output
+  for (const act of activities) {
+    if (act.pullRequest) pr = act.pullRequest;
+    if (act.gitPatch || act.patch || act.diff) {
+      patch = patch || act.gitPatch || act.patch || act.diff;
+    }
+    if (act.artifacts && Array.isArray(act.artifacts)) {
+      for (const art of act.artifacts) {
+        if (art.patch || art.diff || (typeof art.content === "string" && art.content.startsWith("diff --git"))) {
+          patch = patch || art.patch || art.diff || art.content;
+        }
+        if (art.path || art.filename) {
+          files.add(art.path || art.filename);
+        }
+      }
+    }
+    if (act.changedFiles && Array.isArray(act.changedFiles)) {
+      act.changedFiles.forEach((f) => files.add(f));
+    }
+  }
+
+  // Extract changed files from patch headers if files set is empty
+  if (patch && files.size === 0) {
+    const fileMatches = patch.matchAll(/^diff --git a\/(.+?) b\/(.+?)$/gm);
+    for (const m of fileMatches) {
+      files.add(m[2]);
+    }
+  }
+
+  return {
+    ok: Boolean(patch || pr),
+    id: sessionId,
+    patch: patch ? (patch.endsWith("\n") ? patch : patch + "\n") : "",
+    pr,
+    files: Array.from(files),
+    rawSession: session.raw,
+  };
+}
+
+/**
+ * Applies a Jules session's patch to the local working tree with git apply safety checks.
+ *
+ * @param {string} sessionId
+ * @param {object} opts
+ * @returns {Promise<{ ok: boolean, patchApplied: boolean, checkPassed: boolean, patch: string, files: string[], error?: string }>}
+ */
+export async function applySessionPatch(sessionId, opts = {}) {
+  const root = opts.root || resolveRoot();
+  const res = await extractSessionPatch(sessionId, { ...opts, root });
+
+  if (!res.patch) {
+    return {
+      ok: false,
+      patchApplied: false,
+      checkPassed: false,
+      patch: "",
+      files: res.files || [],
+      error: "No git patch found in session output or activities.",
+    };
+  }
+
+  if (opts.save) {
+    const savePath = resolve(root, opts.save);
+    writeFileSync(savePath, res.patch, "utf-8");
+  }
+
+  // 1. Dry run: git apply --check
+  const checkRes = spawnSync("git", ["apply", "--check", "-"], {
+    cwd: root,
+    input: res.patch,
+    encoding: "utf-8",
+  });
+
+  if (checkRes.status !== 0) {
+    const stderr = (checkRes.stderr || "").trim();
+    return {
+      ok: false,
+      patchApplied: false,
+      checkPassed: false,
+      patch: res.patch,
+      files: res.files,
+      error: `git apply --check failed: ${stderr || "Patch does not cleanly apply to working directory"}`,
+    };
+  }
+
+  // 2. If apply requested, execute git apply
+  if (opts.apply) {
+    const applyRes = spawnSync("git", ["apply", "-"], {
+      cwd: root,
+      input: res.patch,
+      encoding: "utf-8",
+    });
+
+    if (applyRes.status !== 0) {
+      const stderr = (applyRes.stderr || "").trim();
+      return {
+        ok: false,
+        patchApplied: false,
+        checkPassed: true,
+        patch: res.patch,
+        files: res.files,
+        error: `git apply failed: ${stderr}`,
+      };
+    }
+
+    return {
+      ok: true,
+      patchApplied: true,
+      checkPassed: true,
+      patch: res.patch,
+      files: res.files,
+    };
+  }
+
+  return {
+    ok: true,
+    patchApplied: false,
+    checkPassed: true,
+    patch: res.patch,
+    files: res.files,
+  };
+}
+
+/**
+ * Gathers failure context and error output from a failed session and synthesizes a new OODA retry session.
+ *
+ * @param {string} sessionId
+ * @param {object} opts
+ * @returns {Promise<{ ok: boolean, originalSessionId: string, newSession: object, failureReason: string }>}
+ */
+export async function retrySession(sessionId, opts = {}) {
+  if (!sessionId || typeof sessionId !== "string") {
+    throw new TypeError("retrySession requires a valid sessionId string");
+  }
+  const root = opts.root || resolveRoot();
+  const config = opts.config || loadConfig(root);
+  const provider = opts.provider || createProvider(config.provider || "jules", config);
+
+  const session = await provider.getSession(sessionId, opts);
+  const activitiesRes = await provider.listActivities(sessionId, opts).catch(() => ({ activities: [] }));
+  const activities = activitiesRes.activities || [];
+
+  // Extract failure diagnostics
+  const errors = [];
+  for (const act of activities) {
+    if (act.error) errors.push(typeof act.error === "string" ? act.error : JSON.stringify(act.error));
+    if (act.executionOutput && (act.exitCode !== 0 || act.status === "FAILED")) {
+      errors.push(act.executionOutput);
+    }
+  }
+
+  const rawPrompt = session?.raw?.prompt || session?.prompt || "";
+  const title = session?.raw?.title || `Retry of Session ${sessionId}`;
+  const failureReason = errors.join("\n").slice(0, 4000) || "Previous session did not complete cleanly.";
+
+  let synthesizedPrompt = rawPrompt;
+  if (opts.withFailure !== false && failureReason) {
+    synthesizedPrompt = `${rawPrompt}\n\n[PREVIOUS_ATTEMPT_FAILURE_DIAGNOSTIC]\nThe previous automated session failed with the following error output:\n\`\`\`\n${redactSecrets(failureReason)}\n\`\`\`\nPlease analyze this failure, fix the root cause, and ensure all tests pass.\n`;
+  }
+
+  const source = session?.raw?.sourceContext?.source || opts.source;
+  const branch = session?.raw?.sourceContext?.githubRepoContext?.startingBranch || opts.branch || "main";
+
+  const dispatchRes = await provider.dispatch(
+    {
+      title: opts.title || title,
+      prompt: synthesizedPrompt,
+      role: opts.role,
+      source,
+      branch,
+    },
+    opts
+  );
+
+  return {
+    ok: true,
+    originalSessionId: sessionId,
+    newSession: dispatchRes,
+    failureReason,
+  };
+}
+
+/**
+ * Queries and batch-archives old or completed Jules sessions based on age and state filters.
+ *
+ * @param {object} opts
+ * @returns {Promise<{ ok: boolean, matchedCount: number, archivedCount: number, sessions: Array<{ id: string, state: string, createTime: string, action: string }> }>}
+ */
+export async function pruneSessions(opts = {}) {
+  const root = opts.root || resolveRoot();
+  const config = opts.config || loadConfig(root);
+  const provider = opts.provider || createProvider(config.provider || "jules", config);
+
+  const listRes = await provider.listSessions({ ...opts, pageSize: opts.pageSize || 100 });
+  const allSessions = listRes.sessions || [];
+
+  const maxAgeMs = opts.age ? parseAgeDuration(opts.age) : 0;
+  const now = Date.now();
+  const targetState = opts.state ? String(opts.state).toUpperCase() : null;
+
+  const matched = [];
+  for (const s of allSessions) {
+    const state = (s.state || s.status || "UNKNOWN").toUpperCase();
+    if (targetState && state !== targetState) continue;
+
+    if (maxAgeMs > 0) {
+      const timeStr = s.createTime || s.updateTime;
+      const sessionTime = timeStr ? new Date(timeStr).getTime() : 0;
+      if (sessionTime > 0 && now - sessionTime < maxAgeMs) {
+        continue; // Session is newer than the cutoff age
+      }
+    }
+
+    matched.push(s);
+  }
+
+  const results = [];
+  for (const s of matched) {
+    const id = s.id || (s.name ? s.name.split("/").pop() : "");
+    if (!id) continue;
+
+    if (opts.dryRun) {
+      results.push({ id, state: s.state || s.status, createTime: s.createTime, action: "DRY_RUN_SKIP" });
+    } else {
+      try {
+        if (opts.delete) {
+          await provider.deleteSession(id, opts);
+          results.push({ id, state: s.state || s.status, createTime: s.createTime, action: "DELETED" });
+        } else {
+          await provider.archiveSession(id, opts);
+          results.push({ id, state: s.state || s.status, createTime: s.createTime, action: "ARCHIVED" });
+        }
+      } catch (err) {
+        results.push({ id, state: s.state || s.status, createTime: s.createTime, action: `ERROR: ${err.message}` });
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    matchedCount: matched.length,
+    archivedCount: results.filter((r) => r.action === "ARCHIVED" || r.action === "DELETED").length,
+    sessions: results,
+  };
+}