@tea-agent/loop-agent 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -4,8 +4,29 @@
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-07-16
+
+### 新增
+
+- 只读 Pi DAG 节点支持 opt-in 安全重试：仅 planner/scout/reviewer/verifier/closeout 角色且无写入能力的 Pi 节点可声明 `retryPolicy`，在同一 run 内重试模型连接中断（`network`）、provider 限流（`rate-limit`）、临时不可用（`unavailable`）或请求 timeout。生成模板默认总尝试 3 次，手工配置最多 5 次，并使用有上限的指数退避。每次 attempt 保留独立证据，节点耗时、Token 与事件数按尝试聚合；后一次成功不会覆盖前一次失败证据。`quota`、`auth`、`invalid-output`、`write-guard` 与未知失败不重试；supervisor、implementer、writer、dynamic、shell、static、docs-only、decision-gate 节点声明策略会在校验阶段失败。未声明策略的历史 DAG 不新增 attempt artifact，行为保持不变。
+- 新增 `taskKind: "backend-test"` 专用 DAG：从需求分析开始，生成并评审后端功能用例，再生成和执行 pytest 自动化，最后产出测试复盘报告；新 DAG 沿用当前 Pi-only runtime、版本化 runtime contract 与既有执行恢复机制。
+
+### 修复
+
+- `loop-agent init check-update` / `init update --apply-safe` 漏检初始化投影文件：fresh `init --profile full` 通过目录复制把整个 `docs/templates/` 与 `skills/`（镜像到 `.agents/skills/`）投影到目标项目，但期望 init surface 只跟踪其中一个子集。旧版本（如 0.11.0）初始化的项目升级 controller 后，缺失的 backend-test 模板、agent-dag schema/prompt、`loop-agent` 必需 references 等文件无法被报告或补齐，`check-update` 会错误返回 `ok: true`。现在期望 surface 会自动发现包内 `docs/templates/` 与 `skills/` 的所有文件并纳入校验；`check-update` 会报告全部缺失/陈旧 surface；`apply-safe` 会确定性补齐缺失文件，对无法证明 ownership 的旧文件仍保持 fail-safe（给出 model merge / human decision，不覆盖用户内容）。`scripts/check-init-surface.sh` 新增 drift 门，阻止“fresh init 会复制、surface 却不跟踪”的漂移。
+
+## [0.11.0] - 2026-07-15
+
 ### 新增
 
