jules-orchestrator-kit 0.29.0 → 0.31.0

package/src/engine.mjs

@@ -6,11 +6,26 @@ import { withBudget, appendLedger, getQueueDir, ensureDir, rollbackBudgetReserva
 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";
+
+export { recordVerifyRun, readVerifyRuns, flakyVerdict, sanitizeUntrustedData, resolveAffectedTests };
+
+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.
@@ -46,14 +61,8 @@ export function isTaskFile(fileName, queueDirOrContent = null) {
       }
       if (typeof content === "string") {
         const trimmed = content.trimStart();
-        if (trimmed.startsWith("---")) {
-          const endFm = trimmed.indexOf("\n---", 3);
-          if (endFm !== -1) {
-            const frontMatter = trimmed.slice(3, endFm);
-            if (/(?:taskId|envelopeId|baseRef|baseSha|task|title|id|version|capabilities|scope|verify):/i.test(frontMatter)) {
-              return true;
-            }
-          }
+        if (trimmed.includes("JULES_TASK_ENVELOPE") || trimmed.includes("# Task ID:") || trimmed.startsWith("---")) {
+          return true;
         }
       }
     } catch (_) {}
@@ -134,8 +143,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 (_) {}
@@ -207,34 +219,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");
@@ -348,7 +405,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;
@@ -479,7 +536,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);
@@ -509,7 +569,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;
@@ -540,7 +600,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");
@@ -559,9 +620,12 @@ 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)) {
@@ -575,6 +639,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);
@@ -589,3 +656,195 @@ 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 });
@@ -103,3 +108,20 @@ export function validateEnvelope(envelope = {}, opts = {}) {
     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/mcp.mjs

@@ -9,7 +9,7 @@ import { ProgressBus } from "./mcp-progress.mjs";
 
 export const MCP_SERVER_INFO = {
   name: "jules-orchestrator-kit",
-  version: "0.29.0",
+  version: "0.29.1",
 };
 
 export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling
@@ -148,6 +148,19 @@ export const MCP_TOOLS = [
       },
     },
   },
+  {
+    name: "optimize_jules_prompt",
+    description: "Evaluate task prompt falsifiability, check static path validity, and synthesize optimized task envelope.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "Raw task prompt instructions to analyze or optimize" },
+        fix: { type: "boolean", description: "If true, synthesizes and returns an optimized task envelope" },
+        verifyCmd: { type: "string", description: "Optional explicit verification command" },
+      },
+      required: ["prompt"],
+    },
+  },
 ];
 
 export async function handleMcpRequest(request, opts = {}) {
@@ -291,6 +304,27 @@ export async function handleMcpRequest(request, opts = {}) {
         };
       }
 
