@tea-agent/loop-agent 0.24.4 → 0.24.6

package/AGENTS.md

@@ -37,7 +37,7 @@
 4. 涉及测试纪律/验证声明/调试时继续读：`docs/governance/harness-methodology-*.md`。
 5. 查看最近提交、相关 plan/progress/report；`git status --short --branch`；跑最小基线验证。
 6. 后端/接口/pytest → `taskKind: "backend-test"`（不是 `--profile`）；知识回写 `knowledge-sync`；图谱开荒 `knowledge-graph-bootstrap`。`--profile` 仅 `auto|minimal|standard|reviewed|supervised`。
-7. 看板/observe → `agent-worker console serve --repo . --port 8790`（`/inspect/` 只读）；`observe serve` 仅为兼容入口。
+7. 看板/observe → `agent-worker console`（默认 repo=当前目录、port=8790；兼容入口 `agent-worker console serve --repo . --port 8790`）（`/inspect/` 只读）；`observe serve` 仅为兼容入口。
 8. 分支合并 → 先读 `docs/operations/branch-merge-guideline.md`。
 
 ## 会话协议

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 ## [Unreleased]
 
+### 新增
+
+- Observe / Inspect 节点检查器在「节点输出」左侧新增「节点输入」页签：只读投影冻结 `run.json` 顶层节点定义（任务正文、依赖、执行器摘要、边界）与可选 assembled prompt 指纹；完整 assembled prompt 与动态展开子节点仍不在本轮范围
+
+## [0.24.6] - 2026-07-29
+
+### 重点更新
+
+- 修复后端测试 Markdown-first 成功路径未投影 `backend-test-result` 的问题，Ready Planner 可再次放行 FE-TEST
+
+### 修复
+
+- Markdown-first `markdown-execute-html` 在解析原生 pytest-html 后立即物化 `contracts/backend-test-result.json`（Result v1），避免 styled HTML 覆盖后丢失 JSON island
+- `node-execution` 对 `markdown-execute-html` 绑定 `structuredArtifact*`，Outcome 适配器可投影 `kind: backend-test-result`
+
+## [0.24.5] - 2026-07-28
+
+### 重点更新
+
+- 后端测试 Markdown 模块与 pytest 脚本实现一对一精准映射，提升测试执行的确定性
+- 修复后端测试 HTML 报告中请求参数显示为空的问题，正确展示请求与响应日志
+- 初始化项目支持将「帮我完成/实现/修复」等通用需求表达直接路由进 Agent DAG
+- 新增裸 agent-worker console 入口，简化本地看板启动流程
+
+### 新增
+
+- 初始化后的目标项目支持将「帮我完成/实现/修复/开发」等通用需求表达确定性地路由进 Agent DAG（new-task → dag run-task → dag validate → run-dag），无需追加额外的 cli 关键词
+- 新增裸 agent-worker console 入口，直接启动 Loop Operator Console，repo 默认当前目录、port 默认 8790
+- check-skill-entry.sh 及初始化投影脚本支持解析 YAML 折叠块，对通用需求触发词建立机器门禁以防漂移
+
+### 改进
+
+- 后端测试收敛模块映射，生成与评审 prompt 强制模块文件一对一映射，在映射缺失时支持确定性恢复
+- 后端测试 execute/report 节点文案与 pytest-html 真源对齐，移除残留的 JUnit 表述
+- 后端测试 HTML 报告对齐 R04 模板样式，采用全 inline style 设计（渐变 banner、可折叠用例卡片、状态胶囊及请求/响应分块展示）
+- 本地看板启动更简，端口被占用时不再自动更换，改为明确提示使用 --port 显式指定其它端口
+- 旧项目经 init check-update 与 apply-safe 即可安全补回新的「通用需求实现」路由行，并保留用户自定义前言
+
+### 修复
+
+- 修复后端测试 HTML 报告中请求参数显示为空的问题：渲染器现已兼容 payload= 键或 JSON request_record 格式的请求摘要
+- 修复后端测试报告无法正确获取请求/响应日志的问题：兼容 HTTP_REQUEST 与 HTTP REQUEST 两种日志前缀，并在解析前正确解码 HTML 实体
+- 修复 shell-executor 在 Windows 环境下因反斜杠路径导致 runDir 损坏的问题，确保路径注入稳定
+- 修复前端 lint baseline 在 Windows 下因路径解析逻辑缺陷，拒绝相对路径输出导致评估误报为不可用的问题
+- 修复多个测试固件在 Windows 下因嵌套 Shell 引号剥离导致命令执行输出为空或报错的问题（涉及 composite-shell 与 init-command）
+
 ## [0.24.4] - 2026-07-28
 
 ### 重点更新
