agent-steward 0.0.1 → 0.0.2

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 (333) hide show
  1. package/CHANGELOG.md +376 -0
  2. package/CROSS_PLATFORM.md +149 -0
  3. package/README.md +306 -15
  4. package/ROADMAP-STRATEGY.md +147 -0
  5. package/ROADMAP.md +1069 -0
  6. package/dist/core/analytics.d.ts +132 -0
  7. package/dist/core/analytics.d.ts.map +1 -0
  8. package/dist/core/analytics.js +290 -0
  9. package/dist/core/audit.d.ts +96 -0
  10. package/dist/core/audit.d.ts.map +1 -0
  11. package/dist/core/audit.js +297 -0
  12. package/dist/core/cron-to-schtasks.d.ts +20 -0
  13. package/dist/core/cron-to-schtasks.d.ts.map +1 -0
  14. package/dist/core/cron-to-schtasks.js +250 -0
  15. package/dist/core/dry-run.d.ts +102 -0
  16. package/dist/core/dry-run.d.ts.map +1 -0
  17. package/dist/core/dry-run.js +447 -0
  18. package/dist/core/file-watcher.d.ts +31 -0
  19. package/dist/core/file-watcher.d.ts.map +1 -0
  20. package/dist/core/file-watcher.js +186 -0
  21. package/dist/core/git-trigger.d.ts +82 -0
  22. package/dist/core/git-trigger.d.ts.map +1 -0
  23. package/dist/core/git-trigger.js +312 -0
  24. package/dist/core/glob.d.ts +38 -0
  25. package/dist/core/glob.d.ts.map +1 -0
  26. package/dist/core/glob.js +233 -0
  27. package/dist/core/local-ai.d.ts +52 -0
  28. package/dist/core/local-ai.d.ts.map +1 -0
  29. package/dist/core/local-ai.js +119 -0
  30. package/dist/core/lock.d.ts +57 -0
  31. package/dist/core/lock.d.ts.map +1 -0
  32. package/dist/core/lock.js +195 -0
  33. package/dist/core/matrix.d.ts +167 -0
  34. package/dist/core/matrix.d.ts.map +1 -0
  35. package/dist/core/matrix.js +724 -0
  36. package/dist/core/native-notify.d.ts +36 -0
  37. package/dist/core/native-notify.d.ts.map +1 -0
  38. package/dist/core/native-notify.js +113 -0
  39. package/dist/core/one-shot.d.ts +68 -0
  40. package/dist/core/one-shot.d.ts.map +1 -0
  41. package/dist/core/one-shot.js +139 -0
  42. package/dist/core/otel.d.ts +4 -0
  43. package/dist/core/otel.d.ts.map +1 -0
  44. package/dist/core/otel.js +98 -0
  45. package/dist/core/permissions.d.ts +69 -0
  46. package/dist/core/permissions.d.ts.map +1 -0
  47. package/dist/core/permissions.js +143 -0
  48. package/dist/core/prometheus.d.ts +23 -0
  49. package/dist/core/prometheus.d.ts.map +1 -0
  50. package/dist/core/prometheus.js +146 -0
  51. package/dist/core/ps-wrapper.d.ts +73 -0
  52. package/dist/core/ps-wrapper.d.ts.map +1 -0
  53. package/dist/core/ps-wrapper.js +1071 -0
  54. package/dist/core/record-history.d.ts +25 -0
  55. package/dist/core/record-history.d.ts.map +1 -0
  56. package/dist/core/record-history.js +471 -0
  57. package/dist/core/retention.d.ts +29 -0
  58. package/dist/core/retention.d.ts.map +1 -0
  59. package/dist/core/retention.js +98 -0
  60. package/dist/core/savings.d.ts +70 -0
  61. package/dist/core/savings.d.ts.map +1 -0
  62. package/dist/core/savings.js +87 -0
  63. package/dist/core/schedule-gate.d.ts +2 -0
  64. package/dist/core/schedule-gate.d.ts.map +1 -0
  65. package/dist/core/schedule-gate.js +211 -0
  66. package/dist/core/schedule-v2.d.ts +116 -0
  67. package/dist/core/schedule-v2.d.ts.map +1 -0
  68. package/dist/core/schedule-v2.js +586 -0
  69. package/dist/core/scheduler/index.d.ts +32 -0
  70. package/dist/core/scheduler/index.d.ts.map +1 -0
  71. package/dist/core/scheduler/index.js +63 -0
  72. package/dist/core/scheduler/linux.d.ts +44 -0
  73. package/dist/core/scheduler/linux.d.ts.map +1 -0
  74. package/dist/core/scheduler/linux.js +225 -0
  75. package/dist/core/scheduler/logs.d.ts +11 -0
  76. package/dist/core/scheduler/logs.d.ts.map +1 -0
  77. package/dist/core/scheduler/logs.js +34 -0
  78. package/dist/core/scheduler/mac.d.ts +40 -0
  79. package/dist/core/scheduler/mac.d.ts.map +1 -0
  80. package/dist/core/scheduler/mac.js +207 -0
  81. package/dist/core/scheduler/posix.d.ts +40 -0
  82. package/dist/core/scheduler/posix.d.ts.map +1 -0
  83. package/dist/core/scheduler/posix.js +89 -0
  84. package/dist/core/scheduler/registry.d.ts +41 -0
  85. package/dist/core/scheduler/registry.d.ts.map +1 -0
  86. package/dist/core/scheduler/registry.js +57 -0
  87. package/dist/core/scheduler/types.d.ts +86 -0
  88. package/dist/core/scheduler/types.d.ts.map +1 -0
  89. package/dist/core/scheduler/types.js +1 -0
  90. package/dist/core/scheduler/windows.d.ts +99 -0
  91. package/dist/core/scheduler/windows.d.ts.map +1 -0
  92. package/dist/core/scheduler/windows.js +596 -0
  93. package/dist/core/secrets.d.ts +66 -0
  94. package/dist/core/secrets.d.ts.map +1 -0
  95. package/dist/core/secrets.js +433 -0
  96. package/dist/core/self-analysis.d.ts +117 -0
  97. package/dist/core/self-analysis.d.ts.map +1 -0
  98. package/dist/core/self-analysis.js +539 -0
  99. package/dist/core/self-analysis.test.d.ts +2 -0
  100. package/dist/core/self-analysis.test.d.ts.map +1 -0
  101. package/dist/core/self-analysis.test.js +219 -0
  102. package/dist/core/session.d.ts +42 -0
  103. package/dist/core/session.d.ts.map +1 -0
  104. package/dist/core/session.js +134 -0
  105. package/dist/core/shutdown.d.ts +26 -0
  106. package/dist/core/shutdown.d.ts.map +1 -0
  107. package/dist/core/shutdown.js +49 -0
  108. package/dist/core/structured-log.d.ts +84 -0
  109. package/dist/core/structured-log.d.ts.map +1 -0
  110. package/dist/core/structured-log.js +146 -0
  111. package/dist/core/summary.d.ts +69 -0
  112. package/dist/core/summary.d.ts.map +1 -0
  113. package/dist/core/summary.js +250 -0
  114. package/dist/core/telegram.d.ts +55 -0
  115. package/dist/core/telegram.d.ts.map +1 -0
  116. package/dist/core/telegram.js +344 -0
  117. package/dist/core/triage-chain.d.ts +40 -0
  118. package/dist/core/triage-chain.d.ts.map +1 -0
  119. package/dist/core/triage-chain.js +80 -0
  120. package/dist/core/triage-compare.d.ts +68 -0
  121. package/dist/core/triage-compare.d.ts.map +1 -0
  122. package/dist/core/triage-compare.js +184 -0
  123. package/dist/core/triage-rules.d.ts +23 -0
  124. package/dist/core/triage-rules.d.ts.map +1 -0
  125. package/dist/core/triage-rules.js +196 -0
  126. package/dist/core/triage-shadow.d.ts +91 -0
  127. package/dist/core/triage-shadow.d.ts.map +1 -0
  128. package/dist/core/triage-shadow.js +160 -0
  129. package/dist/core/triage-worker.d.ts +55 -0
  130. package/dist/core/triage-worker.d.ts.map +1 -0
  131. package/dist/core/triage-worker.js +314 -0
  132. package/dist/core/triage.d.ts +76 -0
  133. package/dist/core/triage.d.ts.map +1 -0
  134. package/dist/core/triage.js +271 -0
  135. package/dist/core/watch-paths.d.ts +6 -0
  136. package/dist/core/watch-paths.d.ts.map +1 -0
  137. package/dist/core/watch-paths.js +62 -0
  138. package/dist/core/wrappers/bash.d.ts +95 -0
  139. package/dist/core/wrappers/bash.d.ts.map +1 -0
  140. package/dist/core/wrappers/bash.js +413 -0
  141. package/dist/db/git-state-repo.d.ts +16 -0
  142. package/dist/db/git-state-repo.d.ts.map +1 -0
  143. package/dist/db/git-state-repo.js +38 -0
  144. package/dist/db/history-repo.d.ts +110 -0
  145. package/dist/db/history-repo.d.ts.map +1 -0
  146. package/dist/db/history-repo.js +300 -0
  147. package/dist/db/index.d.ts +47 -0
  148. package/dist/db/index.d.ts.map +1 -0
  149. package/dist/db/index.js +120 -0
  150. package/dist/db/metrics-repo.d.ts +46 -0
  151. package/dist/db/metrics-repo.d.ts.map +1 -0
  152. package/dist/db/metrics-repo.js +103 -0
  153. package/dist/db/migrate.d.ts +24 -0
  154. package/dist/db/migrate.d.ts.map +1 -0
  155. package/dist/db/migrate.js +244 -0
  156. package/dist/db/recovery.d.ts +11 -0
  157. package/dist/db/recovery.d.ts.map +1 -0
  158. package/dist/db/recovery.js +38 -0
  159. package/dist/db/schema.d.ts +24 -0
  160. package/dist/db/schema.d.ts.map +1 -0
  161. package/dist/db/schema.js +170 -0
  162. package/dist/db/settings-repo.d.ts +8 -0
  163. package/dist/db/settings-repo.d.ts.map +1 -0
  164. package/dist/db/settings-repo.js +27 -0
  165. package/dist/db/tasks-repo.d.ts +26 -0
  166. package/dist/db/tasks-repo.d.ts.map +1 -0
  167. package/dist/db/tasks-repo.js +120 -0
  168. package/dist/db/templates-repo.d.ts +17 -0
  169. package/dist/db/templates-repo.d.ts.map +1 -0
  170. package/dist/db/templates-repo.js +57 -0
  171. package/dist/gui-experimental.cjs +1 -0
  172. package/dist/history.d.ts +60 -0
  173. package/dist/history.d.ts.map +1 -0
  174. package/dist/history.js +70 -0
  175. package/dist/i18n.d.ts +75 -0
  176. package/dist/i18n.d.ts.map +1 -0
  177. package/dist/i18n.js +357 -0
  178. package/dist/index.d.ts +858 -0
  179. package/dist/index.d.ts.map +1 -0
  180. package/dist/index.js +5179 -0
  181. package/dist/integrations.d.ts +72 -0
  182. package/dist/integrations.d.ts.map +1 -0
  183. package/dist/integrations.js +233 -0
  184. package/dist/notifications.d.ts +199 -0
  185. package/dist/notifications.d.ts.map +1 -0
  186. package/dist/notifications.js +967 -0
  187. package/dist/profiles.d.ts +60 -0
  188. package/dist/profiles.d.ts.map +1 -0
  189. package/dist/profiles.js +227 -0
  190. package/dist/rpc.d.ts +3806 -0
  191. package/dist/rpc.d.ts.map +1 -0
  192. package/dist/rpc.js +1507 -0
  193. package/dist/schtasks.d.ts +32 -0
  194. package/dist/schtasks.d.ts.map +1 -0
  195. package/dist/schtasks.js +45 -0
  196. package/dist/server.d.ts +128 -0
  197. package/dist/server.d.ts.map +1 -0
  198. package/dist/server.js +2413 -0
  199. package/dist/settings.d.ts +389 -0
  200. package/dist/settings.d.ts.map +1 -0
  201. package/dist/settings.js +770 -0
  202. package/dist/shared/jobs-view.d.ts +59 -0
  203. package/dist/shared/jobs-view.d.ts.map +1 -0
  204. package/dist/shared/jobs-view.js +146 -0
  205. package/dist/skill.d.ts +15 -0
  206. package/dist/skill.d.ts.map +1 -0
  207. package/dist/skill.js +93 -0
  208. package/dist/task-transfer.d.ts +252 -0
  209. package/dist/task-transfer.d.ts.map +1 -0
  210. package/dist/task-transfer.js +628 -0
  211. package/dist/templates.d.ts +57 -0
  212. package/dist/templates.d.ts.map +1 -0
  213. package/dist/templates.js +16 -0
  214. package/dist/types.d.ts +96 -0
  215. package/dist/types.d.ts.map +1 -0
  216. package/dist/types.js +130 -0
  217. package/dist/version.d.ts +8 -0
  218. package/dist/version.d.ts.map +1 -0
  219. package/dist/version.js +27 -0
  220. package/dist/workspaces.d.ts +113 -0
  221. package/dist/workspaces.d.ts.map +1 -0
  222. package/dist/workspaces.js +393 -0
  223. package/docs/ARCHITECTURE.md +457 -0
  224. package/docs/COMPATIBILITY.md +233 -0
  225. package/docs/CONCEPT.md +230 -0
  226. package/docs/CROSS_PLATFORM.ru.md +150 -0
  227. package/docs/CROSS_PLATFORM.zh.md +146 -0
  228. package/docs/FAQ.md +52 -0
  229. package/docs/FAQ.ru.md +53 -0
  230. package/docs/FAQ.zh.md +43 -0
  231. package/docs/FEATURES.md +698 -0
  232. package/docs/FEATURES.zh.md +655 -0
  233. package/docs/LOCAL-AI.md +300 -0
  234. package/docs/MIGRATION.md +355 -0
  235. package/docs/README.ru.md +268 -0
  236. package/docs/README.zh.md +305 -0
  237. package/docs/SAVINGS.md +61 -0
  238. package/docs/SAVINGS.ru.md +60 -0
  239. package/docs/SAVINGS.zh.md +52 -0
  240. package/docs/V1-V2-COMPATIBILITY-PLAN.md +366 -0
  241. package/docs/ZH-LOCALE-PLAN.md +324 -0
  242. package/docs/dashboard.png +0 -0
  243. package/docs/spikes/local-model-structured-output.md +81 -0
  244. package/docs/spikes/ollama-qwen3-4b-smoke.json +28 -0
  245. package/docs/spikes/ollama-qwen3-4b.json +163 -0
  246. package/gui-experimental.cjs +9 -0
  247. package/index.js +1 -0
  248. package/locales/en.json +780 -0
  249. package/locales/ru.json +780 -0
  250. package/locales/zh.json +780 -0
  251. package/package.json +133 -13
  252. package/scripts/bench-local.mjs +321 -0
  253. package/scripts/check-zh-locale.mjs +218 -0
  254. package/scripts/demo-dashboard.mjs +209 -0
  255. package/scripts/run-tests.mjs +236 -0
  256. package/scripts/spike-local-structured.mjs +182 -0
  257. package/scripts/test-locale.mjs +45 -0
  258. package/skills/scheduled-job-best-practices/SKILL.md +158 -0
  259. package/skills/scheduled-job-best-practices/references/recipes.md +163 -0
  260. package/src/core/analytics.ts +424 -0
  261. package/src/core/audit.ts +418 -0
  262. package/src/core/cron-to-schtasks.ts +288 -0
  263. package/src/core/dry-run.ts +601 -0
  264. package/src/core/file-watcher.ts +245 -0
  265. package/src/core/git-trigger.ts +391 -0
  266. package/src/core/glob.ts +226 -0
  267. package/src/core/local-ai.ts +173 -0
  268. package/src/core/lock.ts +219 -0
  269. package/src/core/matrix.ts +947 -0
  270. package/src/core/native-notify.ts +157 -0
  271. package/src/core/one-shot.ts +189 -0
  272. package/src/core/otel.ts +128 -0
  273. package/src/core/permissions.ts +200 -0
  274. package/src/core/prometheus.ts +215 -0
  275. package/src/core/ps-wrapper.ts +1140 -0
  276. package/src/core/record-history.ts +615 -0
  277. package/src/core/retention.ts +141 -0
  278. package/src/core/savings.ts +150 -0
  279. package/src/core/schedule-gate.ts +253 -0
  280. package/src/core/schedule-v2.ts +668 -0
  281. package/src/core/scheduler/index.ts +82 -0
  282. package/src/core/scheduler/linux.ts +257 -0
  283. package/src/core/scheduler/logs.ts +37 -0
  284. package/src/core/scheduler/mac.ts +270 -0
  285. package/src/core/scheduler/posix.ts +114 -0
  286. package/src/core/scheduler/registry.ts +99 -0
  287. package/src/core/scheduler/types.ts +90 -0
  288. package/src/core/scheduler/windows.ts +711 -0
  289. package/src/core/secrets.ts +503 -0
  290. package/src/core/self-analysis.ts +744 -0
  291. package/src/core/session.ts +150 -0
  292. package/src/core/shutdown.ts +69 -0
  293. package/src/core/structured-log.ts +214 -0
  294. package/src/core/summary.ts +318 -0
  295. package/src/core/telegram.ts +436 -0
  296. package/src/core/triage-chain.ts +125 -0
  297. package/src/core/triage-compare.ts +277 -0
  298. package/src/core/triage-rules.ts +238 -0
  299. package/src/core/triage-shadow.ts +240 -0
  300. package/src/core/triage-worker.ts +344 -0
  301. package/src/core/triage.ts +366 -0
  302. package/src/core/watch-paths.ts +70 -0
  303. package/src/core/wrappers/bash.ts +532 -0
  304. package/src/db/git-state-repo.ts +62 -0
  305. package/src/db/history-repo.ts +492 -0
  306. package/src/db/index.ts +166 -0
  307. package/src/db/metrics-repo.ts +170 -0
  308. package/src/db/migrate.ts +328 -0
  309. package/src/db/recovery.ts +46 -0
  310. package/src/db/schema.ts +188 -0
  311. package/src/db/settings-repo.ts +31 -0
  312. package/src/db/tasks-repo.ts +162 -0
  313. package/src/db/templates-repo.ts +77 -0
  314. package/src/gui.tsx +5222 -0
  315. package/src/history.ts +128 -0
  316. package/src/i18n.ts +413 -0
  317. package/src/index.ts +6605 -0
  318. package/src/integrations.ts +297 -0
  319. package/src/notifications.ts +1346 -0
  320. package/src/profiles.ts +254 -0
  321. package/src/rpc.ts +1609 -0
  322. package/src/schtasks.ts +75 -0
  323. package/src/server.ts +2662 -0
  324. package/src/settings.ts +1369 -0
  325. package/src/shared/jobs-view.ts +188 -0
  326. package/src/skill.ts +113 -0
  327. package/src/task-transfer.ts +944 -0
  328. package/src/templates.ts +67 -0
  329. package/src/tui-v1.tsx +341 -0
  330. package/src/tui.tsx +329 -0
  331. package/src/types.ts +191 -0
  332. package/src/version.ts +27 -0
  333. package/src/workspaces.ts +487 -0