+- 受治理 DAG 的 repair 环节改为显式声明：`shell.repairArtifactGate` 新增 `repairNodeId`，新生成的 supervised DAG 会直接写明由哪个 Pi 修复节点承接 supervisor 的修订请求；旧 DAG 未声明时，只有在能唯一、安全地推导出下游 Pi 修复节点时才继续兼容，缺失、歧义或修复节点不满足受治理写入契约都会在执行前明确报错。
+- 新生成的 DagSpec 升级为 `version: 3`，并携带必需的 `runtimeContract`（`agentRuntime` / `repairWriterProtocol` / 可选最低 controller 版本）。旧 controller 会因不认识 v3 而在解析阶段拒绝，新 controller 则在 `dag validate`、执行和 resume 前检查 capability 与最低版本，避免版本漂移运行到中途才失败；legacy v1/v2 DAG 继续可读。
+- 每个新的 DAG run 必须把实际执行的 controller identity（package version、binary SHA-256、portable fingerprint）冻结为 run-owned 事实并记录内容哈希；identity 无法解析时不创建 run。`dag report` 会展示 identity 与 runtime-contract compatibility，resume 时重新校验；身份漂移、artifact 篡改或 legacy-unpinned run 都会拒绝继续。
+- Observe R5：控制台前端拆为原生 ES modules（router/api/format/state/views 等），`app.js` 作轻量入口并 re-export 可测 API；统一 loading/empty/degraded/error 状态 helper；资源池支持可分享的 hash 筛选（`status`/`q`）；不引入框架或构建器，R1–R4 路由/API/行为保持。
+- Observe R4：Batch/Pool 有界事件历史 `GET /api/batches/:batchRunId/events` 与 `GET /api/events`（默认 limit 50、硬顶 200，opaque `cursor`/`nextCursor`，与 SSE/run 整数 `after` 分离）；服务端尾部有界 JSONL 扫描；snapshot 事件归约容量硬顶并暴露 `projectionWarnings`；Pool 投影失败 fault-first，避免健康零值 KPI。
+- Observe R3：`#/feature/:featureId` 决策详情（状态、AC 覆盖、blocking、risk、follow-ups、evidence、projectionWarnings）；总览 Feature 可下钻；Feature/Task/Batch/Run/DAG 统一对象关系条，仅 snapshot 可证对象出链；建议命令仅可复制，与已执行事实分区。
+- Observe R2：Batch 详情展示完整 summary（含 additive `recordErrors?`/`runErrors?`）、派生总耗时、Task 诊断列（失败分类、follow-up、harnessTaskId、起止）与页内安全 artifact preview；Worker Run 收敛为「主事实 / 执行过程 / 诊断证据」三层，Task/Batch/DAG 深链仅在 canonical 字段且 snapshot 命中时生成。`TaskSummary.batchRunId?` 对外保留。
+- Observe R1：顶栏「资源池」与 `#/pool` 盘点当前 Worker Task（状态分布、最新 run、更新时间、失败分类）；`#/task/:taskId` 下钻当前事实、真实关联 batch/run/DAG、失败证据与有界 run history（`GET /api/tasks/:taskId/runs`，limit/cursor，`retryOfWorkerRunId`）。`TaskSummary` additive `updatedAt?`；snapshot additive `taskPool.present` 区分未使用与空池。
 - 新增版本更新提醒。发现新版本时可以直接确认升级；忽略某个版本后不会重复提醒，后续新版本仍会正常提示。可用 `LOOP_AGENT_DISABLE_UPDATE_CHECK=1` 关闭检查。
 - 新增 `loop-agent plan create`、`plan complete` 和 `plan check`，统一维护执行计划及其索引，并在生成 DAG 前发现遗漏或不一致。
 - 目标项目可以选择复用本地 SDD skills，为需求、设计、实现和评审节点补充方法指引；未安装时保持原有流程。
@@ -19,6 +40,8 @@
 
 ### 变更
 
+- `observe serve` 提高对外访问稳定性：HTTP keep-alive 默认约 65s（避免 Node 5s 默认导致连接池复用失败），SSE 增加 keepalive comment 与 `X-Accel-Buffering: no`；新增 `--debug` 在 stderr 打印请求来源/方法/路径/状态/耗时。
+- `observe serve` 允许显式绑定非 loopback 地址（如 `--host 0.0.0.0`）以便局域网访问；默认仍是 `127.0.0.1`，非本机绑定时会在 stderr 提示无鉴权风险。
 - 根 README 在「核心概念」后增加极简「仓库地图」，方便一眼区分 `src/`、`skills/`、`.harness/`、`docs/` 等职责；细节仍以 `AGENTS.md` 与 `docs/README.md` 为准。
 - 文档治理收敛：站上「当前规划」与 active plan 同步（无进行中计划时明确写出）；`docs/README` 只索引核心契约与产物目录入口，progress/report 全量列表下沉到子目录 README；Dynamic Workflow 路线图迁入 `docs/design/`；补齐 design 漏索引与 DAG recovery playbook 入口。
 - 活文档校准：Dynamic Workflow 路线图页首标明已落地 vs 设计输入（Pi-only）；六个月规划第 1–2 月改为 archive/reports 指针；`repository-analysis` 冻结为基线快照，新增 `docs/reports/current-capability-summary.md`；落地 ADR 0001–0003（Pi-only、Task Pool 根、双树/docs-converge）。
@@ -30,6 +53,8 @@
 
 ### 修复
 
