@tea-agent/loop-agent 0.16.19 → 0.16.20

package/CHANGELOG.md

@@ -2,27 +2,44 @@
 
 ## [Unreleased]
 
+### 修复
+
+- Backend-test 节点 10 `backend-test-semantic-gate-shell` 不再用 Markdown `first-verdict-line` 读取 raw Pi 输出；改为同一 `semantic-initial` pipeline 按 task id 只读 `contracts/backend-test-semantic-review.json`，仅 `verdict=pass` 放行 pytest，`request-revision`/缺失/malformed 清晰 fail-closed；节点 09 仍只负责 materialize+trace，15 节点与单次 pytest 不变。
+- 公开 Case Manifest schema（`docs/templates/backend-test-case-manifest.schema.json`）对齐 materializer dual-scope coverage：`coverageSummary` 在 `additionalProperties:false` 下 required 并声明 `global`/`inScope`（`total`/`covered`/`gapped`/`ratio`）与 `crossDomainGapCount`；回归测试以无依赖轻量 contract 锁定 schema↔canonical 一致性；不改 materializer/15 节点。
+- Backend-test Case Manifest materializer 将模型顶层 `coverageSummary` 视为非权威：secret 扫描后剥离，再 strict parse 其余字段，并始终 `computeCaseManifestCoverageSummary` 写入 canonical summary；my-webapp 自定义/部分 summary 不再导致 invalid-output；prompt 禁止模型输出 coverageSummary；15 节点与单次 pytest 不变。
+- Backend-test 裸 object 路径现消费 scanner 的 `unclosedObject`：当文本含一个完整裸 JSON object，且其前或后仍有未闭合裸 object 时一律 fail-closed，不再因 `spans.length === 1` 错误接受完整对象；Semantic Review / Classification / contracts envelope 共用该行为。
+- Backend-test contracts composite pipeline （`validate-backend-test-contracts-shell`） 使用唯一确定性 envelope 提取：接受 pure JSON、唯一 fenced json、prose+唯一 fence、prose+唯一括号平衡裸 object；对无 JSON、多候选、未闭合、非 object、缺 `analysis`/`execution` fail-closed。提取后仍走 Analysis v2 / Execution v1 schema、source-binding 与 secret 门禁；不引入全局 Pi output rewrite，不将 `invalid-output` 加入自动 retry，不改 15 节点拓扑。
+- Backend-test Semantic Review（08→09）与 Classification（12→13）materializer 复用同一 `extractUniqueJsonObject` scanner：接受 pure / whole-fence / prose+唯一 fence / prose+唯一裸 object；多候选、未闭合、非 object 与 strict schema 错误继续 fail-closed；不改 Case Manifest、Pi SDK/retry 或 15 节点拓扑。
+
 ### 改进
 
 - 前端测试 DAG 收紧体验：execution preflight 仅硬校验绝对非生产 `baseUrl`；用例 map 缩短为优先用 `playwright-cli` 执行；复盘合并执行证据审查且不依赖 outcome=pass，失败也能出报告。
 - 前端测试用例生成现在会解析明确 `baseUrl`：优先读取任务源 `config.md` 中的前端 URL，缺失时默认 `http://localhost:5173`，并写入 RAG `context.md`；生成命令不得再保留 `<base-url>` 占位符。
 - 前端浏览器测试 DAG 的复盘报告现写入 `testcase/frontend/reports/**`，不再要求 `docs/test-reports/**` 权限；任务执行约束可以安全禁止整个 `docs/**`，同时仍保留可审计的测试资产。
 - `frontend-test` 结果链新增 run-owned `frontend-test-result-v1`、单次用例修订与终审门禁；只有所有浏览器用例和 AC 覆盖通过且结果合同明确为 real/pass 时，Worker 才会投影真实集成。
