@tea-agent/loop-agent 0.28.1 → 0.28.2

package/dist/worker/scheduler/workspace-adapter.js

@@ -0,0 +1,91 @@
+import { access, symlink, unlink } from "node:fs/promises";
+import path from "node:path";
+import { ensureOwnedWorktree, verifyOwnedWorktree, } from "../../task/worktree.js";
+import { getSchedulerRoot } from "./paths.js";
+export function defaultNightWorktreeRelativePath(scheduleId) {
+    return path.posix.join(".worktrees", "night", scheduleId);
+}
+export function defaultNightBranch(scheduleId) {
+    return `night/${scheduleId}`;
+}
+/**
+ * Create or reuse a schedule-owned worktree under control repo.
+ * Does not copy secrets/.env. Optional node_modules symlink only.
+ */
+export async function prepareNightWorkspace(spec) {
+    const relativeWorktreePath = spec.worktreePath ?? defaultNightWorktreeRelativePath(spec.scheduleId);
+    const branch = spec.branch ?? defaultNightBranch(spec.scheduleId);
+    const expectedBranch = defaultNightBranch(spec.scheduleId);
+    if (branch !== expectedBranch) {
+        throw new Error(`night worktree branch must be ${expectedBranch}, got ${branch}`);
+    }
+    const absolutePath = path.isAbsolute(relativeWorktreePath)
+        ? relativeWorktreePath
+        : path.resolve(spec.controlRepoRoot, relativeWorktreePath);
+    // Ensure parent of worktree root exists (and keep scheduler root alive).
+    void getSchedulerRoot(spec.controlRepoRoot);
+    const ensured = await ensureOwnedWorktree(spec.controlRepoRoot, {
+        worktreePath: absolutePath,
+        branch,
+        baseBranch: spec.baseBranch,
+        baseCommit: spec.baseCommit,
+        scheduleId: spec.scheduleId,
+        ...(spec.ownershipToken ? { ownershipToken: spec.ownershipToken } : {}),
+        ...(spec.now ? { now: spec.now } : {}),
+    });
+    let nodeModulesLinked = false;
+    if (spec.hydrateNodeModules !== false) {
+        nodeModulesLinked = await linkNodeModulesIfPresent(spec.controlRepoRoot, ensured.path);
+    }
+    const relative = path
+        .relative(spec.controlRepoRoot, ensured.path)
+        .split(path.sep)
+        .join("/") || relativeWorktreePath;
+    return {
+        ...ensured,
+        relativeWorktreePath: relative.startsWith("..") ? ensured.path : relative,
+        relativeBranch: branch,
+        nodeModulesLinked,
+    };
+}
+export async function revalidateNightWorkspace(input) {
+    const result = await verifyOwnedWorktree({
+        repoRoot: input.controlRepoRoot,
+        worktreePath: input.worktreePath,
+        scheduleId: input.scheduleId,
+        branch: input.branch,
+        baseCommit: input.baseCommit,
+        ownershipToken: input.ownershipToken,
+    });
+    return { head: result.head };
+}
+async function linkNodeModulesIfPresent(controlRepoRoot, worktreePath) {
+    const host = path.join(controlRepoRoot, "node_modules");
+    const target = path.join(worktreePath, "node_modules");
+    try {
+        await access(host);
+    }
+    catch {
+        return false;
+    }
+    try {
+        await access(target);
+        return true;
+    }
+    catch {
+        // continue to link
+    }
+    try {
+        await symlink(host, target, "junction");
+        return true;
+    }
+    catch {
+        try {
+            await unlink(target);
+        }
+        catch {
+            // ignore
+        }
+        return false;
+    }
+}

package/docs/architecture/runtime-boundaries.md

@@ -12,6 +12,9 @@ Skill layer
 CLI layer (src/cli/)
   └─ argv 解析、adapter 解析、调用 application / command handler、格式化输出
 
+Init-upgrade command layer (src/commands/init-upgrade.ts)
+  └─ controller-owned init-upgrade state machine、frozen identity、target `.harness/init-upgrades/` facts、safe action receipts and bounded merge contracts
+
 Application layer (src/application/，逐步引入)
   └─ 一次用户意图的 typed use-case interface，供 CLI、Loop、Workflow 复用
 
@@ -54,6 +57,12 @@ Governance (scripts/check-*.sh, src/governance/)
 - **允许依赖**：`src/commands/**`（handler wiring）、`src/adapters/**`、`src/shared/**`、逐步引入的 `src/application/**`。
 - **禁止**：在 router 中维护与 catalog 独立的 command 事实源（Phase 1 整改目标）。
 
+### Init-upgrade command boundary
+
+- **位置**：`src/commands/init-upgrade.ts`，复用 `src/commands/init.ts` 的 ownership scan / safe action 与 `src/commands/client-recovery.ts` 的 generated recovery builders。
+- **职责**：拥有可恢复升级状态机与目标项目 run facts；version gate、identity drift、active runtime/lock、workspace re-scan、single-file merge boundary、home zero-write fingerprint 和 completion invariant 都由 controller 决定。
+- **禁止**：OpenCode/Pi plugin、主会话 skill 或 notifier 拥有升级状态机；命令不得修改业务源码、用户 home 或以宽泛路径授权模型。主会话仅可按 controller 返回的具体 `allowedPaths` 合并 init surface，随后必须 `--continue`。
+
 ### Application layer
 
 - **位置**：`src/application/**`（按计划逐步引入）

package/docs/init-surface.manifest.json