+- 修复 supervised convergence DAG 在 `process-gate-shell` 报「repair artifact gate cannot find downstream repair task」的问题：修复环节不再按固定节点名（历史上的 `repair-cursor` / `repair-pi`）猜测，而是根据 gate 声明的 `repairNodeId` 或唯一安全的下游 Pi 写入节点解析，合法的 `request-revision` 修订请求能正常走完 repair、hard verify 与 review。
+- Observe UI R5：可变 UI 状态改为 `uiState` plain object，修复 Chrome 中 ES module namespace 赋值导致的路由崩溃；`app.js` 收为约 136 行 bootstrap/route/listeners/re-export，KPI、DAG helpers、run processing 与 shell chrome 迁入职责模块，移除 nullable `registerShell/getShell` locator；Pool grouped filters、四态、DAG inspector ARIA/方向键同步收敛，并通过 focused tests、构建治理与 fresh dist Chrome 验证。
 - 前端 DAG 从 `需求.md` / `执行约束.md` 读取验证命令时不再交给 shell 解释执行；命令会先解析为受限参数列表并拒绝 shell 特殊语法，避免任务文本触发额外命令。
 - 改进 Windows 下 Git Bash、npm 和集成测试的运行方式，减少环境识别错误与资源竞争导致的误失败。
 

package/README.md

@@ -78,7 +78,7 @@ loop-agent init update --repo-root <target-repo> --bootstrap-surface
 loop-agent init update --repo-root <target-repo> --apply-safe
 ```
 
-`check-update` 只读报告 deterministic actions、model merge tasks、human decisions 和 recommended next。`update --bootstrap-surface` 为旧项目补 inferred baseline；`update --apply-safe` 只补缺失文件、目录和 managed block（包括过期的 `.gitignore` managed block），不覆盖已有但无法确认来源的本地文件。
+`check-update` 只读报告 deterministic actions、model merge tasks、human decisions 和 recommended next。期望 init surface 会自动发现包内 `docs/templates/` 与 `skills/` 的所有文件，因此 fresh `init --profile full` 投影到目标项目的每个 template/skill 文件都会被纳入校验。`update --bootstrap-surface` 为旧项目补 inferred baseline；`update --apply-safe` 只补缺失文件、目录和 managed block（包括过期的 `.gitignore` managed block），不覆盖已有但无法确认来源的本地文件；对在旧路径被用户修改过的遗留副本，会在对应标准路径上给出 model merge / human decision，不会静默用包内容覆盖。
 
 当初始化由模型/Agent 执行时，它应把初始化当成一个自动化闭环：确认真正不能安全默认的 provider/model、治理根目录或凭据/成本问题后，运行 deterministic init，随后立刻读取目标项目真实文件，补全根 README 的项目概览、技术栈/目录结构、开发与验证命令，并同步适配 `ai_workspace/loop-agent/verification-matrix.md` 和必要的 `scripts/ci-tests.sh`。
 
@@ -95,7 +95,7 @@ loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --st
 loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
 ```
 