+      if (toolName === "optimize_jules_prompt") {
+        if (!args || typeof args.prompt !== "string") {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32602, message: "Invalid parameters: 'prompt' must be a string" },
+          };
+        }
+        const { scorePromptFalsifiability, optimizeTaskPrompt } = await import("./task-optimizer.mjs");
+        const res = args.fix
+          ? optimizeTaskPrompt(args.prompt, { rootDir: root, verifyCmd: args.verifyCmd })
+          : scorePromptFalsifiability(args.prompt, { rootDir: root, verifyCmd: args.verifyCmd });
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
+          },
+        };
+      }
+
       return {
         jsonrpc: "2.0",
         id,

package/src/ops/checkpoint.mjs

@@ -0,0 +1,167 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { git, changedFiles, diffText } from "../git.mjs";
+import { resolveRoot } from "../config.mjs";
+
+export class CheckpointError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "CheckpointError";
+    this.code = opts.code || 1;
+  }
+}
+
+/**
+ * Ensures checkpoint storage directory exists.
+ */
+export function getCheckpointDir(root = resolveRoot()) {
+  const dir = join(root, ".agent", "state", "checkpoints");
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch (_) {}
+  return dir;
+}
+
+/**
+ * Creates an atomic pre-flight snapshot of the repository state before an agent task runs.
+ * @param {string} sessionId
+ * @param {object} options
+ * @returns {object} Checkpoint metadata
+ */
+export function createCheckpoint(sessionId = `session-${Date.now()}`, options = {}) {
+  const root = options.root || resolveRoot();
+  const dir = getCheckpointDir(root);
+
+  let headSha = "";
+  try {
+    headSha = git(["rev-parse", "HEAD"], { cwd: root, ignoreError: true }).trim();
+  } catch (_) {}
+
+  let branch = "";
+  try {
+    branch = git(["rev-parse", "--abbrev-ref", "HEAD"], { cwd: root, ignoreError: true }).trim();
+  } catch (_) {}
+
+  const uncommittedFiles = changedFiles(root, branch || "main", "working-tree");
+  const diffContent = diffText(root, branch || "main", "working-tree");
+
+  const snapshot = {
+    version: 1,
+    id: sessionId,
+    timestamp: new Date().toISOString(),
+    headSha,
+    branch,
+    uncommittedFiles,
+    diffContent,
+  };
+
+  const snapshotPath = join(dir, `${sessionId}.json`);
+  writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), "utf-8");
+
+  // Keep last 10 checkpoints
+  pruneCheckpoints(root, 10);
+
+  return snapshot;
+}
+
+/**
+ * Restores working tree and git state to a previously saved checkpoint.
+ * @param {string} sessionId or '--latest'
+ * @param {object} options
+ * @returns {object} Restore result summary
+ */
+export function restoreCheckpoint(sessionId = "--latest", options = {}) {
+  const root = options.root || resolveRoot();
+  const dir = getCheckpointDir(root);
+
+  let targetId = sessionId;
+  if (!targetId || targetId === "--latest" || targetId === "latest") {
+    const list = listCheckpoints(root);
+    if (list.length === 0) {
+      throw new CheckpointError("No checkpoints found to restore.");
+    }
+    targetId = list[0].id;
+  }
+
+  const snapshotFile = join(dir, `${targetId}.json`);
+  if (!existsSync(snapshotFile)) {
+    throw new CheckpointError(`Checkpoint snapshot file not found for session '${targetId}'.`);
+  }
+
+  let snapshot;
+  try {
+    snapshot = JSON.parse(readFileSync(snapshotFile, "utf-8"));
+  } catch (err) {
+    throw new CheckpointError(`Corrupted checkpoint file '${targetId}.json': ${err.message}`);
+  }
+
+  if (snapshot.headSha) {
+    try {
+      git(["reset", "--hard", snapshot.headSha], { cwd: root, ignoreError: true });
+    } catch (err) {
+      throw new CheckpointError(`Failed git reset --hard ${snapshot.headSha}: ${err.message}`);
+    }
+  }
+
+  // Clean untracked files generated during session
+  try {
+    git(["clean", "-fd"], { cwd: root, ignoreError: true });
+  } catch (_) {}
+
+  return {
+    ok: true,
+    id: snapshot.id,
+    headSha: snapshot.headSha,
+    restoredAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Lists all active checkpoints ordered by timestamp descending.
+ */
+export function listCheckpoints(root = resolveRoot()) {
+  const dir = getCheckpointDir(root);
+  if (!existsSync(dir)) return [];
+
+  const files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+  const items = [];
+
+  for (const file of files) {
+    const filePath = join(dir, file);
+    try {
+      const data = JSON.parse(readFileSync(filePath, "utf-8"));
+      items.push({
+        id: data.id || file.replace(/\.json$/, ""),
+        timestamp: data.timestamp || new Date(statSync(filePath).mtimeMs).toISOString(),
+        headSha: data.headSha || "",
+        branch: data.branch || "",
+        filePath,
+      });
+    } catch (_) {}
+  }
+
+  items.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
+  return items;
+}
+
+/**
+ * Prunes checkpoints keeping only the most recent N sessions.
+ */
+export function pruneCheckpoints(root = resolveRoot(), maxRetention = 10) {
+  const list = listCheckpoints(root);
+  if (list.length <= maxRetention) return 0;
+
+  const toRemove = list.slice(maxRetention);
+  let prunedCount = 0;
+
+  for (const item of toRemove) {
+    try {
+      if (existsSync(item.filePath)) {
+        rmSync(item.filePath, { force: true });
+        prunedCount++;
+      }
+    } catch (_) {}
+  }
+
+  return prunedCount;
+}