@@ -56,6 +56,7 @@
     "skills/agent-worker/references/agent-worker-operator.md",
     "skills/loop-agent/SKILL.md",
     "skills/loop-agent/references/command-reference.md",
+    "skills/loop-agent/references/hybrid-dag.md",
     "skills/loop-agent/references/source-and-plan-practice.md",
     "skills/loop-agent/references/docs-converge.md",
     "skills/ai-engineering-context/SKILL.md",
@@ -135,6 +136,7 @@
     ".agents/skills/agent-worker/references/agent-worker-operator.md",
     ".agents/skills/loop-agent/SKILL.md",
     ".agents/skills/loop-agent/references/command-reference.md",
+    ".agents/skills/loop-agent/references/hybrid-dag.md",
     ".agents/skills/loop-agent/references/source-and-plan-practice.md",
     ".agents/skills/loop-agent/references/docs-converge.md",
     ".agents/skills/ai-engineering-context/SKILL.md",
@@ -168,7 +170,8 @@
     "docs/templates/backend-test-case-manifest.schema.json",
     ".opencode/plugins/loop-agent-transient-retry.js",
     ".opencode/plugins/loop-agent-context-overflow-compact.js",
-    ".pi/extensions/loop-agent-context-overflow.js"
+    ".pi/extensions/loop-agent-context-overflow.js",
+    ".pi/settings.json"
   ],
   "initSurface": {
     "README.md": "managed-block",
@@ -218,6 +221,7 @@
     ".agents/skills/agent-worker/references/agent-worker-operator.md": "copied",
     ".agents/skills/loop-agent/SKILL.md": "copied",
     ".agents/skills/loop-agent/references/command-reference.md": "copied",
+    ".agents/skills/loop-agent/references/hybrid-dag.md": "copied",
     ".agents/skills/loop-agent/references/source-and-plan-practice.md": "copied",
     ".agents/skills/loop-agent/references/docs-converge.md": "copied",
     ".agents/skills/ai-engineering-context/SKILL.md": "copied",
@@ -251,7 +255,8 @@
     "docs/templates/backend-test-case-manifest.schema.json": "copied",
     ".opencode/plugins/loop-agent-transient-retry.js": "generated",
     ".opencode/plugins/loop-agent-context-overflow-compact.js": "generated",
-    ".pi/extensions/loop-agent-context-overflow.js": "generated"
+    ".pi/extensions/loop-agent-context-overflow.js": "generated",
+    ".pi/settings.json": "generated"
   },
   "packageExcluded": [
     "docs/progress/20*.md",
@@ -273,6 +278,7 @@
     "package.json",
     "src/commands/init.ts",
     "src/commands/client-recovery.ts",
+    "src/commands/init-upgrade.ts",
     "src/cli.ts",
     "src/cli/update/init-surface-notifier.ts",
     "src/cli/update/policy.ts",
@@ -297,6 +303,7 @@
         "patterns": [
           "src/commands/init.ts",
           "src/commands/client-recovery.ts",
+          "src/commands/init-upgrade.ts",
           "src/cli.ts",
           "src/cli/update/init-surface-notifier.ts",
           "src/cli/update/policy.ts",

package/docs/templates/harness.schema.json

@@ -111,6 +111,113 @@
         }
       }
     },