-当前 `dag run-task` 也支持按 `task.json.taskKind` 选择专用模板；例如 `frontend-implementation` 会生成前端契约、design gate、静态验证、行为验证和 review gate 节点链。
+当前 `dag run-task` 也支持按 `task.json.taskKind` 选择专用模板；`frontend-implementation` 会生成前端契约、design gate、静态验证、行为验证和 review gate 节点链，`backend-test` 会生成从需求分析、功能用例、pytest 自动化到测试复盘的专用节点链。
 
 `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。
 
@@ -169,6 +169,7 @@ nightly wrapper 按 feature 互斥，保留批次/超时退出码，并输出 mo
 - **可选 SDD skill 嵌入**：如果目标项目在 `.agents/skills/` 中提供 `SDD-requirement-analysis`、`SDD-design-analysis`、`SDD-implementation-test-review`，`dag run-task` 会把它们作为知识与方法补充追加到对应的 Contract、Plan、Implement/Repair、Verify、Review 节点。loop-agent 仍控制 DAG、状态、写入边界、验证和收口；不会自动运行 SDD 初始化/扫描 skill，也不会推进 `ai_workspace` 状态或归档。没有这些 repo-local skills 时，生成结果保持原有默认流程。
 - **run-owned skill snapshot**：新 DAG run 会在任何节点执行前，把本次实际注入 prompt 的 resolved skill profiles 冻结到 run 自己的 `.runtime/skill-snapshot.json`。后续节点、dynamic child、approve/resume 都使用同一份 hash-anchored snapshot；run 内修改 skill 只会从下一次 run 生效。
 - **controller identity**：`agent-worker` 把一次 Feature/batch 实际使用的发布包、入口、启动参数和 package 内容 fingerprint 固定下来，并把 identity 传播到 Worker、Task Pool、batch/Feature 与最终验证证据。
+- **只读 Pi 节点安全重试**：仅 planner/scout/reviewer/verifier/closeout 这类没有仓库写入能力的 Pi 节点，遇到模型连接中断、provider 限流、临时不可用或 timeout 时，可在同一 run 内有界重试；生成模板会自动声明默认 `retryPolicy`（总尝试 3 次、最多可配置 5 次、指数退避、单次等待上限 30s）。每次 attempt 保留独立证据，耗时与 Token 用量按尝试聚合，后一次成功不覆盖前一次失败证据。`quota`/`auth`/`invalid-output`/`write-guard` 与未知失败不重试；supervisor、implementer、writer、dynamic、shell、static、docs-only、decision-gate 节点不重试。
 - **`agent-worker` operator skill**：`skills/agent-worker/` 只负责 Feature Packet、TaskSpec、Task Pool、自举 release train 和失败恢复的外层路由；单个 DAG 实现、DAG kernel 修复和节点执行仍由 `loop-agent` 负责，该 skill 不进入默认 DAG role skills。
 - **治理文档**：`docs/` 保存原则、工作流、验证矩阵、runtime 边界、计划和报告。
 - **shell verification**：完成声明必须有可复现命令作为依据，而不是只靠聊天结论。

package/dist/application/dag/generate-task-dag.js

@@ -204,6 +204,7 @@ export async function generateTaskDagUseCase(input) {
     await assertExecPlanIndexConsistent(repoRoot);
     const taskConfig = await loadTaskConfig(repoRoot, parsed.taskId);
     const isFrontendImplementationTask = taskConfig.taskKind === "frontend-implementation";
+    const isBackendTestTask = taskConfig.taskKind === "backend-test";
     const candidateResult = await initHybridDagFromTask(repoRoot, parsed.taskId, {
         outputPath: parsed.outputPath,
         template: "standard-dag",
@@ -230,6 +231,20 @@ export async function generateTaskDagUseCase(input) {
             profileRouting.selectedByProfile = parsed.profile;
         }
     }
+    if (isBackendTestTask) {
+        profileRouting.selectedTemplate = "backend-test-dag";
+        profileRouting.source = "taskKind";
+        profileRouting.routingReasons = [
+            'taskKind "backend-test" selects the dedicated backend test DAG template',
+        ];
+        if (parsed.profile === "auto") {
+            profileRouting.selectedByProfile =
+                resolveAutoRoutingProfile(profileRouting.candidateProfile);
+        }
+        else if (parsed.profileExplicit) {
+            profileRouting.selectedByProfile = parsed.profile;
+        }
+    }
     const initResult = profileRouting.selectedTemplate === "standard-dag"
         ? candidateResult
         : await initHybridDagFromTask(repoRoot, parsed.taskId, {

package/dist/application/dag/run-dag.js

@@ -3,6 +3,9 @@ import { composeDagRunObservers } from "../../workflows/dag/observer-compose.js"
 import { createDagCanvasObserver, resolveCanvasPath, } from "../../workflows/dag/canvas-observer.js";
 import { loadDagSpecFromFile, runDag } from "../../workflows/dag/runner.js";
 import { assertValidDagSpec } from "../../workflows/dag/validate.js";
+import { assertRuntimeContractCompatible } from "../../workflows/dag/runtime-contract.js";
+import { DAG_CONTROLLER_CAPABILITIES } from "../../workflows/dag/runtime-contract.js";
+import { resolveRunningControllerIdentity } from "../../shared/package-metadata.js";
 function getCanvasFlushErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -29,6 +32,13 @@ function buildRunDagNextSteps(runId) {
 export async function runDagUseCase(input) {
     const spec = await loadDagSpecFromFile(input.dagPath);
     assertValidDagSpec(spec);
+    const runningIdentity = resolveRunningControllerIdentity();
+    assertRuntimeContractCompatible(spec, {
+        ...DAG_CONTROLLER_CAPABILITIES,
+        ...(runningIdentity
+            ? { controllerVersion: runningIdentity.packageVersion }
+            : {}),
+    });
     const resolvedCanvasPath = resolveCanvasPath({
         canvasPath: input.canvasPath,
         canvasName: input.canvasName,

package/dist/application/dag/validate-dag.js

@@ -1,6 +1,9 @@
 import { readFile } from "node:fs/promises";
 import { loadDagSpecFromFile } from "../../workflows/dag/runner.js";
 import { assertValidDagSpec, collectExecutorModelWarnings, collectForbiddenExecutorIssues, collectGovernanceWarnings, validateDagSpec, } from "../../workflows/dag/validate.js";
+import { assertRuntimeContractCompatible } from "../../workflows/dag/runtime-contract.js";
+import { DAG_CONTROLLER_CAPABILITIES } from "../../workflows/dag/runtime-contract.js";
+import { resolveRunningControllerIdentity } from "../../shared/package-metadata.js";
 import { inferGovernanceProfile } from "../../workflows/dag/governance-profile.js";
 import { topoSortToRanks } from "../../workflows/dag/topo.js";
 import { runSpineAudit } from "../../governance/spine-audit.js";
@@ -103,6 +106,14 @@ export async function validateDagUseCase(input) {
     const spec = await loadDagSpecFromFile(input.dagPath);
     const rawTaskExecutors = await loadRawTaskExecutorMap(input.dagPath);
     ensureNoForbiddenExecutors(spec, input.forbidExecutors, rawTaskExecutors);
+    // Runtime contract drift is always a hard error at validate time.
+    const runningIdentity = resolveRunningControllerIdentity();
+    assertRuntimeContractCompatible(spec, {
+        ...DAG_CONTROLLER_CAPABILITIES,
+        ...(runningIdentity
+            ? { controllerVersion: runningIdentity.packageVersion }
+            : {}),
+    });
     const validationIssues = validateDagSpec(spec);
     const expectedMatrices = await loadExpectedExecutorModelMatrices(input.repoRoot);
     const warnings = collectExecutorModelWarnings(spec, expectedMatrices);

package/dist/commands/init.js

@@ -1036,15 +1036,62 @@ async function readInitSurfaceManifest(assetRoot) {
     const manifest = JSON.parse(raw);
     const initFullRequired = manifest.initFullRequired ?? [];
     const initSurface = manifest.initSurface ?? {};
-    const entries = initFullRequired.map((relativePath) => ({
-        path: relativePath,
-        mode: initSurface[relativePath] ?? inferInitSurfaceMode(relativePath),
-    }));
+    const seenPaths = new Set();
+    const entries = [];
+    for (const relativePath of initFullRequired) {
+        if (seenPaths.has(relativePath))
+            continue;
+        seenPaths.add(relativePath);
+        entries.push({
+            path: relativePath,
+            mode: initSurface[relativePath] ?? inferInitSurfaceMode(relativePath),
+        });
+    }
+    // Fresh `init --profile full` copies the entire `docs/templates/` and
+    // `skills/` directories via copyDirMerge. Every file actually projected to a
+    // target project must be represented in the desired init surface so that
+    // check-update can detect missing or stale copies during controller upgrades.
+    // The static manifest intentionally only pins explicit modes for the subset
+    // that needs them; the rest are auto-discovered here as "copied" entries.
+    for (const discovered of await discoverCopiedSurfaceFiles(assetRoot)) {
+        if (seenPaths.has(discovered))
+            continue;
+        seenPaths.add(discovered);
+        entries.push({
+            path: discovered,
+            mode: initSurface[discovered] ?? inferInitSurfaceMode(discovered),
+        });
+    }
     if (!entries.some((entry) => entry.path === INIT_SURFACE_STATE_PATH)) {
         entries.push({ path: INIT_SURFACE_STATE_PATH, mode: "state" });
     }
     return { manifest, raw, sha256: sha256Text(raw), entries };
 }
+/**
+ * Returns manifest-path entries for every file that fresh `init --profile full`
+ * copies from the bundled package into a target project: all of `docs/templates/`
+ * and all of `skills/` (the latter is mirrored to `.agents/skills/` at the
+ * target). Paths use the package source convention so manifestPathToTargetPath
+ * can remap them per governance root.
+ */
+async function discoverCopiedSurfaceFiles(assetRoot) {
+    const discovered = [];
+    const roots = [
+        { source: "docs/templates", prefix: "docs/templates/" },
+        { source: "skills", prefix: "skills/" },
+    ];
+    for (const { source, prefix } of roots) {
+        const rootPath = path.join(assetRoot, source);
+        const rootInfo = await stat(rootPath).catch(() => null);
+        if (!rootInfo?.isDirectory())
+            continue;
+        const files = await listRelativeFiles(rootPath);
+        for (const relativePath of files) {
+            discovered.push(`${prefix}${relativePath}`);
+        }
+    }
+    return discovered.sort();
+}
 function inferInitSurfaceMode(relativePath) {
     if (relativePath === INIT_SURFACE_STATE_PATH)
         return "state";
@@ -1378,8 +1425,9 @@ function hasLegacyHarnessGovernancePaths(harness) {
     return false;
 }
 async function collectRetiredLayoutActions(input) {
+    const blockedTargetPaths = new Set();
     if (!input.recordedState)
-        return [];
+        return { actions: [], blockedTargetPaths };
     const actions = [];
     const retiredOwnedPaths = [];
     const currentPaths = new Set(Object.keys(input.currentState.files));
@@ -1399,6 +1447,9 @@ async function collectRetiredLayoutActions(input) {
                 path: oldPath,
                 reason: `legacy init file may have local edits; review before migrating to ${targetPath}`,
             });
+            // The user owns a modified copy at the legacy path; do not silently
+            // install the package version at the canonical target path.
+            blockedTargetPaths.add(targetPath);
             continue;
         }
         const targetAbsolute = path.join(input.repoRoot, targetPath);
@@ -1442,6 +1493,7 @@ async function collectRetiredLayoutActions(input) {
             path: oldPath,
             reason: `legacy init file is owned, but target path ${targetPath} already exists with different content`,
         });
+        blockedTargetPaths.add(targetPath);
     }
     for (const legacyRoot of ["docs", "skills"]) {
         for (const relativePath of await listRelativeFiles(path.join(input.repoRoot, legacyRoot))) {
@@ -1476,6 +1528,7 @@ async function collectRetiredLayoutActions(input) {
                     path: oldPath,
                     reason: `legacy init-shaped file is not recorded and differs from the current bundled/generated asset; review before migrating to ${targetPath}`,
                 });
+                blockedTargetPaths.add(targetPath);
                 continue;
             }
             if (!targetHash) {
@@ -1492,6 +1545,7 @@ async function collectRetiredLayoutActions(input) {
                 path: oldPath,
                 reason: `legacy init-shaped file matches the package, but target path ${targetPath} already exists with different content`,
             });
+            blockedTargetPaths.add(targetPath);
         }
     }
     for (const dir of collectSafeRetiredDirectories(retiredOwnedPaths)) {
@@ -1501,7 +1555,7 @@ async function collectRetiredLayoutActions(input) {
             reason: "remove directory if it is empty after legacy init files are migrated",
         });
     }
-    return actions;
+    return { actions, blockedTargetPaths };
 }
 async function resolveInitProjectContext(input) {
     const harness = await readJsonIfExists(path.join(input.repoRoot, "harness.json"));
@@ -1771,6 +1825,13 @@ function buildTargetFeatureWorkflow(input) {
         "",
         "Before executing a DAG, review profile routing, governance profile, writer writeSet, allowed paths, forbidden paths, shell verification, and decision gate mode.",
         "",
+        "## Specialized Task Kinds",
+        "",
+        "Set `taskKind` in `.harness/tasks/<task-id>/task.json` to route a task to a dedicated DAG profile instead of the default auto profile:",
+        "",
+        "- `taskKind: \"backend-test\"` selects the dedicated backend test DAG. Its Pi nodes analyze requirements, generate and review backend cases, generate pytest, and retrospect on results; shell gate/execution nodes enforce the review verdict and run the target project's pytest. The backend test templates (`backend-test-dag.json` and the `backend-test-dag.*.prompt.md` files) ship inside the loop-agent package as static references and are projected to target projects under the governance `templates/` directory.",
+        "- Only eligible read-only Pi nodes (planner, scout, reviewer, verifier, closeout with no write-capable tool profile) receive the conservative automatic retry policy. Supervisor, implementer, writer, docs-only, dynamic, shell, static, and decision-gate nodes are not retried automatically. Eligible nodes cannot write repository files; the controller only records immutable attempt evidence under `.harness/dag-runs/<state>/<run-id>/<node-id>/attempt-<n>.json`.",
+        "",
         "## Verification",
         "",
         `Use \`${input.governanceRoot}/verification-matrix.md\` to choose the narrowest command that proves the claim.`,
