@tea-agent/loop-agent 0.18.1 → 0.20.0

package/AGENTS.md

@@ -54,7 +54,7 @@
 10. 检查 `git status --short --branch`。
 11. 运行本次任务相关的最小基线验证。
 12. 如果用户提到"后端测试"、"接口测试"、"pytest"、"自动化测试"，在任务 `task.json` 中设置 `taskKind: "backend-test"` 再 `dag run-task`；不要用 `--profile backend-test`（CLI 不接受该值，专用模板只走 taskKind）。知识回写用 `taskKind: "knowledge-sync"`（须 `featureId`），图谱开荒用 `taskKind: "knowledge-graph-bootstrap"`。`--profile` 仅表示治理强度：`auto|minimal|standard|reviewed|supervised`。
-13. 如果用户提到"看板"、"observe"、"监控面板"、"启动看板"，使用 `agent-worker observe serve --repo . --port 8787` 命令启动。
+13. 如果用户提到"看板"、"observe"、"监控面板"、"启动看板"，使用 `agent-worker console serve --repo . --port 8790` 启动统一 Operator Console；`/inspect/` 提供只读检视。`agent-worker observe serve --repo . --port 8787` 仅为兼容入口。
 14. 如果用户要求“合并 `<source>` 到 `<target>`”或“合并 origin/main 到当前分支”，先阅读 `docs/branch-merge-guideline.md`，按影响自动选择快速、标准或深度模式；始终冻结 source SHA、审查双方功能、运行 merge-tree、生成 source-SHA 合并报告，并在提交前再次 fetch 防止主干前进。
 
 ## 会话协议
@@ -89,7 +89,7 @@
 - 长期决策写入 `docs/`，不要只留在聊天里。
 - 分支合并遵循 `docs/branch-merge-guideline.md`；快速模式只用于可证明的低风险/no-op 合并，涉及冲突、init/package/runtime/release/public API 时必须升级为标准或深度模式。
 - 后端测试、接口/API 测试、pytest 或明确的后端自动化测试，必须把 `.harness/tasks/<task-id>/task.json` 的 `taskKind` 设置为 `"backend-test"`，不得保留默认 `standard`。`backend-test` 是 `taskKind`，不是 `--profile` 的可选值；`dag run-task` 继续使用 `--profile auto` 选择治理等级。仅说“自动化测试”且前后端不明时，先根据任务源和项目技术栈判断，禁止无条件路由。
