@tea-agent/loop-agent 0.28.2-beta.1 → 0.28.2

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。