@@ -0,0 +1,698 @@
1
+ # Features
2
+
3
+ A complete catalog of what the scheduler can do, with examples and the caveats that
4
+ matter in practice.
5
+
6
+ Translations: [中文](FEATURES.zh.md).
7
+
8
+ - [Scheduling](#scheduling)
9
+ - [Execution policy](#execution-policy)
10
+ - [Orchestration](#orchestration)
11
+ - [Multi-repository workspaces](#multi-repository-workspaces)
12
+ - [Profiles (multi-project)](#profiles-multi-project-sprint-21)
13
+ - [Workspace environment variables](#workspace-environment-variables-sprint-21)
14
+ - [Observability](#observability)
15
+ - [Management](#management)
16
+ - [Agent interface](#agent-interface)
17
+ - [Platform support](#platform-support)
18
+ - [Limits and non-goals](#limits-and-non-goals)
19
+
20
+ ## Scheduling
21
+
22
+ ### Cron schedules
23
+
24
+ Five-field cron: `minute hour day-of-month month day-of-week`. Supports lists,
25
+ ranges and steps in every field (`0 8-10,18 * * 1-5/2`), month and weekday names
26
+ (`0 9 * * MON-FRI`), `@every` sugar (`@every 15m`, `@every 2h`, `@every 1d`),
27
+ `L` as the last day of the month and the `d#n` n-th weekday form (`0 9 * * FRI#3`).
28
+
29
+ | Pattern | Example | Meaning |
30
+ | --- | --- | --- |
31
+ | Every N minutes | `*/15 * * * *` | Every 15 minutes |
32
+ | Fixed time | `0 9 * * *` | Daily at 09:00 |
33
+ | Weekdays | `30 8 * * 1-5` | 08:30 Monday to Friday |
34
+ | Monthly | `0 3 1 * *` | 03:00 on the 1st |
35
+ | Last day | `0 3 L * *` | 03:00 on the last day of the month |
36
+ | N-th weekday | `0 9 * * FRI#3` | 09:00 on the third Friday |
37
+ | Sugar | `@every 15m` | Every 15 minutes |
38
+
39
+ The Windows backend translates simple cron expressions to native Task Scheduler
40
+ triggers. Expressions `schtasks` cannot express (`L`, `#`, complex lists) or tasks
41
+ with a timezone other than the system one are registered in poll mode: the OS task
42
+ wakes the wrapper every minute and `schedule-gate` decides whether the agent runs.
43
+
44
+ ### One-shot runs
45
+
46
+ `triggerType: "once"` runs a task exactly once at a specific moment. Use either
47
+ `runAt` (ISO-8601, or a local date string such as `2026-11-13 22:40`) or
48
+ `delaySeconds` (delay from now):
49
+
50
+ ```json
51
+ {
52
+ "name": "deploy-once",
53
+ "triggerType": "once",
54
+ "runAt": "2026-11-13T22:40:00+03:00",
55
+ "prompt": "Deploy the current main branch."
56
+ }
57
+ ```
58
+
59
+ ```json
60
+ { "name": "remind-later", "triggerType": "once", "delaySeconds": 3600, "prompt": "..." }
61
+ ```
62
+
63
+ `runAt` wins when both are present. `schedule` is ignored. One-shot tasks are
64
+ registered natively (`schtasks /sc ONCE`, Linux `at`, macOS launchd cleanup
65
+ agent), are not repeated after a plugin restart, and cannot be combined with a
66
+
67
+ > **Windows locale note.** `schtasks /sd` only accepts dates in the format of the
68
+ > current Windows locale. The plugin emits `DD.MM.YYYY`, which matches Russian
69
+ > (and most European) locales. On a system with an English/US locale (`MM/DD/YYYY`)
70
+ > `schtasks` rejects the date, so one-shot tasks are not available there.
71
+ matrix.
72
+
73
+ ### Session continuity
74
+
75
+ Each scheduled run can either start a fresh OpenCode session (`new`, default),
76
+ reuse a persistent session stored on the task, or continue the latest session
77
+ (`last`, mapped to `opencode --continue`). Set `session` on the task; for
78
+ `reuse` a `sessionId` is auto-generated and stored with the task definition —
79
+ it is never accepted from user input or exported as plain text.
80
+
81
+ ```json
82
+ {
83
+ "name": "nightly-analyst",
84
+ "schedule": "0 3 * * *",
85
+ "session": "reuse",
86
+ "sessionMaxRuns": 10,
87
+ "prompt": "Refresh the analysis."
88
+ }
89
+ ```
90
+
91
+ - `session`: `new` (default), `reuse` (pass `--session <id>`), `last` (pass `--continue`).
92
+ - `sessionMaxRuns` (only for `reuse`): how many runs the reused session
93
+ survives before it is deleted (`opencode session delete`) and a fresh session
94
+ is started. Unset/0 means no limit.
95
+ - `sessionId` is per machine/profile. The internal run counter
96
+ (`sessionRunCount`) is never exported.
97
+ - Old export/import files without session fields import as `new`.
98
+
99
+ ### Timezones and launch windows
100
+
101
+ - `timezone` — IANA zone per task (e.g. `Europe/Moscow`). `nextRun`/`prevRun`,
102
+ dry-run next-run estimates and the gate evaluate cron in this zone; DST
103
+ transitions are handled (nonexistent spring-forward times are skipped).
104
+ - `notBefore` / `notAfter` — daily launch window in `HH:MM` (may cross midnight,
105
+ e.g. `22:00`–`06:00`). A run that fires outside the window is **postponed**
106
+ until the window opens (once, via a defer-file), not skipped.
107
+ - `activeDays` — allowed weekdays `0`=Sunday … `6`=Saturday (Sprint 27). Empty or
108
+ all seven means every day. Applies to cron and event triggers.
109
+ - `windowPolicy` — behaviour outside the window or on a disallowed day (Sprint 27):
110
+ `postpone` (default) waits for the next opening (max 12 hours), `skip` drops the
111
+ run, `run` executes anyway.
112
+ - `pausedUntil` — pause a task until an ISO moment. `pause_task` accepts
113
+ `until`; the plugin re-enables the task automatically at startup and on a
114
+ 5-minute timer, and `resume_task` resumes early.
115
+
116
+ ### File triggers
117
+
118
+ ```json
119
+ {
120
+ "name": "regen-api-client",
121
+ "triggerType": "file",
122
+ "watchPath": "C:\\projects\\api\\openapi.yaml",
123
+ "prompt": "Regenerate the API client from openapi.yaml and run contract tests."
124
+ }
125
+ ```
126
+
127
+ The file is watched with chokidar in the plugin host, changes are debounced. File
128
+ triggers ignore `schedule`.
129
+
130
+ #### Glob masks for file triggers (Sprint 27)
131
+
132
+ `watchGlobs` and `watchIgnore` restrict which changes count as a trigger:
133
+
134
+ Masks support `*` (does not cross `/`), `**` (any segments, including zero),
135
+ `?` (one character), `[abc]` / `[a-z]` (classes), `{a,b}` (alternatives) and `!`
136
+ (negation). Empty `watchGlobs` means "any change". Paths are normalized to POSIX
137
+ form (`\` → `/`), comparison is case-insensitive on Windows.
138
+
139
+ ### Git triggers (Sprint 27)
140
+
141
+ ```json
142
+ {
143
+ "name": "deploy-on-push",
144
+ "triggerType": "git",
145
+ "workingDirectory": "C:\\projects\\api",
146
+ "gitBranch": "main, release/*",
147
+ "gitPaths": ["src/**", "package.json"],
148
+ "gitIgnore": ["**/*.md", "CHANGELOG.md"],
149
+ "gitPollSeconds": 60,
150
+ "prompt": "Deploy the changed services to staging."
151
+ }
152
+ ```
153
+
154
+ A task with `triggerType: "git"` starts when a new commit appears in its working
155
+ directory. The first poll only remembers the current `HEAD` (baseline) and does not
156
+ start anything. Later polls compare `git diff --name-only <last>..HEAD` and start
157
+ the task when masks `gitPaths` (empty — any file) match and are not excluded by
158
+ `gitIgnore`. Filter `gitBranch` limits branches (comma-separated, supports `*` and `?`).
159
+
160
+ Poll period `gitPollSeconds` — minimum 5 seconds, default 60. State (the last
161
+ processed commit) is stored in SQLite table `git_state`, so a plugin restart does
162
+ not cause repeated runs.
163
+
164
+ ### MCP event triggers
165
+
166
+ ```json
167
+ {
168
+ "name": "on-pr-opened",
169
+ "triggerType": "mcp-event",
170
+ "mcpEvent": { "server": "github", "event": "pull_request.opened", "filter": "repo=acme/api" },
171
+ "prompt": "Review the newly opened pull request."
172
+ }
173
+ ```
174
+
175
+ Events are emitted through the `emit_event` RPC method.
176
+
177
+ ### Manual runs and pause
178
+
179
+ - `run_task_now` starts a task immediately, through the same wrapper (timeout, lock,
180
+ hooks, Quality Gate).
181
+ - `pause_task` / `resume_task` disable and re-enable the OS entry. For a matrix parent
182
+ every clone is paused.
183
+
184
+ ### Logon mode (Windows)
185
+
186
+ By default a task is **interactive only**: Task Scheduler runs it only while the user
187
+ who created it is logged on. That is the safe default — the job sees the user profile,
188
+ mapped drives, the project's `opencode.json` and saved credentials.
189
+
190
+ Some jobs must run outside business hours or on a locked/signed-out machine. Pass
191
+ `runWhenLoggedOff: true` (agent tool `schedule_task` / `update_task`, or the sidebar) to
192
+ register the task as `schtasks /ru SYSTEM` instead. The run then happens in session 0,
193
+ without the user's profile, mapped drives, network shares or saved credentials. Tasks
194
+ that depend on the user environment can fail with `Access is denied` or missing files,
195
+ so check them with `dry_run` first and prefer absolute paths.
196
+
197
+ `runWhenLoggedOff` is Windows-only: Linux crontab already runs without a logged-on user,
198
+ and a macOS launchd agent runs only inside a user session. `list_tasks` reports both the
199
+ OS value (`logonMode`) and the plugin setting (`runWhenLoggedOff`); `dry_run` shows the
200
+ same pair before the task is registered.
201
+
202
+ ## Execution policy
203
+
204
+ ### Timeout and no-overlap
205
+
206
+ Every run has `timeoutSeconds` (default 3600). On expiry the process tree is stopped
207
+ and the run is recorded as `timeout`. A lock file prevents two runs of the same task
208
+ from overlapping; the second start exits immediately and is recorded as `skipped`.
209
+
210
+ ### Pre-flight, Quality Gate, post-flight
211
+
212
+ ```json
213
+ {
214
+ "name": "nightly-deps",
215
+ "schedule": "0 2 * * *",
216
+ "beforeScript": "git pull --ff-only",
217
+ "prompt": "Update dependencies, fix breaking changes, keep the diff minimal.",
218
+ "qualityGate": "npm test",
219
+ "afterScript": "git push",
220
+ "timeoutSeconds": 2400
221
+ }
222
+ ```
223
+
224
+ | Hook | When | Effect of non-zero exit |
225
+ | --- | --- | --- |
226
+ | `beforeScript` | before the agent starts | run is cancelled, pre-flight marked failed |
227
+ | `qualityGate` | after a successful response | run is marked as a Quality Gate failure (error) |
228
+ | `afterScript` | after the run, even on failure | reported in history, does not rewrite a success |
229
+
230
+ ### Retries
231
+
232
+ `retryCount` and `retryDelay` (seconds) retry a failed run. Retry state is persisted,
233
+ so a crash cannot produce an infinite retry loop. Retries happen before chains and
234
+ dependents.
235
+
236
+ ### Model and priority
237
+
238
+ `model` selects an OpenCode model (for example `anthropic/claude-3-5-sonnet`);
239
+ omitting it uses the OpenCode default. `priority` is `0..10` and is passed through to
240
+ the scheduler entry.
241
+
242
+ ### Tool restrictions
243
+
244
+ The baseline comes from `permissions.defaultPolicy`: `hybrid` (default) allows
245
+ read/edit/glob/grep/subagent/skill/webfetch/websearch and denies `shell` and `question`,
246
+ `secure` allows only read/glob/grep/skill, and `legacy` restores the 1.5.x behaviour that
247
+ allowed everything. Task-level `legacyShell: true` re-enables `shell` under `hybrid` for
248
+ jobs migrated from older versions; `legacy` is the blunt alternative.
249
+
250
+ `allowedTools` and `deniedTools` are enforced for the `opencode run` process that the
251
+ task wrapper starts. The wrapper passes the generated `permissions` rules to the
252
+ process through `OPENCODE_CONFIG_CONTENT`; no file is written to the task workdir, so a
253
+ project-level `opencode.jsonc` is never overwritten. Each `deniedTools` entry becomes an
254
+ `effect: "deny"` rule for the matching OpenCode action, and `allowedTools` (when set)
255
+ denies every action that is not listed. The wrapper runs `opencode` with `--auto`, so
256
+ only non-denied permissions are auto-approved. Restrictions apply to the agent process,
257
+ not to hooks, Quality Gates or scripts, which still run with your user privileges. See
258
+ [ARCHITECTURE.md](ARCHITECTURE.md#permission-enforcement--known-limitations-spike-291-findings)
259
+ for the exact action mapping and known limitations (project/system config, nested
260
+ subagents).
261
+
262
+ ## Orchestration
263
+
264
+ ### Chains
265
+
266
+ ```json
267
+ { "name": "build", "nextTaskOnSuccess": "deploy", "nextTaskOnError": "notify-failure" }
268
+ ```
269
+
270
+ Exactly one follow-up task is started after a run.
271
+
272
+ ### DAG dependencies
273
+
274
+ ```json
275
+ { "name": "smoke-tests", "dependsOn": ["deploy"], "schedule": "0 * * * *" }
276
+ ```
277
+
278
+ A dependent starts only when every dependency's latest run is successful. If a
279
+ dependency is a matrix, **all clones** must be successful — a `partial` matrix blocks
280
+ dependents.
281
+
282
+ ### Matrix builds (fan-out)
283
+
284
+ One definition, one clone per workspace:
285
+
286
+ ```json
287
+ {
288
+ "name": "deploy",
289
+ "schedule": "0 3 * * *",
290
+ "prompt": "Build, test and deploy this repository. Report what changed.",
291
+ "matrix": {
292
+ "workspaceIds": ["ws-frontend", "ws-backend", "ws-mobile"],
293
+ "strategy": "parallel",
294
+ "failureMode": "continue",
295
+ "concurrency": 2,
296
+ "overrides": {
297
+ "ws-mobile": { "qualityGate": "flutter test", "prompt": "Use the Flutter toolchain." }
298
+ }
299
+ }
300
+ }
301
+ ```
302
+
303
+ | Field | Default | Meaning |
304
+ | --- | --- | --- |
305
+ | `strategy` | `parallel` | `sequential` starts the next clone only after the previous one finishes |
306
+ | `failureMode` | `continue` | `stop` aborts the remaining clones after the first failure |
307
+ | `concurrency` | unlimited | Maximum clones running at once (ignored for `sequential`) |
308
+ | `aggregation` | `summary` | `summary` writes one aggregate record for the parent |
309
+ | `createAggregator` | `false` | Also create `<parent>-matrix-complete` depending on every clone |
310
+ | `overrides` | none | Per-workspace prompt/model/Quality Gate/hooks |
311
+
312
+ Behavior worth knowing:
313
+
314
+ - Clones are named `<parent>-matrix-<workspace>`, inherit the parent definition and get
315
+ their own working directory.
316
+ - The parent never runs itself; its status is the aggregate: `success`, `error`,
317
+ `partial` (some clones failed under `continue`), or `running`.
318
+ - Editing the parent (workspaces, prompt, overrides, concurrency) **syncs** the clone
319
+ set: missing clones are created, changed ones updated, removed ones deleted. Clones
320
+ with a running job are never touched.
321
+ - Cancelling a matrix (`matrix_control` with `action: "cancel"`) marks pending clones
322
+ as cancelled and stops running ones. Deleting a parent deletes its whole family.
323
+ - `matrix_control` with `action: "cleanup"` removes orphaned clones whose parent is
324
+ gone; the same cleanup also runs at plugin startup.
325
+
326
+ ## Multi-repository workspaces
327
+
328
+ A workspace is a named directory: id, name, path, optional git remote and color.
329
+
330
+ ```json
331
+ { "id": "ws-api", "name": "API", "path": "C:\\projects\\api", "color": "#3b82f6" }
332
+ ```
333
+
334
+ Use `workspaceId` instead of `workingDirectory` to run a task in a workspace. Paths are
335
+ validated on add/update/import, and the dashboard groups tasks and runs by workspace.
336
+ Workspaces are the unit that matrix builds fan out to.
337
+
338
+ ## Profiles (multi-project, Sprint 21)
339
+
340
+ Profiles let you run several independent scheduler installations inside one plugin,
341
+ each with its own SQLite database, settings, logs, wrappers and dashboard port.
342
+ This is useful for separating projects, clients or environments (e.g. `default` and
343
+ `work`) without them seeing each other's data.
344
+
345
+ - Profile `default` uses the plugin's base directory (no migration, behaves exactly
346
+ as before Sprint 21). Named profiles live in `<base>/profiles/<name>`.
347
+ - Profile selection order: `OPENCODE_SCHEDULER_PROFILE` env var → file `active-profile`
348
+ in the base directory → `default`. Switching profiles writes the marker and requires
349
+ an OpenCode restart because plugin directories are resolved at module load time.
350
+ - Dashboard port per profile: `OPENCODE_SCHEDULER_PORT` env var → port from
351
+ `profile.json` → server default (3782, then 4782/5782 fallback).
352
+ - RPC: `get_profiles` lists profiles with dirs, ports and the active flag;
353
+ `set_profile` switches the active profile (restart hint); `create_profile` /
354
+ `delete_profile` manage named profiles (`default` cannot be deleted).
355
+
356
+ ### Workspace environment variables (Sprint 21)
357
+
358
+ Each workspace can carry env variables that are injected into every task run in that
359
+ workspace:
360
+
361
+ - `env` — explicit `KEY=VALUE` pairs stored in SQLite as JSON;
362
+ - `envFile` — optional path to a `.env` file whose variables are loaded first, then
363
+ explicit pairs override them;
364
+ - File format: `KEY=value` lines, `#` comments, blank lines, leading `export `,
365
+ values in matching quotes are unquoted;
366
+ - Key validation: `^[A-Za-z_][A-Za-z0-9_]*$`, max 100 pairs per workspace;
367
+ - Delivery: at task create/update the plugin writes `<PLUGIN_DIR>/env/<sanitized>.env`
368
+ with real values (mode `0600` on POSIX) and passes it to the wrapper
369
+ (Windows: `-EnvFile "<path>"`; POSIX: `set -a; . "$ENV_FILE"; set +a` before the
370
+ `opencode run` invocation);
371
+ - Secret masking: keys matching `/(TOKEN|SECRET|PASS|PASSWORD|KEY|CREDENTIAL|AUTH)/i`
372
+ are shown as `***` in logs and masked API responses — values never leak into logs.
373
+
374
+ ## Observability
375
+
376
+ ### History
377
+
378
+ Every run becomes a row: status, start/finish, duration, error, tokens, cost, model,
379
+ pre/post-flight results, next chained task, workspace and tool restrictions. Statuses:
380
+
381
+ | Status | Meaning |
382
+ | --- | --- |
383
+ | `running` | started, not finished |
384
+ | `success` | finished, no Quality Gate failure |
385
+ | `error` | agent error, hook failure or Quality Gate failure |
386
+ | `timeout` | killed by the timeout |
387
+ | `partial` | matrix aggregate with both successes and failures |
388
+
389
+ ### Metrics
390
+
391
+ Per-task counters and totals: runs, successes, errors, tokens, cost. Available through
392
+ `get_history`, the RPC layer and the dashboard header. A 14-day analytics slice —
393
+ Per-day buckets (UTC), success rate, token-based cost estimate, top tasks by cost,
394
+ matrix and model breakdowns — is available through `get_analytics` /
395
+ `GET /api/analytics` and the dashboard's **Analytics for the period** block.
396
+ pruned automatically (age and size limits, see Settings) and can be exported as
397
+ CSV/JSON (`GET /api/history/export`), or as OTLP/JSON for OpenTelemetry
398
+ (`GET /api/history/export?format=otlp`).
399
+
400
+ The same slice carries a **"Saved"** counter: runs that spent tokens without
401
+ a recorded cost (local models, prepaid plans) are priced against a reference cloud
402
+ rate of $0.01 / 1k tokens. The KPI is labelled as an estimate and links to
403
+ [docs/SAVINGS.md](SAVINGS.md) with the full methodology; `report.savings` exposes
404
+ `savedUsd`, `runs`, `tokens` and a per-task breakdown.
405
+
406
+ ### Prometheus
407
+
408
+ `GET /metrics` exposes the Prometheus text format (0.0.4): `opencode_scheduler_info`,
409
+ `up`, `queue_depth`, `history_records`, `runs_total{task,status}`,
410
+ `errors_total{task}`, `tokens_total{task}`, `cost_usd_total{task}` and the
411
+ `run_duration_seconds` histogram (1 s … 3600 s + `+Inf`). `runs_total` has
412
+ separate `success`, `error` and `partial` statuses; `errors_total` counts only
413
+ errors and timeouts, so `partial` never inflates it. Values are read from
414
+ SQLite at scrape time, so no extra agent or exporter process is required.
415
+
416
+ ### Structured logs
417
+
418
+ Every run start/finish and every webhook decision is appended to
419
+ `<PLUGIN_DIR>/logs/runs.jsonl` (one JSON object per line, 10 MiB rotation to
420
+ `runs.jsonl.1`). `GET /api/logs` returns newest-first records and supports `task`,
421
+ `status`, `event`, `since`, `until`, `limit` and `format=jsonl`. The database
422
+ `history` table remains the source of truth for aggregates; JSONL is for log
423
+ shipping and debugging and never blocks a run if writing fails.
424
+
425
+ ### Incoming webhooks
426
+
427
+ `POST /api/hooks/:task?token=…` starts a task from GitHub Actions, GitLab CI or any
428
+ external system. The request must carry an HMAC-SHA256 of the raw body in
429
+ `X-Scheduler-Signature: sha256=<hex>` (GitHub's `X-Hub-Signature-256` and a bare
430
+ hex digest are also accepted). The token may instead come from `X-Scheduler-Token`
431
+ or `X-Gitlab-Token`. An optional `X-Scheduler-Timestamp` is checked against
432
+ `timestampToleranceSeconds`. Hooks are disabled by default; enabling them with empty
433
+ credentials generates a token and secret automatically. Errors: 401 (bad
434
+ token/signature/timestamp), 403 (channel disabled or credentials missing), 404
435
+ (unknown task), 413 (body over `maxBodyBytes`). The dashboard still binds to
436
+ localhost only, so external CI needs a tunnel or self-hosted runner.
437
+
438
+ #### Replay protection guidance for senders
439
+
440
+ Both remaining authentication modes are replayable at the transport level, so
441
+ senders should be chosen with that in mind:
442
+
443
+ - **Signature with `timestampToleranceSeconds = 0` (legacy).** The HMAC covers
444
+ only the body, so any intercepted request can be replayed verbatim, forever.
445
+ Set a non-zero tolerance and send `X-Scheduler-Timestamp` (unix seconds or
446
+ milliseconds): the signature then covers `<timestamp>.<body>` and a captured
447
+ request stops working outside the window.
448
+ - **Token-only mode.** A bearer token in a query parameter or header is also
449
+ replayable — the scheduler cannot distinguish a repeat from a replay. If you
450
+ cannot switch to timestamp-signed HMAC, mitigate instead: keep the token in
451
+ CI secrets (not in code), rotate it regularly, scope one token per task, and
452
+ make the target task idempotent so an accidental replay does no harm.
453
+ - **GitHub Actions.** GitHub does not send `X-Scheduler-Timestamp` itself, so
454
+ `X-Hub-Signature-256` alone runs in legacy (replayable) mode. Prefer a
455
+ workflow step that signs `<timestamp>.<body>` with the shared secret, or rely
456
+ on short-lived workflow runs and idempotent tasks.
457
+ - The scheduler itself performs no replay cache: unique-request deduplication
458
+ (e.g. event IDs) is the sender's responsibility.
459
+
460
+ ### OpenTelemetry
461
+
462
+ History can be exported as OTLP/JSON: one span per run, deterministic 32-hex
463
+ `traceId` and 16-hex `spanId`, nanosecond timestamps, task/status/duration/tokens/
464
+ cost/model/error attributes and OK/ERROR status. The output can be posted to an
465
+ OpenTelemetry Collector or inspected directly.
466
+
467
+ ### Logs
468
+
469
+ Each run appends to `logs/<task>.log` — pre/post hooks, Quality Gate output and the
470
+ agent's stdout/stderr. `get_task_logs` returns the tail (1–1000 lines).
471
+
472
+ ### Dry run
473
+
474
+ `dry_run` simulates one task or every task: execution order, DAG prerequisites, matrix
475
+ fan-out and estimated time. Nothing is executed and nothing is created.
476
+
477
+ ### Dashboard
478
+
479
+ A local web dashboard shows tasks, matrix tabs, per-workspace summaries, DAG markers,
480
+ metrics, a 14-day analytics block (KPIs, daily bar chart, top tasks by cost, matrices),
481
+ recent runs and CSV/JSON history export. It binds to localhost and has no authentication
482
+ — do not expose it. `GET /api/health` reports plugin version, scheduler backend, queue
483
+ depth and database status for external monitoring.
484
+
485
+ ## Management
486
+
487
+ ### Templates
488
+
489
+ Save a definition as a reusable template, then create tasks from it with one click or
490
+ one tool call.
491
+
492
+ ### Export and import
493
+
494
+ `export_tasks` produces a versioned JSON document with definitions, including matrix
495
+ configuration and `matrixParentId`. `import_tasks` validates every record and reports
496
+ per-record errors instead of failing the whole batch. Unknown workspaces and invalid
497
+ matrix combinations are rejected explicitly.
498
+
499
+ ### Notifications
500
+
501
+ Notifications on run completion through three independent channels — webhook, Telegram
502
+ and native OS notifications — configurable in settings and testable with
503
+ `test_notification`.
504
+
505
+ - **Webhook delivery:** per-task completion (success/error/timeout) through a
506
+ Discord/Slack compatible webhook (`{ content, text }`). `webhook.timeoutMs`
507
+ (default 10 000), `webhook.retryCount` (default 2) and `webhook.retryDelayMs`
508
+ (default 1000) control the request; network errors, timeouts, HTTP 5xx and 429 are
509
+ retried with exponential backoff (capped at 30 s), other 4xx are not.
510
+ - **Telegram:** Bot API `sendMessage` with `chat_id`, `parse_mode` (`HTML`,
511
+ `MarkdownV2`, `Markdown` or plain text), optional silent mode, forum topic
512
+ (`messageThreadId`) and a dashboard link (`includeDashboardLink`). Configured in the
513
+ GUI or with `manage_settings` → `notifications.telegram`. `botToken` and `chatId`
514
+ may instead come from `OPENCODE_SCHEDULER_TELEGRAM_BOT_TOKEN` and
515
+ `OPENCODE_SCHEDULER_TELEGRAM_CHAT_ID` so no secret is stored in `settings.json`;
516
+ the token is masked in every error message and log line.
517
+ - **Native OS notifications:** Windows Toast (PowerShell/WinRT), macOS Notification
518
+ Center (`osascript`) and Linux `notify-send`. No extra dependency: `node-notifier`
519
+ is not required. `notifications.native.sound` toggles the sound where supported.
520
+ - **Templates:** `templates.success` and `templates.error` accept placeholders
521
+ `{task}`, `{status}`, `{duration}`, `{error}`, `{emoji}`, `{cost}` and `{tokens}`.
522
+ When token/cost data is present the message gains a ` · 1500 tok · $0.0060` suffix.
523
+ - **Filters:** `filters.include` / `filters.exclude` are task-name patterns with `*`
524
+ wildcards; an empty include list means all tasks, exclude wins.
525
+ - **Quiet hours:** `quietHours.enabled` with `from`/`to` in `HH:MM` (an overnight
526
+ range such as 22:00 → 08:00 is supported). During the window `success` and
527
+ `partial` are suppressed while `error` and `timeout` are still delivered.
528
+ - **Dedup (31.2):** `notifications.dedup.enabled` groups identical task + status
529
+ notifications inside `windowMinutes` (default 60). With `suppressDuplicates`,
530
+ non-important repeats are suppressed; statuses listed in `importantStatuses`
531
+ (default `error`, `timeout`) are always delivered and get a localized repeat
532
+ suffix, e.g. `(repeat 3)`. Counters live in the SQLite `notification_dedup`
533
+ table, so they survive the short-lived `record-history` processes, and
534
+ `maxCount` caps the counter.
535
+ - **Matrix notifications:** on family completion — success, `partial` (`onPartial`)
536
+ and all clones failed (`onAllFailed`). A stuck detector reports clones running
537
+ longer than `matrix.stuckAfterMinutes` (default 60, `0` disables) once per run.
538
+ - **Digest:** `digest.enabled` sends a daily (`frequency: "daily"`, at `digest.time`)
539
+ or weekly (Mondays, catch-up afterwards) summary: runs, success rate, cost, tokens
540
+ and top errors through every enabled channel. Also available as the
541
+ `send_digest` RPC and the GUI's **Send digest now** button (manual sends
542
+ do not move the schedule).
543
+ - **Test button:** sends a test message to `all`, `webhook`, `telegram` or `native`
544
+ and reports per-channel success/failure. Failures in one channel never block the
545
+ others and never throw into the task run.
546
+
547
+ ### Secrets (Sprint 26)
548
+
549
+ Encrypted secret storage in `<PLUGIN_DIR>/secrets.json` with AES-256-GCM and a
550
+ 32-byte key file `secrets.key` (mode 0600 on POSIX; on Windows an ACL granting only
551
+ the current user, applied via `icacls`). The `manage_secrets` tool (and the **Secrets**
552
+ GUI panel) supports `list`, `set` and `delete`. Secret names match
553
+ `[A-Za-z0-9_.-]` and are up to 64 characters; list shows only name, masked preview
554
+ (`••••` + last 4 chars) and update time — never the value.
555
+
556
+ In task workspace `env`, reference a secret as `${secret:NAME}`. The value is
557
+ substituted at run time (missing secrets resolve to an empty string with a
558
+ name-only warning). Secret references survive masking — they are shown verbatim in
559
+ the GUI env editor — while literal secret-like values (`TOKEN=`, `PASSWORD=`, …)
560
+ are masked as `***` in logs, structured logs, history and audit.
561
+
562
+ #### Recovering a quarantined secrets store
563
+
564
+ If `secrets.json` fails to parse, it is quarantined, not deleted: the file is
565
+ renamed to `secrets.json.corrupt-<timestamp>` next to the original. This is a
566
+ side effect of a read operation — recovery is **manual by design** so that no
567
+ automatic rewrite can destroy data:
568
+
569
+ 1. Find the quarantined file in the plugin directory: `secrets.json.corrupt-*`
570
+ (Windows: `%APPDATA%\opencode\windows-scheduler\`, macOS/Linux:
571
+ `~/.config/opencode/windows-scheduler/` or `$XDG_CONFIG_HOME`).
572
+ 2. Inspect it: the corruption is usually truncated JSON (interrupted write) or
573
+ manual editing. Fix the JSON syntax in a text editor.
574
+ 3. Copy the fixed file back to `secrets.json` (keep the `.corrupt-*` copy as a
575
+ backup) and verify with `manage_secrets` (`action: "list"`).
576
+ 4. If the file cannot be repaired, secrets are re-set with `manage_secrets`
577
+ (`action: "set"`); values encrypted with a lost `secrets.key` cannot be
578
+ recovered — re-enter them.
579
+ 5. In the rarer case where even the rename failed, writes stay blocked
580
+ (`corruptedStore` is set) until the `.corrupt-*` path is cleared manually —
581
+ move the broken file away yourself, then re-set the secrets.
582
+
583
+ ### Audit log (Sprint 26)
584
+
585
+ Every mutation — task create/update/delete/run, settings, templates, profiles,
586
+ workspaces, secrets, import, history cleanup — is recorded in an `audit_log`
587
+ table in SQLite with action, target type/target, actor (`mcp`/`gui`/`http`),
588
+ source, redacted details and remote address. Indexes on `ts` and `action`;
589
+ retention defaults to 90 days / 10 000 records with automatic cleanup.
590
+
591
+ The `get_audit_log` tool (and the **Audit log** GUI panel) reads the journal
592
+ with filters by `action`, `target`, `actor`, `since`/`until` and `limit`. Also
593
+ available as RPC `get_audit` and HTTP `GET /api/audit`. Secret values in details
594
+ are redacted; `${secret:NAME}` references are preserved verbatim.
595
+
596
+ ### Crash recovery
597
+
598
+ Runs left in `running` after a crash are marked `error` on the next plugin start, so
599
+ the timeline never lies. Orphaned matrix clones are cleaned up at startup as well.
600
+
601
+ ### Settings
602
+
603
+ Global defaults (timeout, concurrency, notifications, history retention) live in
604
+ `settings.json` and are editable from the GUI/RPC layer. History retention keeps the
605
+ raw run log bounded: `history.retentionDays` (default 30) and `history.maxRecords`
606
+ (default 5000); `0` disables the respective limit. Cleanup runs at most once a day on
607
+ plugin start, records `lastCleanupAt` / `lastCleanupDeleted`, and is also available as
608
+ the `cleanup_history` RPC and the GUI's **Clear now** button. Aggregates in
609
+ `metrics.json` are not affected by retention.
610
+
611
+ ## Agent interface
612
+
613
+ Twenty-five tools: `schedule_task`, `list_tasks`, `update_task`, `delete_task`,
614
+ `run_task_now`, `pause_task`, `resume_task`, `get_history`, `get_task_logs`, `dry_run`,
615
+ `manage_workspaces`, `matrix_control` (results/cancel/cleanup/preview), `get_metrics`,
616
+ `get_analytics`, `manage_settings`, `manage_local_ai`, `manage_templates`, `manage_profiles`,
617
+ `transfer_tasks`, `send_notification`, `get_dashboard_info`, `cleanup_history`,
618
+ `manage_secrets`, `get_audit_log`,
619
+ `emit_event`.
620
+
621
+ A bundled skill, `scheduled-job-best-practices`, teaches the agent safe defaults:
622
+ least privilege, Quality Gates, timeout, matrix concurrency, DAG rules and a
623
+ create → dry-run → run-now → inspect loop. It is registered automatically by the
624
+ plugin, no installation step required.
625
+
626
+ The `manage_local_ai` tool reads, updates and tests the local triage settings
627
+ (`action: "get" | "update" | "test"`); see [LOCAL-AI.md](LOCAL-AI.md).
628
+
629
+ ## Local assistant (triage)
630
+
631
+ An optional offline model classifies failed and partial runs (category, severity,
632
+ confidence, reason). The model never suppresses a notification by itself: only a
633
+ matching rules-engine rule with `action: "skip"` can do that. It is opt-in and
634
+ fail-open: without a model the rules engine or direct delivery takes over, and
635
+ notifications are never blocked by an unavailable model.
636
+ It never changes run status, retries, Quality Gates, DAG dependencies or history.
637
+
638
+ - `mode`: `off` (default), `rules`, `llm` or `auto` (model, then rules).
639
+ - `fallback`: `rules` (default) or `notify` when the model fails or is unsure.
640
+ The legacy value `skip` is accepted as an alias for `notify`.
641
+ - `confidenceThreshold`: minimum model confidence (0..1).
642
+ - `rules` omitted means the built-in rules; `rules: []` disables them; a custom
643
+ array replaces the built-in set.
644
+ - Built-in rules cover errors, status, cost and task name
645
+ (deploy/release/backup/migration); all are notify-only. Examples are in
646
+ [LOCAL-AI.md](LOCAL-AI.md).
647
+ - The GUI shows a colored connection status (not checked / checking /
648
+ connected / no connection) and resets it when the mode, URL or model changes.
649
+ - In `llm`/`auto`, triage is asynchronous: the notification is delivered
650
+ immediately and a detached worker writes the verdict to the audit. Only
651
+ `rules` mode triages before delivery, because only rules can suppress.
652
+ - `notifications.embedding` adds semantic dedup on top of the exact dedup:
653
+ messages are converted to normalized bag-of-words vectors stored in SQLite,
654
+ compared by cosine similarity against the window, and suppressed above
655
+ `threshold` (0.85 default). Important statuses are never suppressed. No new
656
+ dependencies and no external embedding model are required.
657
+ - `notifications.summary` renders at most three short lines for Telegram and
658
+ toasts. The model returns strict JSON `{"lines": [...]}`; any failure falls
659
+ back to deterministic truncation (status, error, runtime/tokens/cost), and
660
+ delivery waits at most `summary.timeoutMs` (8 s default).
661
+ - Shadow mode logs decisions to the persistent audit journal
662
+ (`get_audit_log`, action `triage.decision`) without suppressing notifications,
663
+ so triage can be evaluated safely before it is enforced and the report
664
+ survives restarts.
665
+
666
+ Setup, model tiers by RAM, the `npm run bench:local` benchmark, shadow workflow
667
+ and troubleshooting (including `OLLAMA_CONTEXT_LENGTH`) are documented in
668
+ [LOCAL-AI.md](LOCAL-AI.md).
669
+
670
+ ## Platform support
671
+
672
+ | Capability | Windows | Linux | macOS |
673
+ | --- | --- | --- | --- |
674
+ | Cron scheduling | Task Scheduler | crontab | launchd |
675
+ | Fallback | — | — | crontab |
676
+ | Timeout and lock | PowerShell wrapper | bash wrapper | bash wrapper |
677
+ | File triggers | chokidar | chokidar | chokidar |
678
+ | History, metrics, dashboard | yes | yes | yes |
679
+ | Agent tools and skill | yes | yes | yes |
680
+ | Runs without a logged-on user | opt-in (`runWhenLoggedOff`) | always (crontab) | no (per-user agent) |
681
+
682
+ ## Limits and non-goals
683
+
684
+ - **No one-shot scheduling without `triggerType: "once"`.** One-shot runs exist
685
+ via `runAt`/`delaySeconds`; use `run_task_now` for immediate runs.
686
+ - **No session continuity beyond the built-in `session` modes.** `new`, `reuse`
687
+ and `last` cover the common cases; per-message session forking/branching is
688
+ not supported.
689
+ - **No sandbox.** Hooks, Quality Gates and prompts run with your user privileges.
690
+ - **No authentication on the dashboard.** Localhost only by design.
691
+ - **Secrets are not encrypted.** Use environment variables or an external secret
692
+ manager.
693
+ - **`allowedTools` / `deniedTools` restrict the agent process, not the whole job.**
694
+ Hooks, Quality Gates and wrapper scripts still run with your user privileges, and a
695
+ project-level or system `opencode.jsonc` can weaken task-scoped denies. See the
696
+ permission-enforcement limitations in ARCHITECTURE.md.
697
+ - **Matrix clones are separate tasks.** They appear in the task list (grouped under the
698
+ parent) and consume global concurrency slots like any other run.