@tea-agent/loop-agent 0.20.1 → 0.22.0

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

@@ -1,6 +1,6 @@
 import { appendFile, mkdir } from 'node:fs/promises';
 import path from 'node:path';
-import { BoundedTextPreview, classifyPiFailure, createPiJsonlStreamCollector, DEFAULT_TIMEOUT_MS, extractAssistantTextFromPiJson, } from './pi-executor.js';
+import { BoundedTextPreview, classifyPiFailure, createPiJsonlStreamCollector, DEFAULT_ABORT_GRACE_MS, DEFAULT_STALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, extractAssistantTextFromPiJson, } from './pi-executor.js';
 import { serializeSessionEvent } from './pi-event-serializer.js';
 let sdkSessionFactoryOverride;
 let sdkImportOverrideForTests;
@@ -169,6 +169,21 @@ export function shouldPersistSessionEvent(event) {
     }
     return true;
 }
+function classifySdkActivityKind(event) {
+    if (!event || typeof event !== 'object')
+        return 'provider';
+    const type = typeof event.type === 'string'
+        ? String(event.type)
+        : '';
+    if (type === 'tool_start' || type === 'tool_end'
+        || type === 'tool_execution_start' || type === 'tool_execution_end') {
+        return 'tool';
+    }
+    if (type === 'thinking_delta' || type === 'message_update') {
+        return null;
+    }
+    return 'provider';
+}
 function createSessionEventAppender(filePath, onSessionEvent) {
     let chain = Promise.resolve();
     let dirEnsured = false;
@@ -181,6 +196,9 @@ function createSessionEventAppender(filePath, onSessionEvent) {
                         dirEnsured = true;
                     }
                     await appendFile(filePath, `${line}\n`, 'utf-8');
+                    // Only after successful persistence: surface the persisted session event.
+                    // Transport activity is reported synchronously by the subscription so
+                    // filtered deltas and slow disk writes cannot trip the stall watchdog.
                     onSessionEvent?.(line, event);
                 }
                 catch {
@@ -271,6 +289,8 @@ export async function executeSingleSdkAttempt(options) {
         ? `${modelConfig.provider}/${modelConfig.model}`
         : modelConfig.model ?? 'default';
     const timeoutMs = options.timeoutMs ?? modelConfig.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const stallTimeoutMs = options.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+    const abortGraceMs = options.abortGraceMs ?? DEFAULT_ABORT_GRACE_MS;
     const piSdkArgs = [
         '--provider', modelConfig.provider ?? '(default)',
         '--model', modelConfig.model ?? '(default)',
@@ -282,15 +302,46 @@ export async function executeSingleSdkAttempt(options) {
     ];
     const startedAt = Date.now();
     let timedOut = false;
+    let terminationConfirmed = true;
     let stderr = '';
     const stdoutPreview = new BoundedTextPreview('stdout');
     const stdoutCollector = createPiJsonlStreamCollector();
     const usageSamples = [];
     let session;
+    let unsubscribe;
     let timeoutHandle;
+    let stallHandle;
+    let disposeAttempted = false;
     const sessionEventAppender = options.sessionEventsPath
         ? createSessionEventAppender(options.sessionEventsPath, options.onSessionEvent)
         : undefined;
+    const appendStderr = (message) => {
+        stderr = stderr ? `${stderr}\n${message}` : message;
+    };
+    const runSessionActionWithGrace = async (label, action) => {
+        let graceHandle;
+        const outcome = await Promise.race([
+            Promise.resolve()
+                .then(action)
+                .then(() => ({ ok: true }))
+                .catch((error) => ({ ok: false, error })),
+            new Promise((resolve) => {
+                graceHandle = setTimeout(() => resolve({ ok: false, timedOut: true }), abortGraceMs);
+            }),
+        ]);
+        if (graceHandle)
+            clearTimeout(graceHandle);
+        if (outcome.ok)
+            return true;
+        if ('timedOut' in outcome) {
+            appendStderr(`pi SDK ${label} was not confirmed within ${abortGraceMs}ms`);
+        }
+        else {
+            const message = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
+            appendStderr(`pi SDK ${label} failed: ${message}`);
+        }
+        return false;
+    };
     try {
         const createSession = await resolveSdkSessionFactory(options.reuseScope);
         session = await createSession({
@@ -301,7 +352,32 @@ export async function executeSingleSdkAttempt(options) {
             model: modelConfig.model,
             thinking: modelConfig.thinking,
         });
-        const unsubscribe = session.subscribe((event) => {
+        let resolveStall;
+        const stallPromise = stallTimeoutMs > 0
+            ? new Promise((resolve) => {
+                resolveStall = resolve;
+            })
+            : null;
+        const armStallWatchdog = () => {
+            if (!stallPromise || !resolveStall)
+                return;
+            if (stallHandle)
+                clearTimeout(stallHandle);
+            stallHandle = setTimeout(() => resolveStall?.('stall'), stallTimeoutMs);
+        };
+        unsubscribe = session.subscribe((event) => {
+            // Every real SDK event proves transport activity, including noisy deltas
+            // intentionally excluded from persisted JSONL and meaningful DAG progress.
+            armStallWatchdog();
+            const activityKind = classifySdkActivityKind(event);
+            if (activityKind) {
+                try {
+                    options.onActivity?.({ kind: activityKind, at: new Date().toISOString() });
+                }
+                catch {
+                    // best-effort: activity must never change Pi result
+                }
+            }
             const usageSample = extractSdkUsageSample(event);
             if (usageSample)
                 usageSamples.push(usageSample);
@@ -317,44 +393,44 @@ export async function executeSingleSdkAttempt(options) {
             ? `${filePrefix}\n${options.userMessage}`
             : options.userMessage;
         const promptPromise = session.prompt(promptMessage);
+        armStallWatchdog();
         const timeoutPromise = timeoutMs > 0
             ? new Promise((resolve) => {
                 timeoutHandle = setTimeout(() => {
-                    timedOut = true;
-                    void session?.abort();
-                    resolve('timeout');
+                    resolve('absolute-timeout');
                 }, timeoutMs);
             })
             : null;
-        if (timeoutPromise) {
-            const raced = await Promise.race([
-                promptPromise.then(() => 'done'),
-                timeoutPromise,
-            ]);
-            if (raced === 'timeout') {
-                stderr = `pi SDK step timed out after ${timeoutMs}ms`;
-            }
+        const raced = await Promise.race([
+            promptPromise.then(() => 'done'),
+            ...(timeoutPromise ? [timeoutPromise] : []),
+            ...(stallPromise ? [stallPromise] : []),
+        ]);
+        if (raced !== 'done') {
+            timedOut = true;
+            appendStderr(raced === 'stall'
+                ? `pi SDK step stalled after ${stallTimeoutMs}ms with no provider activity`
+                : `pi SDK step timed out after ${timeoutMs}ms`);
+            const abortConfirmed = await runSessionActionWithGrace('abort', () => session.abort());
+            disposeAttempted = true;
+            const disposeConfirmed = await runSessionActionWithGrace('dispose', () => session.dispose());
+            terminationConfirmed = abortConfirmed && disposeConfirmed;
         }
-        else {
-            await promptPromise;
-        }
-        unsubscribe();
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        stderr = stderr ? `${stderr}\n${message}` : message;
+        appendStderr(message);
     }
     finally {
         if (timeoutHandle)
             clearTimeout(timeoutHandle);
-        if (session) {
-            try {
-                await session.dispose();
-            }
-            catch (disposeError) {
-                const message = disposeError instanceof Error ? disposeError.message : String(disposeError);
-                stderr = stderr ? `${stderr}\n${message}` : message;
-            }
+        if (stallHandle)
+            clearTimeout(stallHandle);
+        unsubscribe?.();
+        if (session && !disposeAttempted) {
+            disposeAttempted = true;
+            const disposeConfirmed = await runSessionActionWithGrace('dispose', () => session.dispose());
+            terminationConfirmed = terminationConfirmed && disposeConfirmed;
         }
         if (sessionEventAppender) {
             try {
@@ -378,14 +454,14 @@ export async function executeSingleSdkAttempt(options) {
         ? collected.parsedEvents
         : fallbackParsed?.parsedEvents ?? 0;
     const tokensUsed = aggregateSdkTokenUsage(usageSamples);
-    const failureCategory = classifyPiFailure({
+    const failureCategory = terminationConfirmed ? classifyPiFailure({
         assistantText,
         exitCode: timedOut ? 1 : stderr ? 1 : 0,
         outputTooLarge: collected.outputTooLarge,
         stderr,
         stdout,
         timedOut,
-    });
+    }) : 'termination-unconfirmed';
     return {
         assistantText,
         backend: 'sdk',
@@ -394,7 +470,7 @@ export async function executeSingleSdkAttempt(options) {
         exitCode: timedOut || stderr ? 1 : 0,
         failureCategory,
         modelDisplay,
-        ok: !timedOut && !stderr && assistantText.length > 0 && !collected.outputTooLarge,
+        ok: terminationConfirmed && !timedOut && !stderr && assistantText.length > 0 && !collected.outputTooLarge,
         parsedEvents,
         stderr,
         stdout,

package/dist/executors/shell-executor.js

@@ -14,10 +14,11 @@ import { formatFrontendWorktreeDiffStdout, runFrontendWorktreeDiffGate, } from "
 import { formatFrontendFailureAssessStdout, formatFrontendRepairContractStdout, runFrontendFailureAssessGate, runFrontendRepairContractGate, } from "../workflows/dag/frontend-repair.js";
 import { formatFrontendPrewriteGateStdout, runFrontendPrewriteGate, } from "../workflows/dag/frontend-prewrite-gate.js";
 import { formatFrontendReviewContextStdout, runFrontendReviewContextGate, } from "../workflows/dag/frontend-review-context.js";
+import { materializeFrontendLintAssessment, materializeFrontendLintBaseline, } from "../workflows/dag/frontend-lint-baseline.js";
 import { formatTraceabilityGateStdout, materializeBackendTestCaseManifest, runBackendTestTraceabilityGate, } from "../workflows/dag/backend-test-case-manifest.js";
 import { materializeBackendTestExecutionContract } from "../workflows/dag/backend-test-execution-contract.js";
 import { materializeBackendTestResultFromRunDir, parseJunitXml } from "../workflows/dag/backend-test-result-contract.js";
-import { collectBackendTestHumanCaseCatalog, inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
+import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, hasBlockingBackendMarkdownSafetyFindings, inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
 import { buildBackendTestCanonicalResultFromInitialShellSnippet, materializeBackendTestClassification, } from "../workflows/dag/backend-test-classification-contract.js";
 import { backendTestSemanticReviewSchema, materializeBackendTestSemanticReview, } from "../workflows/dag/backend-test-semantic-review-contract.js";
 import { pathsChangedDuringRun, readGitStatusPorcelain, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
@@ -304,6 +305,14 @@ async function runShellWriteGuard(input) {
         forbiddenPaths: input.task.forbiddenPaths,
     });
 }
+async function readRequiredRunReport(reportsDir, filename) {
+    try {
+        return await readFile(path.join(reportsDir, filename), "utf8");
+    }
+    catch {
+        throw new Error(`missing required upstream report: reports/${filename}`);
+    }
+}
 async function executeBackendTestPipeline(input, meta) {
     const pipeline = input.task.shell?.backendTestPipeline;
     const started = Date.now();
@@ -332,22 +341,56 @@ async function executeBackendTestPipeline(input, meta) {
                 meta.spec.objective ?? "",
                 ...(meta.spec.successCriteria ?? []),
             ]);
-            const report = await validateBackendMarkdownCases({
-                workspaceRoot: input.cwd,
-                environmentMarkdown,
-                requiredRequirementIds,
-                sourceBinding: meta.spec.sourceBinding,
-            });
+            let report;
+            try {
+                report = await validateBackendMarkdownCases({
+                    workspaceRoot: input.cwd,
+                    environmentMarkdown,
+                    requiredRequirementIds,
+                    sourceBinding: meta.spec.sourceBinding,
+                });
+            }
+            catch (error) {
+                report = `# Backend Markdown Case Validation\n\n## Status\n\nFAIL\n\n## Findings\n\n- Validator could not complete: ${error instanceof Error ? error.message : String(error)}\n`;
+            }
             const reportPath = await writeRunReport(meta.runDir, "backend-md-case-validation.md", report);
             outputs.push(`caseValidation=${reportPath}`, report);
+            if (hasBlockingBackendMarkdownSafetyFindings(report)) {
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n"),
+                    stderr: "backend Markdown safety gate blocked: secret-shaped values detected",
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
         }
         else if (pipeline === "markdown-traceability") {
-            const report = await validateBackendMarkdownTraceability(input.cwd);
+            let report;
+            try {
+                report = await validateBackendMarkdownTraceability(input.cwd);
+            }
+            catch (error) {
+                report = `# Backend Test Traceability\n\n## Status\n\nFAIL\n\n## Findings\n\n- Traceability validation could not complete: ${error instanceof Error ? error.message : String(error)}\n`;
+            }
             const reportPath = await writeRunReport(meta.runDir, "backend-test-traceability.md", report);
             outputs.push(`traceability=${reportPath}`, report);
         }
         else if (pipeline === "markdown-execute-html") {
-            const results = await executePipelineCommands(input, meta);
+            const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd);
+            const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+            const pytestTargets = mappedScripts.map(shellQuote).join(" ");
+            const pytestCommand = [
+                'mkdir -p "${HARNESS_DAG_RUN_DIR}/reports"',
+                'PYTHON_BIN="$(command -v python || command -v python3 || true)"',
+                'if [ -z "${PYTHON_BIN}" ]; then echo "python/python3 is required for backend-test execution" >&2; exit 127; fi',
+                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 "\${PYTHON_BIN}" -m pytest ${pytestTargets} -v -p no:cacheprovider -o junit_logging=all -o junit_log_passing_tests=true --junitxml="\${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml"`,
+                "STATUS=$?",
+                'printf "%s" "${STATUS}" > "${HARNESS_DAG_RUN_DIR}/reports/backend-test-pytest-exit.txt"',
+                'if { [ "${STATUS}" -eq 0 ] || [ "${STATUS}" -eq 1 ]; } && [ -s "${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml" ]; then exit 0; fi',
+                'exit "${STATUS}"',
+            ].join("; ");
+            const results = await executePipelineCommands(input, meta, [pytestCommand]);
             if (!results.every((result) => result.ok)) {
                 const failure = results.find((result) => !result.ok);
                 return { ok: false, stdout: results.map((result) => result.stdout).join("\n"), stderr: failure.stderr, failureCategory: failure.failureCategory, durationMs: Date.now() - started };
@@ -359,18 +402,22 @@ async function executeBackendTestPipeline(input, meta) {
                 throw new Error(`pytest did not complete with a reportable exit code: ${pytestExitCode}`);
             const parsed = parseJunitXml(junitContent);
             const cases = await collectBackendTestHumanCaseCatalog(input.cwd);
+            const caseValidationSummary = await readRequiredRunReport(reportsDir, "backend-md-case-validation.md");
+            const traceabilitySummary = await readRequiredRunReport(reportsDir, "backend-test-traceability.md");
             const htmlContent = renderBackendTestHtml({
                 title: meta.spec.title,
                 parsed,
                 cases,
                 environmentSummary: await readFile(path.join(reportsDir, "backend-test-environment.md"), "utf8"),
-                traceabilitySummary: await readFile(path.join(reportsDir, "backend-test-traceability.md"), "utf8"),
+                caseValidationSummary,
+                traceabilitySummary,
             });
             const htmlPath = await writeRunReport(meta.runDir, "backend-test.html", htmlContent);
-            const facts = renderBackendTestFacts({ parsed, cases, pytestExitCode, junitRelativePath: "reports/backend-test.junit.xml", htmlRelativePath: "reports/backend-test.html", junitContent, htmlContent });
+            const facts = renderBackendTestFacts({ parsed, cases, pytestExitCode, junitRelativePath: "reports/backend-test.junit.xml", htmlRelativePath: "reports/backend-test.html", junitContent, htmlContent, caseValidationSummary, traceabilitySummary });
+            const markdownPath = await writeRunReport(meta.runDir, "backend-test.md", facts);
             const factsPath = await writeRunReport(meta.runDir, "backend-test-facts.md", facts);
             const sanitizedOutputs = results.map((result) => redactBackendTestOutput(result.stdout));
-            outputs.push(...sanitizedOutputs, `html=${htmlPath}`, `facts=${factsPath}`, facts);
+            outputs.push(...sanitizedOutputs, `html=${htmlPath}`, `markdown=${markdownPath}`, `facts=${factsPath}`, facts);
         }
         else if (pipeline === "contracts") {
             const wrapperPath = path.join(meta.runDir, "analyze-and-discover-backend-test-pi.json");
@@ -618,13 +665,46 @@ async function executeFrontendVerificationBundle(input, meta) {
     catch {
         beforeStatus = undefined;
     }
+    const lintResults = [];
+    for (const command of bundle.lintCommands ?? []) {
+        const commandNumber = results.length + 1;
+        const result = await executeShellCommand({
+            command,
+            cwd,
+            timeoutMs: shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS,
+            envAllowlist: shell.envAllowlist,
+            dagRunMeta: { runDir: meta.runDir, runId: meta.runId },
+            outputArtifacts: {
+                stdoutPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stdout.txt`),
+                stderrPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stderr.txt`),
+            },
+        });
+        lintResults.push(result);
+        results.push(result);
+    }
+    let lintAssessment;
+    if ((bundle.lintCommands?.length ?? 0) > 0 &&
+        bundle.lintBaselineNodeId &&
+        (bundle.writerNodeIds?.length ?? 0) > 0) {
+        lintAssessment = await materializeFrontendLintAssessment({
+            runDir: meta.runDir,
+            workspaceRoot: input.cwd,
+            commands: bundle.lintCommands,
+            results: lintResults,
+            baselineNodeId: bundle.lintBaselineNodeId,
+            writerNodeIds: bundle.writerNodeIds,
+        });
+    }
+    const lintBlocked = lintAssessment?.status === "failed" ||
+        lintAssessment?.status === "unavailable";
     const groups = [
-        { name: "mock", commands: bundle.mockCommands },
-        { name: "static", commands: bundle.staticCommands },
-        { name: "behavior", commands: bundle.behaviorCommands },
+        { name: "mock", commands: bundle.mockCommands, labels: bundle.mockEvidence?.commandLabels ?? [] },
+        { name: "static", commands: bundle.staticCommands, labels: bundle.staticEvidence.commandLabels },
+        { name: "behavior", commands: bundle.behaviorCommands, labels: bundle.behaviorEvidence.commandLabels },
     ];
-    for (const group of groups) {
-        for (const command of group.commands) {
+    const successfulLabels = new Map();
+    for (const group of lintBlocked ? [] : groups) {
+        for (const [index, command] of group.commands.entries()) {
             const commandNumber = results.length + 1;
             const result = await executeShellCommand({
                 command,
@@ -638,6 +718,11 @@ async function executeFrontendVerificationBundle(input, meta) {
                 },
             });
             results.push(result);
+            if (result.ok && group.labels[index]) {
+                const labels = successfulLabels.get(group.name) ?? [];
+                labels.push(group.labels[index]);
+                successfulLabels.set(group.name, labels);
+            }
             if (!result.ok)
                 break;
         }
@@ -670,20 +755,36 @@ async function executeFrontendVerificationBundle(input, meta) {
         failureCategory: result.failureCategory,
         command: result.command,
     }));
-    const firstFailure = results.find((result) => !result.ok);
+    const firstFailure = lintBlocked
+        ? lintResults.find((result) => !result.ok)
+        : results
+            .filter((result) => !lintResults.includes(result))
+            .find((result) => !result.ok);
+    const lintSyntheticFailure = lintBlocked && !firstFailure
+        ? {
+            failureCategory: "invalid-output",
+            stderr: lintAssessment?.blockingReasons.join("; ") ??
+                "frontend lint assessment failed",
+        }
+        : undefined;
     let traceError;
     try {
         await runFrontendVerificationTraceGate({
             runDir: meta.runDir,
             workspaceRoot: input.cwd,
             evidence: {
+                mock: {
+                    nodeId: input.task.id,
+                    commandLabels: successfulLabels.get("mock") ?? [],
+                    commandTexts: bundle.mockCommands.slice(0, successfulLabels.get("mock")?.length ?? 0),
+                },
                 static: {
                     nodeId: input.task.id,
-                    commandLabels: bundle.staticEvidence.commandLabels,
+                    commandLabels: successfulLabels.get("static") ?? [],
                 },
                 behavior: {
                     nodeId: input.task.id,
-                    commandLabels: bundle.behaviorEvidence.commandLabels,
+                    commandLabels: successfulLabels.get("behavior") ?? [],
                 },
             },
         });
@@ -692,19 +793,26 @@ async function executeFrontendVerificationBundle(input, meta) {
         traceError = error instanceof Error ? error : new Error(String(error));
     }
     if (bundle.mode === "repair") {
-        if (firstFailure || traceError) {
+        if (firstFailure || lintSyntheticFailure || traceError) {
             return {
                 ok: false,
                 stdout: summarizeCommandResults(results).stdout,
-                stderr: firstFailure?.stderr || traceError?.message || "frontend reverify failed",
-                failureCategory: firstFailure?.failureCategory ?? "invalid-output",
+                stderr: firstFailure?.stderr ||
+                    lintSyntheticFailure?.stderr ||
+                    traceError?.message ||
+                    "frontend reverify failed",
+                failureCategory: firstFailure?.failureCategory ??
+                    lintSyntheticFailure?.failureCategory ??
+                    "invalid-output",
                 durationMs: Date.now() - started,
                 ...{ commandResults },
             };
         }
         return {
             ok: true,
-            stdout: "Frontend reverify bundle: pass",
+            stdout: lintAssessment?.status === "baseline-debt"
+                ? "Frontend reverify bundle: pass with lint baseline-debt"
+                : "Frontend reverify bundle: pass",
             stderr: "",
             failureCategory: "success",
             durationMs: Date.now() - started,
@@ -712,14 +820,22 @@ async function executeFrontendVerificationBundle(input, meta) {
         };
     }
     const failureFacts = [];
-    if (firstFailure) {
+    if (firstFailure || lintSyntheticFailure) {
+        const failureStdout = firstFailure
+            ? [firstFailure.command, firstFailure.stdout]
+                .filter(Boolean)
+                .join("\n")
+            : "";
         failureFacts.push({
             nodeId: input.task.id,
             record: {
                 status: "FINISHED",
-                failureCategory: firstFailure.failureCategory,
-                stdout: summarizeCommandResults(results).stdout,
-                stderr: firstFailure.stderr,
+                failureCategory: firstFailure?.failureCategory ??
+                    lintSyntheticFailure?.failureCategory,
+                // Keep classification scoped to the failed command. Aggregate
+                // successful output may contain unrelated writeSet-like JSON.
+                stdout: failureStdout,
+                stderr: firstFailure?.stderr ?? lintSyntheticFailure?.stderr,
                 commandResults,
             },
         });
@@ -760,6 +876,68 @@ async function executeFrontendVerificationBundle(input, meta) {
         };
     }
 }
+async function executeFrontendLintBaseline(input, meta) {
+    const started = Date.now();
+    const shell = input.task.shell;
+    const baseline = shell.frontendLintBaseline;
+    const cwd = resolveShellCwd(input.cwd, shell.cwd);
+    let beforeStatus;
+    try {
+        beforeStatus = await readGitStatusPorcelain(input.cwd);
+    }
+    catch {
+        beforeStatus = undefined;
+    }
+    const results = [];
+    for (const command of baseline.lintCommands) {
+        const commandNumber = results.length + 1;
+        results.push(await executeShellCommand({
+            command,
+            cwd,
+            timeoutMs: shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS,
+            envAllowlist: shell.envAllowlist,
+            dagRunMeta: { runDir: meta.runDir, runId: meta.runId },
+            outputArtifacts: {
+                stdoutPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stdout.txt`),
+                stderrPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stderr.txt`),
+            },
+        }));
+    }
+    let afterStatus;
+    try {
+        afterStatus = await readGitStatusPorcelain(input.cwd);
+    }
+    catch {
+        afterStatus = undefined;
+    }
+    try {
+        const materialized = await materializeFrontendLintBaseline({
+            runDir: meta.runDir,
+            workspaceRoot: input.cwd,
+            commands: baseline.lintCommands,
+            results,
+            worktreeChanged: beforeStatus === undefined ||
+                afterStatus === undefined ||
+                beforeStatus !== afterStatus,
+        });
+        return {
+            ok: true,
+            stdout: `Frontend lint baseline: ${materialized.artifact.status}\nArtifact: ${materialized.ref.path}\nDiagnostics: ${materialized.artifact.diagnostics.length}`,
+            stderr: materialized.artifact.reason ?? "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+            failureCategory: "invalid-output",
+            durationMs: Date.now() - started,
+        };
+    }
+}
 export async function executeDagShellNode(input, meta) {
     const shell = input.task.shell;
     if (shell?.frontendPrewriteGate) {
@@ -769,6 +947,7 @@ export async function executeDagShellNode(input, meta) {
                 runDir: meta.runDir,
                 config: shell.frontendPrewriteGate,
                 sourceBinding: meta.spec.sourceBinding,
+                workspaceRoot: input.cwd,
                 repoRoot: input.cwd,
             });
             return { ok: true, stdout: formatFrontendPrewriteGateStdout(result), stderr: "", failureCategory: "success", durationMs: Date.now() - started };
@@ -777,13 +956,20 @@ export async function executeDagShellNode(input, meta) {
             return { ok: false, stdout: "", stderr: error instanceof Error ? error.message : String(error), failureCategory: "invalid-output", durationMs: Date.now() - started };
         }
     }
+    if (shell?.frontendLintBaseline) {
+        return executeFrontendLintBaseline(input, meta);
+    }
     if (shell?.frontendVerificationBundle) {
         return executeFrontendVerificationBundle(input, meta);
     }
     if (shell?.frontendReviewContext) {
         const started = Date.now();
         try {
-            const result = await runFrontendReviewContextGate({ runDir: meta.runDir, workspaceRoot: input.cwd });
+            const result = await runFrontendReviewContextGate({
+                runDir: meta.runDir,
+                workspaceRoot: input.cwd,
+                requireBaseline: shell.frontendReviewContext.requireBaseline,
+            });
             return { ok: true, stdout: formatFrontendReviewContextStdout(result), stderr: "", failureCategory: "success", durationMs: Date.now() - started };
         }
         catch (error) {

package/dist/shared/openspec-spec.js

@@ -0,0 +1,49 @@
+/**
+ * Shared openspec specification path predicates.
+ *
+ * Canonical frontend specification directories (case-sensitive) and extension
+ * allowlist.
+ * All consumers in candidate discovery, DAG schema, prewrite gate, and observe
+ * must use these predicates to ensure a single consistent scope definition.
+ */
+/** Canonical spec directories (case-sensitive, POSIX form). */
+export const OPENSPEC_SPEC_DIRS = [
+    "openspec/schemas",
+    "openspec/project-specs",
+    "ai_workspace",
+];
+/** Allowed spec file extensions (case-insensitive). */
+export const OPENSPEC_SPEC_EXT_RE = /\.(md|mdx|json|yaml|yml)$/i;
+/**
+ * Returns `true` when `filePath` is inside one of the canonical frontend spec
+ * directories.  `filePath` must be a repo-relative POSIX path (backslashes are
+ * normalised internally).  Directory names are case-sensitive.
+ */
+export function isOpenspecSpecPath(filePath) {
+    const normalized = filePath.replaceAll("\\", "/");
+    for (const dir of OPENSPEC_SPEC_DIRS) {
+        if (normalized === dir || normalized.startsWith(dir + "/"))
+            return true;
+    }
+    return false;
+}
+/**
+ * Returns `true` when `filename` (the basename only, not a full path) has an
+ * allowed frontend specification extension.
+ */
+export function isValidOpenspecExtension(filename) {
+    return OPENSPEC_SPEC_EXT_RE.test(filename);
+}
+/** Returns `true` for a supported file inside a canonical openspec spec dir. */
+export function isOpenspecSpecFilePath(filePath) {
+    return (isOpenspecSpecPath(filePath) &&
+        isValidOpenspecExtension(filePath.replaceAll("\\", "/")));
+}
+/**
+ * Returns `true` when free-form search input references a canonical frontend
+ * specification directory with exact lowercase directory names.
+ */
+export function isOpenspecSpecSearchTarget(value) {
+    const normalized = value.replaceAll("\\", "/");
+    return /(?:^|[^A-Za-z0-9_.-])(?:openspec\/(?:schemas|project-specs)|ai_workspace)(?:\/|$)/.test(normalized);
+}