-
-- 后端测试 DAG 从 38 个收敛为 24 个真实顶层节点；使用 fail-closed `runIf` 和复合 Shell capability 减少调度，同时保留双合同、Manifest、语义评审、JUnit、Result、分类、修复安全、追踪和最终 outcome 证据。三条可选修订/修复分支仍各最多执行一次。
-- Backend Test Analysis、Case Manifest、Semantic Review 与 Classification 的严格 JSON 契约进一步对齐，生成和修订节点明确字段白名单、`sourceBinding` 与 evidence gap 约束，避免模型自定义字段导致确定性门禁失败。
+- 后端测试 DAG 从 24 个收敛为 15 个真实顶层节点；用例与语义 `request-revision` 由确定性 gate 直接失败，pytest 只执行一次，TestBug 保留分类并转为独立 follow-up，不再触发同 run repair 或 final rerun。唯一 initial Result 会确定性复制为 canonical `contracts/backend-test-result.json`，最终 outcome 只认该结构化事实。
+- Backend Test Analysis、Case Manifest、Semantic Review 与 Classification 的严格 JSON 契约进一步对齐，生成节点明确字段白名单、`sourceBinding` 与 evidence gap 约束，避免模型自定义字段导致确定性门禁失败。
+- 新增升级后 init surface notifier：普通安全仓库命令结束后，当目标项目存在有效 `.harness/init-surface.json` 且 `controllerVersion` 与当前包版本不同时自动检测。surface 缺失/损坏、源仓库、未初始化目录与版本一致时直接跳过；`checkInitUpdate().ok` 时仅在无活跃运行时静默刷新 state；非 TTY 只向 stderr 输出 `loop-agent init reconcile --repo-root ...` 提示且不写入目标；TTY 且无 human decisions、无活跃 DAG/Worker 时可经明确 `y/yes` 同意后应用 deterministic safe actions；只有 model merge 时直接输出有边界指引，不询问“应用 0 个动作”。notifier 遵循全局 `--repo-root`、不写 stdout、不改变原命令退出码，CI、禁用环境变量、help/version、`--json`/`--markdown`、`init`、`run-dag`、`dag`、`loop`、`delegate`、`pi-prompt`、`cursor-prompt` 均跳过。
+- 新增统一命令 `loop-agent init reconcile --repo-root <target>`：surface 缺失返回 `needs-baseline` 且零写入，存在 human decisions 返回 `needs-human-decision` 且零写入，活跃 DAG/Worker 或 Worker 状态无法确认时返回 `blocked-active-runtime` 且零写入；其余情况复用现有 `applyInitUpdate({ applySafe: true })` 并复查返回 `clean`/`needs-model-merge`/`needs-safe-update`，支持 `--json`/`--markdown`。
 
 ### 修复
 
+- 节点检查器「执行过程」中的事件时间戳现在同时显示本地日期与 24 小时制 `HH:mm:ss`（例如 `2026/7/16 08:09:10`），不再被裁掉时间部分；缺少时间戳时仍显示「未记录时间」，事件字段优先级（`timestamp` → `at` → `recordedAt`）保持不变。
 - `frontend-test` 的 case review 现在是 fail-closed browser gate：只有 `VERDICT: pass` 才能物化 manifest 并启动动态 browser map；生成的 case 固定使用默认 browser session，要求每个子场景的 fixture/UI reset 和 fresh snapshot，并由确定性节点校验每个 case 的 `execution.md`、`case-result.json`、`caseId`、`status`、`evidencePaths` 及 blocked `blockedReason`。
 - 前端实现计划/修订节点会注入当前包内权威 `frontend-implementation-contract-v1` Schema 与固定 source binding，避免模型猜测字段导致契约门禁失败。
 - 前端 Mock 策略节点的 canonical 输出会把首条 `MOCK_STRATEGY:` 协议行提升为第一行，避免解释性前言触发 `first-non-empty` 门禁误判。
 - 前端规范回退目录统一为本地 `openspec/`，DAG 能力发现、提示词、Skill 与验证证据检查不再查找大小写不一致的旧目录名。
 - 后端测试复合 Shell pipeline 现在与普通 Shell 节点共享 Git write guard；即使命令退出成功，只要越过 `read-only`、`allowedPaths` 或 `forbiddenPaths` 边界，节点仍会 fail-closed。
-- Observe 现使用实际的 repair safety 节点，并只在修复节点真正开始执行后计入一次 attempt；条件跳过不再误报已修复，安全门禁失败会显示为 `rejected`。
+- Observe 对新 backend-test run 不再伪造 repair attempt/status，只投影 single-run/canonical Result、分类与 coverage；历史 24 节点 run 的 eligibility、repair、final 和 effective evidence 仍可兼容读取。
 - Pi SDK 对缺少响应 ID 的累计 Token 生命周期事件改为取本次执行最大快照，避免同一响应的匿名 usage 被重复累加。
 - Pi SDK 执行长推理或大段结构化输出时不再把高频流式增量事件无界累积到内存；同一响应在多个生命周期事件中重复出现的 Token 用量只统计一次，避免 `Invalid string length` 和成本数据虚高。