-- 本地只读运行看板：`agent-worker observe serve --repo . --port 8787`，访问 `http://127.0.0.1:8787/`；看板只读，默认只绑定本机 `127.0.0.1`，不要直接暴露到公开网络。
+- 本地 Operator Console：`agent-worker console serve --repo . --port 8790`，访问 `http://127.0.0.1:8790/`；其中 `/inspect/` 为只读运行检视。默认绑定本机 `127.0.0.1`；可用 `--host 0.0.0.0` / `--debug`，不要直接暴露到公开网络。
 - 面向使用者的新增、修改、删除或修复，应同步更新根目录 `CHANGELOG.md`；保持版本级摘要即可，不写过细技术细节。
 - 面向用户的中文更新日志、README 和说明文档应使用自然、结果导向的表达：先说明用户能获得什么或问题如何改善，保留必要的命令和产品术语，避免逐字翻译、内部实现细节和无意义的中英混杂。
 - 涉及 `loop-agent init` 或目标项目投影的改动，必须同步考虑目标项目生成物：`AGENTS.md`、`README.md`、`harness.json`、`ai_workspace/loop-agent/`、`scripts/`、`.agents/skills/`、`.harness/prompts`、`.gitignore`（loop-agent runtime managed block）和 npm 包内置 assets；目标项目根 `docs/` 和根 `skills/` 的旧投影需要由 `init update --apply-safe` 安全迁移或退役。

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-07-23
+
+### 新增
+
+- streamline implementation DAG (#61)
+- improve human-readable artifacts
+
+### 修复
+
+- relax traceability mapping
+
+## [0.19.0] - 2026-07-23
+
+### 重点更新
+
+- Operator Console 统一整合 Operate 与 Inspect，在同一服务即可检视只读 Dashboard、DAG、时间线与 artifacts
+- 原 Observe 服务进入兼容期，仍可运行但会输出迁移提示，引导平滑过渡到统一控制台
+
+### 新增
+
+- 新增统一 Operator Console：`console serve` 同时提供 Operate 与 Inspect，支持通过 `/inspect/` 直接检视运行详情与 DAG
+- Console 健康检查接口升级，包含 Inspect 就绪状态与路由能力信息
+- `console serve` 新增局域网绑定（`--host 0.0.0.0`）与调试日志（`--debug`）选项，并在非本地访问时保留安全校验
+
+### 改进
+
+- `frontend-implementation` 保留独立 contract/scout，并把 Mock 策略与 implementation contract 合入 plan，把写前授权、验证/失败评估、复验和 review context 分别收敛为组合 shell 节点。standard/high-risk 固定 15 个顶层节点、small-risk 13 个；绿色路径执行 11 个节点、7 次 Pi，同时保留唯一 prewrite 写入授权、同 writeSet repair、真实 diff review 与 fail-closed closeout。
+- 优化操作与观测统一界面的导航与布局，合并确认与运行为「开始运行」，DAG 详情跳转路径更加准确
+
+### 修复
+
+- 修复执行计划索引将命名约定占位符（如 `YYYY-MM-DD-<topic>.md`）误判为缺失计划引用的问题
+
 ## [0.18.1] - 2026-07-22
 
 ### 重点更新

package/README.md

@@ -85,24 +85,22 @@ loop-agent dag doctor --run-id <run-id> --markdown
 loop-agent dag report --run-id <run-id>
 ```
 
-### Official 本地操作面（CLI + Console + 独立 Observe）
+### Official 本地操作面（CLI + 统一 Operator Console）
 
 | 入口 | 命令 | 角色 |
 | --- | --- | --- |
 | 受治理 CLI | `loop-agent …` / `agent-worker …` | 权威写入与诊断 |
-| Loop Operator Console | `agent-worker console serve --repo .` | Official 本地控制面（默认 `127.0.0.1:8790`） |
-| Observe | `agent-worker observe serve --repo . --port 8787` | 独立只读看板 |
+| Loop Operator Console | `agent-worker console serve --repo .` | Official 本地控制面（默认 `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 doctor --repo .
 
-# 终端 B：独立 Observe（不经 Console mount/proxy）
-agent-worker observe serve --repo . --port 8787
 ```
 
-访问 Console <http://127.0.0.1:8790/> 与 Observe <http://127.0.0.1:8787/>。Observe 只读运行事实；Console 通过 versioned health（同仓 `repoFingerprint` + route capability）fail-closed 构建深链。openCode 等主会话仍是 **Compatibility / Operator Assist**，不得升级为与 Official 同等保证。
+访问 Console <http://127.0.0.1:8790/>；顶部「检视」以及 `/inspect/` 提供原 Observe 的只读 Dashboard、DAG、时间线与 artifacts。需要保留的旧书签或脚本仍可在兼容窗口使用 Observe `:8787`。openCode 等主会话仍是 **Compatibility / Operator Assist**，不得升级为与 Official 同等保证。
 
 ## 核心边界
 

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

@@ -105,6 +105,17 @@ function isVerificationShellTask(task) {
     const commands = resolveShellCommands(task.shell);
     return commands.some((command) => /(vitest|npm run (lint|typecheck|test)|check-repo\.sh|loop-agent-standard-verify)/.test(command));
 }
+function resolveReviewPacketShellCommands(task) {
+    const bundle = task.shell?.frontendVerificationBundle;
+    if (bundle) {
+        return [
+            ...bundle.mockCommands,
+            ...bundle.staticCommands,
+            ...bundle.behaviorCommands,
+        ];
+    }
+    return resolveShellCommands(task.shell);
+}
 async function buildReviewPacket(input) {
     const spec = parseDagSpec(JSON.parse(await readFile(input.dagPath, "utf-8")));
     const writers = collectWriterTasksForPacket(spec).map((task) => {
@@ -123,7 +134,7 @@ async function buildReviewPacket(input) {
         .filter(isVerificationShellTask)
         .map((task) => ({
         nodeId: task.id,
-        commands: resolveShellCommands(task.shell),
+        commands: resolveReviewPacketShellCommands(task),
     }));
     return {
         profileRouting: {

package/dist/commands/init.js

@@ -783,13 +783,13 @@ function buildManagedAgentsBlock(input) {
         "",
         "### 运行看板（只读）",
         "",
-        "启动本地只读运行看板：",
+        "启动统一 Operator Console（含只读 Inspect）：",
         "",
         "```bash",
-        "agent-worker observe serve --repo . --port 8787",
+        "agent-worker console serve --repo . --port 8790",
         "```",
         "",
-        "浏览器打开 `http://127.0.0.1:8787/`。看板只读，默认只绑定本机 `127.0.0.1`；不要直接暴露到公开网络。",
+        "浏览器打开 `http://127.0.0.1:8790/`；检视面为 `http://127.0.0.1:8790/inspect/`。默认绑定本机 `127.0.0.1`；可用 `--host 0.0.0.0` 做局域网访问（无网络鉴权，仅可信网络），`--debug` 输出请求日志。不要直接暴露到公开网络。`agent-worker observe serve` 仅为兼容入口。",
         "",
         "### DAG 诊断与收口",
         "",

package/dist/executors/shell-executor.js

@@ -12,10 +12,12 @@ import { materializeFrontendTestResult, } from "../workflows/dag/frontend-test-r
 import { formatFrontendVerificationTraceStdout, runFrontendVerificationTraceGate, } from "../workflows/dag/frontend-verification-trace.js";
 import { formatFrontendWorktreeDiffStdout, runFrontendWorktreeDiffGate, } from "../workflows/dag/frontend-worktree-diff.js";
 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 { 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 { inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
+import { collectBackendTestHumanCaseCatalog, 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";
@@ -356,14 +358,16 @@ 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 = parseJunitXml(junitContent);
+            const cases = await collectBackendTestHumanCaseCatalog(input.cwd);
             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"),
             });
             const htmlPath = await writeRunReport(meta.runDir, "backend-test.html", htmlContent);
-            const facts = renderBackendTestFacts({ parsed, 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 });
             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);
@@ -601,8 +605,190 @@ async function executePipelineCommands(input, meta, overrideCommands) {
     }
     return results;
 }
