@tea-agent/loop-agent 0.35.0 → 0.35.1-beta.1

package/AGENTS.md

@@ -94,6 +94,8 @@ npm run build
 node bin/loop-agent.js --help
 ```
 
+- 改 `src/**` 后必须先 `npm run build` 再用 `bin/loop-agent.js`：bin 内置 stale-dist 守卫（src 比 dist 新即硬失败，`--ignore-stale-dist` 逃生），`--version` 会显示构建 git SHA，发布/自测前用它确认跑的是目标改动。
+
 文档站变更：`npm run docs:build`。init / architecture / skill entry / pack 定向验证见 verification-matrix。
 
 ## 交接

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [0.35.1-beta.1] - 2026-08-14
+
+### 改进
+
+- DAG runner 捕获 SIGTERM/SIGINT：外层硬超时或监督层杀进程时，先把 run 写成 `failed` 终态（含 `terminalReason` 与 `finishedAt`）再退出，不再留 orphaned RUNNING；agent-worker 硬超时改为 SIGTERM→宽限 10s→SIGKILL 两级，给终态落盘留窗口
+- prewrite gate 失败结果新增机器可读 `failureCode`（如 `mock-strategy-outside-allowed`、`verdict-not-pass`、`contract-invalid` 等），失败场景强制非空，下游路由不再解析散文
+- plan 节点的契约自校验改为 `schemaId → validator` 注册表（`contract-output-registry`），新增契约无需改 executor；契约 schema 层新增深度 null 归一（`z.preprocess` 递归删 null），模型对可选字段吐 null 不再炸 strict schema，必填字段 null 仍以清晰 Required 报错
+- VERDICT 归一更宽容：`VERDICT:pass`（缺空格）、尾部句号/感叹号等漂移在节点级即归一，减少无谓的 protocol-invalid 重试
+- 构建写入 `dist/build-stamp.json`（git SHA + 时间），`loop-agent --version` 显示构建来源；`bin/loop-agent.js` 在源码树内运行且 dist 落后于 src 时硬失败（`--ignore-stale-dist` 逃生），杜绝「改了没生效」的陈旧产物事故
+
+- `frontend-implementation` DAG 删除冗余的 `frontend-contract-json-pi` 与 `frontend-contract-json-validate-shell` 两个节点，`frontend-prewrite-gate-shell` 直接消费 plan/revision 的 candidate JSON，成为 candidate → canonical 的唯一转换点（standard 17→15、small 15→13、green path 13→11 节点 / 8→7 Pi）
+- prewrite gate 新增 `frontend-prewrite-result-v1` 分类 artifact（accepted / accepted-normalized / retryable-invalid / blocked），blocked/retryable-invalid 先落 artifact 再以结构化结果返回
+- 新增两层 writer 前置门禁：scheduler admission + executeDagNode 运行前 guard，仅在 classification 为 accepted/accepted-normalized 时放行 writer，否则 SKIPPED + `frontend-prewrite-not-authorized`，writer provider 调用次数为 0
+- 终态聚合对 candidate-contract-invalid / prewrite-blocked 强制 `failed`，防止「prewrite FINISHED + writer SKIPPED」误判 partial_failed
+- 删除 contract-json 节点后，frozen command label 提醒与 requirement coverage 指令迁移进 `frontend-plan-pi` / `frontend-plan-revision-pi` 提示，模型侧引导不丢失
+- `frontend-repair.ts` 的失败分类从 nodeId/stdout/stderr 字符串启发式改为结构化证据（verificationTargetId / commandLabel → commandCategory / exitCode / traceRef / changedPaths），字符串匹配降级为兜底
+- `review` 失败不再默认可自动修复：只有 finding 同时具备明确文件、行或符号、requirement/AC 且修复范围 ⊆ writeSet、不需重新规划 contract 时才进入自动 repair，否则转人工
+- `frontendRepairAssessment` 扩展结构化证据字段（verificationTargetId / commandLabel / exitCode / commandCategory / requirementIds / acceptanceCriteriaIds / fixScope / changedPaths / traceRef），缺必要证据时不再判定 repairable
+- `frontend-implement-pi` 与 `frontend-repair-pi` 共享同一 prompt builder / contract loader / writeSet guard，仅 phase 与 baseline 不同
+
 ## [0.35.0] - 2026-08-13
 
 ### 重点更新

package/bin/loop-agent.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -13,6 +13,42 @@ if (!existsSync(cliEntry)) {
   process.exit(1);
 }
 
+/**
+ * Stale-dist guard: when running from a source checkout (src/ present), refuse
+ * to silently execute a dist/ that predates the latest source edit. The
+ * classic failure mode is editing src/** and running the bin without
+ * `npm run build`, which executes the previous build. Suppress with
+ * --ignore-stale-dist when intentionally running a stale build.
+ */
+const srcDir = join(packageRoot, "src");
+const ignoreStale = process.argv.includes("--ignore-stale-dist");
+if (ignoreStale) {
+  process.argv = process.argv.filter((arg) => arg !== "--ignore-stale-dist");
+}
+if (!ignoreStale && existsSync(srcDir)) {
+  const distCliMtime = statSync(cliEntry).mtimeMs;
+  let newestSrcMtime = 0;
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else {
+        const mtime = statSync(full).mtimeMs;
+        if (mtime > newestSrcMtime) newestSrcMtime = mtime;
+      }
+    }
+  };
+  walk(srcDir);
+  if (newestSrcMtime > distCliMtime) {
+    console.error(
+      `loop-agent: dist/ is stale relative to src/ (a source file is newer than ${cliEntry}).\n` +
+        `  Run \`npm run build\` before using the bin, or pass --ignore-stale-dist to run the stale build intentionally.`,
+    );
+    process.exit(1);
+  }
+}
+
 try {
   await import(pathToFileURL(cliEntry).href);
 } catch (error) {

package/dist/build-stamp.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "version": "0.35.1-beta.1",
+  "gitSha": "31d25ffb558dfd21b655692e01202034770a6a0d",
+  "builtAt": "2026-08-14T08:04:09.819Z"
+}