+    "workerPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "agent-worker 侧声明式策略（含 Night Scheduler）。运行时以 Zod harnessManifestSchema 为准。",
+      "properties": {
+        "nightScheduler": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "本地夜间 once 调度默认策略；每个 schedule 会冻结 effective snapshot。",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "是否启用 Night Scheduler 能力面。",
+              "default": false
+            },
+            "timezone": {
+              "type": "string",
+              "minLength": 1,
+              "description": "展示与 allowedHours 解释使用的 IANA 时区。",
+              "default": "Asia/Shanghai"
+            },
+            "allowedHours": {
+              "type": "array",
+              "description": "允许派发的本地时间窗，格式 HH:MM-HH:MM，可跨午夜。",
+              "items": {
+                "type": "string",
+                "pattern": "^\\d{2}:\\d{2}-\\d{2}:\\d{2}$"
+              },
+              "default": ["00:00-08:00"]
+            },
+            "maxConcurrency": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "全局同时 running 的 schedule 上限（按有效 execution lease 计数）。",
+              "default": 1
+            },
+            "maxAutoAttempts": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "独立 Worker execution attempt 上限；MVP 为 1。",
+              "default": 1
+            },
+            "misfirePolicy": {
+              "enum": ["run-immediately", "wait-next-window", "human-required"],
+              "description": "机器休眠或 tick 延迟后的 misfire 策略。",
+              "default": "wait-next-window"
+            },
+            "keepFailedWorktree": {
+              "type": "boolean",
+              "description": "失败后是否默认保留 worktree 供人工 inspect。",
+              "default": true
+            },
+            "mergePolicy": {
+              "enum": ["manual-on-success", "auto-on-success"],
+              "description": "成功后的 merge 策略；MVP 仅 manual-on-success。",
+              "default": "manual-on-success"
+            },
+            "autoFollowUp": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "ADR 0010：失败后是否自动 draft Follow-up（永不 auto-approve）。默认 off。",
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "为 true 时，terminal failed night execution 可调用 draftFollowUpDecision。",
+                  "default": false
+                },
+                "mode": {
+                  "enum": ["draft-only"],
+                  "description": "MVP 仅 draft-only；自动 Ready/approve 需另 ADR。",
+                  "default": "draft-only"
+                }
+              }
+            },
+            "traceability": {
+              "type": "object",
+              "additionalProperties": false,
+              "description": "可 push commit 的工作项可追溯策略（任务卡片）。",
+              "properties": {
+                "required": {
+                  "type": "boolean",
+                  "description": "创建 schedule 时是否强制任务卡片。",
+                  "default": false
+                },
+                "label": {
+                  "type": "string",
+                  "minLength": 1,
+                  "default": "Task Card"
+                },
+                "pattern": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "workItemRef 正则；默认通用公司卡片格式。",
+                  "default": "^[A-Z][A-Z0-9]+-[A-Z0-9]+#[0-9]+$"
+                },
+                "commitMessageTemplate": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "必须包含 {workItemRef} 占位符。",
+                  "default": "{summary}\n\n{workItemRef}"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "entrypoints": {
       "type": "object",
       "description": "具名的仓库相对文件路径，用作人类和 agent 的入口。",

package/docs/templates/init-managed-agents.md

@@ -42,24 +42,34 @@
 | 用户表达 | 入口 | 执行动作 |
 | --- | --- | --- |
 | loop-agent 初始化 / loop agent 初始化 / loop agent初始化 / 初始化 loop-agent | 初始化 | 完成确定性初始化闭环 |
-| 初始化更新校验 / 检查初始化更新 / loop-agent 初始化更新校验 / loop agent初始化更新校验 | 更新校验 | 只读报告，不写入 |
-| 初始化对齐 / 升级后对齐 / reconcile 初始化 / loop-agent 初始化对齐 | 升级对齐 | 自动应用确定性安全动作；surface 缺失、人工决策、活跃 DAG/Worker 或 Worker 状态无法确认时零写入 |
-| 初始化安全更新 / 应用初始化更新 / loop-agent 初始化安全更新 / loop agent初始化安全更新 | 安全更新 | 先 check-update，再只执行确定性安全动作 |
+| loop-agent初始化更新 / loop-agent 初始化更新 / 更新 loop-agent 初始化内容 / 升级 loop-agent 初始化 | 初始化升级闭环 | 直接运行 `init upgrade`；自动安全更新、返回单文件语义合并任务并 `--continue` 至稳定终态，禁止停在只读检查或 `needs-model-merge` |
+| 初始化更新校验 / 检查初始化更新 / loop-agent 初始化更新校验 / loop agent初始化更新校验 / 只检查，不要修改 | 更新校验 | 严格只读报告，不创建 upgrade run、不写入 |
+| 初始化对齐 / 升级后对齐 / reconcile 初始化 / loop-agent 初始化对齐 | 初始化升级闭环 | 直接运行 `init upgrade`，而非拼接低层 safe-update 命令 |
+| 初始化安全更新 / 应用初始化更新 / loop-agent 初始化安全更新 / loop agent初始化安全更新 | 初始化升级闭环 | 直接运行 `init upgrade`，由 controller 处理安全更新与验证 |
 | loop-agent 帮我完成 / 帮我实现 / 帮我修复 / 帮我开发 <需求>；使用 loop-agent 完成 <X>；按 loop-agent 流程处理 <X> | 通用需求实现 | 先提供 PRD 与 `allowedPaths` / `forbiddenPaths` / verify，再 `task advance` → 审查 writeSet gate → `task advance --approve-gate`；主会话不得直接修改业务实现 |
 
-**更新校验（只读）**：只读执行下面命令；**不得自动**执行 `apply-safe` 或模型合并。
+**初始化升级闭环（写入型）**：主会话收到上述写入型表达时自动调用统一入口，并在 controller 返回的具体单文件 `allowedPaths` 内完成必要语义合并后使用 `--continue`。不得停在 `check-update`、`needs-safe-update`、`needs-model-merge` 或 `verification-pending`。默认安装/合并项目 `.opencode/plugins/`、`.pi/extensions/` 与 `.pi/settings.json`；Pi 必须 trust 项目才能加载，默认严禁写 `~/.pi/agent/settings.json`。
 
 ```bash
-loop-agent init check-update --repo-root . --markdown
+loop-agent init upgrade --repo-root . --json
+loop-agent init upgrade --repo-root . --run-id <run-id> --continue --json
+loop-agent init upgrade --repo-root . --run-id <run-id> --report --markdown
 ```
 
-**升级对齐**：`loop-agent init reconcile --repo-root .`；surface 缺失、human decisions、活跃 DAG/Worker 或 Worker 状态无法确认时必须零写入。
+**更新校验（只读）**：只读执行下面命令；**不得自动**执行 `apply-safe`、模型合并或创建 upgrade run。
+
+```bash
+loop-agent init check-update --repo-root . --markdown
+```
 
-**安全更新**：先 check-update；surface 缺失时仅先建立 inferred baseline，再执行确定性 safe actions。不得自动处理 model merge tasks。
+**低层兼容命令（仅诊断/恢复，不是自然语言写入入口）**：`init reconcile`、`init update --bootstrap-surface` 与 `init update --apply-safe` 保留给 controller 诊断、旧自动化和人工排障。主会话收到任何写入型“初始化更新 / 初始化对齐 / 安全更新”表达时，必须唯一进入 `init upgrade`，不得改为直接调用这些低层命令，也不得在它们返回 `needs-model-merge` 后停止。surface 缺失、human decisions、活跃 DAG/Worker 或 Worker 状态无法确认时仍必须零写入。
 
 ```bash
+# 只读诊断
 loop-agent init check-update --repo-root . --markdown
-loop-agent init update --repo-root . --bootstrap-surface  # 仅 surface 缺失时
+# 低层兼容恢复；不得替代写入型自然语言的统一 init upgrade 入口
+loop-agent init reconcile --repo-root .
+loop-agent init update --repo-root . --bootstrap-surface
 loop-agent init update --repo-root . --apply-safe
 ```
 

package/harness.json

@@ -26,6 +26,28 @@
       ]
     }
   },
