agent-steward 0.0.4 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (190) hide show
  1. package/CHANGELOG.md +134 -2
  2. package/CROSS_PLATFORM.md +19 -0
  3. package/README.md +52 -7
  4. package/ROADMAP-STRATEGY.md +21 -18
  5. package/ROADMAP.md +140 -159
  6. package/dist/cli.d.ts +3 -0
  7. package/dist/cli.d.ts.map +1 -0
  8. package/dist/cli.js +351 -0
  9. package/dist/core/execution.d.ts +203 -0
  10. package/dist/core/execution.d.ts.map +1 -0
  11. package/dist/core/execution.js +309 -0
  12. package/dist/core/gate-integrity.d.ts +35 -0
  13. package/dist/core/gate-integrity.d.ts.map +1 -0
  14. package/dist/core/gate-integrity.js +132 -0
  15. package/dist/core/git-trigger.d.ts.map +1 -1
  16. package/dist/core/git-trigger.js +14 -2
  17. package/dist/core/guard-run.d.ts +4 -0
  18. package/dist/core/guard-run.d.ts.map +1 -0
  19. package/dist/core/guard-run.js +101 -0
  20. package/dist/core/guard.d.ts +52 -0
  21. package/dist/core/guard.d.ts.map +1 -0
  22. package/dist/core/guard.js +362 -0
  23. package/dist/core/lock.d.ts +41 -0
  24. package/dist/core/lock.d.ts.map +1 -1
  25. package/dist/core/lock.js +141 -29
  26. package/dist/core/matrix.d.ts.map +1 -1
  27. package/dist/core/matrix.js +75 -15
  28. package/dist/core/mission.d.ts +83 -0
  29. package/dist/core/mission.d.ts.map +1 -0
  30. package/dist/core/mission.js +334 -0
  31. package/dist/core/pipeline-apply.d.ts +38 -0
  32. package/dist/core/pipeline-apply.d.ts.map +1 -0
  33. package/dist/core/pipeline-apply.js +117 -0
  34. package/dist/core/pipeline-io.d.ts +13 -0
  35. package/dist/core/pipeline-io.d.ts.map +1 -0
  36. package/dist/core/pipeline-io.js +64 -0
  37. package/dist/core/pipeline-map.d.ts +46 -0
  38. package/dist/core/pipeline-map.d.ts.map +1 -0
  39. package/dist/core/pipeline-map.js +196 -0
  40. package/dist/core/pipeline-spec.d.ts +109 -0
  41. package/dist/core/pipeline-spec.d.ts.map +1 -0
  42. package/dist/core/pipeline-spec.js +554 -0
  43. package/dist/core/ps-wrapper.d.ts +19 -2
  44. package/dist/core/ps-wrapper.d.ts.map +1 -1
  45. package/dist/core/ps-wrapper.js +250 -62
  46. package/dist/core/record-history.d.ts.map +1 -1
  47. package/dist/core/record-history.js +130 -29
  48. package/dist/core/router/rules.d.ts.map +1 -1
  49. package/dist/core/router/rules.js +6 -0
  50. package/dist/core/scheduler/linux.d.ts +8 -1
  51. package/dist/core/scheduler/linux.d.ts.map +1 -1
  52. package/dist/core/scheduler/linux.js +34 -9
  53. package/dist/core/scheduler/mac.d.ts +44 -2
  54. package/dist/core/scheduler/mac.d.ts.map +1 -1
  55. package/dist/core/scheduler/mac.js +126 -15
  56. package/dist/core/scheduler/windows.d.ts.map +1 -1
  57. package/dist/core/scheduler/windows.js +15 -12
  58. package/dist/core/structured-log.d.ts +7 -1
  59. package/dist/core/structured-log.d.ts.map +1 -1
  60. package/dist/core/worktree-run.d.ts +4 -0
  61. package/dist/core/worktree-run.d.ts.map +1 -0
  62. package/dist/core/worktree-run.js +164 -0
  63. package/dist/core/worktree.d.ts +115 -0
  64. package/dist/core/worktree.d.ts.map +1 -0
  65. package/dist/core/worktree.js +462 -0
  66. package/dist/core/wrappers/bash.d.ts +17 -0
  67. package/dist/core/wrappers/bash.d.ts.map +1 -1
  68. package/dist/core/wrappers/bash.js +175 -24
  69. package/dist/db/capability-repo.d.ts +43 -2
  70. package/dist/db/capability-repo.d.ts.map +1 -1
  71. package/dist/db/capability-repo.js +96 -11
  72. package/dist/db/history-repo.d.ts +38 -5
  73. package/dist/db/history-repo.d.ts.map +1 -1
  74. package/dist/db/history-repo.js +88 -25
  75. package/dist/db/metrics-repo.js +2 -2
  76. package/dist/db/recovery.d.ts.map +1 -1
  77. package/dist/db/recovery.js +5 -4
  78. package/dist/db/run-journal.d.ts +33 -5
  79. package/dist/db/run-journal.d.ts.map +1 -1
  80. package/dist/db/run-journal.js +78 -14
  81. package/dist/db/run-resume.d.ts +5 -0
  82. package/dist/db/run-resume.d.ts.map +1 -1
  83. package/dist/db/run-resume.js +9 -2
  84. package/dist/db/runs-repo.d.ts +19 -2
  85. package/dist/db/runs-repo.d.ts.map +1 -1
  86. package/dist/db/runs-repo.js +22 -6
  87. package/dist/db/schema.d.ts +2 -2
  88. package/dist/db/schema.d.ts.map +1 -1
  89. package/dist/db/schema.js +63 -2
  90. package/dist/history.d.ts +1 -1
  91. package/dist/history.d.ts.map +1 -1
  92. package/dist/i18n.d.ts +5 -0
  93. package/dist/i18n.d.ts.map +1 -1
  94. package/dist/i18n.js +11 -4
  95. package/dist/index.d.ts +136 -2
  96. package/dist/index.d.ts.map +1 -1
  97. package/dist/index.js +378 -14
  98. package/dist/notifications.d.ts +22 -0
  99. package/dist/notifications.d.ts.map +1 -1
  100. package/dist/notifications.js +36 -8
  101. package/dist/profiles.d.ts.map +1 -1
  102. package/dist/profiles.js +25 -4
  103. package/dist/rpc.d.ts +246 -0
  104. package/dist/rpc.d.ts.map +1 -1
  105. package/dist/rpc.js +117 -0
  106. package/dist/server.d.ts +15 -0
  107. package/dist/server.d.ts.map +1 -1
  108. package/dist/server.js +77 -18
  109. package/dist/settings.d.ts +2 -2
  110. package/dist/settings.d.ts.map +1 -1
  111. package/dist/settings.js +3 -3
  112. package/dist/shared/jobs-view.d.ts +1 -1
  113. package/dist/shared/jobs-view.d.ts.map +1 -1
  114. package/dist/shared/jobs-view.js +2 -0
  115. package/dist/task-transfer.d.ts +16 -0
  116. package/dist/task-transfer.d.ts.map +1 -1
  117. package/dist/task-transfer.js +16 -0
  118. package/docs/ARCHITECTURE.md +281 -65
  119. package/docs/COMPATIBILITY.md +2 -2
  120. package/docs/CONCEPT.md +18 -4
  121. package/docs/CROSS_PLATFORM.ru.md +20 -0
  122. package/docs/CROSS_PLATFORM.zh.md +18 -0
  123. package/docs/EXECUTION-LOOP.md +22 -7
  124. package/docs/FEATURES.md +65 -4
  125. package/docs/FEATURES.zh.md +52 -4
  126. package/docs/MIGRATION.md +2 -2
  127. package/docs/PIPELINE.md +293 -0
  128. package/docs/README.ru.md +42 -3
  129. package/docs/README.zh.md +43 -3
  130. package/docs/SAFETY.md +23 -3
  131. package/gui-experimental.cjs +9 -8
  132. package/locales/en.json +17 -1
  133. package/locales/ru.json +17 -1
  134. package/locales/zh.json +17 -1
  135. package/opencode.pipeline.yaml +35 -0
  136. package/package.json +23 -4
  137. package/scripts/test-home.mjs +83 -0
  138. package/src/cli.ts +412 -0
  139. package/src/core/dry-run.ts +2 -2
  140. package/src/core/execution.ts +538 -0
  141. package/src/core/file-watcher.ts +2 -2
  142. package/src/core/gate-integrity.ts +160 -0
  143. package/src/core/git-trigger.ts +18 -5
  144. package/src/core/guard-run.ts +119 -0
  145. package/src/core/guard.ts +431 -0
  146. package/src/core/lock.ts +178 -37
  147. package/src/core/matrix.ts +95 -50
  148. package/src/core/mission.ts +485 -0
  149. package/src/core/native-notify.ts +1 -1
  150. package/src/core/pipeline-apply.ts +158 -0
  151. package/src/core/pipeline-io.ts +79 -0
  152. package/src/core/pipeline-map.ts +264 -0
  153. package/src/core/pipeline-spec.ts +775 -0
  154. package/src/core/ps-wrapper.ts +263 -63
  155. package/src/core/record-history.ts +164 -77
  156. package/src/core/router/rules.ts +6 -0
  157. package/src/core/schedule-gate.ts +1 -1
  158. package/src/core/scheduler/at-fallback.ts +1 -1
  159. package/src/core/scheduler/linux.ts +40 -11
  160. package/src/core/scheduler/logs.ts +2 -2
  161. package/src/core/scheduler/mac.ts +174 -14
  162. package/src/core/scheduler/registry.ts +2 -2
  163. package/src/core/scheduler/windows.ts +19 -15
  164. package/src/core/secrets.ts +8 -8
  165. package/src/core/structured-log.ts +22 -5
  166. package/src/core/telegram.ts +2 -2
  167. package/src/core/triage-worker.ts +7 -7
  168. package/src/core/triage.ts +2 -2
  169. package/src/core/worktree-run.ts +199 -0
  170. package/src/core/worktree.ts +600 -0
  171. package/src/core/wrappers/bash.ts +190 -23
  172. package/src/db/capability-repo.ts +127 -10
  173. package/src/db/history-repo.ts +129 -22
  174. package/src/db/metrics-repo.ts +2 -2
  175. package/src/db/recovery.ts +5 -4
  176. package/src/db/run-journal.ts +100 -13
  177. package/src/db/run-resume.ts +17 -1
  178. package/src/db/runs-repo.ts +36 -6
  179. package/src/db/schema.ts +65 -2
  180. package/src/gui.tsx +177 -13
  181. package/src/history.ts +1 -1
  182. package/src/i18n.ts +12 -4
  183. package/src/index.ts +524 -4
  184. package/src/notifications.ts +38 -8
  185. package/src/profiles.ts +26 -4
  186. package/src/rpc.ts +128 -0
  187. package/src/server.ts +94 -18
  188. package/src/settings.ts +5 -5
  189. package/src/shared/jobs-view.ts +3 -1
  190. package/src/task-transfer.ts +31 -0