+async function executeFrontendVerificationBundle(input, meta) {
+    const started = Date.now();
+    const shell = input.task.shell;
+    const bundle = shell.frontendVerificationBundle;
+    const cwd = resolveShellCwd(input.cwd, shell.cwd);
+    const results = [];
+    let beforeStatus;
+    try {
+        beforeStatus = await readGitStatusPorcelain(input.cwd);
+    }
+    catch {
+        beforeStatus = undefined;
+    }
+    const groups = [
+        { name: "mock", commands: bundle.mockCommands },
+        { name: "static", commands: bundle.staticCommands },
+        { name: "behavior", commands: bundle.behaviorCommands },
+    ];
+    for (const group of groups) {
+        for (const command of group.commands) {
+            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`),
+                },
+            });
+            results.push(result);
+            if (!result.ok)
+                break;
+        }
+    }
+    if (beforeStatus !== undefined) {
+        const guard = await runShellWriteGuard({
+            rootCwd: input.cwd,
+            task: input.task,
+            beforeStatus,
+        });
+        if (!guard.ok) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `write guard failed: ${guard.violations.join(", ")}`,
+                failureCategory: "write-guard",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    await writeDagNodeTextArtifact(meta.runDir, input.task.id, "result.summary.md", buildShellResultSummaryMarkdown({
+        nodeId: input.task.id,
+        runId: meta.runId,
+        rootCwd: input.cwd,
+        results,
+    }));
+    const commandResults = results.map((result) => ({
+        ok: result.ok,
+        exitCode: result.exitCode,
+        failureCategory: result.failureCategory,
+        command: result.command,
+    }));
+    const firstFailure = results.find((result) => !result.ok);
+    let traceError;
+    try {
+        await runFrontendVerificationTraceGate({
+            runDir: meta.runDir,
+            workspaceRoot: input.cwd,
+            evidence: {
+                static: {
+                    nodeId: input.task.id,
+                    commandLabels: bundle.staticEvidence.commandLabels,
+                },
+                behavior: {
+                    nodeId: input.task.id,
+                    commandLabels: bundle.behaviorEvidence.commandLabels,
+                },
+            },
+        });
+    }
+    catch (error) {
+        traceError = error instanceof Error ? error : new Error(String(error));
+    }
+    if (bundle.mode === "repair") {
+        if (firstFailure || traceError) {
+            return {
+                ok: false,
+                stdout: summarizeCommandResults(results).stdout,
+                stderr: firstFailure?.stderr || traceError?.message || "frontend reverify failed",
+                failureCategory: firstFailure?.failureCategory ?? "invalid-output",
+                durationMs: Date.now() - started,
+                ...{ commandResults },
+            };
+        }
+        return {
+            ok: true,
+            stdout: "Frontend reverify bundle: pass",
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+            ...{ commandResults },
+        };
+    }
+    const failureFacts = [];
+    if (firstFailure) {
+        failureFacts.push({
+            nodeId: input.task.id,
+            record: {
+                status: "FINISHED",
+                failureCategory: firstFailure.failureCategory,
+                stdout: summarizeCommandResults(results).stdout,
+                stderr: firstFailure.stderr,
+                commandResults,
+            },
+        });
+    }
+    if (traceError) {
+        failureFacts.push({
+            nodeId: "frontend-verification-trace-shell",
+            record: {
+                status: "FINISHED",
+                failureCategory: "invalid-output",
+                stderr: traceError.message,
+            },
+        });
+    }
+    try {
+        const assessment = await runFrontendFailureAssessGate({
+            runDir: meta.runDir,
+            failureFacts,
+        });
+        await runFrontendRepairContractGate({ runDir: meta.runDir });
+        return {
+            ok: true,
+            stdout: formatFrontendFailureAssessStdout(assessment),
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+            ...{ commandResults },
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+            failureCategory: "invalid-output",
+            durationMs: Date.now() - started,
+            ...{ commandResults },
+        };
+    }
+}
 export async function executeDagShellNode(input, meta) {
     const shell = input.task.shell;
+    if (shell?.frontendPrewriteGate) {
+        const started = Date.now();
+        try {
+            const result = await runFrontendPrewriteGate({
+                runDir: meta.runDir,
+                config: shell.frontendPrewriteGate,
+                sourceBinding: meta.spec.sourceBinding,
+            });
+            return { ok: true, stdout: formatFrontendPrewriteGateStdout(result), stderr: "", 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 };
+        }
+    }
+    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 });
+            return { ok: true, stdout: formatFrontendReviewContextStdout(result), stderr: "", 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 };
+        }
+    }
     if (shell?.backendTestPipeline) {
         return executeBackendTestPipelineWithWriteGuard(input, meta);
     }

package/dist/governance/exec-plans.js

@@ -177,6 +177,10 @@ function localIndexReference(rawReference) {
         .replaceAll("\\", "/");
     if (!normalized.endsWith(".md") || normalized.includes("/"))
         return null;
+    // Naming-convention placeholders (e.g. `YYYY-MM-DD-<topic>.md`) and other
+    // unsafe stems are documentation, not index entries. Align with assertSafePlanId.
+    if (/[<>:"|?*]/.test(normalized))
+        return null;
     return normalized;
 }
 function extractIndexReferences(indexContent) {

package/dist/worker/cli.js

@@ -559,9 +559,9 @@ export function buildAgentWorkerProgram() {
         .command("serve")
         .requiredOption("--repo <repo-root>", "Target repo root")
         .option("--port <port>", "HTTP port", "8787")
-        .option("--host <host>", "Bind host (default 127.0.0.1; use 0.0.0.0 for LAN, no auth)", "127.0.0.1")
+        .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")
-        .description("Start read-only observe HTTP server")
+        .description("Start read-only observe HTTP server (compat entry; prefer console serve)")
         .action(async (options) => {
         const repoRoot = path.resolve(options.repo);
         const server = await createObserveServer({
@@ -570,6 +570,9 @@ export function buildAgentWorkerProgram() {
             port: Number.parseInt(options.port, 10),
             debug: options.debug === true,
         });
+        process.stderr.write("[OBSERVE_SERVE_DEPRECATED] agent-worker observe serve 作为独立看板入口将在兼容窗口后下线。\n" +
+            "请改用：agent-worker console serve --repo <repo> --port 8790\n" +
+            "统一 Operator Console 已包含原 Observe 的只读检视能力：http://127.0.0.1:8790/\n");
         process.stdout.write(`${server.url}\n`);
         await new Promise((resolve) => {
             const shutdown = () => resolve();
@@ -593,22 +596,18 @@ export function buildAgentWorkerProgram() {
         .command("serve")
         .requiredOption("--repo <repo-root>", "Target repo root")
         .option("--port <port>", "HTTP port", "8790")
-        .option("--host <host>", "Bind host (default 127.0.0.1; non-loopback is rejected)", "127.0.0.1")
+        .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 (static SPA + Operator API)")
+        .description("Start Loop Operator Console HTTP server (Operate + Inspect; static SPA + Operator API)")
         .action(async (options) => {
         const { createConsoleServer } = await import("./console/server.js");
-        const { isLoopbackHost } = await import("./console/loopback.js");
-        if (!isLoopbackHost(options.host)) {
-            process.stderr.write(`console serve: non-loopback host "${options.host}" is not allowed (fail closed)\n`);
-            process.exitCode = 1;
-            return;
-        }
         const repoRoot = path.resolve(options.repo);
         const server = await createConsoleServer({
             repoRoot,
             host: options.host,
             port: Number.parseInt(options.port, 10),
+            debug: options.debug === true,
             appDataRoot: options.appData
                 ? path.resolve(options.appData)
                 : undefined,
@@ -625,13 +624,15 @@ export function buildAgentWorkerProgram() {
         .command("doctor")
         .requiredOption("--repo <repo-root>", "Target repo root")
         .option("--json", "Emit JSON report on stdout")
-        .option("--observe-url <url>", "Optional Observe base URL to probe (non-blocking)", "http://127.0.0.1:8787")
-        .description("Report sibling loop-agent identity, repo preflight, and optional Observe health")
+        .option("--observe-url <url>", "Legacy external Observe base URL to probe (non-blocking)")
+        .option("--console-url <url>", "Unified Console base URL to probe")
+        .description("Report sibling identity, preflight, and unified Inspect readiness")
         .action(async (options) => {
         const { formatConsoleDoctorHuman, runConsoleDoctor } = await import("./console/doctor.js");
         const report = await runConsoleDoctor({
             repoRoot: path.resolve(options.repo),
             observeBaseUrl: options.observeUrl,
+            consoleBaseUrl: options.consoleUrl,
         });
         if (options.json) {
             process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);

package/dist/worker/console/doctor.js

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { mkdtemp } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -7,6 +8,8 @@ import { probePiReadiness, } from "./pi-readiness.js";
 import { DEFAULT_OBSERVE_BASE_URL, OBSERVE_START_COMMAND, probeAndClassifyObserve, } from "./observe-health-match.js";
 import { repoFingerprintV1 } from "./repo-fingerprint.js";
 import { resolveSiblingLoopAgentBin } from "./sibling-controller.js";
+import { defaultObserveStaticDir, ROUTES } from "../observe/routes.js";
+import { deriveObserveRouteCapabilities } from "../observe/health.js";
 async function probeObserve(url, localFingerprint, fetchImpl) {
     const classified = await probeAndClassifyObserve({
         baseUrl: url,
@@ -42,6 +45,48 @@ async function probeObserve(url, localFingerprint, fetchImpl) {
         message: classified.message,
     };
 }
+async function probeInspect(consoleBaseUrl, fetchImpl) {
+    const routeCapabilities = deriveObserveRouteCapabilities(ROUTES);
+    if (!consoleBaseUrl) {
+        const ready = existsSync(path.join(defaultObserveStaticDir(), "index.html"));
+        return {
+            status: ready ? "ready" : "degraded",
+            source: "static-assets",
+            routeCapabilities,
+            message: ready
+                ? "Inspect 静态资源可用；启动 agent-worker console serve 以提供统一入口"
+                : "Inspect 静态资源缺失；请运行构建或检查发布包",
+        };
+    }
+    const url = `${consoleBaseUrl.replace(/\/+$/, "")}/api/health`;
+    try {
+        const response = await fetchImpl(url, {
+            method: "GET",
+            signal: AbortSignal.timeout(1500),
+        });
+        const body = (await response.json());
+        const ready = response.ok &&
+            body.ok === true &&
+            body.schemaVersion === 1 &&
+            body.inspect?.ready === true;
+        return {
+            status: ready ? "ready" : "degraded",
+            source: "console-health",
+            url,
+            routeCapabilities: body.inspect?.routeCapabilities ?? routeCapabilities,
+            message: ready ? undefined : "Console health 未确认 Inspect 已就绪",
+        };
+    }
+    catch (error) {
+        return {
+            status: "degraded",
+            source: "console-health",
+            url,
+            routeCapabilities,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 /**
  * Run console doctor checks. Observe unavailability never fails the report.
  */
@@ -115,8 +160,14 @@ export async function runConsoleDoctor(options) {
             message: "cannot run preflight without sibling loop-agent bin",
         };
     }
-    const observeBase = options.observeBaseUrl ?? DEFAULT_OBSERVE_BASE_URL;
-    const observe = await probeObserve(observeBase, fingerprint, options.fetchImpl ?? fetch);
+    const inspect = await probeInspect(options.consoleBaseUrl, options.fetchImpl ?? fetch);
+    const observe = options.observeBaseUrl
+        ? await probeObserve(options.observeBaseUrl, fingerprint, options.fetchImpl ?? fetch)
+        : {
+            status: "unavailable",
+            url: `${DEFAULT_OBSERVE_BASE_URL}/api/health`,
+            message: "未探测兼容 Observe；统一 Inspect 不依赖 8787",
+        };
     const pi = await probePiReadiness({
         override: options.piReadinessProbe,
         siblingControllerOk: Boolean(controllerIdentity && "packageVersion" in controllerIdentity),
@@ -133,6 +184,7 @@ export async function runConsoleDoctor(options) {
         piReadiness: pi.state,
         pi,
         observe,
+        inspect,
         generatedAt: new Date().toISOString(),
     };
 }
@@ -148,6 +200,7 @@ export function formatConsoleDoctorHuman(report) {
         `pi.interviewSession: ${report.pi.probe.interviewSessionOk}`,
         `preflight: ${report.preflight.ok ? `ok (${report.preflight.summary})` : `fail ${report.preflight.code}: ${report.preflight.message}`}`,
         `observe: ${report.observe.status}${report.observe.status === "unavailable" || report.observe.status === "mismatch" ? ` (${report.observe.message})` : ""}`,
+        `inspect: ${report.inspect.status}${report.inspect.message ? ` (${report.inspect.message})` : ""}`,
     ];
     if (report.observe.status === "unavailable" ||
         report.observe.status === "mismatch") {

package/dist/worker/console/index.js

@@ -1,4 +1,5 @@
 export { createConsoleServer, defaultConsoleStaticDir } from "./server.js";
+export { buildOperatorSurfaceHealthV1 } from "./operator-surface-health.js";
 export { runConsoleDoctor, formatConsoleDoctorHuman } from "./doctor.js";
 export { isLoopbackHost } from "./loopback.js";
 export { repoFingerprintV1, normalizeWorktreeRealpath, } from "./repo-fingerprint.js";

package/dist/worker/console/loopback.js

@@ -1,6 +1,6 @@
 /**
- * Console-local loopback host check. Non-loopback binds fail closed
- * (unlike Observe, which only warns).
+ * Console-local loopback host check.
+ * Used for default bind safety messaging and mutation Host checks on loopback binds.
  */
 export function isLoopbackHost(host) {
     const normalized = host.trim().toLowerCase();

package/dist/worker/console/observe-link.js

@@ -1,7 +1,8 @@
 /**
- * Observe hash-route deep-link builder (Phase 1 skeleton).
- * Does not mount/proxy Observe or fetch its snapshot.
+ * Deprecated Observe deep-link compatibility helpers.
+ * New unified-surface callers should use buildInspectDeepLink.
  */
+import { buildInspectUrl, selectionFromObserveLinkTarget, } from "./operator-selection.js";
 function stripTrailingSlash(baseUrl) {
     return baseUrl.replace(/\/+$/, "");
 }
@@ -31,3 +32,7 @@ export function buildObserveDeepLink(baseUrl, target) {
         }
     }
 }
+/** Build a canonical same-origin Inspect URL for the unified Operator surface. */
+export function buildInspectDeepLink(origin, target) {
+    return buildInspectUrl(origin, selectionFromObserveLinkTarget(target));
+}

package/dist/worker/console/operator-actions.js

@@ -5,7 +5,7 @@ import { getTaskPaths } from "../../task/runtime.js";
 import { stageUtf8Text } from "./app-data.js";
 import { ALL_CONFIRMATION_CHALLENGES, hashDagBytes, } from "./dag-confirmation.js";
 import { capabilityForObserveTarget, DEFAULT_OBSERVE_BASE_URL, OBSERVE_START_COMMAND, probeAndClassifyObserve, } from "./observe-health-match.js";
-import { buildObserveDeepLink, } from "./observe-link.js";
+import { buildInspectDeepLink, buildObserveDeepLink, } from "./observe-link.js";
 import { resolveLatestDagRunIdForTask } from "./resolve-dag-run-for-task.js";
 import { repoFingerprintV1 } from "./repo-fingerprint.js";
 import { scheduleOperation, } from "./operation-runner.js";
@@ -285,7 +285,8 @@ export async function dispatchOperatorAction(ctx, req) {
             };
         }
         case "observeLink": {
-            const baseUrl = ctx.observeBaseUrl ?? DEFAULT_OBSERVE_BASE_URL;
+            const consoleOrigin = ctx.getConsoleOrigin?.();
+            const baseUrl = ctx.observeBaseUrl ?? consoleOrigin ?? DEFAULT_OBSERVE_BASE_URL;
             const dagRunId = str(p.dagRunId);
             const taskId = str(p.taskId);
             const featureId = str(p.featureId);
@@ -320,6 +321,33 @@ export async function dispatchOperatorAction(ctx, req) {
             const requiredCapability = target
                 ? capabilityForObserveTarget(target)
                 : undefined;
+            const usesUnifiedSurface = Boolean(consoleOrigin) &&
+                (!ctx.observeBaseUrl ||
+                    ctx.observeBaseUrl.replace(/\/+$/, "") ===
+                        consoleOrigin?.replace(/\/+$/, ""));
+            if (usesUnifiedSurface) {
+                const inspectPath = target
+                    ? buildInspectDeepLink(consoleOrigin, target).slice(consoleOrigin.length)
+                    : "/inspect/#/";
+                return {
+                    kind: "sync",
+                    status: 200,
+                    body: operatorSucceeded("observeLink", {
+                        url: target
+                            ? buildInspectDeepLink(consoleOrigin, target)
+                            : `${consoleOrigin.replace(/\/+$/, "")}/inspect/#/`,
+                        inspectPath,
+                        status: "same-origin",
+                        requiredCapability: requiredCapability ?? null,
+                        dagRunId: target?.kind === "dag"
+                            ? target.dagRunId
+                            : resolvedFromTask?.dagRunId,
+                        taskId: taskId ?? undefined,
+                        home: openHome || undefined,
+                        fallbackToTask: fallbackToTask || undefined,
+                    }),
+                };
+            }
             let localFingerprint;
             try {
                 localFingerprint = repoFingerprintV1(ctx.repoRoot);