@@ -26,6 +72,7 @@
 ### 重点更新
 
 - 发布工作流改为发布已通过完整门禁并经 SHA-256 校验的 npm tarball，避免 `npm publish` 再次触发全量测试、类型检查与构建。
+- 默认 `standard` 实现任务在 React、Next.js 或 Vue 项目中直接选择 `frontend-implementation` DAG，不再依赖需求关键词；明确后端、文档/测试范围或前端否定仍保留对应通用流程。
 
 ## [0.24.2] - 2026-07-28
 

package/README.md

@@ -52,6 +52,8 @@ loop-agent init reconcile --repo-root .
 
 ### 运行第一个任务
 
+初始化后，在已初始化的目标项目中你可以直接对宿主 agent 说「**loop-agent 帮我完成 XXX 需求**」（或「帮我实现 / 帮我修复 / 帮我开发 XXX」「使用 loop-agent 完成 XXX」「按 loop-agent 流程处理 XXX」），初始化写入的 `AGENTS.md` 与 `.agents/skills/loop-agent/` 会把这类通用需求表达确定性地路由进 Agent DAG，**无需**追加额外的 `cli` 关键词。主会话只负责编排与验证，业务实现由受治理 DAG writer 完成。
+
 ```bash
 loop-agent new-task example-task "实现一个有明确验收标准的小功能"
 ```
@@ -90,12 +92,13 @@ loop-agent dag report --run-id <run-id>
 | 入口 | 命令 | 角色 |
 | --- | --- | --- |
 | 受治理 CLI | `loop-agent …` / `agent-worker …` | 权威写入与诊断 |
-| Loop Operator Console | `agent-worker console serve --repo .` | Official 本地控制面（默认 `127.0.0.1:8790`，含 Operate 与 Inspect） |
+| Loop Operator Console | `agent-worker console` | Official 本地控制面（默认 repo=当前目录、`127.0.0.1:8790`，含 Operate 与 Inspect） |
 | Observe | `agent-worker observe serve --repo . --port 8787` | 兼容期独立只读入口；不再作为推荐路径 |
 
 ```bash
 # 终端 A：Console（任务/运行操作面；canonical mutation 只经 sibling loop-agent）
-agent-worker console serve --repo .
+agent-worker console                              # 默认 repo=当前目录、port=8790
+agent-worker console serve --repo .               # 兼容入口，等价于裸入口
 agent-worker console doctor --repo .
 
 ```

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

@@ -239,10 +239,8 @@ export async function generateTaskDagUseCase(input) {
         reasons: ["dag run-task validate did not report governanceProfile"],
     });
     const hasExplicitSpecializedTaskKind = candidateResult.templateSelection.source === "taskKind";