+  "workerPolicy": {
+    "nightScheduler": {
+      "enabled": true,
+      "timezone": "Asia/Shanghai",
+      "allowedHours": ["00:00-08:00"],
+      "maxConcurrency": 1,
+      "maxAutoAttempts": 1,
+      "misfirePolicy": "wait-next-window",
+      "keepFailedWorktree": true,
+      "mergePolicy": "manual-on-success",
+      "autoFollowUp": {
+        "enabled": false,
+        "mode": "draft-only"
+      },
+      "traceability": {
+        "required": true,
+        "label": "Task Card",
+        "pattern": "^[A-Z][A-Z0-9]+-[A-Z0-9]+#[0-9]+$",
+        "commitMessageTemplate": "{summary}\n\n{workItemRef}"
+      }
+    }
+  },
   "entrypoints": {
     "readme": "README.md",
     "agents": "AGENTS.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.28.1",
+  "version": "0.28.2",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/loop-agent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: loop-agent
 description: >-
-  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG / task advance lifecycle, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, initializing a target project with loop-agent, checking init update status, applying a safe init update, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, task advance, task status, dag validate, dag execute, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现, 初始化 loop-agent, loop agent 初始化, loop agent初始化, loop-agent 初始化, 初始化更新校验, loop agent初始化更新校验, 检查初始化更新, 初始化安全更新, loop agent初始化安全更新, 应用初始化更新. 强路由：loop-agent 帮我完成需求, 帮我实现, 帮我修复, 帮我开发, 使用 loop-agent 完成, 按 loop-agent 流程处理, 通用需求实现；这些表达确定性地进入 task advance / Agent DAG CLI，主会话编排而不直接写业务实现.
+  Use when implementing features, processing PRDs or requirements, running structured loop-agent workflows, creating harness tasks, using Agent DAG / task advance lifecycle, pi-prompt planning/review, cursor-prompt one-shot sidecar intervention, initializing a target project with loop-agent, checking init update status, applying a safe init update, or converging website/governance docs after user-visible changes in loop-agent. Triggers: loop-agent, workflow, structured development, harness task, Agent DAG, task advance, task status, dag validate, dag execute, docs converge, Converge Docs, 文档收敛, 结构化开发, 工作流, 需求实现, PRD 实现, 初始化 loop-agent, loop agent 初始化, loop agent初始化, loop-agent 初始化, 初始化更新校验, loop agent初始化更新校验, 检查初始化更新, 初始化安全更新, loop agent初始化安全更新, 应用初始化更新, loop-agent初始化更新, loop-agent 初始化更新, 更新 loop-agent 初始化内容, 升级后对齐. 强路由：loop-agent 帮我完成需求, 帮我实现, 帮我修复, 帮我开发, 使用 loop-agent 完成, 按 loop-agent 流程处理, 通用需求实现；这些表达确定性地进入 task advance / Agent DAG CLI，主会话编排而不直接写业务实现.
 references:
   - path: references/harness-policy.md
     required: true
@@ -13,61 +13,53 @@ references:
 
 # loop-agent Workflow
 
-Entry: routing and hard rules. Required details come from frontmatter references；`command-reference.md` stays optional below.
+入口只保留路由与硬约束；细节由 frontmatter required references 注入，`command-reference.md` 保持可选。
 
 ## 默认立场
 
-- 主入口是 **Agent DAG**（经 `loop-agent` / 可选 `agent-worker` CLI）。
-- 宿主仅作 **Compatibility / Operator Assist**：主会话编排 CLI、审 writeSet、读 status/doctor/report、处理 human gate、验证与 handoff；不写业务代码。
-- **严禁**主会话绕过 CLI 用宿主 Edit/Write 改业务实现，或 CLI 失败后「救火改文件」。
-- DAG `pi` executor 默认 read-only；`toolProfile: "write"` 时为 bounded writer；sidecar 须 per call 收窄。
-- Shell verification 是事实源；长期结论写回 `ai_workspace/loop-agent/`、`docs/decisions/` 或 `skills/`。
+- 主入口是 **Agent DAG**；主会话只编排 CLI、审 writeSet、处理 gate、验证与 handoff，不写业务实现。
+- 禁止绕过 CLI 用宿主 Edit/Write「救火」；失败走 doctor/reconcile/human gate/重跑。
+- `pi` 默认 read-only；仅 `toolProfile: "write"` 是 bounded writer。Shell verification 是事实源。
 
-## 唯一推荐执行路径
+## 初始化升级路由
 
-```bash
-# 标准 mutation：task advance（create/import/prepare/generate/validate → writeSet gate）
-loop-agent task advance <task-id> "Title" \
-  --prd <prd.md> \
-  --allowed-path "<glob>" \
-  --forbidden-path ".harness/**" \
-  --verify "typecheck:npm run typecheck" \
-  --json
+- 写入型「**loop-agent初始化更新**」「loop-agent 初始化更新」「更新 loop-agent 初始化内容」「升级后对齐」统一运行 `loop-agent init upgrade --repo-root . --json`；处理 controller 返回的单文件 `allowedPaths`，以同一 run `--continue` 推进至终态，不停在中间状态。
+- 「检查初始化更新」「初始化更新校验」「只检查，不要修改」仅运行 `loop-agent init check-update --repo-root . --markdown`，不得创建 run 或写入。
+- facts 位于 `.harness/init-upgrades/<run-id>/`；禁止业务源码和宽泛 glob。默认管理项目 `.opencode/plugins/`、`.pi/extensions/`、`.pi/settings.json`；Pi trust 后加载，默认不读写 `~/.pi/agent/settings.json`。
 
-# 审查 JSON 中的 gate.writeSet / gate.digest 后批准并长跑
-loop-agent task advance <task-id> \
-  --approve-gate "write-set-review:<digest>" \
-  --json
+## 标准路径
 
-# 可选只读（无 refresh 副作用）
+```bash
+loop-agent task advance <task-id> "Title" --prd <prd.md> \
+  --allowed-path "<glob>" --forbidden-path ".harness/**" \
+  --verify "typecheck:npm run typecheck" --json
+loop-agent task advance <task-id> \
+  --approve-gate "write-set-review:<digest>" --json
 loop-agent task status <task-id> --json
 ```
 
-非微小跨会话任务仍可先 `plan create`（见 references/source-and-plan-practice.md）。主会话只审 gate/writeSet 与验证证据，不拼低层 prepare/run-task/run-dag/promote/closeout 命令串。
+非微小跨会话任务可先 `plan create`。主会话只审 gate/writeSet 与验证证据，不拼低层 prepare/run-task/run-dag/promote/closeout 命令串。
 
-## 进阶主题路由
+## 主题路由
 
 | 主题 | Reference |
 | --- | --- |
 | Harness policy、Loop、SePO-lite | `references/harness-policy.md` |
-| Agent DAG topology、writeSet、recovery | `references/hybrid-dag.md` |
+| DAG topology、writeSet、recovery | `references/hybrid-dag.md` |
 | Operator commands、`agent-worker` | `references/command-reference.md` |
-| 独立验证、failure handling、closeout | `references/verification-and-failure-handling.md` |
+| 验证、failure、closeout | `references/verification-and-failure-handling.md` |
 
 ## Hard Rules
 
 1. Use vertical tracer bullets across real integration layers；each needs independent acceptance and verification.
-2. Autonomy ≠ governance profile: declare AFK/HITL in human gate; choose `--profile` by risk.
-3. Source materials mandatory: `source/需求.md`、`source/执行约束.md`、优先 `source/references/*` originals。
-4. Structured task config only: `referenceDocs` uses `{ path, name? }[]`, never a string array；`verifyCommands` uses `{ label, command, timeoutMs? }[]`, never a string array。
-5. Agent DAG is the implementation workflow；review three-way checks references + derived source + implementation。
-6. 主会话不绕过 CLI 直接写业务代码；失败只走 doctor/reconcile/human gate/重跑。
-7. DAG `pi` executor read-only unless `toolProfile: "write"`；completed run facts read-only；不得从 read-only DAG/sidecar 写 root `artifacts/`。
-8. No hidden state in chat only；verify before completion.
-9. Client recovery：`init --client-recovery=auto|project|user|off` 投影 transient-retry + overflow-compact + Pi overflow extension；只有 `user` 写 Pi settings；overflow 与 transient 职责分离；check/update 遵守 ownership。
+2. Autonomy ≠ governance profile；AFK/HITL 属 human gate，`--profile` 按风险选择。
+3. 必须读取 `source/需求.md`、`source/执行约束.md`，优先原始 `source/references/*`。
+4. `referenceDocs` uses `{ path, name? }[]`, never a string array；`verifyCommands` uses `{ label, command, timeoutMs? }[]`, never a string array。
+5. Agent DAG 才是实现流；review 三向核对 references、derived source、implementation。
+6. read-only DAG/sidecar 不得写 root `artifacts/`；completed run facts 只读。
+7. 关键状态不得只留在聊天；完成前必须验证。
+8. Client recovery 的 `auto|project|user|off` 遵守 ownership；仅 `user` 写用户 Pi settings，overflow 与 transient 分工。
 
 ## References
 
-Required（按需 inline）：`references/harness-policy.md`、`references/hybrid-dag.md`、`references/verification-and-failure-handling.md`
-
-Optional 索引见 `references/README.md`；常用：`command-reference.md`、`long-running-loop.md`、`orchestrator-and-interventions.md`、`docs-converge.md`。
+Required：`references/harness-policy.md`、`references/hybrid-dag.md`、`references/verification-and-failure-handling.md`。Optional 见 `references/README.md`；常用 `references/command-reference.md`、`references/source-and-plan-practice.md`、`references/long-running-loop.md`、`references/orchestrator-and-interventions.md`、`references/docs-converge.md`。

package/skills/loop-agent/references/command-reference.md

@@ -36,18 +36,23 @@ loop-agent doctor
 1. **主路径 lifecycle**，用于常规 autonomous work：
 
    ```bash
-   # 非微小 / 跨会话（推荐默认）：loop-agent plan create <plan-id> "<title>"
-   loop-agent task advance <task-id> "Task Title" \
-     --prd <path-to-prd.md> \
-     --accept-recommendations <digest>  # optional P1
-  --allowed-path "<glob>" \
+   # 非微小 / 跨会话（推荐默认）：loop-agent plan create PLAN_ID "Title"
+   loop-agent task advance TASK_ID "Task Title" \
+     --prd path/to/prd.md \
+     --accept-recommendations DIGEST \
+     --allowed-path "src/**" \
      --forbidden-path ".harness/**" \
      --verify "typecheck:npm run typecheck" \
      --json
-   # 审查 gate.writeSet / gate.digest 后：
-   loop-agent task advance <task-id> --approve-gate "write-set-review:<digest>" --json
-   loop-agent task status <task-id> --json
-   # 有 plan 时收尾：loop-agent plan complete <plan-id> --summary "..."
+
+   # 审查 gate.writeSet / gate.digest 后
+   loop-agent task advance TASK_ID \
+     --approve-gate "write-set-review:DIGEST" \
+     --json
+   loop-agent task status TASK_ID --json
+
+   # 有 plan 时收尾
+   loop-agent plan complete PLAN_ID --summary "..."
    ```
 
    首次 `task advance` 内部完成 create、PRD 归档、managed contract 投影、DAG 生成与 strict validate，并停在 writeSet gate；批准后同一命令长跑到稳定终态并做确定性 promotion/closeout。决策表与反模式见 `source-and-plan-practice.md`。
@@ -115,9 +120,10 @@ SDK 回归或 SDK 可选依赖不可用时用 `cli-only` 诊断。CLI fallback
 | 用户表达 | 命令 |
 | --- | --- |
 | loop-agent 初始化 / loop agent 初始化 / loop agent初始化 / 初始化 loop-agent | 先运行 `loop-agent init instructions --repo-root .`，再运行 `loop-agent init --repo-root . --profile full --merge`，随后补全 README/验证矩阵并复查 doctor/inspect/docs audit |
-| 初始化更新校验 / loop agent初始化更新校验 / 检查初始化更新 | `loop-agent init check-update --repo-root . --markdown`（只读，不得隐含 `apply-safe`） |
-| 初始化安全更新 / loop agent初始化安全更新 / 应用初始化更新 | 先 `loop-agent init check-update --repo-root . --markdown`，再 `loop-agent init update --repo-root . --apply-safe`（surface 缺失时先 `--bootstrap-surface`；human decisions 存在时停下等用户） |
-| 初始化对齐 / 升级后对齐 / init reconcile / 控制器升级后对齐目标项目 | `loop-agent init reconcile --repo-root .`（统一入口：surface 缺失返回 `needs-baseline` 零写入；human decisions 返回 `needs-human-decision` 零写入；活跃 DAG/Worker 或 Worker 状态无法确认时返回 `blocked-active-runtime` 零写入；其余执行 safe actions 后复查） |
+| loop-agent初始化更新 / loop-agent 初始化更新 / 更新 loop-agent 初始化内容 / 升级 loop-agent 初始化 / 初始化对齐 / 升级后对齐 | `loop-agent init upgrade --repo-root . --json`（写入型 controller-owned 闭环；主会话完成 controller 返回的具体单文件 merge task 后以 `--continue` 推进，禁止停在中间态） |
+| 初始化更新校验 / loop agent初始化更新校验 / 检查初始化更新 / 只检查，不要修改 | `loop-agent init check-update --repo-root . --markdown`（严格只读；不得创建 upgrade run、`apply-safe` 或模型合并） |
+| 初始化安全更新 / loop agent初始化安全更新 / 应用初始化更新 | `loop-agent init upgrade --repo-root . --json`（不要求用户拼接低层安全更新参数） |
+| init reconcile / 控制器升级后对齐目标项目 | `loop-agent init upgrade --repo-root . --json`（保留 `reconcile` 仅作兼容低层诊断） |
 | loop-agent 帮我完成 / 帮我实现 / 帮我修复 / 帮我开发 <需求>；使用 loop-agent 完成 <X>；按 loop-agent 流程处理 <X> | 先 `loop-agent task advance <task-id> "任务标题" --prd <prd.md> --allowed-path "<glob>" --json`，审查 writeSet gate 后 `task advance --approve-gate write-set-review:<digest> --json`；主会话编排而不直接写业务实现 |
 
 ```bash
@@ -128,14 +134,18 @@ loop-agent init check-update --repo-root <target-repo> --json
 loop-agent init check-update --repo-root <target-repo> --markdown
 loop-agent init update --repo-root <target-repo> --bootstrap-surface
 loop-agent init update --repo-root <target-repo> --apply-safe
-loop-agent init reconcile --repo-root <target-repo> [--json|--markdown]
+loop-agent init reconcile --repo-root <target-repo> [--json|--markdown]  # compatibility low-level diagnostic
+loop-agent init upgrade --repo-root <target-repo> --json
+loop-agent init upgrade --repo-root <target-repo> --run-id <run-id> --status --json
+loop-agent init upgrade --repo-root <target-repo> --run-id <run-id> --continue --json
+loop-agent init upgrade --repo-root <target-repo> --run-id <run-id> --report --markdown
 ```
 
 `init check-update` 是只读升级报告，用于发现目标项目是否落后于当前包内初始化 surface。输出会区分 deterministic actions、model merge tasks、human decisions 和 recommended next。`--markdown` 会渲染可直接交给模型执行的合并指引，包含 `allowedPaths`、`forbiddenPaths`、`mergeRules` 和 `verification`。
 
 `init update --bootstrap-surface` 为旧项目写入 `.harness/init-surface.json` 的 `inferred-baseline`，不伪装成历史 recorded baseline。`init update --apply-safe` 只执行确定性安全动作：补缺失文件、创建目录、刷新 managed block；已有但无法确认与当前包一致的文件会进入 model merge tasks，不会被覆盖。
 
-`init reconcile` 是升级后对齐入口：surface 缺失返回 `needs-baseline` 且零写入，存在 human decisions 返回 `needs-human-decision` 且零写入，活跃 DAG/Worker 或 Worker 状态无法确认时返回 `blocked-active-runtime` 且零写入；其余情况复用 `--apply-safe` 的安全动作并复查返回 `clean`/`needs-model-merge`/`needs-safe-update`。控制器升级成功后，普通安全仓库命令结束时会自动检测目标项目是否需要 reconcile；非 TTY 只向 stderr 输出 `loop-agent init reconcile --repo-root ...` 提示且不写入目标，TTY 且无 human decisions、无活跃运行时可经明确 `y/yes` 同意后应用 deterministic safe actions。
+`init upgrade` 是写入型升级入口：首次运行冻结 controller identity、检查 npm latest、扫描 surface、自动执行安全动作，并把 run facts 持久化到 `.harness/init-upgrades/<run-id>/`。`--status` 与 `--report` 严格只读；`--continue` 会重新核验 identity、当前 hash 与不变量。版本选择、无法判定冲突、凭据、破坏性删除或 active writer 才进入 human decision。普通语义冲突返回具体单文件 `allowedPaths` merge task，主会话必须合并后继续，不能把 `needs-model-merge` 作为完成。默认管理项目级 OpenCode/Pi recovery 与 `.pi/settings.json` nested merge，保留显式 disabled，Pi trust 后才加载；默认不读写 `~/.pi/agent/settings.json`。旧 `init reconcile` 保留为兼容低层诊断。
 
 ### 查看或复制内置示例
 
@@ -541,7 +551,20 @@ agent-worker batch run-ready \
   [--check-repo] [--check-repo-command <command...>] \
   [--quiet] \
   [--pi-model <model>]                           # smoke 覆盖：所有 pi 节点强制用该模型
-agent-worker report morning --repo <repo-root> [--batch-run-id <id>] [--output <path>]
+agent-worker report morning --repo <repo-root> [--batch-run-id <id>] [--output <path>] [--window night] [--date YYYY-MM-DD] [--tz Asia/Shanghai]
+agent-worker admission prepare --repo <repo-root> --feature-dir <path> --task-id <id> --at "YYYY-MM-DD HH:mm" [--tz Asia/Shanghai] [--task-card <ref>] [--json]
+agent-worker admission show <schedule-id> --repo <repo-root> [--json]
+agent-worker scheduler list --repo <repo-root> [--json]
+agent-worker scheduler status <schedule-id> --repo <repo-root> [--json]
+agent-worker scheduler ledger <schedule-id> --repo <repo-root> [--json]
+agent-worker scheduler doctor --repo <repo-root> [--json]
+agent-worker scheduler add <schedule-id> --repo <repo-root> --approve-gate <token> [--json]
+agent-worker scheduler cancel <schedule-id> --repo <repo-root> [--reason <text>] [--json]
+agent-worker scheduler harvest <schedule-id> --repo <repo-root> [--json]
+agent-worker scheduler discard <schedule-id> --repo <repo-root> --reason <text> [--force] [--json]
+agent-worker scheduler tick --repo <repo-root> [--json]  # daemon/clock; not Operator Chat
+agent-worker scheduler submit --repo <repo-root> --feature-id <id> --task-id <id> ...  # low-level planning fact
+agent-worker scheduler transition <schedule-id> --repo <repo-root> --to <status> ...  # internal lifecycle
 agent-worker console [--repo <repo-root>] [--port 8790] [--host 127.0.0.1]  # Official 裸入口；repo 默认当前目录
 agent-worker console serve --repo <repo-root> [--port 8790] [--host 127.0.0.1]  # 兼容入口，等价于裸入口
 agent-worker console doctor --repo <repo-root> [--json] [--console-url <url>]
@@ -570,7 +593,8 @@ agent-worker observe snapshot --repo <repo-root>  # 输出 GlobalSnapshot JSON
 - `task draft-followup` 会按全部 failure category 生成 TaskDraft 或人工行动卡：ProductBug/TestBug/FlakyTest/DependencyFailure 可批准；EnvFailure 连续两次后才生成 ENV-CHECK；Spec/Contract/Risk/Human/Unknown 只给行动卡。人工以 `feature approve-followup --dry-run` 预览，再带非空 `--owner` 批准 TaskDraft；行动卡不能批准。批准在 staging validation 后写 TaskSpec、graph、Ready/approval/event，原失败事实不改写，并有 rename/state/approval/index/event 回滚门禁。
 - `task retry` 是失败 Task 的唯一重试入口。它会保留原有运行记录和 failure handoff，并让下一次 `batch run-ready` 使用新的 `workerRunId`；不要删除运行态文件或手动修改状态来重试。
 - **推荐**裸入口 `agent-worker console`（repo 默认当前目录，默认 `127.0.0.1:8790`）提供 Operate + Inspect；`console serve` 是等价兼容入口。Inspect 路径为 `/inspect/#/...`，API 仍为根 `/api/**`。`observe serve` 为兼容入口（默认 `8787`，启动时 stderr 输出 `OBSERVE_SERVE_DEPRECATED`）；`observe snapshot` 保留。Inspect/Observe 本身不会启动、暂停或重试 Task / Worker / DAG。
-- 当前 Worker 仍是 v0（库 + CLI + dogfood），未接入定时/CI 驱动；`report morning` 只能从已有 Task Pool runs 汇总。
+- Night Scheduler（本地夜间自治）：白天 `admission prepare` 冻结 worktree + DAG writeSet gate；`scheduler add` 消费 gate 并预约 Task Pool `Queued`（不立即执行）；`scheduler tick` 作为 Worker 时钟 claim/dispatch（CLI/cron，不进 Operator Chat）；成功后 `pending-harvest`，早晨 `scheduler harvest`（exact-base FF）或 `scheduler discard`；`report morning --window night` 与 Inspect `#/night` / Operate 夜间面板读取同一套 facts。
+- 当前 Worker 仍是 v0（库 + CLI + dogfood）；日间批处理未强制定时/CI 驱动；`report morning` 默认可从 Task Pool runs 汇总，并支持 `--window night` 投影 Scheduler facts。
 
 ### 查看 duration statistics / context usage
 

package/skills/loop-agent/references/hybrid-dag.md

@@ -65,7 +65,7 @@ loop-agent dag execute --dag <temp-dir>/hybrid-dag.json --init-only --canvas-pat
 
 **运维 warning**：
 
-- **常规 validation**：`dag validate --dag <path>` 做 schema/topology/ranks。JSON 输出含 `governanceProfile`（确定性 `minimal|standard|reviewed|supervised` 推断，含 `process` / `delivery` / `codeChange` signal 与 `reasons`），及 model-matrix drift、governance lint（如 read-only artifact-boundary drift 或 DAG 内 `check-repo.sh` shell env drift）的 warnings。手写临时 DAG spec 执行前用 `dag validate --dag <path> --strict-models`；governance warning 应 fail fast 时加 `--strict-governance`。含 `executor: "cursor"` 的旧 DAG 会在 schema 校验失败；默认生成 DAG 使用 `pi` read-only / Pi write profile / shell。仅当有意在 `.harness/dag-runs/active/` 要 active run snapshot 时用 `dag execute --dry-run`。
+- **常规 validation**：`dag validate --dag <path>` 做 schema/topology/ranks。JSON 输出含 `governanceProfile`（确定性 `minimal|standard|reviewed|supervised` 推断，含 `process` / `delivery` / `codeChange` signal 与 `reasons`），及 model-matrix drift、governance lint（如 read-only artifact-boundary drift 或 DAG 内 `check-repo.sh` shell env drift）的 warnings。手写临时 DAG spec 执行前用 `dag validate --dag <path> --strict-models`；governance warning 应 fail fast 时加 `--strict-governance`。含 `executor: "cursor"` 的旧 DAG 会在 schema 校验失败；默认生成 DAG 使用 `pi` read-only / Pi write profile / shell。`dag execute --dry-run` 仅用于需要预演的场景：snapshot 位于命令返回的 `.harness/dag-runs/dry-run/<runId>/` `runDir`，不创建 active run、不进入 active overview，也不可作为 `dag resume` 目标。
 - **Governance profile 推断与 routing（code vs skill 分工）**：`./src/workflows/dag/governance-profile.ts` 从 DAG 结构与 write scope 做 **硬确定性推断**。JSON 输出 **报告** `process` / `delivery` / `codeChange` signal 与人类可读 `reasons`；`profile` tier（`minimal|standard|reviewed|supervised`）仅由该模块 code rule 选择（如多个 exclusive writer、repair node、review-gate topology、`loop-agent-runtime-paths`、`scripts-ci-harness-paths`、weak post-implementation shell verification、supervised topology）。baseline `forbiddenPaths`（`.harness/**`、`.harness/dag-runs/**`、`artifacts/**`）是默认 governance，**本身不是** process-risk signal。skill prompt 与本 reference **解释** tier 并摘要 profile 选择原因；不替代 code 推断。`task advance` 转发 embedded validate step 的同一 candidate `governanceProfile`。`task advance --profile auto` 先将 candidate profile 经 `harness.json.workflowPolicy.dag.profileRouting` 映射，再在 candidate delivery signal 含 `loop-agent-runtime-paths`、`scripts-ci-harness-paths` 或 `public-contract-paths` 时应用 M4 `supervised-quality-gate` promotion；`profileRouting.routingReasons` 记录确定性 reason。无 profile `task advance <task-id>` 仍为 standard-compatible；显式 `--profile minimal|standard|reviewed|supervised` 与自动 promotion 记录治理强度，已识别的前端业务 workflow 仍使用前端专用模板。高风险 task 应用 `--profile auto` 或显式 `--profile supervised`，而非显式 `--profile reviewed`。
 - **Executor model routing**：DAG spec 选 `executor` 与 `complexity`，可通过 `executorModels.pi` 覆盖模型。值写成 `provider/model` 时显式选择 Pi provider（只分割第一个 `/`）；裸模型名继续走内置映射或默认 `wizard-local`。默认 routing：Pi LOW=`gpt-5.3-codex-spark`、MED=`gpt-5.5`、HIGH=`gpt-5.5`。`shell` 不用 model，忽略 `executorModels`。
 - **Active visibility**：真实 `dag execute` execution 在 run/node 转换时写 active `state.json`，归档前 core runner 暴露 isolated `DagRunObserver` hook 供 derived view。`.harness/dag-runs/completed/<run-id>/` / `paused/<run-id>/` 仍是 source of truth；observer 输出非 canonical。