@@ -53,6 +53,12 @@ interface SchedulerBackend {
53
53
  - 包装脚本:`run-task.ps1` 加每个任务专属的 `run-<name>.cmd`,位于 `%APPDATA%\opencode\agent-steward\wrapper`。旧的 `%APPDATA%\opencode\windows-scheduler` 目录会在首次启动时迁移。
54
54
  - 日志:`%APPDATA%\opencode\agent-steward\logs\<name>.log`。
55
55
  - cron 会转换成 schtasks(`convertCronToSchTasks`)——支持与之前相同的模板集合。
56
+ - 提示词在 `--` 之后传给 `opencode run`,因此以 `-` 开头的提示词不会被当成选项。
57
+ 包装脚本会在 `CreateProcess` 之前拒绝超过 30 000 字符的提示词
58
+ (命令行上限为 32 767 字符)。
59
+ - 超时看门狗:通过 `Get-CimInstance` 读取进程树;如果 CIM 失败或为空,则回退到
60
+ `Get-WmiObject`,再检查 `tasklist`/`Get-Process`。如果完全拿不到树数据,则
61
+ 故障关闭并执行 `taskkill /F /T /PID <root>`,避免孙进程继续运行。
56
62
 
57
63
  ### Linux
58
64
  - 任务保存在受管 `crontab` 块中:
@@ -69,19 +75,31 @@ interface SchedulerBackend {
69
75
  - 支持完整 cron 语法(与 Windows 不同),因为 crontab 原生支持。
70
76
  - 一次性任务(`once`):使用 `at -t`;如果未安装 `at`,插件会退回到分离的 `sleep && 命令` 进程(注册表中为 `pid:<pid>`)。回退方案无法在重启后保留,建议安装 `at` 包。
71
77
  - 删除/重建只触及自己的块,`crontab` 的其他行不受影响。
78
+ - 未闭合的插件块(只有开始标记)按 fail-closed 处理:插件报告错误且不重写 crontab,因此标记之后的用户行不会丢失。
72
79
 
73
80
  ### macOS
74
81
  - 任务是 LaunchAgent plist:`~/Library/LaunchAgents/com.opencode.scheduler.<name>.plist`。
75
82
  - 调度:`* * * * *` 和 `*/N` 使用 `StartInterval`,`M * * * *`、`M H * * *`、`M H * * D`
76
83
  使用 `StartCalendarInterval`。
77
84
  - 暂停 = `launchctl unload -w`,恢复 = `launchctl load -w`。
85
+ - 安装已暂停的任务只写入 plist,不调用 `load -w`(它会清除暂停);
86
+ `unload -w` 保证代理在下次登录后仍保持禁用。
87
+ - `launchctl load` 的错误不会被吞掉:安装/恢复失败会带上命令、退出码和
88
+ stderr(例如损坏的 plist 返回 `Invalid property list`)。
78
89
  - 包装脚本与 Linux 相同的 `.sh`;配置路径:
79
90
  `~/.config/opencode/agent-steward/`(或 `$XDG_CONFIG_HOME`)。
80
91
 
81
92
  ### 共享 POSIX 包装脚本(`.sh`)
82
93
  - `cd` 到工作目录,用文件中的提示词执行 `opencode run`。
94
+ 提示词位于 `--` 之后,因此开头的 `-` 不会被当作选项。
95
+ - argv 保护会在 `PROMPT_BYTES >= 131072` 时拒绝运行:Linux 的 `MAX_ARG_STRLEN`
96
+ 包含结尾 NUL,因此最多只有 131 071 字节的有效负载。
83
97
  - 日志通过 `>>` 追加,并带时间戳。
84
98
  - 通过原子 `mkdir` 加锁——防止并行运行。
99
+ - Node、PS 和 bash 都将锁持有者写为 `<pid>-<iso>`;旧格式 `<iso>|<pid>`(PS)和
100
+ 裸 `<pid>` 仍可读取,因此运行中的锁不会被另一种运行时误判为过期。
101
+ - 插件启动时同时读取 `<task>.lock` 与 `<task>.lock.d/pid` 的持有者:只有 PID
102
+ 已死亡或缺失时才清理锁目录,年龄仅作为回退条件。
85
103
  - 超时:子进程 + 看门狗(先 `TERM`,再 `KILL`)。
86
104
  - Quality Gate:`bash -lc "<命令>"`(相当于 Windows 上的 `cmd.exe /c`)。
87
105
  - 指标:`node "<record-history.js>" <task> <status> <started> <duration> <error> "-" "-"`——
@@ -11,7 +11,7 @@
11
11
  - **Роутер не вызывается live.** `routeStep` / `decideCapabilityRoute` отсутствуют в `index.ts` / `record-history.ts`.
12
12
  - **Карта не обучается.** `recordCapabilityOutcome` не вызывается из горячего пути.
13
13
  - **Эскалация не живая.** `escalateAfterGate` есть, но провал гейта идёт в retry/chain.
14
- - **Нет ad-hoc входа.** Любой запуск требует регистрации: `schedule_task` + `run_task_now`; `once` — это `at` / `schtasks ONCE` / launchd. Цепочки/DAG/retry обходят расписание костылём force-маркера.
14
+ - **Нет ad-hoc входа.** Любой запуск требует регистрации: `schedule_task` + `run_task_now`; `once` — это `at` / `schtasks ONCE` / launchd. Цепочки/DAG/retry обходят расписание костылём force-маркера. *(Закрыто в AB-8: `run_mission` / CLI `run` / GUI / RPC.)*
15
15
 
16
16
  Не построено вовсе: ledger + provenance; класс риска и компиляция политики;
17
17
  бюджет миссии; целостность гейта, flake-aware, отложенные эффекты; context
@@ -119,12 +119,27 @@ CREATE TABLE gate_outcomes (
119
119
 
120
120
  ## 4. Целостность гейта (спринт 39)
121
121
 
122
- - Gate-файлы и команда вне write-scope агента; snapshot фиксируется на старте миссии.
123
- - `gate_hash` и `policy_hash` пишутся в ledger и сверяются перед вердиктом;
124
- расхождение → `fail` + аудит-инцидент.
125
- - Gate-executor отделён от агента; артефакт применяется к защищённому дереву.
126
- - **Гейт всегда hard.** Shadow/canary — только для маршрутов и адаптеров (49).
127
- - **Тест-атака обязательна:** агент правит тесты → гейт обязан провалить.
122
+ **Реализовано (G-1.2):** при создании задачи `src/core/gate-integrity.ts`
123
+ фиксирует snapshot входов гейта — команду/файл хука, prompt и таймаут — с
124
+ SHA-256 в `PLUGIN_DIR/gate-snapshots/`, вне write-scope задачи. Перед запуском
125
+ гейта обе обёртки (Windows и POSIX) вызывают `gate-integrity.js verify`; при
126
+ расхождении хэша, отсутствии или повреждении snapshot гейт не выполняется,
127
+ запуск переходит в `error` с сообщением «snapshot mismatch». Snapshot
128
+ проверяет именно определение гейта, а не исходники репозитория, которые гейт
129
+ тестирует.
130
+
131
+ **Обязательная тест-атака в CI:** `test-execution-hardening.mjs` (Windows) и
132
+ `test-posix-e2e.mjs` (macOS/Linux) подменяют сгенерированный gate-файл/команду
133
+ на `exit 0` после создания snapshot и требуют падения запуска; оба теста уже
134
+ входят в `npm test`/`test:parallel`. Юнит-проверки хэша и CLI — в
135
+ `test-execution-pipeline.mjs`.
136
+
137
+ **Остаётся планом:** отдельный gate-executor, `gate_outcomes` с `gate_hash`,
138
+ `policy_hash`, `prompt_hash` и `prev_hash` в ledger, аудит-инцидент при
139
+ расхождении и перенос gate-файлов под привилегии, отличные от пользовательских.
140
+ Гейт по-прежнему **всегда hard**; shadow/canary — только для маршрутов и
141
+ адаптеров (49). Подмена самих тестов агентом текущей мерой не детектируется —
142
+ защита ограничена целостностью определения гейта.
128
143
 
129
144
  ## 5. Отложенные внешние эффекты
130
145
 
package/docs/FEATURES.md CHANGED
@@ -259,6 +259,41 @@ not to hooks, Quality Gates or scripts, which still run with your user privilege
259
259
  for the exact action mapping and known limitations (project/system config, nested
260
260
  subagents).
261
261
 
262
+ ### One-off git worktree (W-1)
263
+
264
+ Set `worktree: true` to run every tick in a fresh `git worktree` of
265
+ `workingDirectory` on its own `agent-steward/...` branch. The wrapper creates the
266
+ worktree after the schedule gate and before `opencode`, passes the path to the agent
267
+ through the prompt preamble and `AGENT_STEWARD_WORKTREE`, and fails the run closed
268
+ if creation fails (for example, the directory is not a git repository). Paths and
269
+ branches are unique per run, so matrix clones and parallel missions can write files
270
+ without touching the main checkout or each other — safe fan-out without Docker.
271
+
272
+ Worktrees live under `PLUGIN_DIR/worktrees` with a `.json` sidecar used by cleanup.
273
+ After the run the wrapper removes the worktree and its `agent-steward/...` branch
274
+ even when the task fails (W-2.1). Leftovers from crashes are swept opportunistically
275
+ on the next run: worktrees older than 24 hours are removed, sidecars without a
276
+ checkout are pruned, and a `.cleanup-lock` serialises concurrent sweeps (W-2.2).
277
+ Cleanup only touches paths under the worktree root that have a sidecar and an
278
+ `agent-steward/` branch, so foreign directories and fresh active runs are never
279
+ deleted. A worktree does not isolate network, API or database access, and Quality
280
+ Gates still run with your user privileges.
281
+
282
+ ### Guard conditions (W-3)
283
+
284
+ Set `guards` on a task to require conditions before it runs: an optional shell
285
+ `command` (exit 0 — пройден, non-zero — скип, `timeoutSeconds` 1..3600) and/or
286
+ `semantic` conditions — `filesExist` / `filesMissing` (relative paths, resolved
287
+ inside the worktree or cwd), `branch` (glob), and `changedPaths` (glob, at least
288
+ one path in the diff of `changedSince..HEAD`, default `HEAD~1`). All conditions
289
+ are ANDed: when any check fails or errors, the run is skipped gracefully with a
290
+ visible `skipped` status in history and the GUI (`record-history --skip`, no
291
+ notification and no success/error chain). Guards are evaluated after the
292
+ worktree is created, so they run inside the fresh worktree when combined with
293
+ `worktree: true`; the `guard-run.js` helper lives in `src/core/guard-run.ts` and
294
+ `src/core/guard.ts` provides normalization, evaluation and the exit-code
295
+ convention (4 = skip).
296
+
262
297
  ## Orchestration
263
298
 
264
299
  ### Chains
@@ -323,6 +358,21 @@ Behavior worth knowing:
323
358
  - `matrix_control` with `action: "cleanup"` removes orphaned clones whose parent is
324
359
  gone; the same cleanup also runs at plugin startup.
325
360
 
361
+ ### Pipeline as code
362
+
363
+ A whole DAG can be declared in `opencode.pipeline.yaml` and applied as code:
364
+
365
+ - `version: 1`, a pipeline `name`, optional `defaults` and 1..200 `steps`.
366
+ - Each step has a stable `id`, a `prompt` and an optional `needs` list that becomes
367
+ `dependsOn`.
368
+ - `trigger: cron` (default) needs a `schedule`; `trigger: once` needs `runAt`;
369
+ `trigger: dag` runs only after its `needs` succeed.
370
+ - `matrix.workspaces` fans a step out over workspace names or ids.
371
+ - `agent-steward pipeline validate|apply|export` and the `pipeline_validate`,
372
+ `pipeline_apply`, `pipeline_export` tools cover the lifecycle; apply is idempotent,
373
+ skips unchanged steps and never deletes stale tasks.
374
+ - Full format and limits: [PIPELINE.md](PIPELINE.md).
375
+
326
376
  ## Multi-repository workspaces
327
377
 
328
378
  A workspace is a named directory: id, name, path, optional git remote and color.
@@ -348,7 +398,9 @@ This is useful for separating projects, clients or environments (e.g. `default`
348
398
  in the base directory → `default`. Switching profiles writes the marker and requires
349
399
  an OpenCode restart because plugin directories are resolved at module load time.
350
400
  - Dashboard port per profile: `OPENCODE_SCHEDULER_PORT` env var → port from
351
- `profile.json` → server default (3782, then 4782/5782 fallback).
401
+ `profile.json` → server default (3782, then 4782/5782 fallback). A new profile is
402
+ allocated the first free port from 3783 up, skipping 3782/4782, ports already
403
+ recorded in other profiles' `profile.json`, and `OPENCODE_SCHEDULER_PORT`.
352
404
  - RPC: `get_profiles` lists profiles with dirs, ports and the active flag;
353
405
  `set_profile` switches the active profile (restart hint); `create_profile` /
354
406
  `delete_profile` manage named profiles (`default` cannot be deleted).
@@ -474,6 +526,12 @@ agent's stdout/stderr. `get_task_logs` returns the tail (1–1000 lines).
474
526
  `dry_run` simulates one task or every task: execution order, DAG prerequisites, matrix
475
527
  fan-out and estimated time. Nothing is executed and nothing is created.
476
528
 
529
+ The ad-hoc mission API (`runMission` / `agent-steward run --dry-run`) has its own
530
+ `dryRun` contract: it builds the step plan and its description, but does not acquire
531
+ the `activeWorkspaces` lock and does not write `runs`/`run_steps` to the ledger.
532
+ This is intentional — several dry runs in the same `cwd` run in parallel and leave
533
+ no trace in history. Only a real mission is locked to one workspace at a time.
534
+
477
535
  ### Dashboard
478
536
 
479
537
  A local web dashboard shows tasks, matrix tabs, per-workspace summaries, DAG markers,
@@ -610,14 +668,15 @@ the `cleanup_history` RPC and the GUI's **Clear now** button. Aggregates in
610
668
 
611
669
  ## Agent interface
612
670
 
613
- Twenty-six tools: `schedule_task`, `list_tasks`, `update_task`, `delete_task`,
671
+ Twenty-nine tools: `schedule_task`, `list_tasks`, `update_task`, `delete_task`,
614
672
  `run_task_now`, `pause_task`, `resume_task`, `get_history`, `get_task_logs`, `dry_run`,
615
673
  `manage_workspaces`, `matrix_control` (results/cancel/cleanup/preview), `get_metrics`,
616
674
  `get_analytics`, `self_analysis` (health score, anomalies, trends), `manage_settings`,
617
675
  `manage_local_ai`, `manage_templates`, `manage_profiles`,
618
676
  `transfer_tasks`, `send_notification`, `get_dashboard_info`, `cleanup_history`,
619
677
  `manage_secrets`, `get_audit_log`,
620
- `emit_event`.
678
+ `emit_event`,
679
+ `pipeline_validate`, `pipeline_apply`, `pipeline_export`.
621
680
 
622
681
  A bundled skill, `scheduled-job-best-practices`, teaches the agent safe defaults:
623
682
  least privilege, Quality Gates, timeout, matrix concurrency, DAG rules and a
@@ -654,7 +713,9 @@ It never changes run status, retries, Quality Gates, DAG dependencies or history
654
713
  messages are converted to normalized bag-of-words vectors stored in SQLite,
655
714
  compared by cosine similarity against the window, and suppressed above
656
715
  `threshold` (0.85 default). Important statuses are never suppressed. No new
657
- dependencies and no external embedding model are required.
716
+ dependencies and no external embedding model are required. CJK text (Chinese,
717
+ Japanese, Korean) is tokenized into overlapping bigrams, so messages without
718
+ spaces produce non-zero vectors and participate in dedup too.
658
719
  - `notifications.summary` renders at most three short lines for Telegram and
659
720
  toasts. The model returns strict JSON `{"lines": [...]}`; any failure falls
660
721
  back to deterministic truncation (status, error, runtime/tokens/cost), and
@@ -221,6 +221,36 @@ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置
221
221
  嵌套子代理)见
222
222
  [ARCHITECTURE.md](ARCHITECTURE.md#permission-enforcement--known-limitations-spike-291-findings)。
223
223
 
224
+ ### 一次性 git worktree(W-1)
225
+
226
+ 设置 `worktree: true` 后,每次运行都会在 `workingDirectory` 的全新 `git worktree`
227
+ 中执行,并使用独立的 `agent-steward/...` 分支。包装脚本在调度门禁之后、启动
228
+ `opencode` 之前创建 worktree,通过提示词前导和 `AGENT_STEWARD_WORKTREE` 把路径传给
229
+ Agent;创建失败时(例如目录不是 git 仓库)运行会 fail-closed 终止。每次运行的路径和
230
+ 分支都唯一,因此矩阵克隆和并行任务可以各自写文件,互不影响主工作区和彼此——无需
231
+ Docker 即可安全扇出。
232
+
233
+ Worktree 位于 `PLUGIN_DIR/worktrees`,旁边的 `.json` sidecar 用于清理。运行结束后,
234
+ 包装脚本会删除 worktree 及其 `agent-steward/...` 分支,任务失败时也会删除(W-2.1)。
235
+ 崩溃留下的残留会在下一次运行时顺带清扫:超过 24 小时的 worktree 被删除,没有工作
236
+ 副本的 sidecar 被清理,`.cleanup-lock` 串行化并发清扫(W-2.2)。清理只处理 worktree
237
+ 根目录下带 sidecar 且分支为 `agent-steward/` 的路径,因此不会删除外来目录和正在
238
+ 运行的 worktree。worktree 不隔离网络、API 或数据库访问,Quality Gate 仍以你的
239
+ 用户权限运行。
240
+
241
+ ### Guard 条件(W-3)
242
+
243
+ 可以为任务设置 `guards` — 运行前必须满足的条件:可选的 shell `command`
244
+ (exit 0 表示通过,非 0 表示跳过,`timeoutSeconds` 1..3600)和/或 `semantic`
245
+ 条件 — `filesExist` / `filesMissing`(相对路径,在 worktree 或 cwd 内解析)、
246
+ `branch`(glob)和 `changedPaths`(glob;`changedSince..HEAD` 的 diff 中至少
247
+ 匹配一个路径,默认 `HEAD~1`)。所有条件按「与」组合:任一检查失败或出错时,
248
+ 运行会被优雅跳过,并在历史记录和 GUI 中显示为可见的 `skipped` 状态
249
+ (`record-history --skip`;不发送通知、不触发成功/错误链)。检查在创建
250
+ worktree 之后执行,因此与 `worktree: true` 组合时它们在新 worktree 内运行;
251
+ `guard-run.js` 帮助程序位于 `src/core/guard-run.ts`,`src/core/guard.ts`
252
+ 提供规范化、求值和退出码约定(4 = 跳过)。
253
+
224
254
  ## 编排
225
255
 
226
256
  ### 链式调度
@@ -283,6 +313,20 @@ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置
283
313
  - `matrix_control` 的 `action: "cleanup"` 会移除父任务已不存在的孤立
284
314
  克隆;同样的清理也会在插件启动时运行。
285
315
 
316
+ ### 流水线即代码
317
+
318
+ 整个 DAG 可以声明在 `opencode.pipeline.yaml` 中并按代码应用:
319
+
320
+ - `version: 1`、流水线 `name`、可选的 `defaults` 和 1..200 个 `steps`。
321
+ - 每个步骤有稳定的 `id`、`prompt` 和可选的 `needs`(转换为 `dependsOn`)。
322
+ - `trigger: cron`(默认)需要 `schedule`;`trigger: once` 需要 `runAt`;
323
+ `trigger: dag` 只在其 `needs` 成功后运行。
324
+ - `matrix.workspaces` 按 workspace 名称或 id 将步骤扇出。
325
+ - `agent-steward pipeline validate|apply|export` 与 `pipeline_validate`、
326
+ `pipeline_apply`、`pipeline_export` 工具覆盖整个生命周期;apply 幂等、
327
+ 跳过未变化的步骤,且从不删除 stale 任务。
328
+ - 完整格式与限制:[PIPELINE.md](PIPELINE.md)。
329
+
286
330
  ## 多仓库工作区
287
331
 
288
332
  工作区是一个命名目录:id、name、path、可选的 git 远程仓库和颜色。
@@ -308,7 +352,9 @@ OpenCode 动作的 `effect: "deny"` 规则,而 `allowedTools`(一旦设置
308
352
  `active-profile` 文件 → `default`。切换配置档案会写入标记文件,并且需要
309
353
  重启 OpenCode,因为插件目录在模块加载时解析。
310
354
  - 每个配置档案的仪表板端口:`OPENCODE_SCHEDULER_PORT` 环境变量 → 来自
311
- `profile.json` 的端口 → 服务器默认值(3782,其次 4782/5782 回退)。
355
+ `profile.json` 的端口 → 服务器默认值(3782,其次 4782/5782 回退)。新配置档案
356
+ 会分配 3783 起的第一个空闲端口,跳过 3782/4782、其他配置档案 `profile.json`
357
+ 中已记录的端口以及 `OPENCODE_SCHEDULER_PORT`。
312
358
  - RPC:`get_profiles` 列出配置档案及其目录、端口和活动标志;
313
359
  `set_profile` 切换活动配置档案(会提示重启);`create_profile` /
314
360
  `delete_profile` 管理命名配置档案(`default` 不能被删除)。
@@ -566,14 +612,14 @@ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
566
612
 
567
613
  ## Agent 接口
568
614
 
569
- 二十六个工具:`schedule_task`、`list_tasks`、`update_task`、`delete_task`、
615
+ 二十九个工具:`schedule_task`、`list_tasks`、`update_task`、`delete_task`、
570
616
  `run_task_now`、`pause_task`、`resume_task`、`get_history`、`get_task_logs`、`dry_run`、
571
617
  `manage_workspaces`、`matrix_control`(results/cancel/cleanup/preview)、`get_metrics`、
572
618
  `get_analytics`、`self_analysis`(健康评分、异常、趋势)、`manage_settings`、
573
619
  `manage_local_ai`、`manage_templates`、`manage_profiles`、
574
620
  `transfer_tasks`、`send_notification`、`get_dashboard_info`、`cleanup_history`、
575
621
  `manage_secrets`、`get_audit_log`、
576
- `emit_event`。
622
+ `emit_event`、`pipeline_validate`、`pipeline_apply`、`pipeline_export`。
577
623
 
578
624
  捆绑的 skill `scheduled-job-best-practices` 教会 agent 安全的默认做法:
579
625
  最小权限、Quality Gate、超时、矩阵并发、DAG 规则以及
@@ -611,7 +657,9 @@ GUI 面板)支持 `list`、`set` 和 `delete`。密钥名匹配
611
657
  在窗口内按余弦相似度比较,超过
612
658
  `threshold`(默认 0.85)时被抑制。重要状态
613
659
  永远不会被抑制。不需要新依赖,也不需要外部
614
- 嵌入模型。
660
+ 嵌入模型。CJK 文本(中文、日文、韩文)按重叠的
661
+ 二元组切分,因此没有空格的消息也会得到非零向量
662
+ 并参与去重。
615
663
  - `notifications.summary` 为 Telegram 和
616
664
  toast 最多渲染三行短文本。模型返回严格的 JSON
617
665
  `{"lines": [...]}`;任何失败都会回退到确定性截断(状态、
package/docs/MIGRATION.md CHANGED
@@ -27,8 +27,8 @@ timers, launchd, Windows Task Scheduler, or another scheduler plugin.
27
27
  automatically; on V1 restart it). If OpenCode's built-in
28
28
  schedules are enabled, disable them so two schedulers do not run the same work.
29
29
 
30
- 2. **Check Node.** `node --version` must be 20 or newer (22.5+ for the built-in SQLite
31
- driver; Node 24 recommended).
30
+ 2. **Check Node.** `node --version` must be 22.22+ (the built-in SQLite driver and
31
+ chokidar 6 require 22.22+; Node 24 recommended).
32
32
 
33
33
  3. **Inventory the old jobs.** For each job write down: name, schedule, command,
34
34
  working directory, environment variables, timeout, and what "success" means. The
@@ -0,0 +1,293 @@
1
+ # Pipeline as code
2
+
3
+ `opencode.pipeline.yaml` describes a whole workflow — triggers, DAG dependencies,
4
+ defaults and matrix fan-out — as one reviewable file. The scheduler validates it,
5
+ turns every step into a task, and applies it idempotently.
6
+
7
+ - [File format](#file-format)
8
+ - [Steps and dependencies](#steps-and-dependencies)
9
+ - [Triggers](#triggers)
10
+ - [Defaults](#defaults)
11
+ - [Matrix fan-out](#matrix-fan-out)
12
+ - [Validate, apply, export](#validate-apply-export)
13
+ - [Apply semantics](#apply-semantics)
14
+ - [Agent tools](#agent-tools)
15
+ - [Validation rules](#validation-rules)
16
+ - [Limitations](#limitations)
17
+
18
+ A ready-to-run example lives in [`opencode.pipeline.yaml`](../opencode.pipeline.yaml).
19
+
20
+ ## File format
21
+
22
+ ```yaml
23
+ version: 1
24
+ name: nightly-release
25
+ description: Lint, test and build the repository every night.
26
+
27
+ defaults:
28
+ timeoutSeconds: 1800
29
+ retryCount: 1
30
+ retryDelay: 120
31
+
32
+ steps:
33
+ - id: lint
34
+ schedule: "0 2 * * *"
35
+ prompt: Run the linter and fix what it reports.
36
+ qualityGate: npm run lint
37
+
38
+ - id: test
39
+ needs: [lint]
40
+ trigger: dag
41
+ prompt: Run the tests and fix failures.
42
+ qualityGate: npm test
43
+ ```
44
+
45
+ | Field | Required | Meaning |
46
+ | --- | --- | --- |
47
+ | `version` | yes | Format version. Must be `1`. |
48
+ | `name` | yes | Pipeline name, 1–120 characters: letters, digits, space, `.`, `_`, `-`. |
49
+ | `description` | no | Free-form text for humans. |
50
+ | `defaults` | no | Values inherited by every step (see [Defaults](#defaults)). |
51
+ | `steps` | yes | 1–200 steps. |
52
+
53
+ Every step becomes a scheduler task. Unless the step sets `name`, the task is named
54
+ `<pipeline> <step id>` — for example `nightly-release test`. The name must pass the
55
+ normal task-name rules (letters, digits, space, `.`, `_`, `-`), so keep pipeline names
56
+ and step ids reasonably short.
57
+
58
+ ## Steps and dependencies
59
+
60
+ | Field | Type | Meaning |
61
+ | --- | --- | --- |
62
+ | `id` | string | Stable step identifier, 1–64 characters. Unique within the pipeline, case-insensitive. |
63
+ | `name` | string | Task name override. Default: `<pipeline> <id>`. |
64
+ | `prompt` | string | Agent prompt. Required and non-empty. |
65
+ | `needs` | string[] | Step ids that must finish successfully first. Becomes `dependsOn`. |
66
+ | `schedule` | string | Cron expression for `trigger: cron`. |
67
+ | `trigger` | enum | `cron` (default), `once`, `dag`, `file`, `git`, `mcp-event`. |
68
+ | `runAt` | string | ISO-8601 start time for `trigger: once`. |
69
+ | `qualityGate` | string | Command that decides whether the run is successful. |
70
+ | `beforeScript` / `afterScript` | string | Hooks around the agent run. |
71
+ | `model` | string | `provider/model` (optionally `provider/model#variant`). |
72
+ | `priority` | integer | 0–10, higher runs first. |
73
+ | `timeoutSeconds` | integer | Hard timeout, at least 1. |
74
+ | `retryCount` / `retryDelay` | integer | Retries (≥ 0) and delay between them. |
75
+ | `workingDirectory` | string | Run directory for the step. |
76
+ | `workspaceId` | string | Run inside a workspace. Cannot be combined with `matrix`. |
77
+ | `allowedTools` / `deniedTools` | string[] | Per-step tool policy. A non-empty `allowedTools` is an allowlist. |
78
+ | `matrix` | object | Fan the step out over workspaces (see [Matrix fan-out](#matrix-fan-out)). |
79
+ | `timezone` | string | IANA timezone, e.g. `Europe/Moscow`. |
80
+ | `notBefore` / `notAfter` | string | Launch window as `HH:MM`; `notAfter` may be earlier (crosses midnight). |
81
+ | `activeDays` | integer[] | Allowed weekdays, `0` = Sunday. |
82
+ | `windowPolicy` | enum | `skip`, `postpone` (default) or `run` outside the window. |
83
+
84
+ Dependencies are declarative: a step listed in `needs` starts only after every
85
+ dependency's latest run succeeded. Cycles, unknown ids and self-references are rejected
86
+ before anything is created.
87
+
88
+ A step that has no trigger of its own uses `trigger: dag`:
89
+
90
+ ```yaml
91
+ steps:
92
+ - id: lint
93
+ schedule: "0 2 * * *"
94
+ prompt: Lint the repository.
95
+
96
+ - id: test
97
+ needs: [lint]
98
+ trigger: dag
99
+ prompt: Run the tests.
100
+ ```
101
+
102
+ `dag` steps are stored as dependency-only tasks (`triggerType: "file"` with an empty
103
+ schedule), just like matrix parents: the DAG engine starts them, not the OS scheduler.
104
+ They must have a non-empty `needs`; otherwise they would never run.
105
+
106
+ ## Triggers
107
+
108
+ | `trigger` | Requires | Behaviour |
109
+ | --- | --- | --- |
110
+ | `cron` (default) | `schedule` in the step or defaults | Registered with the native OS scheduler. |
111
+ | `once` | `runAt` (ISO-8601) | Runs once at the given moment; `schedule` is ignored. |
112
+ | `dag` | non-empty `needs` | Started by the DAG engine after dependencies succeed; `schedule` is ignored. |
113
+ | `file`, `git`, `mcp-event` | — | Accepted by the validator, but see [Limitations](#limitations). |
114
+
115
+ Cron expressions use the same parser as regular tasks: five fields, lists, ranges,
116
+ steps, month and weekday names, `@every 15m`, `L` and `FRI#3`. The validator calls that
117
+ parser, so an invalid expression is reported before apply.
118
+
119
+ A one-shot pipeline step:
120
+
121
+ ```yaml
122
+ steps:
123
+ - id: deploy
124
+ trigger: once
125
+ runAt: "2026-11-20T22:40:00+03:00"
126
+ prompt: Deploy the current main branch.
127
+ ```
128
+
129
+ ## Defaults
130
+
131
+ `defaults` is inherited by every step that does not set the field itself. Supported
132
+ keys: `schedule`, `trigger`, `model`, `priority`, `timeoutSeconds`, `workingDirectory`,
133
+ `retryCount`, `retryDelay`, `allowedTools`, `deniedTools`, `timezone`.
134
+
135
+ Defaults do not include `matrix`, quality gates, hooks, launch windows or
136
+ `workspaceId` — set those per step. Unknown keys under `defaults` produce warnings so
137
+ typos are visible.
138
+
139
+ ## Matrix fan-out
140
+
141
+ A step with `matrix` becomes a matrix parent: one clone per workspace, with the same
142
+ strategy, failure mode, concurrency and aggregation as a regular matrix task.
143
+
144
+ ```yaml
145
+ steps:
146
+ - id: deploy
147
+ schedule: "0 3 * * *"
148
+ prompt: Build, test and deploy this repository.
149
+ matrix:
150
+ workspaces: [frontend, backend]
151
+ strategy: parallel
152
+ failureMode: continue
153
+ concurrency: 2
154
+ aggregation: summary
155
+ createAggregator: true
156
+ ```
157
+
158
+ | `matrix` field | Default | Meaning |
159
+ | --- | --- | --- |
160
+ | `workspaces` | required | Workspace names or ids; non-empty and unique. |
161
+ | `strategy` | `parallel` | `sequential` starts the next clone after the previous one. |
162
+ | `failureMode` | `continue` | `stop` cancels the remaining clones after the first failure. |
163
+ | `concurrency` | unlimited | Maximum clones running at once. |
164
+ | `aggregation` | `summary` | `summary` writes one aggregate record for the parent. |
165
+ | `createAggregator` | `false` | Also create `<parent>-matrix-complete`. |
166
+
167
+ Workspace names are resolved when the file is applied. An unknown name produces a
168
+ warning and the step is rejected at apply time, so create workspaces first (or use
169
+ their ids). `matrix` cannot be combined with `workspaceId` on the same step.
170
+
171
+ ## Validate, apply, export
172
+
173
+ The CLI ships with the package (`agent-steward` binary):
174
+
175
+ ```bash
176
+ agent-steward pipeline validate opencode.pipeline.yaml
177
+ agent-steward pipeline apply opencode.pipeline.yaml --dry-run
178
+ agent-steward pipeline apply opencode.pipeline.yaml
179
+ agent-steward pipeline export --pipeline nightly-release
180
+ agent-steward pipeline export --pipeline nightly-release --out opencode.pipeline.yaml
181
+ ```
182
+
183
+ | Command | Flags | Result |
184
+ | --- | --- | --- |
185
+ | `pipeline validate <file>` | `--json` | Parses and validates; never changes tasks. |
186
+ | `pipeline apply <file>` | `--dry-run`, `--json` | Creates and updates tasks; `--dry-run` only prints the plan. |
187
+ | `pipeline export` | `--pipeline <name>`, `--out <file>` | Rebuilds YAML from tasks; stdout unless `--out` is given. |
188
+
189
+ Exit codes: `0` success, `1` validation/apply errors (or an unknown pipeline on export),
190
+ `2` bad arguments. Human-readable output is in Russian; add `--json` for stable machine
191
+ output.
192
+
193
+ `validate --json` returns:
194
+
195
+ ```json
196
+ { "ok": true, "errors": [], "warnings": [], "steps": 3 }
197
+ ```
198
+
199
+ `apply --json` returns the plan summary:
200
+
201
+ ```json
202
+ {
203
+ "pipeline": "nightly-release",
204
+ "dryRun": false,
205
+ "creates": ["nightly-release build"],
206
+ "updates": ["nightly-release test"],
207
+ "unchanged": ["nightly-release lint"],
208
+ "stale": []
209
+ }
210
+ ```
211
+
212
+ ## Apply semantics
213
+
214
+ Apply is a three-way diff, not a blind rewrite:
215
+
216
+ 1. Tasks of this pipeline are matched by the `pipelineName` + `pipelineStepId` markers
217
+ stored in their definition. Matching is case-insensitive.
218
+ 2. A step with no matching task is **created**.
219
+ 3. A step whose significant fields changed is **updated**; the comparison covers the
220
+ schedule, prompt, trigger, DAG dependencies, model, matrix, gates, hooks, tool
221
+ policy, launch window and pipeline markers.
222
+ 4. A step with an identical definition is **unchanged** and untouched.
223
+ 5. A task of the same pipeline that is no longer in the file is reported as **stale**.
224
+ It is never deleted automatically — delete it manually or return the step to the
225
+ file.
226
+
227
+ Tasks that do not carry pipeline markers are never read, updated or deleted by apply.
228
+ Running `apply` twice in a row is safe: the second run reports `unchanged` for every
229
+ step.
230
+
231
+ Renaming `name` starts a new pipeline identity. The old tasks keep their old marker, so
232
+ they are not matched, not reported as stale and must be removed by hand.
233
+
234
+ `export` reverses the mapping: it restores `needs` from `dependsOn`,
235
+ `matrix.workspaces` from `matrix.workspaceIds`, and the trigger from `triggerType`.
236
+ A `file` task with no schedule, no watch path and non-empty `dependsOn` is exported as
237
+ `trigger: dag`. Dependencies that point outside the pipeline are dropped with a
238
+ warning, and the default `<pipeline> <step>` name is omitted.
239
+
240
+ ## Agent tools
241
+
242
+ | Tool | Arguments | What it does |
243
+ | --- | --- | --- |
244
+ | `pipeline_validate` | `path?`, `source?` | Validates a file or inline YAML. Returns pipeline name, step count, errors and warnings. |
245
+ | `pipeline_apply` | `path?`, `source?`, `dryRun?` | Idempotent create/update. `dryRun: true` only reports the diff. |
246
+ | `pipeline_export` | `pipeline` | Returns the pipeline as YAML plus warnings. |
247
+
248
+ `pipeline_apply` writes an audit record with action `pipeline.apply`. Pass either
249
+ `path` or `source`; with neither, the tool returns an explicit error.
250
+
251
+ ## Validation rules
252
+
253
+ Validation never throws: it returns `{ ok, errors, warnings }`, where every issue has a
254
+ `path` such as `steps[2].schedule` and a human-readable message. Errors block apply;
255
+ warnings do not.
256
+
257
+ | Area | Rule |
258
+ | --- | --- |
259
+ | Format | YAML up to 1 MiB, duplicate keys rejected, aliases limited to 100. |
260
+ | `version` | Exactly `1`. |
261
+ | `name` | Non-empty, ≤ 120 characters, no control characters, limited alphabet. |
262
+ | `steps` | 1–200 entries. |
263
+ | Step `id` | Non-empty, ≤ 64 characters, must start with a letter or digit, then letters, digits, `.`, `_`, `-`; unique case-insensitively. |
264
+ | `prompt` | Non-empty. |
265
+ | Task name | Explicit `name` must pass task-name validation; generated names must not collide case-insensitively. |
266
+ | `needs` | No duplicates, no self-reference, every id must exist, no cycles. |
267
+ | Cron | A cron step needs `schedule`; the expression must parse with the shared cron parser. |
268
+ | `once` | `runAt` must be valid ISO-8601. |
269
+ | `dag` | `needs` must be non-empty; `schedule` is ignored with a warning. |
270
+ | Other triggers | `schedule` on `file`, `git` or `mcp-event` is ignored with a warning. |
271
+ | Numbers | `priority` 0–10; `timeoutSeconds` ≥ 1; `retryCount` and `retryDelay` are non-negative integers; `concurrency` ≥ 1. |
272
+ | Tools | `allowedTools` must be a non-empty array of non-empty strings; `deniedTools` must be an array of strings. |
273
+ | Matrix | `workspaces` non-empty and unique; valid enum values; no `workspaceId` on the same step. |
274
+ | Timezone | Valid IANA zone name. |
275
+ | Window | `notBefore`/`notAfter` valid `HH:MM`; `activeDays` integers 0–6; `windowPolicy` one of the enum values. |
276
+ | Unknown keys | Reported as warnings at the root, in `defaults`, in a step and in `matrix`. |
277
+
278
+ ## Limitations
279
+
280
+ - **File, git and MCP-event triggers are not fully expressible yet.** The validator
281
+ accepts the trigger names, but the format has no fields for `watchPath`, globs, git
282
+ filters or an MCP event name. Use `schedule_task` / `update_task` for those tasks in
283
+ v1.
284
+ - **No automatic deletion.** Removed steps stay as stale tasks on purpose, so a bad
285
+ edit cannot destroy a working schedule. Clean them up by hand.
286
+ - **Not in the format yet:** session continuity (`session` / `sessionMaxRuns`), `env`
287
+ and secrets, chains (`nextTaskOnSuccess` / `nextTaskOnError`), incoming webhooks,
288
+ `runWhenLoggedOff`, `paused`, and per-workspace matrix `overrides`. Use
289
+ `schedule_task` for those, or manage them after apply.
290
+ - **One profile at a time.** Apply and export work against the active profile's
291
+ database.
292
+ - **A pipeline is identified by `name`.** Treat the name as an immutable key; renaming
293
+ it leaves the old task family behind.