@tea-agent/loop-agent 0.20.1-beta.0 → 0.20.1

package/dist/workflows/dag/rerun-task.js

@@ -0,0 +1,284 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { generateTaskDagUseCase } from "../../application/dag/generate-task-dag.js";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { DAG_RUNS_DIR, isTerminalDagRunStatus, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
+export const RERUN_TASK_LINEAGE_REL_PATH = ".runtime/rerun-task-lineage.json";
+export function parseDagRerunTaskArgs(args) {
+    if (args.length === 0) {
+        throw new Error("usage: dag rerun-task --run-id <id> --reason <text> --request-id <key> [--profile auto|minimal|standard|reviewed|supervised] [--task-id <id>] [--json]");
+    }
+    let parentRunId;
+    let reason;
+    let requestId;
+    let profile = "auto";
+    let profileExplicit = false;
+    let taskIdOverride;
+    let execute = true;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--run-id")
+            parentRunId = args[++index];
+        else if (arg.startsWith("--run-id="))
+            parentRunId = arg.slice("--run-id=".length);
+        else if (arg === "--reason")
+            reason = args[++index];
+        else if (arg.startsWith("--reason="))
+            reason = arg.slice("--reason=".length);
+        else if (arg === "--request-id")
+            requestId = args[++index];
+        else if (arg.startsWith("--request-id="))
+            requestId = arg.slice("--request-id=".length);
+        else if (arg === "--profile") {
+            profile = parseDagRerunTaskProfile(args[++index]);
+            profileExplicit = true;
+        }
+        else if (arg.startsWith("--profile=")) {
+            profile = parseDagRerunTaskProfile(arg.slice("--profile=".length));
+            profileExplicit = true;
+        }
+        else if (arg === "--task-id")
+            taskIdOverride = args[++index];
+        else if (arg.startsWith("--task-id="))
+            taskIdOverride = arg.slice("--task-id=".length);
+        else if (arg === "--json")
+            continue;
+        else if (arg === "--no-execute")
+            execute = false;
+        else if (arg.startsWith("-"))
+            throw new Error(`unknown dag rerun-task flag: ${arg}`);
+        else
+            throw new Error(`unexpected positional argument: ${arg}`);
+    }
+    if (!parentRunId) {
+        throw new Error("dag rerun-task requires --run-id <id>");
+    }
+    if (!reason?.trim()) {
+        throw new Error("dag rerun-task requires --reason <text>");
+    }
+    if (!requestId?.trim()) {
+        throw new Error("dag rerun-task requires --request-id <key>");
+    }
+    return {
+        parentRunId,
+        reason: reason.trim(),
+        requestId: requestId.trim(),
+        profile,
+        profileExplicit,
+        ...(taskIdOverride?.trim() ? { taskIdOverride: taskIdOverride.trim() } : {}),
+        execute,
+    };
+}
+function parseDagRerunTaskProfile(value) {
+    if (value === "auto" ||
+        value === "minimal" ||
+        value === "standard" ||
+        value === "reviewed" ||
+        value === "supervised") {
+        return value;
+    }
+    throw new Error(`dag rerun-task --profile must be one of: auto, minimal, standard, reviewed, supervised; got ${value ?? ""}`);
+}
+function assessStandaloneTaskRerunEligibility(input) {
+    if (input.lifecycle === "paused") {
+        return {
+            eligible: false,
+            blockedReason: "parent-run-paused-use-resume",
+        };
+    }
+    if (input.lifecycle === "active" &&
+        !isTerminalDagRunStatus(input.state.status)) {
+        return {
+            eligible: false,
+            blockedReason: "parent-run-still-active",
+        };
+    }
+    if (!isTerminalDagRunStatus(input.state.status)) {
+        return {
+            eligible: false,
+            blockedReason: "parent-run-not-terminal",
+        };
+    }
+    if (input.state.status === "superseded" || input.state.status === "abandoned") {
+        return {
+            eligible: false,
+            blockedReason: `parent-run-${input.state.status}`,
+        };
+    }
+    if (input.state.status === "finished") {
+        return {
+            eligible: true,
+            note: "parent-run-succeeded-full-rerun-still-allowed",
+        };
+    }
+    return { eligible: true };
+}
+function resolveTaskIdForRerun(spec, taskIdOverride) {
+    if (taskIdOverride?.trim()) {
+        return { taskId: taskIdOverride.trim() };
+    }
+    const fromContract = spec.taskContractBinding?.taskId;
+    const fromSource = spec.sourceBinding?.taskId;
+    if (fromContract && fromSource && fromContract !== fromSource) {
+        return { blockedReason: "ambiguous-task-identity" };
+    }
+    const taskId = fromContract ?? fromSource;
+    if (!taskId) {
+        return {
+            blockedReason: "missing-task-identity-requires-task-id-override",
+        };
+    }
+    return { taskId };
+}
+function operatorRequestPath(cwd, requestId) {
+    return path.join(cwd, DAG_RUNS_DIR, ".operator-requests", `${requestId}.json`);
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readExistingOperatorRequest(cwd, requestId) {
+    try {
+        const raw = JSON.parse(await readFile(operatorRequestPath(cwd, requestId), "utf-8"));
+        if (raw.result && typeof raw.result === "object") {
+            return { ...raw.result, idempotentReplay: true };
+        }
+    }
+    catch {
+        // not found or unreadable
+    }
+    return undefined;
+}
+async function persistOperatorRequest(cwd, result) {
+    await writeJsonAtomic(operatorRequestPath(cwd, result.requestId), {
+        schemaVersion: 1,
+        kind: "standalone-task-rerun-request",
+        parentRunId: result.parentRunId,
+        newRunId: result.newRunId,
+        taskId: result.taskId,
+        reason: result.reason,
+        requestId: result.requestId,
+        createdAt: new Date().toISOString(),
+        result,
+    }, { repoRoot: cwd });
+}
+async function writeRerunTaskLineage(cwd, newRunId, input) {
+    const located = await locateDagRun(cwd, newRunId);
+    if (!located)
+        return;
+    await writeJsonAtomic(path.join(located.runDir, RERUN_TASK_LINEAGE_REL_PATH), {
+        schemaVersion: 1,
+        kind: "standalone-task-rerun",
+        parentRunId: input.parentRunId,
+        reason: input.reason,
+        requestId: input.requestId,
+        createdAt: new Date().toISOString(),
+    }, { repoRoot: cwd, allowCompletedFactsWrite: true });
+}
+function blockedResult(input) {
+    return {
+        ok: false,
+        parentRunId: input.parentRunId,
+        reason: input.reason,
+        requestId: input.requestId,
+        mode: "blocked",
+        blockedReason: input.blockedReason,
+        ...(input.note ? { note: input.note } : {}),
+        ...(input.taskId ? { taskId: input.taskId } : {}),
+    };
+}
+function extractRunSummary(generateResult) {
+    if (generateResult.mode === "generate+validate")
+        return undefined;
+    return generateResult.run;
+}
+function extractNewRunId(generateResult) {
+    const runSummary = extractRunSummary(generateResult);
+    return runSummary?.runId;
+}
+export async function rerunStandaloneTask(input) {
+    const existing = await readExistingOperatorRequest(input.cwd, input.requestId);
+    if (existing) {
+        return existing;
+    }
+    const located = await locateDagRun(input.cwd, input.parentRunId);
+    if (!located) {
+        throw new Error(`dag run not found: ${input.parentRunId}`);
+    }
+    const state = await readDagRunState(located.runDir);
+    const eligibility = assessStandaloneTaskRerunEligibility({
+        lifecycle: located.lifecycle,
+        state,
+    });
+    if (!eligibility.eligible) {
+        return blockedResult({
+            parentRunId: input.parentRunId,
+            reason: input.reason,
+            requestId: input.requestId,
+            blockedReason: eligibility.blockedReason,
+            note: eligibility.note,
+        });
+    }
+    const spec = await readDagRunSpec(located.runDir);
+    const taskResolution = resolveTaskIdForRerun(spec, input.taskIdOverride);
+    if (!taskResolution.taskId) {
+        return blockedResult({
+            parentRunId: input.parentRunId,
+            reason: input.reason,
+            requestId: input.requestId,
+            blockedReason: taskResolution.blockedReason,
+            note: eligibility.note,
+        });
+    }
+    const execute = input.execute ?? true;
+    const generateResult = await generateTaskDagUseCase({
+        repoRoot: input.cwd,
+        taskId: taskResolution.taskId,
+        cwd: input.cwd,
+        strictModels: true,
+        execute,
+        initOnly: false,
+        dryRun: false,
+        profile: input.profile ?? "auto",
+        profileExplicit: input.profileExplicit ?? false,
+    });
+    const newRunId = extractNewRunId(generateResult);
+    const runSummary = extractRunSummary(generateResult);
+    const completedSuccessfully = !execute ||
+        (runSummary !== undefined && "status" in runSummary && runSummary.status === "finished");
+    if (execute && newRunId) {
+        await writeRerunTaskLineage(input.cwd, newRunId, {
+            parentRunId: input.parentRunId,
+            reason: input.reason,
+            requestId: input.requestId,
+        });
+    }
+    const result = {
+        ok: completedSuccessfully,
+        parentRunId: input.parentRunId,
+        reason: input.reason,
+        requestId: input.requestId,
+        mode: "generate+validate+execute",
+        taskId: taskResolution.taskId,
+        ...(newRunId ? { newRunId } : {}),
+        ...(runSummary && !completedSuccessfully && "status" in runSummary
+            ? { note: `child-run-${runSummary.status}` }
+            : eligibility.note
+                ? { note: eligibility.note }
+                : {}),
+        generateResult,
+        ...(runSummary ? { runSummary } : {}),
+    };
+    if (await fileExists(operatorRequestPath(input.cwd, input.requestId))) {
+        const replay = await readExistingOperatorRequest(input.cwd, input.requestId);
+        if (replay)
+            return replay;
+    }
+    await persistOperatorRequest(input.cwd, result);
+    return result;
+}

package/dist/workflows/dag/retry-policy.js

@@ -17,10 +17,21 @@ export const DEFAULT_DAG_RETRY_CATEGORIES = [
     "unavailable",
 ];
 export const STRUCTURED_OUTPUT_RETRY_CATEGORY = "output-too-large";
+export const PROTOCOL_INVALID_RETRY_CATEGORY = "protocol-invalid";
 export const STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES = [
     ...DEFAULT_DAG_RETRY_CATEGORIES,
     STRUCTURED_OUTPUT_RETRY_CATEGORY,
 ];
+/** Categories allowed on nodes that declare a machine-readable outputProtocol. */
+export const PROTOCOL_AWARE_DAG_RETRY_CATEGORIES = [
+    ...DEFAULT_DAG_RETRY_CATEGORIES,
+    PROTOCOL_INVALID_RETRY_CATEGORY,
+];
+export const ALL_DAG_RETRY_CATEGORIES = [
+    ...DEFAULT_DAG_RETRY_CATEGORIES,
+    STRUCTURED_OUTPUT_RETRY_CATEGORY,
+    PROTOCOL_INVALID_RETRY_CATEGORY,
+];
 const RETRY_SAFE_PI_ROLES = new Set([
     "planner",
     "scout",
@@ -28,7 +39,7 @@ const RETRY_SAFE_PI_ROLES = new Set([
     "verifier",
     "closeout",
 ]);
-export const dagRetryCategorySchema = z.enum(STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES);
+export const dagRetryCategorySchema = z.enum(ALL_DAG_RETRY_CATEGORIES);
 export const dagRetryBackoffSchema = z.enum(["exponential"]);
 /**
  * Opt-in retry policy for a DagTask. Generated only for safe read-only Pi
@@ -86,6 +97,14 @@ export const STRUCTURED_REQUIRED_PI_RETRY_POLICY = {
     ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
     retryCategories: [...STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES],
 };
+/**
+ * Default retry for reviewer / recovery nodes that declare outputProtocol.
+ * Includes protocol-invalid so missing VERDICT lines are corrected in-node.
+ */
+export const PROTOCOL_AWARE_PI_RETRY_POLICY = {
+    ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
+    retryCategories: [...PROTOCOL_AWARE_DAG_RETRY_CATEGORIES],
+};
 /**
  * Deterministic helper: is this raw failure category eligible for retry under
  * the given policy? Pure function; executor never decides retry eligibility.

package/dist/workflows/dag/runner.js

@@ -1,4 +1,5 @@
 import { readdir, readFile } from "node:fs/promises";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { hostname } from "node:os";
 import path from "node:path";
 import { isHardBudgetBreached, resolveEffectiveMaxConcurrent, } from "../../application/evaluation/budget.js";
@@ -16,6 +17,7 @@ import { resolveRunningControllerIdentity } from "../../shared/package-metadata.
 import { normalizeDagPromptSources } from "./prompt-source.js";
 import { relocateConvergenceArtifactPaths, relocateRunArtifactPaths, } from "./upstream-artifacts.js";
 import { createSkillSnapshot, prepareSkillSnapshotForContinuation, writeSkillSnapshot, } from "./skill-snapshot.js";
+import { captureWorkspaceCheckpoint, WORKSPACE_CHECKPOINT_START_REL, WORKSPACE_CHECKPOINT_TERMINAL_REL, writeWorkspaceCheckpoint, } from "./workspace-checkpoint.js";
 import { buildNodePrompt, buildNodePromptWithResolvedSkillInstructions, executeDagNode, } from "./node-execution.js";
 import { runConvergencePassController, shouldEnableDagConvergence, } from "./convergence/controller.js";
 import { executeDagRanksOnce, isConditionSkippedReason } from "./scheduler.js";
@@ -149,6 +151,9 @@ export function createInitialRunState(spec, opts, ranks, runId = opts.runId ?? "
                 },
             }
             : {}),
+        ...(opts.workerAssociation
+            ? { workerAssociation: structuredClone(opts.workerAssociation) }
+            : {}),
     };
     initRunBudgetLedger(state, spec.budget);
     return state;
@@ -229,7 +234,17 @@ export async function runDag(spec, opts) {
         throw new Error(`failed to create run-start skill snapshot: ${error instanceof Error ? error.message : String(error)}`);
     }
     await writeRunState(runDir, state);
+    if (opts.workerAssociation) {
+        await writeJsonAtomic(path.join(runDir, ".runtime", "worker-association.json"), opts.workerAssociation);
+    }
     await notifyRunObserver(opts.observer, "onRunStart", state);
+    try {
+        const startCheckpoint = await captureWorkspaceCheckpoint(opts.cwd);
+        await writeWorkspaceCheckpoint(runDir, WORKSPACE_CHECKPOINT_START_REL, startCheckpoint);
+    }
+    catch (error) {
+        console.warn(`[run-dag] warning: failed to write workspace start checkpoint: ${error instanceof Error ? error.message : String(error)}`);
+    }
     if (opts.dryRun || opts.initOnly) {
         return {
             title: spec.title,
@@ -258,6 +273,34 @@ export async function runDag(spec, opts) {
     finally {
     }
 }
+export async function runDagContinuation(opts) {
+    const { maxConcurrent } = resolveEffectiveMaxConcurrent(Math.max(1, opts.maxConcurrent ?? 4), opts.spec.budget);
+    const state = opts.state;
+    state.status = "running";
+    const resumedAt = new Date().toISOString();
+    state.runner = {
+        pid: process.pid,
+        hostname: hostname(),
+        startedAt: resumedAt,
+        heartbeatAt: resumedAt,
+    };
+    const activeRunDir = getDagRunDir(opts.cwd, "active", state.runId);
+    const completedRunDir = getDagRunDir(opts.cwd, "completed", state.runId);
+    const pausedRunDir = getDagRunDir(opts.cwd, "paused", state.runId);
+    return executeDagCheckpoint({
+        spec: opts.spec,
+        state,
+        ranks: state.ranks,
+        runDir: opts.runDir,
+        cwd: opts.cwd,
+        maxConcurrent,
+        executeNode: opts.executeNode,
+        observer: opts.observer,
+        activeRunDir,
+        completedRunDir,
+        pausedRunDir,
+    });
+}
 export async function resumeDagRun(opts) {
     const located = await locateDagRun(opts.cwd, opts.runId);
     if (!located) {
@@ -496,6 +539,13 @@ async function executeDagCheckpoint(input) {
             finalizeTerminalRunStatus(state, spec.tasks.length);
             await persistState();
             await notifyRunObserver(input.observer, "onRunFinish", state);
+            try {
+                const terminalCheckpoint = await captureWorkspaceCheckpoint(cwd);
+                await writeWorkspaceCheckpoint(runDir, WORKSPACE_CHECKPOINT_TERMINAL_REL, terminalCheckpoint);
+            }
+            catch (error) {
+                console.warn(`[run-dag] warning: failed to write workspace terminal checkpoint: ${error instanceof Error ? error.message : String(error)}`);
+            }
             runDir = await moveToCompletedRunDir(runDir, completedRunDir);
         }
         await relocateRunArtifactPaths({

package/dist/workflows/dag/skill-snapshot.js

@@ -2,13 +2,14 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { writeTextAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { writeJsonAtomic, writeTextAtomic, } from "../../infrastructure/harness/atomic-write.js";
 import { resolveContextPolicy } from "./context-policy.js";
 import { buildDagNodePromptEnvelope } from "./prompt.js";
 import { resolveDagSkillInstructions, } from "./skill-instructions.js";
 export const SKILL_SNAPSHOT_SCHEMA_VERSION = 1;
 export const SKILL_SNAPSHOT_RESOLVER_VERSION = 1;
 export const SKILL_SNAPSHOT_REL_PATH = ".runtime/skill-snapshot.json";
+export const SKILL_SNAPSHOT_CONTINUATION_REL_PATH = ".runtime/skill-snapshot-continuation.json";
 const skillReferenceSchema = z.object({
     name: z.string().min(1),
     path: z.string().min(1),
@@ -75,7 +76,7 @@ const skillSnapshotSchema = z.object({
     resolverVersion: z.literal(SKILL_SNAPSHOT_RESOLVER_VERSION),
     runId: z.string().min(1),
     createdAt: z.string().datetime(),
-    mode: z.enum(["run-start", "legacy-resume-backfill"]),
+    mode: z.enum(["run-start", "legacy-resume-backfill", "continuation-from-parent"]),
     initialTaskIds: z.array(z.string().min(1)),
     bindings: z.array(skillSnapshotBindingSchema),
     profiles: z.array(skillSnapshotProfileSchema),
@@ -85,7 +86,7 @@ const skillSnapshotRefSchema = z.object({
     path: z.literal(SKILL_SNAPSHOT_REL_PATH),
     sha256: z.string().regex(/^[a-f0-9]{64}$/),
     createdAt: z.string().datetime(),
-    mode: z.enum(["run-start", "legacy-resume-backfill"]),
+    mode: z.enum(["run-start", "legacy-resume-backfill", "continuation-from-parent"]),
 }).strict();
 export class DagSkillSnapshotIntegrityError extends Error {
     constructor(message, options) {
@@ -329,6 +330,24 @@ function parseSnapshot(value) {
         throw new DagSkillSnapshotIntegrityError(`skill snapshot schema validation failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
 }
+export async function cloneParentSkillSnapshotForContinuation(input) {
+    const parentSnapshot = await readSkillSnapshot(input.parentRunDir, input.parentRef, { expectedRunId: input.parentRunId });
+    const parentSnapshotSha256 = hashSkillSnapshot(parentSnapshot);
+    const cloned = {
+        ...structuredClone(parentSnapshot),
+        runId: input.newRunId,
+        createdAt: (input.now ?? new Date()).toISOString(),
+        mode: "continuation-from-parent",
+    };
+    const ref = await writeSkillSnapshot(input.newRunDir, cloned);
+    await writeJsonAtomic(path.join(input.newRunDir, ...SKILL_SNAPSHOT_CONTINUATION_REL_PATH.split("/")), {
+        schemaVersion: 1,
+        mode: "continuation-from-parent",
+        parentRunId: input.parentRunId,
+        parentSnapshotSha256,
+    });
+    return ref;
+}
 export async function createSkillSnapshot(input) {
     const initialTaskIds = input.initialTaskIds
         ?? input.spec.tasks.map((task) => task.id);

package/dist/workflows/dag/types.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { campaignBudgetSchema, } from "../../application/evaluation/budget.js";
 import { assertDagPromptSourceRule } from "./prompt-source.js";
 import { dagRetryPolicySchema } from "./retry-policy.js";
+import { dagOutputProtocolSchema } from "./output-protocol.js";
 export const dagComplexitySchema = z.enum(["HIGH", "MED", "LOW"]);
 export const dagNodeExecutorSchema = z.enum(["pi", "shell", "static"]);
 export const CURSOR_DAG_EXECUTOR_REMOVED_ERROR = 'executor "cursor" is no longer supported; regenerate the DAG with Pi-only writers (implement-pi / repair-pi)';
@@ -382,6 +383,12 @@ export const dagTaskSchema = z.object({
     outputContract: z.string().optional(),
     outputMode: dagOutputModeSchema.optional(),
     firstProtocolLine: z.string().min(1).optional(),
+    /**
+     * Machine-readable output protocol (phase 1: first-line-enum).
+     * When set with retryOnInvalid, protocol-invalid failures may auto-retry
+     * on safe read-only Pi nodes before the node becomes ERROR.
+     */
+    outputProtocol: dagOutputProtocolSchema.optional(),
     /**
      * Explicit opt-in for the deterministic project governance context resolver
      * (AGENTS.md chain + referenced code standards). Only tasks that set this

package/dist/workflows/dag/validate.js

@@ -593,6 +593,16 @@ function validateRetryPolicyTaskConfig(task, issues) {
         });
     }
 }
+function validateOutputProtocolTaskConfig(task, issues) {
+    if (task.outputProtocol === undefined)
+        return;
+    if (!isSafeReadOnlyPiRetryCandidate(task)) {
+        issues.push({
+            type: "invalid-output-protocol",
+            message: `task ${task.id} declares outputProtocol but is not a safe read-only non-dynamic Pi node; output protocol retry is only allowed for read-only/none Pi planner/scout/reviewer/verifier/closeout nodes`,
+        });
+    }
+}
 function validateDecisionGateTaskConfig(task, issues) {
     if (!task.decisionGate?.enabled) {
         return;
@@ -692,6 +702,7 @@ export function validateDagSpec(spec) {
         validateStaticTaskConfig(task, issues);
         validateDecisionGateTaskConfig(task, issues);
         validateRetryPolicyTaskConfig(task, issues);
+        validateOutputProtocolTaskConfig(task, issues);
         validateProjectGovernanceTaskConfig(task, spec, issues);
     }
     validateSameRankWriteSetConflicts(spec, ranks, issues);

package/dist/workflows/dag/workspace-checkpoint.js

@@ -0,0 +1,163 @@
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+/**
+ * Workspace checkpoint for DAG continuation safety.
+ * Proves current repo content matches parent terminal state before importing facts.
+ */
+export const WORKSPACE_CHECKPOINT_START_REL = ".runtime/workspace-checkpoint-start.json";
+export const WORKSPACE_CHECKPOINT_TERMINAL_REL = ".runtime/workspace-checkpoint-terminal.json";
+function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+async function runGit(cwd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", args, {
+            cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf-8");
+        child.stderr.setEncoding("utf-8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve(stdout);
+                return;
+            }
+            reject(new Error(`git ${args.join(" ")} failed: ${stderr.trim() || stdout.trim()}`));
+        });
+    });
+}
+function normalizeGitPath(value) {
+    const target = value.includes(" -> ")
+        ? (value.split(" -> ").at(-1) ?? value)
+        : value;
+    return target.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function classifyPorcelainState(x, y) {
+    if (x === "?" || y === "?")
+        return "untracked";
+    if (x === "R" || y === "R")
+        return "renamed";
+    if (x === "D" || y === "D")
+        return "deleted";
+    if (x === "A" || y === "A")
+        return "added";
+    if (x === "M" || y === "M")
+        return "modified";
+    return "modified";
+}
+async function hashWorkspacePath(repoRoot, relPath, state) {
+    if (state === "deleted") {
+        return { contentSha256: sha256Hex(`deleted:${relPath}`) };
+    }
+    const abs = path.join(repoRoot, relPath);
+    try {
+        const st = await lstat(abs);
+        const mode = (st.mode & 0o777777).toString(8);
+        if (st.isSymbolicLink()) {
+            const target = await realpath(abs).catch(async () => {
+                const { readlink } = await import("node:fs/promises");
+                return readlink(abs);
+            });
+            return {
+                mode,
+                contentSha256: sha256Hex(`symlink:${relPath}->${target}`),
+            };
+        }
+        if (st.isDirectory()) {
+            // Submodule or directory entry — fingerprint via git ls-files / HEAD if possible.
+            return {
+                mode,
+                contentSha256: sha256Hex(`dir:${relPath}`),
+            };
+        }
+        const bytes = await readFile(abs);
+        return { mode, contentSha256: sha256Hex(bytes) };
+    }
+    catch {
+        return { contentSha256: sha256Hex(`missing:${relPath}`) };
+    }
+}
+function computeFingerprint(input) {
+    const payload = JSON.stringify({
+        gitHeadSha: input.gitHeadSha,
+        statusPorcelainSha256: input.statusPorcelainSha256,
+        changedPaths: input.changedPaths,
+    });
+    return sha256Hex(payload);
+}
+/**
+ * Capture a workspace checkpoint for the current working tree.
+ */
+export async function captureWorkspaceCheckpoint(repoRoot, options) {
+    const capturedAt = (options?.now ?? new Date()).toISOString();
+    const gitHeadSha = (await runGit(repoRoot, ["rev-parse", "HEAD"])).trim();
+    const porcelain = await runGit(repoRoot, [
+        "status",
+        "--porcelain=v1",
+        "--untracked-files=all",
+    ]);
+    const statusPorcelainSha256 = sha256Hex(porcelain);
+    const changedPaths = [];
+    for (const line of porcelain.split("\n")) {
+        const trimmed = line.trimEnd();
+        if (!trimmed)
+            continue;
+        const x = trimmed[0] ?? " ";
+        const y = trimmed[1] ?? " ";
+        const rawPath = trimmed.slice(3);
+        const relPath = normalizeGitPath(rawPath);
+        const state = classifyPorcelainState(x, y);
+        const hashed = await hashWorkspacePath(repoRoot, relPath, state);
+        changedPaths.push({
+            path: relPath,
+            state,
+            ...hashed,
+        });
+    }
+    changedPaths.sort((a, b) => a.path.localeCompare(b.path));
+    const fingerprint = computeFingerprint({
+        gitHeadSha,
+        statusPorcelainSha256,
+        changedPaths,
+    });
+    return {
+        schemaVersion: 1,
+        capturedAt,
+        gitHeadSha,
+        statusPorcelainSha256,
+        changedPaths,
+        fingerprint,
+    };
+}
+export async function writeWorkspaceCheckpoint(runDir, relPath, checkpoint) {
+    await writeJsonAtomic(path.join(runDir, relPath), checkpoint);
+}
+export async function readWorkspaceCheckpoint(runDir, relPath) {
+    try {
+        const raw = JSON.parse(await readFile(path.join(runDir, relPath), "utf8"));
+        if (raw?.schemaVersion !== 1 || typeof raw.fingerprint !== "string") {
+            return undefined;
+        }
+        return raw;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function workspaceFingerprintsMatch(left, right) {
+    if (!left?.fingerprint || !right?.fingerprint)
+        return false;
+    return left.fingerprint === right.fingerprint;
+}