@@ -2169,7 +2230,7 @@ export async function checkInitUpdate(input) {
     const deterministicActions = [];
     const modelMergeTasks = [];
     const humanDecisions = [];
-    const retiredLayoutActions = await collectRetiredLayoutActions({
+    const retiredLayoutResult = await collectRetiredLayoutActions({
         assetRoot,
         repoRoot,
         projectName,
@@ -2178,9 +2239,15 @@ export async function checkInitUpdate(input) {
         currentState,
         humanDecisions,
     });
+    const retiredLayoutActions = retiredLayoutResult.actions;
     const retiredTargetPaths = new Set(retiredLayoutActions
         .filter((action) => action.type === "migrate-owned-file" && action.targetPath)
         .map((action) => action.targetPath));
+    // Targets occupied by a user-modified legacy copy must not be silently
+    // (re)installed from the package; preserve them for a human/model merge.
+    for (const blockedPath of retiredLayoutResult.blockedTargetPaths) {
+        retiredTargetPaths.add(blockedPath);
+    }
     if (!recordedState) {
         deterministicActions.push({
             type: "bootstrap-surface",

package/dist/shared/package-metadata.js

@@ -2,7 +2,9 @@ import { createHash } from "node:crypto";
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { realpathSync } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { platform } from "node:os";
+export const LOOP_AGENT_PACKAGE_NAME = "@tea-agent/loop-agent";
 // ---------------------------------------------------------------------------
 // Public helpers
 // ---------------------------------------------------------------------------
@@ -351,3 +353,136 @@ function assertRegularFile(filePath, requested) {
     }
     throw new Error(`controller identity: resolved executable for ${JSON.stringify(requested)} is not a readable file: ${filePath}`);
 }
+// ---------------------------------------------------------------------------
+// Running-controller identity (in-process capture)
+// ---------------------------------------------------------------------------
+function safeRealpath(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return filePath;
+    }
+}
+/**
+ * Build a ControllerIdentityV1 from a readable entry file inside a Node package
+ * root. Returns `undefined` when any required identity component cannot be
+ * resolved. This reuses the same ControllerIdentityV1 protocol the Worker uses;
+ * it never invents a second identity shape.
+ */
+export function buildControllerIdentityFromEntry(input) {
+    const resolvedAt = (input.now ?? new Date()).toISOString();
+    const realEntry = safeRealpath(path.resolve(input.entry));
+    try {
+        if (!statSync(realEntry).isFile())
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const packageRoot = findPackageRoot(path.dirname(realEntry));
+    if (!packageRoot)
+        return undefined;
+    const packageName = readPackageName(packageRoot);
+    if (!packageName)
+        return undefined;
+    const packageVersion = readPackageVersion(packageRoot);
+    if (!packageVersion)
+        return undefined;
+    const binarySha256 = computeBinarySha256(realEntry);
+    if (!binarySha256)
+        return undefined;
+    let packageFingerprint;
+    try {
+        packageFingerprint = computePackageFingerprint(packageRoot);
+    }
+    catch {
+        return undefined;
+    }
+    const isScript = isJavaScriptScript(realEntry);
+    const launch = isScript
+        ? { command: safeRealpath(process.execPath), argsPrefix: [realEntry] }
+        : { command: realEntry, argsPrefix: [] };
+    return {
+        schemaVersion: 1,
+        packageName,
+        binName: path.basename(realEntry),
+        requested: input.requested,
+        entry: path.resolve(input.entry),
+        realEntry,
+        launch,
+        binarySha256,
+        packageRoot,
+        packageVersion,
+        packageFingerprint,
+        resolvedAt,
+    };
+}
+/**
+ * Stable content anchor for a controller identity. Two identities are the same
+ * controller when their anchors are equal. Kept in sync with the Worker anchor
+ * so DAG-owned and Worker-owned identity facts are comparable.
+ */
+export function controllerIdentityAnchor(identity) {
+    return JSON.stringify({
+        schemaVersion: identity.schemaVersion,
+        packageName: identity.packageName,
+        binName: identity.binName,
+        requested: identity.requested,
+        entry: identity.entry,
+        realEntry: identity.realEntry,
+        launch: identity.launch,
+        binarySha256: identity.binarySha256,
+        packageRoot: identity.packageRoot,
+        packageVersion: identity.packageVersion,
+        packageFingerprint: identity.packageFingerprint,
+    });
+}
+export function controllerIdentitiesMatch(left, right) {
+    return Boolean(left && right && controllerIdentityAnchor(left) === controllerIdentityAnchor(right));
+}
+/**
+ * Resolve the identity of the controller that is executing this process.
+ *
+ * Preference order:
+ * 1. The launched CLI entry (argv[1]) when it resolves inside the loop-agent
+ *    package — this is the real controller binary in production.
+ * 2. The package that physically contains this module — always the loop-agent
+ *    package, which keeps identity resolvable under tests and source runs.
+ *
+ * Returns `undefined` when no loop-agent-rooted identity can be built. Callers
+ * treat `undefined` as legacy-unpinned rather than fabricating an identity.
+ */
+export function resolveRunningControllerIdentity(options) {
+    const argv = options?.argv ?? process.argv;
+    const entryArg = argv[1];
+    if (entryArg) {
+        try {
+            const abs = path.resolve(entryArg);
+            const root = findPackageRoot(path.dirname(abs));
+            if (root && readPackageName(root) === LOOP_AGENT_PACKAGE_NAME) {
+                const identity = buildControllerIdentityFromEntry({
+                    requested: entryArg,
+                    entry: abs,
+                    ...(options?.now ? { now: options.now } : {}),
+                });
+                if (identity)
+                    return identity;
+            }
+        }
+        catch {
+            // Fall back to the module location below.
+        }
+    }
+    try {
+        const moduleFile = fileURLToPath(import.meta.url);
+        return buildControllerIdentityFromEntry({
+            requested: entryArg ?? "loop-agent",
+            entry: moduleFile,
+            ...(options?.now ? { now: options.now } : {}),
+        });
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/task/config-types.js

@@ -11,6 +11,7 @@ export const taskKindSchema = z.enum([
     "standard",
     "feature-study",
     "frontend-implementation",
+    "backend-test",
 ]);
 export const referenceRepoConfigSchema = z.object({
     name: z.string().min(1),

package/dist/worker/cli.js

@@ -326,7 +326,8 @@ export function buildAgentWorkerProgram() {
         .command("serve")
         .requiredOption("--repo <repo-root>", "Target repo root")
         .option("--port <port>", "HTTP port", "8787")
-        .option("--host <host>", "Bind host", "127.0.0.1")
+        .option("--host <host>", "Bind host (default 127.0.0.1; use 0.0.0.0 for LAN, no auth)", "127.0.0.1")
+        .option("--debug", "Log request source/method/path/status to stderr")
         .description("Start read-only observe HTTP server")
         .action(async (options) => {
         const repoRoot = path.resolve(options.repo);
@@ -334,6 +335,7 @@ export function buildAgentWorkerProgram() {
             repoRoot,
             host: options.host,
             port: Number.parseInt(options.port, 10),
+            debug: options.debug === true,
         });
         process.stdout.write(`${server.url}\n`);
         await new Promise((resolve) => {