-- 后端测试复合执行节点继续保持 clean environment、失败分类和 fail-closed outcome，并为 initial/final Result、repair eligibility、traceability 与 Observe 投影保留结构化运行证据。
+- 后端测试复合执行节点继续保持 clean environment、失败分类和 fail-closed outcome，并为唯一 JUnit/initial Result、canonical Result、traceability 与 Observe 投影保留结构化运行证据。
+
+## [0.16.20] - 2026-07-21
+
+### 修复
+
+- Shell write-guard 忽略 playwright-cli 默认会话落盘 `.playwright-cli/**`（console/page dump）。frontend-test 浏览器用例已把权威证据写到 `testcase/frontend/evidence/**` 时，不再因工具缓存误拦 exclusive writer。
 
 ## [0.16.19] - 2026-07-20
 

package/README.md

@@ -40,6 +40,14 @@ loop-agent inspect --repo-root .
 
 初始化会保留已有用户内容，并补充 `AGENTS.md`、`harness.json`、`ai_workspace/loop-agent/`、`.agents/skills/`、`.harness/` 和验证脚本等治理入口。
 
+控制器升级后，旧项目可能仍使用过期的 repo-local skills、模板、managed blocks 和治理说明。普通安全仓库命令结束时会自动检测目标项目是否需要对齐：非 TTY 只向 stderr 输出提示且不写入目标；TTY 且无 human decisions、无活跃 DAG/Worker 时，可经明确 `y/yes` 同意后应用 deterministic safe actions；也可手动运行统一入口：
+
+```bash
+loop-agent init reconcile --repo-root .
+```
+
+`init reconcile` 在 surface 缺失、存在 human decisions、存在活跃 DAG/Worker 或无法确认 Worker 状态时零写入，并返回 `needs-baseline`、`needs-human-decision` 或 `blocked-active-runtime`；其余情况复用 `init update --apply-safe` 的安全动作并复查返回 `clean`、`needs-model-merge` 或 `needs-safe-update`。
+
 完整说明见[初始化目标项目](website/docs/quick-start/init-target-project.md)。
 
 ### 运行第一个任务

package/dist/cli/command-definitions.js

@@ -22,6 +22,7 @@ import { runWorktreeRemove } from "../commands/worktree-remove.js";
 import { runDelegate } from "../commands/delegate.js";
 import { runHarvest } from "../commands/harvest.js";
 import { runInit } from "../commands/init.js";
+import { readInitRuntimeActivity } from "./update/runtime-activity.js";
 import { runRunDag } from "../commands/run-dag.js";
 import { runDagInitHybrid } from "../commands/dag-init-hybrid.js";
 import { runDagValidate } from "../commands/dag-validate.js";
