@tea-agent/loop-agent 0.40.0-next.8 → 0.40.0

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

@@ -1,9 +1,12 @@
 import { appendFile, mkdir } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { computeExtensionToolAllowlistExtras } from "./pi-extension-resolver.js";
 import { BoundedTextPreview, classifyPiFailure, createPiJsonlStreamCollector, DEFAULT_ABORT_GRACE_MS, DEFAULT_STALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, extractPiEventStopReason, extractAssistantTextFromPiJson, } from "./pi-executor.js";
 import { serializeSessionEvent } from "./pi-event-serializer.js";
 import { PI_RECOMMENDED_COMPACTION, PI_RECOMMENDED_RETRY, } from "../shared/pi-retry-settings.js";
+import { createCompactionController, createContextPressureExtension, createSiftBridgeState, inMemoryCompactionSettings, isDagSiftEnabled, parseCompactionPolicy, parseSiftBridgeConfig, SIFT_RETRIEVE_TOOL_NAME, } from "../shared/pi-context-pressure/index.js";
 /** Same-session recovery after a transport stall. Exactly one continue per SDK attempt. */
 export const PI_SDK_STALL_CONTINUE_MAX = 1;
 /**
@@ -215,15 +218,37 @@ async function createSdkSession(sdk, input, shared) {
     // Inject rate-limit-tolerant auto-retry settings for the session lifecycle.
     // Prefer SettingsManager.inMemory so harness runs do not depend on ~/.pi or
     // project .pi/settings.json being present/trusted.
+    const policy = parseCompactionPolicy();
+    const compaction = {
+        ...PI_RECOMMENDED_COMPACTION,
+        ...inMemoryCompactionSettings(policy),
+    };
     const settingsManager = typeof SettingsManager?.inMemory === "function"
         ? SettingsManager.inMemory({
             retry: {
                 ...PI_RECOMMENDED_RETRY,
                 provider: { ...PI_RECOMMENDED_RETRY.provider },
             },
-            compaction: { ...PI_RECOMMENDED_COMPACTION },
+            compaction,
         }, { projectTrusted: true })
         : undefined;
+    const nodeSessionId = `dag-${randomUUID()}`;
+    const controller = createCompactionController();
+    const siftEnabled = isDagSiftEnabled();
+    const sift = siftEnabled.enabled
+        ? createSiftBridgeState(parseSiftBridgeConfig({
+            sessionId: nodeSessionId,
+            defaultStashRoot: path.join(os.tmpdir(), "loop-agent-dag-sift"),
+        }))
+        : undefined;
+    if (sift)
+        sift.counters = controller.counters;
+    const pressureExtension = createContextPressureExtension({
+        name: "dag-pi-context-pressure",
+        policy,
+        controller,
+        sift,
+    });
     const loader = new DefaultResourceLoader({
         cwd: input.cwd,
         agentDir,
@@ -233,6 +258,7 @@ async function createSdkSession(sdk, input, shared) {
         ...(input.additionalExtensionPaths && input.additionalExtensionPaths.length > 0
             ? { additionalExtensionPaths: input.additionalExtensionPaths }
             : {}),
+        ...(pressureExtension ? { extensionFactories: [pressureExtension] } : {}),
         ...(settingsManager ? { settingsManager } : {}),
         appendSystemPromptOverride: (base) => [
             ...base,
@@ -247,10 +273,12 @@ async function createSdkSession(sdk, input, shared) {
     // extras into the create-time allowlist; protected builtins, the deny
     // surface, and write-capable extension tools never join.
     const extensionToolExtras = [];
-    if (input.additionalExtensionPaths &&
-        input.additionalExtensionPaths.length > 0) {
-        const registered = collectLoaderExtensionToolNames(loader);
-        extensionToolExtras.push(...computeExtensionToolAllowlistExtras(registered.map((name) => ({ name })), input.toolNames));
+    const registered = collectLoaderExtensionToolNames(loader);
+    extensionToolExtras.push(...computeExtensionToolAllowlistExtras(registered.map((name) => ({ name })), input.toolNames));
+    if (siftEnabled.enabled &&
+        !extensionToolExtras.includes(SIFT_RETRIEVE_TOOL_NAME) &&
+        !input.toolNames.includes(SIFT_RETRIEVE_TOOL_NAME)) {
+        extensionToolExtras.push(...computeExtensionToolAllowlistExtras([{ name: SIFT_RETRIEVE_TOOL_NAME }], input.toolNames));
     }
     const sessionToolNames = [...input.toolNames, ...extensionToolExtras];
     if (input.requireWriterCustomTools) {
@@ -485,6 +513,9 @@ function extractSdkUsageSample(event) {
     const responseKey = responseKeyCandidates.find((value) => typeof value === "string" && value.length > 0);
     return responseKey ? { responseKey, tokens } : { tokens };
 }
+function maxSdkContextTokens(samples) {
+    return samples.reduce((maximum, sample) => Math.max(maximum, sample.tokens), 0);
+}
 function aggregateSdkTokenUsage(samples) {
     const identified = new Map();
     let anonymousMaximum = 0;
@@ -537,6 +568,9 @@ export async function executeSingleSdkAttempt(options) {
     const stdoutPreview = new BoundedTextPreview("stdout");
     const stdoutCollector = createPiJsonlStreamCollector();
     const usageSamples = [];
+    let observedTurns = 0;
+    let contextBudgetExhausted = false;
+    let contextBudgetDetail = "";
     // Writer-thinking-exhausted diagnosis evidence (AC-002). Collected in the
     // subscribe callback regardless of shouldPersistSessionEvent filtering, so a
     // length-stopped thinking-only attempt with no persisted write tool calls is
@@ -625,6 +659,7 @@ export async function executeSingleSdkAttempt(options) {
         });
         let resolveStall;
         let resolveSettlement;
+        let resolveContextBudget;
         let settled = false;
         let abortConfirmed = true;
         const persistRuntimeNote = (event) => {
@@ -655,6 +690,30 @@ export async function executeSingleSdkAttempt(options) {
                 clearTimeout(stallHandle);
             stallHandle = setTimeout(() => resolveStall?.("stall"), stallTimeoutMs);
         };
+        const checkContextBudget = () => {
+            if (contextBudgetExhausted || !options.contextBudget)
+                return;
+            // Context protection follows the largest provider-reported response
+            // snapshot, not cumulative billing usage across turns. Summing repeated
+            // input contexts would abort healthy multi-turn sessions far below the
+            // model's actual context window.
+            const observedTokens = maxSdkContextTokens(usageSamples);
+            const turnExceeded = options.contextBudget.maxTurns !== undefined &&
+                observedTurns >= options.contextBudget.maxTurns;
+            const tokenExceeded = options.contextBudget.maxTokens !== undefined &&
+                observedTokens >= options.contextBudget.maxTokens;
+            if (!turnExceeded && !tokenExceeded)
+                return;
+            contextBudgetExhausted = true;
+            contextBudgetDetail = [
+                "context-budget-exhausted:",
+                `observedTurns=${observedTurns}`,
+                `observedTokens=${observedTokens}`,
+                `maxTurns=${options.contextBudget.maxTurns ?? "unbounded"}`,
+                `maxTokens=${options.contextBudget.maxTokens ?? "unbounded"}`,
+            ].join(" ");
+            resolveContextBudget?.("context-budget");
+        };
         unsubscribe = session.subscribe((event) => {
             if (event.type === "agent_settled" && !settled) {
                 settled = true;
@@ -678,6 +737,9 @@ export async function executeSingleSdkAttempt(options) {
             const usageSample = extractSdkUsageSample(event);
             if (usageSample)
                 usageSamples.push(usageSample);
+            if (event.type === "turn_end")
+                observedTurns += 1;
+            checkContextBudget();
             // Capture writer-thinking-exhausted evidence BEFORE the
             // shouldPersistSessionEvent filter: thinking_delta is intentionally
             // excluded from persisted JSONL, but must still count toward the
@@ -700,6 +762,11 @@ export async function executeSingleSdkAttempt(options) {
         const runTurn = async (userMessage) => {
             const settlementPromise = resetSettlement();
             const stallPromise = resetStallPromise();
+            const contextBudgetPromise = options.contextBudget
+                ? new Promise((resolve) => {
+                    resolveContextBudget = resolve;
+                })
+                : null;
             const promptPromise = session.prompt(userMessage);
             // A settlement event is permitted to win the race while prompt() remains
             // pending. Observe a later rejection so it never becomes unhandled.
@@ -710,6 +777,7 @@ export async function executeSingleSdkAttempt(options) {
                 settlementPromise,
                 ...(timeoutPromise ? [timeoutPromise] : []),
                 ...(stallPromise ? [stallPromise] : []),
+                ...(contextBudgetPromise ? [contextBudgetPromise] : []),
             ]);
         };
         const disposeSession = async () => {
@@ -737,7 +805,12 @@ export async function executeSingleSdkAttempt(options) {
             : options.userMessage;
         let continuesSent = 0;
         let raced = await runTurn(promptMessage);
-        if (raced === "stall") {
+        if (raced === "context-budget") {
+            appendStderr(contextBudgetDetail);
+            abortConfirmed = await runSessionActionWithGrace("abort", () => session.abort());
+            await disposeSession();
+        }
+        else if (raced === "stall") {
             abortConfirmed = await runSessionActionWithGrace("abort", () => session.abort());
             const withinAbsoluteTimeout = timeoutMs <= 0 || Date.now() - startedAt < timeoutMs;
             const canContinue = abortConfirmed &&

package/dist/executors/shell-executor.js

@@ -32,11 +32,11 @@ import { materializeBackendTestExecutionContract } from "../workflows/dag/backen
 import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
 import { frontendTestLayoutFromSpec, } from "../workflows/dag/frontend-test-layout.js";
 import { backendTestGapDocSchema, ingestBackendTestGap, } from "../workflows/dag/backend-test-gap-fill.js";
-import { analyzeBackendTestCaseCoverage, analyzeBackendTestMarkdownPytestCorrespondence, materializeBackendTestCaseManifestFromFacts, } from "../workflows/dag/backend-test-case-coverage-analysis.js";
+import { analyzeBackendTestCaseCoverage, analyzeBackendTestMarkdownPytestCorrespondence, classifyBackendTestCorrespondenceRepair, materializeBackendTestCaseManifestFromFacts, } from "../workflows/dag/backend-test-case-coverage-analysis.js";
 import { materializeBackendTestResultFromPytestHtml, materializeBackendTestResultFromRunDir, parsePytestHtmlReport, } from "../workflows/dag/backend-test-result-contract.js";
 import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, resolveBackendTestMappedPytestScripts, collectJacocoCoverage, hasBlockingBackendMarkdownSafetyFindings, hasBlockingBackendMarkdownModuleStemFindings, inspectBackendTestEnvironment, markdownFiles, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, renderBackendTestL5Dashboard, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
 import { applyDeterministicScenarioParamRepairs, assessBackendScenarioParamConsistency, classifyBackendTestFailureWithScenarioParam, readBackendScenarioParamFacts, renderBackendTestFailureAnalysis, writeBackendScenarioParamArtifacts, writeScenarioParamRepairAudit, } from "../workflows/dag/backend-test-scenario-param.js";
-import { assessBackendPytestCollection, assessMissingBackendPytestScripts, assessPriorityOnlyBackendPytestModules, assertBackendTestExecutionReadinessFresh, buildBackendPytestAssetInventory, buildBackendTestItemEligibility, materializeBackendTestExecutionReadiness, materializeEffectiveBackendPytestCollection, readBackendPytestCollectionFacts, readBackendTestExecutionReadiness, writeBackendPytestCollectionArtifacts, } from "../workflows/dag/backend-test-pytest-collection.js";
+import { assessBackendPytestCollection, assessMissingBackendPytestScripts, assessPriorityOnlyBackendPytestModules, assertBackendTestExecutionReadinessFresh, buildBackendPytestAssetInventory, buildBackendTestItemEligibility, materializeBackendTestExecutionReadiness, materializeEffectiveBackendPytestCollection, readBackendPytestCollectionFacts, readBackendTestExecutionReadiness, summarizeBackendTestExclusions, writeBackendPytestCollectionArtifacts, } from "../workflows/dag/backend-test-pytest-collection.js";
 import { computeL5ReportMetrics } from "../workflows/dag/l5-report-metrics.js";
 import { buildBackendTestCanonicalResultFromInitialShellSnippet, materializeBackendTestClassification, } from "../workflows/dag/backend-test-classification-contract.js";
 import { backendTestSemanticReviewSchema, materializeBackendTestSemanticReview, } from "../workflows/dag/backend-test-semantic-review-contract.js";
@@ -870,26 +870,49 @@ async function executeBackendTestPipeline(input, meta) {
                 const correspondenceFactsPath = path.join(contractsDir, "backend-test-markdown-pytest-correspondence-initial.json");
                 await writeFile(correspondenceFactsPath, JSON.stringify(correspondence.facts, null, 2), "utf8");
                 outputs.push(`initialCorrespondence=${correspondenceReportPath}`, `initialCorrespondenceFacts=${correspondenceFactsPath}`);
-                if (correspondence.facts.status === "FAIL" && facts.status === "PASS") {
-                    const correspondenceRepairPaths = Array.from(new Set(correspondence.facts.entries
-                        .filter((entry) => entry.status !== "EXACT_1_TO_1")
-                        .flatMap((entry) => [entry.expectedScript, ...entry.actualScripts])
-                        .filter((candidate) => candidate.startsWith("testcase/") && candidate.endsWith(".py")))).sort();
-                    if (correspondenceRepairPaths.length > 0) {
-                        facts.status = "REPAIRABLE";
-                        facts.repairEligible = true;
-                        facts.repairPaths = Array.from(new Set([...facts.repairPaths, ...correspondenceRepairPaths])).sort();
+                if (correspondence.facts.status === "FAIL") {
+                    const repair = classifyBackendTestCorrespondenceRepair(correspondence.facts, backendLayout);
+                    if (repair.markdownBlockingEntries.length > 0) {
+                        facts.status = "BLOCKED";
+                        facts.repairEligible = false;
+                        facts.repairPaths = [];
                         facts.findings.push({
-                            kind: "markdown-pytest-correspondence",
+                            kind: "markdown-correspondence-contract",
                             classification: "test-asset-defect",
-                            repairability: "repairable",
-                            detail: correspondence.facts.entries
-                                .filter((entry) => entry.status !== "EXACT_1_TO_1")
-                                .flatMap((entry) => entry.findings)
+                            repairability: "blocked",
+                            detail: repair.markdownBlockingEntries
+                                .map((entry) => `${entry.caseId ?? "unknown Case"}: ${entry.reasonCodes.join(", ")}`)
                                 .join("; ")
-                                .slice(0, 12_000) || "Markdown-to-pytest correspondence is incomplete",
+                                .slice(0, 12_000),
                         });
                     }
+                    else if (repair.pytestRepairPaths.length > 0 &&
+                        (facts.status === "PASS" || facts.status === "REPAIRABLE")) {
+                        facts.status = "REPAIRABLE";
+                        facts.repairEligible = true;
+                        facts.repairPaths = Array.from(new Set([...facts.repairPaths, ...repair.pytestRepairPaths])).sort();
+                        const repairEntries = correspondence.facts.entries.filter((entry) => repair.pytestRepairEntries.some((candidate) => candidate.caseId === entry.caseId));
+                        for (const entry of repairEntries.slice(0, 40)) {
+                            const classified = repair.pytestRepairEntries.find((candidate) => candidate.caseId === entry.caseId);
+                            facts.findings.push({
+                                kind: "markdown-pytest-correspondence",
+                                classification: "test-asset-defect",
+                                repairability: "repairable",
+                                detail: entry.findings.join("; ").slice(0, 2_000) || "Markdown-to-pytest correspondence is incomplete",
+                                ...(entry.caseId ? { caseId: entry.caseId } : {}),
+                                reasonCodes: classified?.reasonCodes ?? [],
+                                repairPaths: classified?.paths ?? [],
+                                payloadExpectedPaths: Array.from(new Set([
+                                    ...entry.payloadAssessment.requiredPaths,
+                                    ...entry.payloadAssessment.allowedPaths,
+                                ])).sort(),
+                                payloadObservedPaths: entry.payloadAssessment.observedPaths,
+                                payloadMissingPaths: entry.payloadAssessment.missingPaths,
+                                payloadUnexpectedPaths: entry.payloadAssessment.unexpectedPaths,
+                                payloadEnumMismatches: entry.payloadAssessment.enumMismatches,
+                            });
+                        }
+                    }
                 }
             }
             catch (error) {
@@ -912,6 +935,19 @@ async function executeBackendTestPipeline(input, meta) {
                     collectedItemCount: facts.collectedItemCount,
                     missingMappedScripts: facts.missingMappedScripts,
                     repairPaths: facts.repairPaths,
+                    repairFindings: facts.findings.map((finding) => ({
+                        kind: finding.kind,
+                        repairability: finding.repairability,
+                        detail: finding.detail,
+                        ...(finding.caseId ? { caseId: finding.caseId } : {}),
+                        ...(finding.reasonCodes ? { reasonCodes: finding.reasonCodes } : {}),
+                        ...(finding.repairPaths ? { repairPaths: finding.repairPaths } : {}),
+                        ...(finding.payloadExpectedPaths ? { payloadExpectedPaths: finding.payloadExpectedPaths } : {}),
+                        ...(finding.payloadObservedPaths ? { payloadObservedPaths: finding.payloadObservedPaths } : {}),
+                        ...(finding.payloadMissingPaths ? { payloadMissingPaths: finding.payloadMissingPaths } : {}),
+                        ...(finding.payloadUnexpectedPaths ? { payloadUnexpectedPaths: finding.payloadUnexpectedPaths } : {}),
+                        ...(finding.payloadEnumMismatches ? { payloadEnumMismatches: finding.payloadEnumMismatches } : {}),
+                    })),
                     factsPath: "contracts/backend-test-pytest-collection-initial.json",
                 }),
                 stderr: "",
@@ -1011,6 +1047,7 @@ async function executeBackendTestPipeline(input, meta) {
                 })
                 : { eligibleItemIds: effective.collectedItemIds, excludedItems: [] };
             const eligibilityInputHashes = Object.fromEntries((correspondence?.facts.inputFiles ?? []).map((item) => [item.path, item.sha256]));
+            const exclusionSummary = summarizeBackendTestExclusions(eligibility.excludedItems);
             const eligibilityFactsPath = path.join(meta.runDir, "contracts", "backend-test-execution-eligibility.json");
             await mkdir(path.dirname(eligibilityFactsPath), { recursive: true });
             await writeFile(eligibilityFactsPath, `${JSON.stringify({
@@ -1021,6 +1058,9 @@ async function executeBackendTestPipeline(input, meta) {
                 excludedItemCount: eligibility.excludedItems.length,
                 eligibleItemIds: eligibility.eligibleItemIds,
                 excludedItems: eligibility.excludedItems,
+                exclusionSummary,
+                pytestSpawned: false,
+                businessTestBodyExecutedCount: 0,
                 inputHashes: eligibilityInputHashes,
             }, null, 2)}\n`, "utf8");
             const eligibilityReportPath = await writeRunReport(meta.runDir, "backend-test-execution-eligibility.md", [
@@ -1033,6 +1073,10 @@ async function executeBackendTestPipeline(input, meta) {
                 `- Collected items: ${effective.collectedItemIds.length}`,
                 `- Eligible items: ${eligibility.eligibleItemIds.length}`,
                 `- Excluded items: ${eligibility.excludedItems.length}`,
+                `- Excluded Cases: ${exclusionSummary.excludedCaseCount}`,
+                `- Exclusion categories: ${Object.entries(exclusionSummary.excludedByReason).map(([category, count]) => `${category}=${count}`).join("; ") || "none"}`,
+                "- pytest spawned: false",
+                "- Business test bodies executed: 0",
                 "",
                 "## Excluded Items",
                 "",
@@ -1061,6 +1105,9 @@ async function executeBackendTestPipeline(input, meta) {
                     executionReadinessStatus: readiness.status,
                     eligibleItemCount: readiness.eligibleItemIds.length,
                     excludedItemCount: readiness.excludedItems.length,
+                    exclusionSummary: readiness.exclusionSummary,
+                    pytestSpawned: readiness.pytestSpawned,
+                    businessTestBodyExecutedCount: readiness.businessTestBodyExecutedCount,
                     factsPath: "contracts/backend-test-pytest-collection-effective.json",
                     readinessPath: "contracts/backend-test-execution-readiness.json",
                     reportPath: artifacts.reportPath,
@@ -1183,7 +1230,33 @@ async function executeBackendTestPipeline(input, meta) {
             const pytestTargetsRelative = "reports/backend-test-pytest-targets.txt";
             const pytestTargetsAbsolute = path.join(meta.runDir, pytestTargetsRelative);
             await writeFile(pytestTargetsAbsolute, `${eligibleItemIds.join("\n")}\n`, "utf8");
-            const pytestTargetsArg = `@\"\${HARNESS_DAG_RUN_DIR}/${pytestTargetsRelative}\"`;
+            const pytestLauncherRelative = "reports/backend-test-pytest-launcher.py";
+            const pytestLauncherAbsolute = path.join(meta.runDir, pytestLauncherRelative);
+            await writeFile(pytestLauncherAbsolute, [
+                "import os",
+                "import pathlib",
+                "import sys",
+                "",
+                "sys.path[0] = os.getcwd()",
+                "import pytest",
+                "",
+                "if len(sys.argv) != 3:",
+                "    print('usage: backend-test-pytest-launcher.py <targets-file> <html-file>', file=sys.stderr)",
+                "    raise SystemExit(4)",
+                "targets_path = pathlib.Path(sys.argv[1])",
+                "html_path = pathlib.Path(sys.argv[2])",
+                "try:",
+                "    targets = targets_path.read_text(encoding='utf-8').splitlines()",
+                "except (OSError, UnicodeError) as error:",
+                "    print(f'backend-test targets unreadable: {error}', file=sys.stderr)",
+                "    raise SystemExit(4)",
+                "if not targets or any(not target or target != target.strip() for target in targets):",
+                "    print('backend-test targets must contain non-empty exact pytest node IDs', file=sys.stderr)",
+                "    raise SystemExit(4)",
+                "pytest_args = [*targets, '-v', '-p', 'no:cacheprovider', f'--html={html_path}', '--self-contained-html']",
+                "raise SystemExit(pytest.main(pytest_args))",
+                "",
+            ].join("\n"), "utf8");
             // Split into short bash -c commands (aligned with markdown-environment).
             // A single ultra-long compound command has been observed on Windows to
             // exit 0xC0000142 (STATUS_DLL_INIT_FAILED) in ~40ms with empty stdout/
@@ -1260,10 +1333,11 @@ async function executeBackendTestPipeline(input, meta) {
                 'PYTHON_BIN="$(command -v python || command -v python3 || true)"',
                 'if [ -z "${PYTHON_BIN}" ]; then echo "python/python3 is required for backend-test execution" | tee -a "${DIAG_FILE}" >&2; exit 127; fi',
                 'echo "STEP=pytest-run"',
-                `echo "- pytestCommand: python -m pytest <${eligibleItemIds.length} eligibility-authorized-items> -v -p no:cacheprovider --html=reports/backend-test.html --self-contained-html" >> "\${DIAG_FILE}"`,
+                `echo "- pytestCommand: controller launcher -> pytest.main(<${eligibleItemIds.length} eligibility-authorized-items>, -v, -p no:cacheprovider, --html=reports/backend-test.html, --self-contained-html)" >> "\${DIAG_FILE}"`,
                 `echo "- eligibleItemCount: ${eligibleItemIds.length}" >> "\${DIAG_FILE}"`,
                 `echo "- excludedItemCount: ${executionReadiness.excludedItems.length}" >> "\${DIAG_FILE}"`,
-                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 "\${PYTHON_BIN}" -m pytest ${pytestTargetsArg} -v -p no:cacheprovider --html="\${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" --self-contained-html`,
+                'rm -f "${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" "${HARNESS_DAG_RUN_DIR}/reports/backend-test-pytest-native.html"',
+                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 "\${PYTHON_BIN}" "\${HARNESS_DAG_RUN_DIR}/${pytestLauncherRelative}" "\${HARNESS_DAG_RUN_DIR}/${pytestTargetsRelative}" "\${HARNESS_DAG_RUN_DIR}/reports/backend-test.html"`,
                 "STATUS=$?",
                 'printf "%s" "${STATUS}" > "${HARNESS_DAG_RUN_DIR}/reports/backend-test-pytest-exit.txt"',
                 'echo "- pytestExitCode: ${STATUS}" >> "${DIAG_FILE}"',

package/dist/governance/checks.js

@@ -8,6 +8,7 @@ import { buildTaskReadModel } from '../task/read-model.js';
 const SKIP_DIRS = new Set([
     '.git',
     '.harness',
+    '.scratch',
     'node_modules',
     'dist',
     'coverage',

package/dist/shared/operator/capabilities.js

@@ -51,6 +51,8 @@ const OFFICIAL_ACTION_DESCRIPTIONS = {
     workerSchedulerStatus: "Night-scheduler status overview (agent-worker). Use to check whether overnight jobs are healthy.",
     workerSchedulerLedger: "Night-scheduler harvest ledger (agent-worker). Use to audit what overnight runs produced.",
     workerSchedulerDoctor: "Diagnose night-scheduler health (agent-worker). Use when overnight jobs fail to fire or harvest.",
+    dagResume: "Unpause a run paused at a human decision checkpoint. Orphaned runs (dead runner, liveness=orphaned) are NOT continuable — do not resume them: use dagReconcileRun --action supersede to archive and then advance/rerun the task fresh.",
+    dagReconcileRun: "Reconcile an orphaned run (dead runner, liveness=orphaned). These are NOT continuable: supersede archives the run for a fresh same-task advance/rerun; abandon discards it. resume only unpauses human-decision checkpoints — never for orphaned runs.",
 };
 const officialAction = (action, cli, kind, coverage) => ({
     action,
@@ -817,7 +819,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "BINDING_DRIFT",
                 "HUMAN_CONFIRMATION_REQUIRED",
             ],
-            description: "Issue a session-bound single-use execution receipt after server-side G2 assessment (bounded writeSet ⊆ allowedPaths, no forbidden overlap, no broad/destructive risk, structured verification). The model never passes a raw DAG path.",
+            description: "Returns SYNCHRONOUSLY (not an operation): it immediately yields a session-bound single-use executionId + receipt, which you then pass to runDag to actually execute. It is a server-side G2 assessment (bounded writeSet ⊆ allowedPaths, no forbidden overlap, no broad/destructive risk, structured verification). The model never passes a raw DAG path.",
             inputParams: [
                 {
                     name: "taskId",
@@ -1067,6 +1069,12 @@ export function buildOperatorCapabilitiesDocument() {
                     required: false,
                     description: "verification entries as label:command strings",
                 },
+                {
+                    name: "approveGate",
+                    type: "string",
+                    required: false,
+                    description: "optional write-set gate approval token `<gate-id>:sha256:<64-hex>` exactly as reported by task status gate.approveCommand; forwards as --approve-gate and executes the approved DAG as this background operation (preferred over a foreground terminal)",
+                },
             ],
             modelCallable: "always",
             humanConfirmation: "none",

package/dist/shared/pi-context-pressure/checkpoint.js

@@ -0,0 +1,116 @@
+const CHECKPOINT_MAX_BYTES = 12 * 1024;
+function boundText(value, maxChars) {
+    if (typeof value !== "string" || !value.trim())
+        return "";
+    return value.length <= maxChars ? value : `${value.slice(0, maxChars - 1)}…`;
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function extractLastUserGoal(messages) {
+    if (!Array.isArray(messages))
+        return "";
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = asRecord(messages[index]);
+        if (!message || message.role !== "user")
+            continue;
+        const content = message.content;
+        if (typeof content === "string")
+            return boundText(content, 800);
+        if (Array.isArray(content)) {
+            const texts = content
+                .map((block) => {
+                const rec = asRecord(block);
+                return typeof rec?.text === "string" ? rec.text : "";
+            })
+                .filter(Boolean);
+            if (texts.length > 0)
+                return boundText(texts.join("\n"), 800);
+        }
+    }
+    return "";
+}
+function extractTodos(details) {
+    const record = asRecord(details);
+    const todos = record?.todos ?? record?.items;
+    if (!Array.isArray(todos))
+        return "";
+    const lines = todos
+        .slice(0, 24)
+        .map((item) => {
+        const rec = asRecord(item);
+        const status = typeof rec?.status === "string" ? rec.status : "pending";
+        const content = typeof rec?.content === "string"
+            ? rec.content
+            : typeof rec?.title === "string"
+                ? rec.title
+                : "";
+        return content ? `- [${status}] ${content}` : "";
+    })
+        .filter(Boolean);
+    return boundText(lines.join("\n"), 1200);
+}
+function extractFileOps(fileOps) {
+    const record = asRecord(fileOps);
+    if (!record)
+        return "";
+    const parts = [];
+    for (const key of ["edited", "written", "read", "deleted", "ops"]) {
+        const value = record[key];
+        if (Array.isArray(value)) {
+            parts.push(`${key}: ${value
+                .slice(0, 20)
+                .map((item) => (typeof item === "string" ? item : JSON.stringify(item)))
+                .join(", ")}`);
+        }
+        else if (typeof value === "string" && value) {
+            parts.push(`${key}: ${value}`);
+        }
+    }
+    if (parts.length === 0) {
+        try {
+            return boundText(JSON.stringify(fileOps), 800);
+        }
+        catch {
+            return "";
+        }
+    }
+    return boundText(parts.join("\n"), 800);
+}
+export function buildOverflowCheckpoint(input) {
+    const preparation = input.preparation;
+    const firstKeptEntryId = typeof preparation?.firstKeptEntryId === "string" &&
+        preparation.firstKeptEntryId
+        ? preparation.firstKeptEntryId
+        : undefined;
+    const tokensBefore = typeof preparation?.tokensBefore === "number" &&
+        Number.isFinite(preparation.tokensBefore)
+        ? preparation.tokensBefore
+        : undefined;
+    if (!firstKeptEntryId || tokensBefore === undefined)
+        return undefined;
+    const sections = [
+        "Deterministic overflow checkpoint (no extra summary request).",
+        boundText(preparation?.previousSummary, 2000)
+            ? `Previous summary:\n${boundText(preparation?.previousSummary, 2000)}`
+            : "",
+        extractLastUserGoal(preparation?.messagesToSummarize)
+            ? `Latest user goal:\n${extractLastUserGoal(preparation?.messagesToSummarize)}`
+            : "",
+        extractTodos(input.todos) ? `Open todos:\n${extractTodos(input.todos)}` : "",
+        extractFileOps(preparation?.fileOps)
+            ? `File ops:\n${extractFileOps(preparation?.fileOps)}`
+            : "",
+        typeof input.lastError === "string" && input.lastError
+            ? `Latest error:\n${boundText(input.lastError, 400)}`
+            : "",
+        "Next step: continue the interrupted turn from the kept recent messages. Do not repeat completed file writes.",
+    ].filter(Boolean);
+    let summary = sections.join("\n\n");
+    if (Buffer.byteLength(summary, "utf8") > CHECKPOINT_MAX_BYTES) {
+        summary = `${summary.slice(0, CHECKPOINT_MAX_BYTES - 1)}…`;
+    }
+    return { summary, firstKeptEntryId, tokensBefore };
+}