package/dist/cli/program.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { readPackageVersion } from "../shared/package-metadata.js";
+import { readCliVersionLabel } from "../shared/package-metadata.js";
 import { resolveAdapter } from "../adapters/index.js";
 import { runCoverageAudit } from "../commands/coverage-audit.js";
 import { runCoverageReport } from "../commands/coverage-report.js";
@@ -547,7 +547,7 @@ export function buildLoopAgentProgram(options) {
     program
         .name("loop-agent")
         .description("Loop Agent task and DAG automation CLI")
-        .version(readPackageVersion(path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))))) ?? "0.0.0", "-V, --version", "display version")
+        .version(readCliVersionLabel(path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))))) ?? "0.0.0", "-V, --version", "display version")
         .showHelpAfterError()
         .option("--repo-root <path>", "repository root")
         .option("--adapter <name>", "harness adapter name")

package/dist/shared/package-metadata.js

@@ -45,6 +45,38 @@ export function readPackageName(packageDir) {
     }
     return undefined;
 }
+/**
+ * Read the build stamp (git SHA + build time) written by the build pipeline
+ * into `<packageDir>/dist/build-stamp.json`. `undefined` when absent (e.g.
+ * running from source via tsx, or a hand-assembled package), which callers
+ * treat as "no stamp available".
+ */
+export function readBuildStamp(packageDir) {
+    try {
+        const raw = readFileSync(path.join(packageDir, "dist", "build-stamp.json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed.schemaVersion !== 1 ||
+            typeof parsed.version !== "string" ||
+            typeof parsed.builtAt !== "string")
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Human-readable CLI version label: plain version, enriched with the build
+ * stamp (short git SHA + build date) when available so a stale dist/ that was
+ * built from an old commit is immediately recognizable in `--version`.
+ */
+export function readCliVersionLabel(packageDir) {
+    const version = readPackageVersion(packageDir) ?? "0.0.0";
+    const stamp = readBuildStamp(packageDir);
+    if (!stamp?.gitSha)
+        return version;
+    return `${version} (build ${stamp.gitSha.slice(0, 8)} ${stamp.builtAt.slice(0, 10)})`;
+}
 /**
  * Compute the SHA-256 hash of a file on disk.
  *

package/dist/worker/loop-agent/loop-agent-client.js

@@ -7,6 +7,10 @@ import { parseCommandJson } from "./parse-json.js";
 export const DEFAULT_WORKER_COMMAND_TIMEOUT_MS = 120_000;
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 15_000;
 export const LOOP_AGENT_PACKAGE_NAME = "@tea-agent/loop-agent";
+/** Grace window between the SIGTERM and SIGKILL stages of a hard timeout, so a
+ * runner can persist terminal state (see executeDagCheckpoint) before being
+ * force-killed. */
+export const HARD_TIMEOUT_KILL_GRACE_MS = 10_000;
 const MAX_BUFFERED_OUTPUT_BYTES = 64 * 1024;
 /**
  * Bind evidence supplied by an orchestration layer to the identity exposed by
@@ -381,10 +385,17 @@ function spawnCommand(input) {
             });
         };
         let hardTimeout;
+        let killGraceTimeout;
         if (input.hardTimeoutMs !== undefined && input.hardTimeoutMs > 0) {
             hardTimeout = setTimeout(() => {
                 timedOut = true;
+                // Two-stage termination: SIGTERM first so the runner can persist a
+                // terminal state (see executeDagCheckpoint signal handler), then
+                // SIGKILL only after the grace window expires.
                 child.kill("SIGTERM");
+                killGraceTimeout = setTimeout(() => {
+                    child.kill("SIGKILL");
+                }, HARD_TIMEOUT_KILL_GRACE_MS);
             }, input.hardTimeoutMs);
         }
         let heartbeatTimer;
@@ -394,6 +405,8 @@ function spawnCommand(input) {
         const clearTimers = () => {
             if (hardTimeout !== undefined)
                 clearTimeout(hardTimeout);
+            if (killGraceTimeout !== undefined)
+                clearTimeout(killGraceTimeout);
             if (heartbeatTimer !== undefined) {
                 clearInterval(heartbeatTimer);
                 heartbeatTimer = undefined;

package/dist/workflows/dag/contract-output-registry.js

@@ -0,0 +1,14 @@
+import { structuredContractOutputSchemaIds, } from "./types.js";
+const validators = new Map();
+export function registerStructuredContractValidator(schemaId, validator) {
+    if (validators.has(schemaId)) {
+        throw new Error(`structured contract validator already registered for ${schemaId}`);
+    }
+    validators.set(schemaId, validator);
+}
+export function getStructuredContractValidator(schemaId) {
+    if (structuredContractOutputSchemaIds.includes(schemaId)) {
+        return validators.get(schemaId);
+    }
+    return undefined;
+}

package/dist/workflows/dag/contract-validator-registrations.js

@@ -0,0 +1,8 @@
+/**
+ * Side-effect module: registers every structured contract validator against
+ * its schemaId in the contract output registry. Imported once by the node
+ * executor; keeps per-contract imports out of the executor.
+ */
+import { validateFrontendContractNodeOutput } from "./frontend-implementation-contract.js";
+import { registerStructuredContractValidator } from "./contract-output-registry.js";
+registerStructuredContractValidator("frontend-implementation-contract-v1", validateFrontendContractNodeOutput);

package/dist/workflows/dag/dynamic-runtime/shared.js

@@ -31,7 +31,15 @@ export function getNodeOutputAsJson(state, nodeId) {
 export function normalizeVerdictCandidateLine(value) {
     const trimmed = String(value).trim();
     const emphasized = trimmed.match(/^\*{1,3}\s*(VERDICT:[^*]+?)\s*\*{1,3}$/);
-    return (emphasized ? emphasized[1] : trimmed).trim();
+    const line = (emphasized ? emphasized[1] : trimmed).trim();
+    // Canonicalize the colon separator and trailing sentence punctuation so
+    // "VERDICT:pass", "VERDICT:  pass", or "VERDICT: pass." match the declared
+    // enum lines without accepting free-text verdicts. Conflicting verdicts
+    // still canonicalize to distinct enum lines and remain fail-closed.
+    const verdictMatch = line.match(/^VERDICT:\s*(pass|request-revision)\s*[.!?。！？]*$/i);
+    if (verdictMatch)
+        return `VERDICT: ${verdictMatch[1].toLowerCase()}`;
+    return line;
 }
 /** First line matching /^VERDICT:/ from node assistantText/stdout (markdown emphasis OK). */
 export function extractFirstVerdictLineFromNodeText(text) {