@@ -75,6 +76,7 @@ const INIT_SUBCOMMANDS = [
     "doctor",
     "check-update",
     "update",
+    "reconcile",
 ];
 const EXAMPLES_SUBCOMMANDS = ["list", "show", "copy"];
 const EVAL_SUBCOMMANDS = [
@@ -195,10 +197,10 @@ export const COMMAND_DEFINITIONS = [
         adapter: "none",
         tier: "primary",
         intent: "Initialize a target repository with loop-agent harness capabilities.",
-        usage: "init [instructions|doctor|check-update|update] [--profile full|minimal] [--merge] [--json|--markdown] [--bootstrap-surface|--apply-safe]",
+        usage: "init [instructions|doctor|check-update|update|reconcile] [--profile full|minimal] [--merge] [--json|--markdown] [--bootstrap-surface|--apply-safe]",
         subcommands: [...INIT_SUBCOMMANDS],
         handler: async ({ repoRoot, subcommand, rest }) => {
-            await runInit(repoRoot, [subcommand, ...rest].filter(Boolean));
+            await runInit(repoRoot, [subcommand, ...rest].filter(Boolean), { readRuntimeActivity: readInitRuntimeActivity });
         },
     },
     {

package/dist/cli/program.js

@@ -29,6 +29,7 @@ import { runGoal } from "../commands/goal.js";
 import { runHandoffCheck } from "../commands/handoff-check.js";
 import { runHarvest } from "../commands/harvest.js";
 import { runInit } from "../commands/init.js";
+import { readInitRuntimeActivity } from "./update/runtime-activity.js";
 import { runInspect } from "../commands/inspect.js";
 import { runInstructions } from "../commands/instructions.js";
 import { runKnowledge } from "../commands/knowledge.js";
@@ -518,7 +519,7 @@ async function runPiPromptCommand(args) {
 async function runInitCommand(args, command, defaultRepoRoot) {
     const initArgs = commandArgsWithOptions(args, command);
     const quiet = initArgs.includes("--json") || initArgs.includes("--markdown");
-    await runInit(resolveRepoRootOnly(command, defaultRepoRoot, { quiet }), initArgs);
+    await runInit(resolveRepoRootOnly(command, defaultRepoRoot, { quiet }), initArgs, { readRuntimeActivity: readInitRuntimeActivity });
 }
 async function runExamplesCommand(args, command, defaultRepoRoot) {
     await runExamples(resolveRepoRootOnly(command, defaultRepoRoot), commandArgsWithOptions(args, command));

package/dist/cli/update/init-surface-notifier.js

@@ -0,0 +1,167 @@
+import { applyInitUpdate, checkInitUpdate, readRecordedSurfaceControllerVersion, } from "../../commands/init.js";
+import path from "node:path";
+import { isInitRuntimeActive, } from "../../shared/runtime-activity.js";
+import { shouldRunInitSurfaceCheck } from "./policy.js";
+import { readInitRuntimeActivity } from "./runtime-activity.js";
+/**
+ * Post-upgrade init surface notifier.
+ *
+ * Runs only after a normal successful CLI invocation when:
+ *  - the invocation is not a controller-sensitive / machine-output / `init`
+ *    command (see {@link shouldRunInitSurfaceCheck}), and
+ *  - the target repo records a valid `.harness/init-surface.json` whose
+ *    `controllerVersion` differs from the currently running controller.
+ *
+ * It never writes to stdout and never changes the host command's exit code.
+ * In non-TTY contexts it only emits a stderr pointer to
+ * `loop-agent init reconcile --repo-root ...` and writes nothing to the target.
+ * In TTY contexts with deterministic actions, no pending human decisions, and
+ * no active DAG/Worker runtime, it may ask for an explicit `y/yes` before
+ * applying safe actions. Human decisions and active runtimes block all writes.
+ */
+export async function runInitSurfaceNotifier(options) {
+    if (!shouldRunInitSurfaceCheck(options))
+        return;
+    // Purity contract: the notifier must never pollute machine stdout.
+    void options.writeStdout;
+    const writeStderr = options.writeStderr ?? ((chunk) => process.stderr.write(chunk));
+    try {
+        const recorded = await readRecordedSurfaceControllerVersion(options.repoRoot);
+        if (!recorded)
+            return; // missing / corrupt / uninitialized -> skip silently
+        if (recorded.controllerVersion === options.currentVersion)
+            return; // already aligned
+        const report = await checkInitUpdate({
+            repoRoot: options.repoRoot,
+            projectName: options.projectName,
+            governanceRoot: options.governanceRoot,
+        });
+        const readRuntime = options.readRuntimeActivity ?? readInitRuntimeActivity;
+        // Already aligned to a clean surface; silently refresh recorded state only
+        // when no DAG or Worker runtime can observe the state write.
+        if (report.ok) {
+            const activity = await readRuntime(options.repoRoot);
+            if (isInitRuntimeActive(activity)) {
+                writeStderr(buildActiveRuntimeNotice(options.repoRoot, activity));
+                return;
+            }
+            await applyInitUpdate({
+                repoRoot: options.repoRoot,
+                projectName: options.projectName,
+                governanceRoot: options.governanceRoot,
+                applySafe: true,
+            }).catch(() => undefined);
+            return;
+        }
+        const hasHumanDecisions = report.humanDecisions.length > 0;
+        if (hasHumanDecisions) {
+            writeStderr(buildHumanDecisionNotice(options.repoRoot, report.humanDecisions.length));
+            return;
+        }
+        if (report.deterministicActions.length === 0) {
+            writeStderr(buildRemainingNotice(report, options.repoRoot));
+            return;
+        }
+        if (!options.stdoutIsTTY || !options.stdinIsTTY || !options.stderrIsTTY) {
+            writeStderr(buildReconcileNotice(options.repoRoot));
+            return;
+        }
+        const activity = await readRuntime(options.repoRoot);
+        if (isInitRuntimeActive(activity)) {
+            writeStderr(buildActiveRuntimeNotice(options.repoRoot, activity));
+            return;
+        }
+        const prompt = `loop-agent 控制器版本已变化（${recorded.controllerVersion} → ${options.currentVersion}），` +
+            `目标项目 init surface 有 ${report.deterministicActions.length} 个待处理安全动作。\n` +
+            `现在应用 deterministic safe actions？[y/N] `;
+        const answer = await ask(options, prompt);
+        if (!isYes(answer)) {
+            writeStderr(buildReconcileNotice(options.repoRoot));
+            return;
+        }
+        const update = await applyInitUpdate({
+            repoRoot: options.repoRoot,
+            projectName: options.projectName,
+            governanceRoot: options.governanceRoot,
+            applySafe: true,
+        });
+        writeStderr(`loop-agent init surface safe actions applied to ${options.repoRoot}.\n` +
+            buildRemainingNotice(update.report, options.repoRoot));
+    }
+    catch (error) {
+        writeStderr(`loop-agent init surface check skipped: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+function buildReconcileNotice(repoRoot) {
+    return (`loop-agent init surface needs reconciliation at ${repoRoot}.\n` +
+        `Run: loop-agent init reconcile --repo-root ${repoRoot}\n`);
+}
+function buildHumanDecisionNotice(repoRoot, count) {
+    return (`loop-agent init surface has ${count} pending human decision(s) at ${repoRoot}.\n` +
+        `Run: loop-agent init reconcile --repo-root ${repoRoot}\n`);
+}
+function buildRemainingNotice(report, repoRoot) {
+    const lines = [];
+    if (report.modelMergeTasks.length > 0) {
+        lines.push(`Remaining model merge tasks: ${report.modelMergeTasks.length}. Run: loop-agent init check-update --repo-root ${repoRoot} --markdown`);
+    }
+    if (report.deterministicActions.length > 0) {
+        lines.push(`Remaining deterministic actions: ${report.deterministicActions.length}. Run: loop-agent init reconcile --repo-root ${repoRoot}`);
+    }
+    if (lines.length === 0)
+        lines.push("init surface is now clean.");
+    return lines.join("\n") + "\n";
+}
+function buildActiveRuntimeNotice(repoRoot, activity) {
+    const details = [
+        activity.activeDagRunIds.length > 0
+            ? `active DAG runs: ${activity.activeDagRunIds.join(", ")}`
+            : undefined,
+        activity.activeWorkerTasks > 0
+            ? `active Worker tasks: ${activity.activeWorkerTasks}`
+            : undefined,
+        activity.activeWorkerBatches > 0
+            ? `active Worker batches: ${activity.activeWorkerBatches}`
+            : undefined,
+        activity.workerProjectionError
+            ? `Worker activity unavailable: ${activity.workerProjectionError}`
+            : undefined,
+    ].filter((value) => Boolean(value));
+    return (`loop-agent init reconcile blocked-active-runtime at ${repoRoot}.\n` +
+        `${details.join("; ")}\n` +
+        "Wait for the active runtime to finish, then run: " +
+        `loop-agent init reconcile --repo-root ${repoRoot}\n`);
+}
+export function resolveInitSurfaceRepoRoot(argv, defaultRepoRoot) {
+    let selected = defaultRepoRoot;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--repo-root") {
+            const value = argv[index + 1];
+            if (value && !value.startsWith("-"))
+                selected = value;
+            index += 1;
+        }
+        else if (arg.startsWith("--repo-root=")) {
+            selected = arg.slice("--repo-root=".length) || selected;
+        }
+    }
+    return path.resolve(defaultRepoRoot, selected);
+}
+async function ask(options, prompt) {
+    if (options.readLine) {
+        options.writeStderr?.(prompt);
+        return options.readLine(prompt);
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await rl.question(prompt);
+    }
+    finally {
+        rl.close();
+    }
+}
+function isYes(answer) {
+    return /^(y|yes)$/i.test(answer.trim());
+}

package/dist/cli/update/policy.js

@@ -8,6 +8,7 @@ const CONTROLLER_SENSITIVE_COMMANDS = new Set([
     "cursor-prompt",
 ]);
 const MACHINE_OUTPUT_FLAGS = new Set(["--json", "--markdown"]);
+const GLOBAL_VALUE_FLAGS = new Set(["--repo-root", "--adapter", "--worktree"]);
 export function isStrictReleaseVersion(version) {
     if (!version)
         return false;
@@ -30,6 +31,35 @@ export function shouldCheckForUpdates(input) {
         return false;
     return true;
 }
+/**
+ * Eligibility predicate for the post-upgrade init surface notifier.
+ *
+ * Mirrors {@link shouldCheckForUpdates}'s skip conditions (CI, disable env,
+ * help/version, machine-output flags, controller-sensitive commands) and
+ * additionally skips the `init` command family itself so the notifier never
+ * re-enters the explicit init surface write path.
+ *
+ * Unlike {@link shouldCheckForUpdates}, this predicate does NOT require a TTY:
+ * non-interactive invocations are still eligible because the notifier emits a
+ * read-only stderr pointer (zero target writes) in non-TTY contexts. The TTY
+ * distinction is handled inside the notifier.
+ */
+export function shouldRunInitSurfaceCheck(input) {
+    if (input.env.CI || input.env.LOOP_AGENT_DISABLE_UPDATE_CHECK === "1")
+        return false;
+    const args = input.argv;
+    if (args.some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-V")) {
+        return false;
+    }
+    if (args.some((arg) => MACHINE_OUTPUT_FLAGS.has(arg)))
+        return false;
+    const command = firstCommand(args);
+    if (command === "init")
+        return false;
+    if (command && CONTROLLER_SENSITIVE_COMMANDS.has(command))
+        return false;
+    return true;
+}
 export function evaluateLatestVersion(input) {
     const now = input.now ?? new Date();
     if (input.retryAfter && Date.parse(input.retryAfter) > now.getTime()) {
@@ -50,7 +80,12 @@ export function evaluateLatestVersion(input) {
     return { shouldPrompt: true, targetVersion: input.latestVersion };
 }
 function firstCommand(argv) {
-    for (const arg of argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (GLOBAL_VALUE_FLAGS.has(arg)) {
+            index += 1;
+            continue;
+        }
         if (!arg.startsWith("-"))
             return arg;
     }

package/dist/cli/update/runtime-activity.js

@@ -0,0 +1,29 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { buildGlobalSnapshot } from "../../worker/observability/read-model.js";
+/**
+ * Read-only runtime guard for init-surface writes.
+ *
+ * DAG activeness is anchored to real directories in the canonical active
+ * lifecycle root. Worker activeness reuses the Observe read model so Task Pool
+ * status precedence and composite identity stay owned by the Worker adapter.
+ * Projection failures block writes because liveness cannot be proven safely.
+ */
+export async function readInitRuntimeActivity(repoRoot) {
+    const resolvedRoot = path.resolve(repoRoot);
+    const activeDagRoot = path.join(resolvedRoot, ".harness", "dag-runs", "active");
+    const entries = await readdir(activeDagRoot, { withFileTypes: true }).catch(() => []);
+    const activeDagRunIds = entries
+        .filter((entry) => entry.isDirectory() && entry.name !== ".gitkeep")
+        .map((entry) => entry.name)
+        .sort();
+    const snapshot = await buildGlobalSnapshot({ repoRoot: resolvedRoot });
+    return {
+        activeDagRunIds,
+        activeWorkerBatches: snapshot.health.worker.activeBatches,
+        activeWorkerTasks: snapshot.health.worker.activeTasks,
+        ...(snapshot.projectionError
+            ? { workerProjectionError: snapshot.projectionError.message }
+            : {}),
+    };
+}

package/dist/cli.js

@@ -6,9 +6,12 @@ import { fileURLToPath } from "node:url";
 import { buildLoopAgentProgram } from "./cli/program.js";
 import { createNpmUpdateClient } from "./cli/update/npm-client.js";
 import { runSelfUpdateNotifier } from "./cli/update/notifier.js";
+import { resolveInitSurfaceRepoRoot, runInitSurfaceNotifier, } from "./cli/update/init-surface-notifier.js";
 async function main() {
+    const defaultRepoRoot = process.cwd();
+    const argv = process.argv.slice(2);
     const program = buildLoopAgentProgram({
-        defaultRepoRoot: process.cwd(),
+        defaultRepoRoot,
     });
     await program.parseAsync(process.argv);
     if (process.exitCode && process.exitCode !== 0)
@@ -16,7 +19,7 @@ async function main() {
     const packageRoot = resolvePackageRoot();
     const currentVersion = readPackageVersion(packageRoot);
     await runSelfUpdateNotifier({
-        argv: process.argv.slice(2),
+        argv,
         currentVersion,
         env: process.env,
         homeDir: os.homedir(),
@@ -29,6 +32,15 @@ async function main() {
             env: process.env,
         }),
     });
+    await runInitSurfaceNotifier({
+        argv,
+        currentVersion,
+        env: process.env,
+        repoRoot: resolveInitSurfaceRepoRoot(argv, defaultRepoRoot),
+        stdinIsTTY: process.stdin.isTTY === true,
+        stdoutIsTTY: process.stdout.isTTY === true,
+        stderrIsTTY: process.stderr.isTTY === true,
+    });
 }
 main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));

package/dist/commands/init.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { fileURLToPath } from "node:url";
 import { copyDir } from "../shared/copy-dir.js";
+import { isInitRuntimeActive, } from "../shared/runtime-activity.js";
 import { loadHarnessManifest } from "../governance/harness.js";
 const MANAGED_BLOCK_START = "<!-- LOOP_AGENT_INIT_START -->";
 const MANAGED_BLOCK_END = "<!-- LOOP_AGENT_INIT_END -->";
@@ -687,6 +688,7 @@ function buildManagedAgentsBlock(input) {
         "|---|---|---|",
         "| loop-agent 初始化 / loop agent 初始化 / loop agent初始化 / 初始化 loop-agent | 初始化 | 完成确定性初始化闭环 |",
         "| 初始化更新校验 / 检查初始化更新 / loop-agent 初始化更新校验 / loop agent初始化更新校验 | 更新校验 | 只读报告，不写入 |",
+        "| 初始化对齐 / 升级后对齐 / reconcile 初始化 / loop-agent 初始化对齐 | 升级对齐 | 自动应用确定性安全动作；活跃运行或人工决策时零写入 |",
         "| 初始化安全更新 / 应用初始化更新 / loop-agent 初始化安全更新 / loop agent初始化安全更新 | 安全更新 | check-update 后只执行确定性安全动作 |",
         "",
         "**更新校验（只读）**：用户说“初始化更新校验”“检查初始化更新”时，只读执行下面命令，汇报 deterministic actions、model merge、human decisions 和 next steps。**这一步不得自动执行 `apply-safe` 或模型合并。**",
@@ -695,6 +697,8 @@ function buildManagedAgentsBlock(input) {
         "loop-agent init check-update --repo-root . --markdown",
         "```",
         "",
+        "**升级对齐（写入型统一入口）**：用户说“初始化对齐”“升级后对齐”时，执行 `loop-agent init reconcile --repo-root .`。该入口不自动 bootstrap surface、不自动模型合并；存在活跃 DAG/Worker、human decisions 或无法确认 Worker 状态时必须零写入并报告状态。",
+        "",
         "**安全更新（写入型）**：用户明确说“初始化安全更新”“应用初始化更新”时，先 check-update，再执行确定性安全动作；surface 缺失时先 bootstrap，存在 human decisions 时停下等用户决策。model merge 任务必须带 allowed/forbidden paths，且不得自动决策。安全更新完成后必须复查 `loop-agent init doctor --repo-root .`、`loop-agent inspect --repo-root .`、`loop-agent docs audit --repo-root .` 与目标项目治理检查（如 `bash scripts/check-repo.sh`）。",
         "",
         "```bash",
@@ -1277,6 +1281,26 @@ async function readExistingSurfaceState(repoRoot) {
         return undefined;
     return parsed;
 }
+/**
+ * Lightweight read-only preflight for the post-upgrade init surface notifier.
+ *
+ * Returns the recorded controller version and state kind only when a valid
+ * `.harness/init-surface.json` exists. Missing or corrupt state, the source
+ * repo, and uninitialized directories all resolve to `undefined`, so the
+ * notifier can cheaply skip without running a full surface diff.
+ */
+export async function readRecordedSurfaceControllerVersion(repoRoot) {
+    let state;
+    try {
+        state = await readExistingSurfaceState(repoRoot);
+    }
+    catch {
+        return undefined;
+    }
+    if (!state || typeof state.controllerVersion !== "string")
+        return undefined;
+    return { controllerVersion: state.controllerVersion, stateKind: state.stateKind };
+}
 async function buildCurrentSurfaceState(input) {
     const assetRoot = await findPackageRoot();
     const controllerVersion = await readPackageVersion(assetRoot);
@@ -2754,6 +2778,40 @@ export async function runInitDoctor(input) {
         checks,
     };
 }
+export async function runInitReconcile(input) {
+    const repoRoot = path.resolve(input.repoRoot);
+    const preReport = await checkInitUpdate({
+        repoRoot,
+        projectName: input.projectName,
+        governanceRoot: input.governanceRoot,
+    });
+    if (preReport.surfaceState === "missing") {
+        return { status: "needs-baseline", report: preReport };
+    }
+    if (preReport.humanDecisions.length > 0) {
+        return { status: "needs-human-decision", report: preReport };
+    }
+    const runtimeActivity = await input.readRuntimeActivity(repoRoot);
+    if (isInitRuntimeActive(runtimeActivity)) {
+        return {
+            status: "blocked-active-runtime",
+            report: preReport,
+            runtimeActivity,
+        };
+    }
+    const update = await applyInitUpdate({
+        repoRoot,
+        projectName: input.projectName,
+        governanceRoot: input.governanceRoot,
+        applySafe: true,
+    });
+    const status = update.report.ok
+        ? "clean"
+        : update.report.modelMergeTasks.length > 0
+            ? "needs-model-merge"
+            : "needs-safe-update";
+    return { status, report: update.report, applied: update.applied, skipped: update.skipped };
+}
 function parseInitArgs(repoRoot, args) {
     let subcommand;
     let projectName;
@@ -2768,7 +2826,7 @@ function parseInitArgs(repoRoot, args) {
     let applySafe = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
-        if ((arg === "instructions" || arg === "doctor" || arg === "check-update" || arg === "update") && !subcommand) {
+        if ((arg === "instructions" || arg === "doctor" || arg === "check-update" || arg === "update" || arg === "reconcile") && !subcommand) {
             subcommand = arg;
             continue;
         }
@@ -2826,7 +2884,7 @@ function parseInitArgs(repoRoot, args) {
         applySafe,
     };
 }
-export async function runInit(repoRoot, rawArgs) {
+export async function runInit(repoRoot, rawArgs, dependencies) {
     const parsed = parseInitArgs(repoRoot, rawArgs);
     if (parsed.subcommand === "instructions") {
         console.log(buildInitInstructions(parsed));
@@ -2857,6 +2915,14 @@ export async function runInit(repoRoot, rawArgs) {
         console.log(parsed.json ? JSON.stringify(result, null, 2) : formatInitUpdateResult(result));
         return;
     }
+    if (parsed.subcommand === "reconcile") {
+        const result = await runInitReconcile({
+            ...parsed,
+            readRuntimeActivity: dependencies.readRuntimeActivity,
+        });
+        console.log(parsed.json ? JSON.stringify(result, null, 2) : formatReconcileResult(result));
+        return;
+    }
     const result = await initializeLoopAgentProject(parsed);
     console.log(parsed.json ? JSON.stringify(result, null, 2) : formatInitResult(result));
 }
@@ -2871,6 +2937,23 @@ function formatInitUpdateResult(result) {
         ...result.report.recommendedNext.map((item) => `- ${item}`),
     ].join("\n");
 }
+function formatReconcileResult(result) {
+    const lines = [
+        `loop-agent init reconcile: ${result.status}`,
+        `surfaceState: ${result.report.surfaceState}`,
+    ];
+    if (result.applied && result.skipped) {
+        lines.push(`applied: ${result.applied.length}`, `skipped: ${result.skipped.length}`);
+    }
+    if (result.runtimeActivity) {
+        lines.push(`activeDagRuns: ${result.runtimeActivity.activeDagRunIds.length}`, `activeWorkerTasks: ${result.runtimeActivity.activeWorkerTasks}`, `activeWorkerBatches: ${result.runtimeActivity.activeWorkerBatches}`);
+        if (result.runtimeActivity.workerProjectionError) {
+            lines.push(`workerProjectionError: ${result.runtimeActivity.workerProjectionError}`);
+        }
+    }
+    lines.push(`deterministicActions: ${result.report.deterministicActions.length}`, `modelMergeTasks: ${result.report.modelMergeTasks.length}`, `humanDecisions: ${result.report.humanDecisions.length}`, "recommendedNext:", ...result.report.recommendedNext.map((item) => `- ${item}`));
+    return lines.join("\n");
+}
 function formatInitResult(result) {
     return [
         `Initialized loop-agent harness at ${result.repoRoot}`,