@tea-agent/loop-agent 0.1.0 → 0.2.1

package/dist/commands/loop.js

@@ -1,4 +1,5 @@
-import { appendLoopSignal, appendLoopRound, generateLoopCloseout, initializeLoop, loadLoopState, parseLoopSignalType, rewriteLoopContext, runLoopAuto, runLoopCursorFix, runLoopDagAction, runLoopPiReview, runLoopShellVerification, runLoopWorkflowAction, } from "../workflows/loop/index.js";
+import { appendLoopSignal, appendLoopRound, generateLoopCloseout, initializeLoop, loadLoopState, parseLoopSignalType, rewriteLoopContext, runLoopAuto, } from "../workflows/loop/index.js";
+import { runLoopAction } from "../application/loop/run-action.js";
 function usage() {
     return [
         "usage: loop <init|status|run|record-round|add-signal|closeout> <task-id> [options]",
@@ -159,20 +160,30 @@ export async function runLoop(repoRoot, args) {
             timeoutMs = parsed;
         }
         if (action === "pi-review") {
-            const record = await runLoopPiReview(repoRoot, taskId, {
-                timeoutMs,
-                cwd: readFlag(rest, "--cwd"),
-                provider: readFlag(rest, "--provider"),
-                model: readFlag(rest, "--model"),
+            const record = await runLoopAction({
+                action,
+                repoRoot,
+                taskId,
+                options: {
+                    timeoutMs,
+                    cwd: readFlag(rest, "--cwd"),
+                    provider: readFlag(rest, "--provider"),
+                    model: readFlag(rest, "--model"),
+                },
             });
             console.log(JSON.stringify(record, null, 2));
             return;
         }
         if (action === "cursor-fix") {
-            const record = await runLoopCursorFix(repoRoot, taskId, {
-                timeoutMs,
-                cwd: readFlag(rest, "--cwd"),
-                model: readFlag(rest, "--model"),
+            const record = await runLoopAction({
+                action,
+                repoRoot,
+                taskId,
+                options: {
+                    timeoutMs,
+                    cwd: readFlag(rest, "--cwd"),
+                    model: readFlag(rest, "--model"),
+                },
             });
             console.log(JSON.stringify(record, null, 2));
             return;
@@ -187,13 +198,18 @@ export async function runLoop(repoRoot, args) {
                 }
                 maxConcurrent = parsed;
             }
-            const record = await runLoopDagAction(repoRoot, taskId, {
-                mode: rest.includes("--execute") ? "execute" : "review",
-                cwd: readFlag(rest, "--cwd"),
-                dagPath: readFlag(rest, "--dag"),
-                runId: readFlag(rest, "--run-id"),
-                maxConcurrent,
-                noCursor: rest.includes("--no-cursor"),
+            const record = await runLoopAction({
+                action,
+                repoRoot,
+                taskId,
+                options: {
+                    mode: rest.includes("--execute") ? "execute" : "review",
+                    cwd: readFlag(rest, "--cwd"),
+                    dagPath: readFlag(rest, "--dag"),
+                    runId: readFlag(rest, "--run-id"),
+                    maxConcurrent,
+                    noCursor: rest.includes("--no-cursor"),
+                },
             });
             console.log(JSON.stringify(record, null, 2));
             return;
@@ -212,16 +228,21 @@ export async function runLoop(repoRoot, args) {
             if (profile && profile !== "pr-review") {
                 throw new Error(`unsupported workflow profile: ${profile}`);
             }
-            const record = await runLoopWorkflowAction(repoRoot, taskId, {
-                mode: rest.includes("--execute") ? "execute" : "review",
-                cwd: readFlag(rest, "--cwd"),
-                profile: profile,
-                workflowPath: readFlag(rest, "--workflow"),
-                runId: readFlag(rest, "--run-id"),
-                maxConcurrent,
-                base: readFlag(rest, "--base"),
-                head: readFlag(rest, "--head"),
-                changedFiles: readRepeatedFlag(rest, "--changed-file"),
+            const record = await runLoopAction({
+                action,
+                repoRoot,
+                taskId,
+                options: {
+                    mode: rest.includes("--execute") ? "execute" : "review",
+                    cwd: readFlag(rest, "--cwd"),
+                    profile: profile,
+                    workflowPath: readFlag(rest, "--workflow"),
+                    runId: readFlag(rest, "--run-id"),
+                    maxConcurrent,
+                    base: readFlag(rest, "--base"),
+                    head: readFlag(rest, "--head"),
+                    changedFiles: readRepeatedFlag(rest, "--changed-file"),
+                },
             });
             console.log(JSON.stringify(record, null, 2));
             return;
@@ -229,10 +250,15 @@ export async function runLoop(repoRoot, args) {
         if (action !== "shell-verify") {
             throw new Error("loop run currently supports --action shell-verify|pi-review|cursor-fix|dag|workflow");
         }
-        const record = await runLoopShellVerification(repoRoot, taskId, {
-            commands: readRepeatedFlag(rest, "--command"),
-            timeoutMs,
-            cwd: readFlag(rest, "--cwd"),
+        const record = await runLoopAction({
+            action: "shell-verify",
+            repoRoot,
+            taskId,
+            options: {
+                commands: readRepeatedFlag(rest, "--command"),
+                timeoutMs,
+                cwd: readFlag(rest, "--cwd"),
+            },
         });
         console.log(JSON.stringify(record, null, 2));
         return;

package/dist/commands/pi-prompt.js

@@ -9,17 +9,10 @@
  *   pi-prompt --cwd /path --timeout 120000 "task"
  */
 import { DEFAULT_TIMEOUT_MS } from "../executors/pi-executor.js";
+import { DEFAULT_PI_MODEL, DEFAULT_PI_PROVIDER, DEFAULT_PI_TOOLS, } from "../executors/pi-defaults.js";
 import { createOneShotPromptParseAccum, formatUnknownFlagError, parseOneShotCommonFlag, printOneShotHelpAndExit, resolveOneShotCwd, resolveOneShotTask, } from "../shared/one-shot-prompt-args.js";
 import { executeSingleSdkAttempt } from "../executors/pi-sdk-executor.js";
-export const DEFAULT_PI_PROVIDER = "wizard-local";
-export const DEFAULT_PI_MODEL = "glm-5.2";
-export const DEFAULT_PI_TOOLS = [
-    "read",
-    "bash",
-    "ast_grep_search",
-    "lsp_diagnostics",
-    "subagent",
-];
+export { DEFAULT_PI_MODEL, DEFAULT_PI_PROVIDER, DEFAULT_PI_TOOLS };
 const PI_PROMPT_USAGE = [
     "usage: pi-prompt [options] [task]",
     "",

package/dist/commands/run-dag.js

@@ -1,184 +1,11 @@
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { createDagCanvasObserver, resolveCanvasPath, } from "../workflows/dag/canvas-observer.js";
-import { loadDagSpecFromFile, runDag } from "../workflows/dag/runner.js";
-import { assertValidDagSpec, collectForbiddenExecutorIssues, } from "../workflows/dag/validate.js";
-export function parseRunDagArgs(args, defaultCwd) {
-    if (args.length === 0) {
-        throw new Error("usage: run-dag --dag <path> [--cwd <dir>] [--init-only] [--dry-run] [--max-concurrent N] [--run-id id] [--canvas-path <abs-path> | --canvas <name> [--canvases-dir <dir>]]");
-    }
-    let dagPath;
-    let cwd;
-    let initOnly = false;
-    let dryRun = false;
-    let maxConcurrent;
-    let runId;
-    let noCursor = false;
-    let canvasPath;
-    let canvasName;
-    let canvasesDir;
-    for (let i = 0; i < args.length; i += 1) {
-        const arg = args[i];
-        if (arg === "--dag") {
-            dagPath = args[++i];
-        }
-        else if (arg.startsWith("--dag=")) {
-            dagPath = arg.slice(6);
-        }
-        else if (arg === "--cwd" || arg === "-C") {
-            cwd = args[++i];
-        }
-        else if (arg.startsWith("--cwd=")) {
-            cwd = arg.slice(6);
-        }
-        else if (arg === "--init-only") {
-            initOnly = true;
-        }
-        else if (arg === "--dry-run") {
-            dryRun = true;
-        }
-        else if (arg === "--max-concurrent") {
-            maxConcurrent = Number(args[++i]);
-        }
-        else if (arg === "--run-id") {
-            runId = args[++i];
-        }
-        else if (arg === "--no-cursor") {
-            noCursor = true;
-        }
-        else if (arg === "--canvas-path") {
-            canvasPath = args[++i];
-        }
-        else if (arg.startsWith("--canvas-path=")) {
-            canvasPath = arg.slice(14);
-        }
-        else if (arg === "--canvas") {
-            canvasName = args[++i];
-        }
-        else if (arg.startsWith("--canvas=")) {
-            canvasName = arg.slice(9);
-        }
-        else if (arg === "--canvases-dir") {
-            canvasesDir = args[++i];
-        }
-        else if (arg.startsWith("--canvases-dir=")) {
-            canvasesDir = arg.slice(15);
-        }
-        else if (!arg.startsWith("-")) {
-            if (!dagPath)
-                dagPath = arg;
-            else
-                throw new Error(`unexpected positional argument: ${arg}`);
-        }
-        else {
-            throw new Error(`unknown run-dag flag: ${arg}`);
-        }
-    }
-    if (!dagPath) {
-        throw new Error("run-dag requires --dag <path>");
-    }
-    return {
-        dagPath: path.resolve(dagPath),
-        cwd: path.resolve(cwd ?? defaultCwd ?? process.cwd()),
-        initOnly,
-        dryRun,
-        maxConcurrent,
-        runId,
-        noCursor,
-        canvasPath,
-        canvasName,
-        canvasesDir,
-    };
-}
-async function loadRawTaskExecutorMap(dagPath) {
-    const raw = JSON.parse(await readFile(dagPath, "utf-8"));
-    const map = new Map();
-    for (const task of raw.tasks ?? []) {
-        if (typeof task.id === "string")
-            map.set(task.id, task.executor);
-    }
-    return map;
-}
-function assertNoCursorTasks(spec, rawTaskExecutors) {
-    const issues = collectForbiddenExecutorIssues(spec, ["cursor"]);
-    if (issues.length === 0)
-        return;
-    const details = issues
-        .map((issue) => {
-        const implicitDefault = rawTaskExecutors.get(issue.taskId) === undefined;
-        return `task=${issue.taskId}${implicitDefault ? " (implicit default)" : ""}`;
-    })
-        .join("; ");
-    throw new Error(`--no-cursor forbids cursor executor tasks: ${details}`);
-}
-function getCanvasFlushErrorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-async function flushCanvasSafely(canvas) {
-    if (!canvas)
-        return undefined;
-    try {
-        await canvas.flush();
-        return undefined;
-    }
-    catch (error) {
-        // Canvas is a derived view; failed writes must not decide canonical DAG success.
-        return getCanvasFlushErrorMessage(error);
-    }
-}
+import { parseRunDagArgs } from "../application/dag/args.js";
+import { runDagUseCase } from "../application/dag/run-dag.js";
+export { parseRunDagArgs };
 export async function runRunDag(repoRoot, rawArgs) {
     const parsed = parseRunDagArgs(rawArgs, repoRoot);
-    const spec = await loadDagSpecFromFile(parsed.dagPath);
-    if (parsed.noCursor) {
-        const rawTaskExecutors = await loadRawTaskExecutorMap(parsed.dagPath);
-        assertNoCursorTasks(spec, rawTaskExecutors);
-    }
-    assertValidDagSpec(spec);
-    const resolvedCanvasPath = resolveCanvasPath({
-        canvasPath: parsed.canvasPath,
-        canvasName: parsed.canvasName,
-        canvasesDir: parsed.canvasesDir,
-        cwd: parsed.cwd,
-    });
-    const canvas = resolvedCanvasPath
-        ? createDagCanvasObserver({ canvasPath: resolvedCanvasPath, spec })
-        : undefined;
-    if (parsed.dryRun) {
-        const summary = await runDag(spec, {
-            cwd: parsed.cwd,
-            dryRun: true,
-            runId: parsed.runId,
-            observer: canvas?.observer,
-        });
-        const canvasError = await flushCanvasSafely(canvas);
-        console.log(JSON.stringify({
-            mode: "dry-run",
-            title: spec.title,
-            taskCount: spec.tasks.length,
-            ranks: summary.ranks,
-            runId: summary.runId,
-            runDir: summary.runDir,
-            ...(resolvedCanvasPath ? { canvasPath: resolvedCanvasPath } : {}),
-            ...(canvasError ? { canvasError } : {}),
-        }, null, 2));
-        return;
-    }
-    const maxConcurrent = parsed.maxConcurrent;
-    const summary = await runDag(spec, {
-        cwd: parsed.cwd,
-        initOnly: parsed.initOnly,
-        dryRun: false,
-        maxConcurrent,
-        runId: parsed.runId,
-        observer: canvas?.observer,
+    const result = await runDagUseCase({
+        repoRoot,
+        ...parsed,
     });
-    const canvasError = await flushCanvasSafely(canvas);
-    const payload = resolvedCanvasPath
-        ? {
-            ...summary,
-            canvasPath: resolvedCanvasPath,
-            ...(canvasError ? { canvasError } : {}),
-        }
-        : summary;
-    console.log(JSON.stringify(payload, null, 2));
+    console.log(JSON.stringify(result, null, 2));
 }

package/dist/executors/cursor-executor-artifacts.js

@@ -1,5 +1,5 @@
-import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { writeTextArtifactFile } from "../infrastructure/harness/artifact-store.js";
 import { redactPromptForLog, truncateOutput, } from "./cursor-executor.js";
 import { formatCursorFailureMessage, } from "./cursor-execution-log.js";
 const SUMMARY_STDOUT_MAX = 4_000;
@@ -126,10 +126,9 @@ export function buildResultSummaryMarkdown(input) {
     return meta.join("\n");
 }
 export async function writeCursorExecutorArtifacts(artifactsDir, input) {
-    await mkdir(artifactsDir, { recursive: true });
     const promptPath = path.join(artifactsDir, "prompt.redacted.md");
     const summaryPath = path.join(artifactsDir, "result.summary.md");
-    await writeFile(promptPath, buildPromptRedactedMarkdown(input.prompt), "utf-8");
-    await writeFile(summaryPath, buildResultSummaryMarkdown(input), "utf-8");
+    await writeTextArtifactFile(promptPath, buildPromptRedactedMarkdown(input.prompt));
+    await writeTextArtifactFile(summaryPath, buildResultSummaryMarkdown(input));
     return { promptPath, summaryPath };
 }

package/dist/executors/cursor-worker-client.js

@@ -3,8 +3,9 @@ import { createInterface } from 'node:readline';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DEFAULT_CURSOR_TIMEOUT_MS, } from './cursor-executor.js';
-const WORKER_MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
-const WORKER_ENTRY = path.join(WORKER_MODULE_DIR, '../cursor-worker-entry.ts');
+const WORKER_MODULE_PATH = fileURLToPath(import.meta.url);
+const WORKER_MODULE_DIR = path.dirname(WORKER_MODULE_PATH);
+const WORKER_ENTRY = resolveCursorWorkerEntryPath(WORKER_MODULE_PATH);
 let workerProcess = null;
 let workerBoot = null;
 const pending = new Map();
@@ -37,8 +38,17 @@ export function shouldUseCursorWorker(options) {
         return true;
     return isCursorWorkerEnabled();
 }
+export function resolveCursorWorkerEntryPath(modulePath) {
+    const extension = path.extname(modulePath) === '.ts' ? '.ts' : '.js';
+    return path.join(path.dirname(modulePath), `../cursor-worker-entry${extension}`);
+}
+export function buildCursorWorkerScriptArgs(entryPath) {
+    return path.extname(entryPath) === '.ts'
+        ? ['--import', 'tsx/esm', entryPath]
+        : [entryPath];
+}
 function workerScriptArgs() {
-    return ['--import', 'tsx/esm', WORKER_ENTRY];
+    return buildCursorWorkerScriptArgs(WORKER_ENTRY);
 }
 export function getCursorWorkerEntryPath() {
     return WORKER_ENTRY;

package/dist/executors/dag-cursor-executor.js

@@ -1,5 +1,5 @@
-import { mkdir } from "node:fs/promises";
 import path from "node:path";
+import { ensureDagNodeArtifactDir } from "../infrastructure/harness/artifact-store.js";
 import { executeCursorTask } from "./cursor-executor.js";
 import { writeCursorExecutorArtifacts } from "./cursor-executor-artifacts.js";
 import { buildCursorExecutionLogRecord, persistCursorExecutionLog, } from "./cursor-execution-log.js";
@@ -14,8 +14,7 @@ export async function executeDagCursorNode(input, meta) {
         // Non-git cwd: skip write guard (documented limitation).
         beforeStatus = undefined;
     }
-    const artifactDir = path.join(meta.runDir, "artifacts", input.task.id);
-    await mkdir(artifactDir, { recursive: true });
+    const artifactDir = await ensureDagNodeArtifactDir(meta.runDir, input.task.id);
     const result = await executeCursorTask({
         task: input.prompt,
         cwd: input.cwd,

package/dist/executors/dag-pi-executor.js

@@ -1,5 +1,5 @@
-import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { writeTextArtifactFile } from "../infrastructure/harness/artifact-store.js";
 import { executePiStep, } from "./pi-executor.js";
 import { redactPromptForLog, truncateOutput } from "./cursor-executor.js";
 import { readGitStatusPorcelain, runPostRunWriteGuard, } from "./shell-write-guard.js";
@@ -211,11 +211,10 @@ export function buildPiResultSummaryMarkdown(input) {
     return lines.join("\n");
 }
 export async function writePiExecutorArtifacts(artifactsDir, input) {
-    await mkdir(artifactsDir, { recursive: true });
     const promptPath = path.join(artifactsDir, "prompt.redacted.md");
     const summaryPath = path.join(artifactsDir, "result.summary.md");
-    await writeFile(promptPath, buildPiPromptRedactedMarkdown(input.prompt), "utf-8");
-    await writeFile(summaryPath, buildPiResultSummaryMarkdown(input), "utf-8");
+    await writeTextArtifactFile(promptPath, buildPiPromptRedactedMarkdown(input.prompt));
+    await writeTextArtifactFile(summaryPath, buildPiResultSummaryMarkdown(input));
     return { promptPath, summaryPath };
 }
 export async function executeDagPiNode(input, meta, piStepFn = executePiStep) {

package/dist/executors/dag-static-executor.js

@@ -1,5 +1,4 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import path from "node:path";
+import { writeDagNodeTextArtifact } from "../infrastructure/harness/artifact-store.js";
 export function buildStaticResultSummaryMarkdown(input) {
     const lines = [
         "# Static execution summary",
@@ -26,15 +25,13 @@ export async function executeDagStaticNode(input, meta) {
     }
     const status = staticConfig.status ?? "success";
     const started = Date.now();
-    const nodeDir = path.join(meta.runDir, input.task.id);
-    await mkdir(nodeDir, { recursive: true });
     const summary = buildStaticResultSummaryMarkdown({
         nodeId: input.task.id,
         runId: meta.runId,
         resultMarkdown: staticConfig.resultMarkdown,
         status,
     });
-    await writeFile(path.join(nodeDir, "result.summary.md"), summary, "utf-8");
+    await writeDagNodeTextArtifact(meta.runDir, input.task.id, "result.summary.md", summary);
     return {
         ok: status === "success",
         stdout: staticConfig.resultMarkdown,

package/dist/executors/pi-defaults.js

@@ -0,0 +1,9 @@
+export const DEFAULT_PI_PROVIDER = "wizard-local";
+export const DEFAULT_PI_MODEL = "glm-5.2";
+export const DEFAULT_PI_TOOLS = [
+    "read",
+    "bash",
+    "ast_grep_search",
+    "lsp_diagnostics",
+    "subagent",
+];

package/dist/executors/shell-executor.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { writeDagNodeTextArtifact } from "../infrastructure/harness/artifact-store.js";
 import { truncateOutput } from "./cursor-executor.js";
 import { expandShellPreset, buildVerdictGateShellCommand } from "./shell-presets.js";
 import { pathsChangedDuringRun, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
@@ -12,23 +12,17 @@ const SUMMARY_STDERR_MAX = 2_000;
 const NODE_STDOUT_MAX = 12_000;
 const NODE_STDERR_MAX = 8_000;
 function resolveBashExecutable() {
-    if (process.env.LOOP_AGENT_BASH)
-        return process.env.LOOP_AGENT_BASH;
+    const envCandidate = process.env.LOOP_AGENT_BASH ?? process.env.GIT_BASH;
+    if (envCandidate && existsSync(envCandidate))
+        return envCandidate;
     if (process.platform !== "win32")
-        return "bash";
+        return envCandidate || "bash";
     const candidates = [
-        process.env.GIT_BASH,
-        process.env.ProgramFiles
-            ? path.join(process.env.ProgramFiles, "Git", "bin", "bash.exe")
-            : undefined,
-        process.env["ProgramFiles(x86)"]
-            ? path.join(process.env["ProgramFiles(x86)"], "Git", "bin", "bash.exe")
-            : undefined,
-        process.env.LocalAppData
-            ? path.join(process.env.LocalAppData, "Programs", "Git", "bin", "bash.exe")
-            : undefined,
-    ];
-    return candidates.find((candidate) => candidate && existsSync(candidate)) ?? "bash";
+        path.join(process.env.ProgramFiles ?? "C:\\Program Files", "Git", "bin", "bash.exe"),
+        path.join(process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)", "Git", "bin", "bash.exe"),
+        path.join(process.env.LocalAppData ?? "", "Programs", "Git", "bin", "bash.exe"),
+    ].filter(Boolean);
+    return candidates.find((candidate) => existsSync(candidate)) ?? envCandidate ?? "bash";
 }
 function isWithinRoot(root, candidate) {
     const relative = path.relative(root, candidate);
@@ -272,15 +266,13 @@ export async function executeDagShellNode(input, meta) {
     const commandsOk = results.every((result) => result.ok);
     const ok = commandsOk && writeGuardOk;
     const firstFailure = results.find((result) => !result.ok);
-    const nodeDir = path.join(meta.runDir, input.task.id);
-    await mkdir(nodeDir, { recursive: true });
-    await writeFile(path.join(nodeDir, "result.summary.md"), buildShellResultSummaryMarkdown({
+    await writeDagNodeTextArtifact(meta.runDir, input.task.id, "result.summary.md", buildShellResultSummaryMarkdown({
         nodeId: input.task.id,
         runId: meta.runId,
         rootCwd: input.cwd,
         results,
         writeGuardViolations: writeGuardOk ? undefined : writeGuardViolations,
-    }), "utf-8");
+    }));
     const aggregate = summarizeCommandResults(results);
     const stderrParts = [aggregate.stderr];
     if (!writeGuardOk) {

package/dist/governance/manifest-types.js

@@ -83,6 +83,7 @@ export const workflowPolicySchema = z
 export const harnessManifestSchema = z.object({
     version: z.number(),
     project: z.string(),
+    adapter: z.string().optional(),
     governanceRoot: z.string(),
     features: z
         .object({

package/dist/infrastructure/harness/active-residue-policy.js

@@ -0,0 +1,73 @@
+import path from "node:path";
+export const DAG_ACTIVE_DIR = ".harness/dag-runs/active";
+export const TOOL_ACTIVE_DIR = ".harness/runs/active";
+function filterRuntimeEntries(entries) {
+    return entries
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .filter((entry) => path.basename(entry) !== ".gitkeep");
+}
+export function evaluateActiveResidue(input) {
+    const findings = [];
+    const dagEntries = filterRuntimeEntries(input.dagActiveEntries);
+    if (dagEntries.length > 0) {
+        findings.push({
+            allowEnv: "HARNESS_ALLOW_ACTIVE_DAG_RUNS",
+            dir: DAG_ACTIVE_DIR,
+            entries: dagEntries,
+            kind: "dag-active",
+            message: "[HARNESS RUNTIME DIRTY] .harness/dag-runs/active contains runtime entries:",
+            remediation: [
+                "",
+                ".harness/dag-runs/active is a transient runtime area and should be empty at governance check time.",
+                "Completed DAG runs must be archived by run-dag to .harness/dag-runs/completed/<run-id>/.",
+                "Paused DAG runs (decision gate requiresHuman) live under .harness/dag-runs/paused/<run-id>/ and are gitignored runtime state.",
+                "Dry-run/init-only/stale active directories must be removed after review.",
+                "",
+                "If a live DAG is intentionally running while this check executes, rerun with:",
+                "  HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash scripts/check-harness-runtime-clean.sh",
+            ].join("\n"),
+            severity: "error",
+            strictEnv: null,
+        });
+    }
+    const toolEntries = filterRuntimeEntries(input.toolActiveEntries);
+    if (toolEntries.length > 0) {
+        findings.push({
+            allowEnv: "HARNESS_ALLOW_ACTIVE_TOOL_RUNS",
+            dir: TOOL_ACTIVE_DIR,
+            entries: toolEntries,
+            kind: "tool-active",
+            message: "[HARNESS RUNTIME WARNING] .harness/runs/active contains runtime entries:",
+            remediation: [
+                "",
+                ".harness/runs/active is for live one-shot tool runs only.",
+                "Completed, failed, or stale one-shot run evidence must be moved or explicitly reconciled.",
+                "",
+                "If a live one-shot run is intentionally active while this check executes, rerun with:",
+                "  HARNESS_ALLOW_ACTIVE_TOOL_RUNS=1 bash scripts/check-harness-runtime-clean.sh",
+            ].join("\n"),
+            severity: "warning",
+            strictEnv: "HARNESS_STRICT_ACTIVE_TOOL_RUNS",
+        });
+    }
+    return findings;
+}
+export function shouldFailActiveResidue(findings, env) {
+    const blocking = findings.filter((finding) => {
+        if (env[finding.allowEnv] === "1")
+            return false;
+        if (finding.kind === "dag-active")
+            return true;
+        return finding.strictEnv ? env[finding.strictEnv] === "1" : false;
+    });
+    return { blocking, fail: blocking.length > 0 };
+}
+export function formatActiveResidueFinding(finding) {
+    const lines = [
+        finding.message,
+        ...finding.entries.map((entry) => `  - ${entry}`),
+        finding.remediation,
+    ];
+    return `${lines.join("\n")}\n`;
+}