-    const hasSafeAutomaticTaskSourceRoute = candidateResult.templateSelection.source === "task-source" &&
-        profileRouting.selectedByProfile !== "supervised" &&
-        profileRouting.selectedTemplate !== "supervised-implementation";
-    if (hasExplicitSpecializedTaskKind || hasSafeAutomaticTaskSourceRoute) {
+    const hasAutomaticTaskSourceRoute = candidateResult.templateSelection.source === "task-source";
+    if (hasExplicitSpecializedTaskKind || hasAutomaticTaskSourceRoute) {
         profileRouting.selectedTemplate = candidateResult.template;
         profileRouting.source = hasExplicitSpecializedTaskKind
             ? "taskKind"
@@ -256,10 +254,9 @@ export async function generateTaskDagUseCase(input) {
             profileRouting.selectedByProfile = parsed.profile;
         }
     }
-    // Persist only a safe automatic route. Explicit supervised/profile policy
-    // must remain authoritative and must not be weakened by this convenience
-    // marker. Keep taskId stable; frontend-implementation is the taskKind.
-    if (hasSafeAutomaticTaskSourceRoute && candidateResult.template === "frontend-implementation") {
+    // Persist the automatic business workflow route while preserving the
+    // governance profile as a separate routing dimension.
+    if (hasAutomaticTaskSourceRoute && candidateResult.template === "frontend-implementation") {
         const taskConfig = await loadTaskConfig(repoRoot, parsed.taskId);
         if (!taskConfig.taskKind || taskConfig.taskKind === "standard") {
             await writeTaskConfig(repoRoot, parsed.taskId, {

package/dist/commands/init.js

@@ -415,6 +415,18 @@ check_skill "loop-agent" \\
   "references/command-reference.md"
 check_skill "agent-worker" "references/agent-worker-operator.md"
 
+# loop-agent description is a YAML folded block (>-); grep ^description: only
+# captures the indicator line. Validate the general-demand trigger terms
+# against the whole skill file so host auto-discovery phrasing cannot drift.
+loop_agent_skill=".agents/skills/loop-agent/SKILL.md"
+loop_agent_text="$(tr '[:upper:]' '[:lower:]' < "\${loop_agent_skill}")"
+for term in "loop-agent 帮我完成" "帮我实现" "帮我修复" "帮我开发" "agent dag" "new-task" "dag run-task" "dag validate" "run-dag"; do
+  if [[ "\${loop_agent_text}" != *"\${term}"* ]]; then
+    echo "skill entry 检查失败（loop-agent）：description 缺少触发/路由词 \${term}" >&2
+    exit 1
+  fi
+done
+
 description_line="$(grep -E '^description:' .agents/skills/agent-worker/SKILL.md | head -n 1 | tr '[:upper:]' '[:lower:]')"
 for term in "agent-worker" "feature packet" "taskspec" "task pool" "self-host" "candidate" "loop-agent"; do
   if [[ "\${description_line}" != *"\${term}"* ]]; then
@@ -802,6 +814,7 @@ function buildManagedAgentsBlock(input) {
         "| 初始化更新校验 / 检查初始化更新 / loop-agent 初始化更新校验 / loop agent初始化更新校验 | 更新校验 | 只读报告，不写入 |",
         "| 初始化对齐 / 升级后对齐 / reconcile 初始化 / loop-agent 初始化对齐 | 升级对齐 | 自动应用确定性安全动作；活跃 DAG/Worker 或人工决策时零写入 |",
         "| 初始化安全更新 / 应用初始化更新 / loop-agent 初始化安全更新 / loop agent初始化安全更新 | 安全更新 | 先 check-update，再只执行确定性安全动作 |",
+        "| loop-agent 帮我完成 / 帮我实现 / 帮我修复 / 帮我开发 <需求>；使用 loop-agent 完成 <X>；按 loop-agent 流程处理 <X> | 通用需求实现 | 先建任务源与 `task.json.allowedPaths` / `forbiddenPaths`，再 `new-task` → `dag run-task` → `dag validate` → `run-dag`；主会话不得直接修改业务实现 |",
         "",
         "**更新校验（只读）**：只读执行下面命令；**不得自动**执行 `apply-safe` 或模型合并。",
         "",
@@ -861,10 +874,11 @@ function buildManagedAgentsBlock(input) {
         "### 运行看板（只读）",
         "",
         "```bash",
-        "agent-worker console serve --repo . --port 8790",
+        "agent-worker console                       # 默认 repo=当前目录，port=8790",
+        "agent-worker console serve --repo . --port 8790   # 兼容入口，等价于上面裸入口",
         "```",
         "",
-        "浏览器打开 `http://127.0.0.1:8790/`；检视面为 `http://127.0.0.1:8790/inspect/`。默认绑定本机 `127.0.0.1`；不要直接暴露到公开网络。`agent-worker observe serve` 仅为兼容入口。",
+        "浏览器打开 `http://127.0.0.1:8790/`；检视面为 `http://127.0.0.1:8790/inspect/`。默认绑定本机 `127.0.0.1`；不要直接暴露到公开网络。端口被占用时不会自动更换，请用 `--port <port>` 显式指定。`agent-worker observe serve` 仅为兼容入口。",
         "",
         "### DAG 诊断与收口",
         "",
@@ -2049,11 +2063,11 @@ function buildTargetFeatureWorkflow(input) {
         "",
         "## Specialized Task Kinds",
         "",
-        "- standard tasks are classified conservatively by combining the task title, `source/需求.md`, structured `allowedPaths`, strong React/Next/Vue project evidence, and user-visible interaction/state semantics.",
-        "- An implicit frontend demand selects the frontend DAG only when project or frontend-path evidence is paired with product-delivery semantics; framework evidence alone is insufficient. Backend, mixed, negated, documentation/test maintenance, and unknown demands keep the template selected by the normal governance profile.",
+        "- standard tasks first use the structured task type in `source/需求.md`, then combine `allowedPaths` with strong React/Next/Vue project evidence for deterministic routing.",
+        "- A frontend project defaults eligible implementation work to the frontend DAG without requirement keyword matching. Explicit backend, mixed, frontend-negated, and documentation/test-only scopes keep the template selected by the normal governance profile.",
         "- `frontend-mock-assess-pi` reads Mock/API/schema evidence and selects `native|browser-intercept|request-adapter|not-needed|blocked` before frontend planning; its deterministic gate rejects blocked or malformed output, while the existing frontend implementer remains the only writer.",
         "- Mock-backed verification never proves real API integration. When the backend was not exercised, closeout must retain the gap and name `<task-id>-real-api-integration-verify`; that follow-up is explicitly created/run after backend readiness, never automatic.",
-        "- Automatic frontend classification never replaces a supervised template selected by an explicit profile, workflowPolicy, or the supervised quality gate.",
+        "- Automatic frontend classification selects the frontend implementation workflow and persists taskKind; explicit profiles, workflowPolicy, and supervised quality gates record governance strength without switching the business workflow back to a generic DAG.",
         "- A backend implementation does not select the backend test DAG. `backend-test` remains an explicit test-engineering workflow.",
         "- Explicit specialized `taskKind` values remain compatible and take precedence over task-source classification.",
         "",

package/dist/executors/shell-executor.js

@@ -17,7 +17,7 @@ import { formatFrontendReviewContextStdout, runFrontendReviewContextGate, } from
 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, parsePytestHtmlReport } from "../workflows/dag/backend-test-result-contract.js";
+import { materializeBackendTestResultFromPytestHtml, materializeBackendTestResultFromRunDir, parsePytestHtmlReport } from "../workflows/dag/backend-test-result-contract.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";
@@ -414,6 +414,14 @@ async function executeBackendTestPipeline(input, meta) {
             if (![0, 1].includes(pytestExitCode))
                 throw new Error(`pytest did not complete with a reportable exit code: ${pytestExitCode}`);
             const parsed = parsePytestHtmlReport(pytestHtmlContent);
+            // Bind Result v1 from the native pytest-html report BEFORE overwriting with the
+            // styled renderer (which drops the data-jsonblob island).
+            const resultArtifact = await materializeBackendTestResultFromPytestHtml({
+                runDir: meta.runDir,
+                htmlRelativePath: "reports/backend-test.html",
+                htmlContent: pytestHtmlContent,
+                pytestExitCode,
+            });
             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");
@@ -430,7 +438,7 @@ async function executeBackendTestPipeline(input, meta) {
             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}`, `markdown=${markdownPath}`, `facts=${factsPath}`, facts);
+            outputs.push(...sanitizedOutputs, `html=${htmlPath}`, `markdown=${markdownPath}`, `facts=${factsPath}`, `result=${resultArtifact.path}`, facts);
         }
         else if (pipeline === "contracts") {
             const wrapperPath = path.join(meta.runDir, "analyze-and-discover-backend-test-pi.json");

package/dist/task/task-demand-routing.js

@@ -298,6 +298,11 @@ export function classifyTaskDemand(input) {
             message: "allowedPaths include a backend-specific source path",
         });
     }
+    const allowedPathsOnlyCoverNonProductArtifacts = input.allowedPaths.length > 0 &&
+        input.allowedPaths.every((rawPath) => {
+            const allowedPath = normalizedAllowedPath(rawPath);
+            return matchesAny(allowedPath, NON_PRODUCT_ALLOWED_PATH_PATTERNS);
+        });
     const pathSupportedFrontendDelivery = frontendPath &&
         (titleSignals.pathSupportedFrontendDelivery ||
             requirementSignals.pathSupportedFrontendDelivery ||
@@ -328,20 +333,27 @@ export function classifyTaskDemand(input) {
             message: "task text contains user-visible interaction/state delivery and the project has strong frontend framework evidence",
         });
     }
+    const backendDelivery = titleSignals.backendDelivery || requirementSignals.backendDelivery;
+    const frontendProjectDefaultImplementation = hasStrongFrontendProjectEvidence &&
+        !backendDelivery &&
+        !frontendNegated &&
+        !allowedPathsOnlyCoverNonProductArtifacts;
+    if (frontendProjectDefaultImplementation) {
+        addSignal(signals, {
+            id: "frontend-project-default-implementation",
+            source: "project",
+            message: "frontend project evidence selects the frontend implementation workflow by default",
+        });
+    }
     const frontendDelivery = titleSignals.frontendDelivery ||
         requirementSignals.frontendDelivery ||
         pathSupportedFrontendDelivery ||
-        projectSupportedFrontendDelivery;
-    const allowedPathsOnlyCoverNonProductArtifacts = input.allowedPaths.length > 0 &&
-        input.allowedPaths.every((rawPath) => {
-            const allowedPath = normalizedAllowedPath(rawPath);
-            return matchesAny(allowedPath, NON_PRODUCT_ALLOWED_PATH_PATTERNS);
-        });
+        projectSupportedFrontendDelivery ||
+        frontendProjectDefaultImplementation;
     if (allowedPathsOnlyCoverNonProductArtifacts && frontendDelivery) {
         blockers.push("non-product-allowed-paths");
     }
     const eligibleFrontendDelivery = frontendDelivery && !allowedPathsOnlyCoverNonProductArtifacts;
-    const backendDelivery = titleSignals.backendDelivery || requirementSignals.backendDelivery;
     const taskTypeConflict = (hasFrontendTaskType && (backendDelivery || frontendNegated)) ||
         (hasBackendTaskType && eligibleFrontendDelivery);
     if (taskTypeConflict)
@@ -402,13 +414,6 @@ export function resolveTaskDagTemplateSelection(input) {
             reasons: [],
         };
     }
-    if (requestedTemplate !== "standard-dag") {
-        return {
-            template: requestedTemplate,
-            source: "requested-template",
-            reasons: [],
-        };
-    }
     const classification = classifyTaskDemand(input);
     if (classification.kind === "frontend") {
         const frontendSignals = classification.signals
@@ -423,6 +428,14 @@ export function resolveTaskDagTemplateSelection(input) {
             classification,
         };
     }
+    if (requestedTemplate !== "standard-dag") {
+        return {
+            template: requestedTemplate,
+            source: "requested-template",
+            reasons: [],
+            classification,
+        };
+    }
     return {
         template: requestedTemplate,
         source: "requested-template",

package/dist/worker/cli.js

@@ -41,7 +41,8 @@ export function buildAgentWorkerProgram() {
         .description("Local product-line worker utilities for TaskSpec validation")
         .version(readPackageVersion(path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))))) ?? "0.0.0", "-V, --version", "display version")
         .showHelpAfterError()
-        .showSuggestionAfterError();
+        .showSuggestionAfterError()
+        .enablePositionalOptions();
     const task = program.command("task").description("TaskSpec utilities");
     const batch = program
         .command("batch")
@@ -593,18 +594,17 @@ export function buildAgentWorkerProgram() {
         process.stdout.write(`${JSON.stringify(snapshot)}\n`);
     });
     consoleCmd
-        .command("serve")
-        .requiredOption("--repo <repo-root>", "Target repo root")
+        .description("Loop Operator Console (local); bare `agent-worker console` starts it directly (repo defaults to current working directory, port defaults to 8790)")
+        .enablePositionalOptions()
+        .passThroughOptions()
+        .option("--repo <repo-root>", "Target repo root (default: current working directory)", process.cwd())
         .option("--port <port>", "HTTP port", "8790")
         .option("--host <host>", "Bind host (default 127.0.0.1; use 0.0.0.0 for LAN, no network auth)", "127.0.0.1")
         .option("--debug", "Log request source/method/path/status to stderr")
         .option("--app-data <path>", "Override Console application-data root (Draft/Operation/confirmation)")
-        .description("Start Loop Operator Console HTTP server (Operate + Inspect; static SPA + Operator API)")
         .action(async (options) => {
-        const { createConsoleServer } = await import("./console/server.js");
-        const repoRoot = path.resolve(options.repo);
-        const server = await createConsoleServer({
-            repoRoot,
+        await runConsoleServe({
+            repoRoot: path.resolve(options.repo),
             host: options.host,
             port: Number.parseInt(options.port, 10),
             debug: options.debug === true,
@@ -612,13 +612,25 @@ export function buildAgentWorkerProgram() {
                 ? path.resolve(options.appData)
                 : undefined,
         });
-        process.stdout.write(`${server.url}\n`);
-        await new Promise((resolve) => {
-            const shutdown = () => resolve();
-            process.once("SIGINT", shutdown);
-            process.once("SIGTERM", shutdown);
+    });
+    consoleCmd
+        .command("serve")
+        .option("--repo <repo-root>", "Target repo root (default: current working directory)", process.cwd())
+        .option("--port <port>", "HTTP port", "8790")
+        .option("--host <host>", "Bind host (default 127.0.0.1; use 0.0.0.0 for LAN, no network auth)", "127.0.0.1")
+        .option("--debug", "Log request source/method/path/status to stderr")
+        .option("--app-data <path>", "Override Console application-data root (Draft/Operation/confirmation)")
+        .description("Start Loop Operator Console HTTP server (compat entry; equivalent to bare `agent-worker console`)")
+        .action(async (options) => {
+        await runConsoleServe({
+            repoRoot: path.resolve(options.repo),
+            host: options.host,
+            port: Number.parseInt(options.port, 10),
+            debug: options.debug === true,
+            appDataRoot: options.appData
+                ? path.resolve(options.appData)
+                : undefined,
         });
-        await server.close();
     });
     consoleCmd
         .command("doctor")
@@ -693,6 +705,39 @@ export async function main(argv = process.argv) {
 async function readTaskYaml(taskSpecPath) {
     return YAML.parse(await readFile(taskSpecPath, "utf-8"));
 }
+/** Shared console serve entry used by both bare `console` and `console serve`. */
+async function runConsoleServe(options) {
+    const { createConsoleServer } = await import("./console/server.js");
+    try {
+        const server = await createConsoleServer({
+            repoRoot: options.repoRoot,
+            host: options.host,
+            port: options.port,
+            debug: options.debug === true,
+            appDataRoot: options.appDataRoot,
+        });
+        process.stdout.write(`${server.url}\n`);
+        await new Promise((resolve) => {
+            const shutdown = () => resolve();
+            process.once("SIGINT", shutdown);
+            process.once("SIGTERM", shutdown);
+        });
+        await server.close();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const code = error?.code;
+        const isPortInUse = code === "EADDRINUSE" ||
+            /listen EADDRINUSE/i.test(detail) ||
+            /address already in use/i.test(detail);
+        if (isPortInUse) {
+            process.stderr.write(`端口 ${options.port} 已被占用，请使用 --port <port> 指定其它端口后重试。\n`);
+            process.exit(1);
+        }
+        process.stderr.write(`${detail}\n`);
+        process.exit(1);
+    }
+}
 function handlePoolRecoveryCliError(error) {
     const detail = error instanceof Error ? error.message : String(error);
     process.stderr.write(`${detail}\n`);

package/dist/worker/observe/dag-run-artifacts.js

@@ -0,0 +1,90 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { isSafeObservabilityIdentifier } from "../observability/event-store.js";
+export const DAG_RUN_LIFECYCLES = ["active", "completed", "paused"];
+function isPathInside(root, target) {
+    const normalizedRoot = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+    const normalizedTarget = path.normalize(target);
+    return (normalizedTarget === root || normalizedTarget.startsWith(normalizedRoot));
+}
+function normalizeRelativeSegments(relativeSegments) {
+    if (!Array.isArray(relativeSegments) || relativeSegments.length === 0) {
+        return null;
+    }
+    const segments = [];
+    for (const segment of relativeSegments) {
+        if (typeof segment !== "string" || !segment)
+            return null;
+        if (segment === "." || segment === "..")
+            return null;
+        if (segment.includes("/") || segment.includes("\\") || segment.includes("\0")) {
+            return null;
+        }
+        segments.push(segment);
+    }
+    return segments;
+}
+/**
+ * Resolve a path under `.harness/dag-runs/{lifecycle}/{dagRunId}/...`.
+ * Fail closed on invalid ids, path escape, or the same runId appearing in
+ * multiple lifecycle directories.
+ */
+export function resolveDagRunArtifact(repoRoot, dagRunId, relativeSegments) {
+    if (!isSafeObservabilityIdentifier(dagRunId)) {
+        return { ok: false, reason: "invalid-id" };
+    }
+    const segments = normalizeRelativeSegments(relativeSegments);
+    if (!segments) {
+        return { ok: false, reason: "unsafe-path" };
+    }
+    for (const segment of segments) {
+        if (segment !== "run.json" &&
+            segment !== "state.json" &&
+            !isSafeObservabilityIdentifier(segment) &&
+            !/^[a-zA-Z0-9._-]+$/.test(segment)) {
+            // Allow known artifact filenames under a validated node id prefix.
+            if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(segment)) {
+                return { ok: false, reason: "unsafe-path" };
+            }
+        }
+    }
+    const dagRunsRoot = path.resolve(repoRoot, ".harness", "dag-runs");
+    const matches = [];
+    for (const lifecycle of DAG_RUN_LIFECYCLES) {
+        const runDir = path.join(dagRunsRoot, lifecycle, dagRunId);
+        const absolutePath = path.resolve(runDir, ...segments);
+        if (!isPathInside(dagRunsRoot, absolutePath))
+            continue;
+        const relative = path.relative(dagRunsRoot, absolutePath);
+        const parts = relative.split(path.sep).filter(Boolean);
+        if (parts[0] !== lifecycle || parts[1] !== dagRunId)
+            continue;
+        if (!existsSync(absolutePath))
+            continue;
+        matches.push({
+            lifecycle,
+            runDir,
+            absolutePath,
+            relativePath: path.join(lifecycle, dagRunId, ...segments),
+        });
+    }
+    if (matches.length === 0) {
+        return { ok: false, reason: "not-found" };
+    }
+    if (matches.length > 1) {
+        return { ok: false, reason: "ambiguous" };
+    }
+    return { ok: true, result: matches[0] };
+}
+export function resolveDagRunJson(repoRoot, dagRunId) {
+    return resolveDagRunArtifact(repoRoot, dagRunId, ["run.json"]);
+}
+export function resolveDagNodePromptRedacted(repoRoot, dagRunId, nodeId) {
+    if (!isSafeObservabilityIdentifier(nodeId)) {
+        return { ok: false, reason: "invalid-id" };
+    }
+    return resolveDagRunArtifact(repoRoot, dagRunId, [
+        nodeId,
+        "prompt.redacted.md",
+    ]);
+}