opencode-windows-scheduler 1.5.4 → 1.5.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 (218) hide show
  1. package/CHANGELOG.md +65 -5
  2. package/CROSS_PLATFORM.md +107 -71
  3. package/README.md +72 -25
  4. package/ROADMAP-STRATEGY.md +6 -0
  5. package/ROADMAP.md +116 -85
  6. package/dist/core/analytics.d.ts +3 -0
  7. package/dist/core/analytics.d.ts.map +1 -1
  8. package/dist/core/analytics.js +4 -0
  9. package/dist/core/audit.d.ts +2 -1
  10. package/dist/core/audit.d.ts.map +1 -1
  11. package/dist/core/audit.js +32 -1
  12. package/dist/core/cron-to-schtasks.d.ts.map +1 -1
  13. package/dist/core/cron-to-schtasks.js +21 -4
  14. package/dist/core/file-watcher.d.ts.map +1 -1
  15. package/dist/core/file-watcher.js +16 -1
  16. package/dist/core/git-trigger.d.ts +4 -2
  17. package/dist/core/git-trigger.d.ts.map +1 -1
  18. package/dist/core/git-trigger.js +34 -16
  19. package/dist/core/lock.d.ts +14 -0
  20. package/dist/core/lock.d.ts.map +1 -1
  21. package/dist/core/lock.js +81 -4
  22. package/dist/core/matrix.d.ts.map +1 -1
  23. package/dist/core/matrix.js +3 -2
  24. package/dist/core/native-notify.d.ts.map +1 -1
  25. package/dist/core/native-notify.js +3 -0
  26. package/dist/core/one-shot.d.ts +7 -1
  27. package/dist/core/one-shot.d.ts.map +1 -1
  28. package/dist/core/one-shot.js +15 -2
  29. package/dist/core/permissions.d.ts +69 -0
  30. package/dist/core/permissions.d.ts.map +1 -0
  31. package/dist/core/permissions.js +143 -0
  32. package/dist/core/ps-wrapper.d.ts +9 -2
  33. package/dist/core/ps-wrapper.d.ts.map +1 -1
  34. package/dist/core/ps-wrapper.js +293 -96
  35. package/dist/core/record-history.d.ts +11 -0
  36. package/dist/core/record-history.d.ts.map +1 -1
  37. package/dist/core/record-history.js +106 -4
  38. package/dist/core/savings.d.ts +70 -0
  39. package/dist/core/savings.d.ts.map +1 -0
  40. package/dist/core/savings.js +87 -0
  41. package/dist/core/schedule-gate.js +7 -3
  42. package/dist/core/schedule-v2.js +1 -1
  43. package/dist/core/scheduler/index.d.ts +13 -1
  44. package/dist/core/scheduler/index.d.ts.map +1 -1
  45. package/dist/core/scheduler/index.js +35 -4
  46. package/dist/core/scheduler/linux.d.ts +4 -1
  47. package/dist/core/scheduler/linux.d.ts.map +1 -1
  48. package/dist/core/scheduler/linux.js +53 -20
  49. package/dist/core/scheduler/mac.d.ts +2 -1
  50. package/dist/core/scheduler/mac.d.ts.map +1 -1
  51. package/dist/core/scheduler/mac.js +24 -6
  52. package/dist/core/scheduler/posix.d.ts +1 -1
  53. package/dist/core/scheduler/posix.d.ts.map +1 -1
  54. package/dist/core/scheduler/posix.js +2 -2
  55. package/dist/core/scheduler/registry.d.ts +3 -2
  56. package/dist/core/scheduler/registry.d.ts.map +1 -1
  57. package/dist/core/scheduler/registry.js +6 -5
  58. package/dist/core/scheduler/windows.d.ts +49 -1
  59. package/dist/core/scheduler/windows.d.ts.map +1 -1
  60. package/dist/core/scheduler/windows.js +219 -34
  61. package/dist/core/secrets.d.ts +5 -3
  62. package/dist/core/secrets.d.ts.map +1 -1
  63. package/dist/core/secrets.js +86 -8
  64. package/dist/core/self-analysis.d.ts +117 -0
  65. package/dist/core/self-analysis.d.ts.map +1 -0
  66. package/dist/core/self-analysis.js +539 -0
  67. package/dist/core/session.d.ts +11 -3
  68. package/dist/core/session.d.ts.map +1 -1
  69. package/dist/core/session.js +34 -5
  70. package/dist/core/shutdown.d.ts +26 -0
  71. package/dist/core/shutdown.d.ts.map +1 -0
  72. package/dist/core/shutdown.js +49 -0
  73. package/dist/core/summary.d.ts +69 -0
  74. package/dist/core/summary.d.ts.map +1 -0
  75. package/dist/core/summary.js +250 -0
  76. package/dist/core/telegram.d.ts +10 -0
  77. package/dist/core/telegram.d.ts.map +1 -1
  78. package/dist/core/telegram.js +228 -47
  79. package/dist/core/triage-chain.d.ts +9 -3
  80. package/dist/core/triage-chain.d.ts.map +1 -1
  81. package/dist/core/triage-chain.js +15 -5
  82. package/dist/core/triage-compare.d.ts +68 -0
  83. package/dist/core/triage-compare.d.ts.map +1 -0
  84. package/dist/core/triage-compare.js +184 -0
  85. package/dist/core/triage-rules.d.ts.map +1 -1
  86. package/dist/core/triage-rules.js +22 -0
  87. package/dist/core/triage-shadow.d.ts +54 -10
  88. package/dist/core/triage-shadow.d.ts.map +1 -1
  89. package/dist/core/triage-shadow.js +138 -26
  90. package/dist/core/triage-worker.d.ts +55 -0
  91. package/dist/core/triage-worker.d.ts.map +1 -0
  92. package/dist/core/triage-worker.js +314 -0
  93. package/dist/core/triage.js +1 -1
  94. package/dist/core/watch-paths.d.ts +6 -0
  95. package/dist/core/watch-paths.d.ts.map +1 -0
  96. package/dist/core/watch-paths.js +62 -0
  97. package/dist/core/wrappers/bash.d.ts +15 -3
  98. package/dist/core/wrappers/bash.d.ts.map +1 -1
  99. package/dist/core/wrappers/bash.js +153 -120
  100. package/dist/db/history-repo.d.ts +1 -1
  101. package/dist/db/history-repo.d.ts.map +1 -1
  102. package/dist/db/history-repo.js +29 -14
  103. package/dist/db/schema.d.ts +1 -1
  104. package/dist/db/schema.d.ts.map +1 -1
  105. package/dist/db/schema.js +31 -0
  106. package/dist/history.d.ts +2 -2
  107. package/dist/history.d.ts.map +1 -1
  108. package/dist/history.js +3 -3
  109. package/dist/i18n.d.ts +25 -2
  110. package/dist/i18n.d.ts.map +1 -1
  111. package/dist/i18n.js +41 -3
  112. package/dist/index.d.ts +40 -4
  113. package/dist/index.d.ts.map +1 -1
  114. package/dist/index.js +345 -71
  115. package/dist/integrations.d.ts +9 -1
  116. package/dist/integrations.d.ts.map +1 -1
  117. package/dist/integrations.js +34 -6
  118. package/dist/notifications.d.ts +30 -2
  119. package/dist/notifications.d.ts.map +1 -1
  120. package/dist/notifications.js +287 -16
  121. package/dist/profiles.d.ts +1 -1
  122. package/dist/profiles.d.ts.map +1 -1
  123. package/dist/profiles.js +21 -3
  124. package/dist/rpc.d.ts +145 -8
  125. package/dist/rpc.d.ts.map +1 -1
  126. package/dist/rpc.js +81 -6
  127. package/dist/server.d.ts +20 -0
  128. package/dist/server.d.ts.map +1 -1
  129. package/dist/server.js +136 -14
  130. package/dist/settings.d.ts +89 -5
  131. package/dist/settings.d.ts.map +1 -1
  132. package/dist/settings.js +143 -23
  133. package/dist/task-transfer.d.ts +8 -1
  134. package/dist/task-transfer.d.ts.map +1 -1
  135. package/dist/task-transfer.js +2 -2
  136. package/dist/types.d.ts +8 -1
  137. package/dist/types.d.ts.map +1 -1
  138. package/dist/types.js +23 -5
  139. package/dist/workspaces.d.ts +9 -0
  140. package/dist/workspaces.d.ts.map +1 -1
  141. package/dist/workspaces.js +25 -0
  142. package/docs/ARCHITECTURE.md +40 -22
  143. package/docs/CONCEPT.md +230 -0
  144. package/docs/CROSS_PLATFORM.ru.md +150 -0
  145. package/docs/CROSS_PLATFORM.zh.md +146 -0
  146. package/docs/FAQ.md +52 -0
  147. package/docs/FAQ.ru.md +53 -0
  148. package/docs/FAQ.zh.md +43 -0
  149. package/docs/FEATURES.md +125 -48
  150. package/docs/FEATURES.zh.md +655 -0
  151. package/docs/LOCAL-AI.md +114 -16
  152. package/docs/README.ru.md +18 -13
  153. package/docs/README.zh.md +286 -0
  154. package/docs/SAVINGS.md +61 -0
  155. package/docs/SAVINGS.ru.md +60 -0
  156. package/docs/SAVINGS.zh.md +52 -0
  157. package/docs/ZH-LOCALE-PLAN.md +324 -0
  158. package/gui-experimental.cjs +8 -8
  159. package/locales/en.json +54 -1
  160. package/locales/ru.json +54 -1
  161. package/locales/zh.json +780 -0
  162. package/package.json +24 -7
  163. package/scripts/check-zh-locale.mjs +218 -0
  164. package/scripts/run-tests.mjs +236 -0
  165. package/scripts/test-locale.mjs +4 -3
  166. package/skills/scheduled-job-best-practices/SKILL.md +6 -3
  167. package/skills/scheduled-job-best-practices/references/recipes.md +1 -1
  168. package/src/core/analytics.ts +10 -0
  169. package/src/core/audit.ts +39 -1
  170. package/src/core/cron-to-schtasks.ts +23 -4
  171. package/src/core/file-watcher.ts +20 -1
  172. package/src/core/git-trigger.ts +34 -16
  173. package/src/core/lock.ts +88 -3
  174. package/src/core/matrix.ts +5 -1
  175. package/src/core/native-notify.ts +3 -0
  176. package/src/core/one-shot.ts +18 -2
  177. package/src/core/permissions.ts +200 -0
  178. package/src/core/ps-wrapper.ts +300 -96
  179. package/src/core/record-history.ts +111 -4
  180. package/src/core/savings.ts +150 -0
  181. package/src/core/schedule-gate.ts +9 -3
  182. package/src/core/schedule-v2.ts +1 -1
  183. package/src/core/scheduler/index.ts +41 -3
  184. package/src/core/scheduler/linux.ts +67 -22
  185. package/src/core/scheduler/mac.ts +24 -7
  186. package/src/core/scheduler/posix.ts +2 -2
  187. package/src/core/scheduler/registry.ts +7 -5
  188. package/src/core/scheduler/windows.ts +237 -32
  189. package/src/core/secrets.ts +101 -7
  190. package/src/core/self-analysis.ts +744 -0
  191. package/src/core/session.ts +40 -5
  192. package/src/core/shutdown.ts +69 -0
  193. package/src/core/summary.ts +318 -0
  194. package/src/core/telegram.ts +266 -55
  195. package/src/core/triage-chain.ts +15 -6
  196. package/src/core/triage-compare.ts +277 -0
  197. package/src/core/triage-rules.ts +23 -0
  198. package/src/core/triage-shadow.ts +176 -32
  199. package/src/core/triage-worker.ts +344 -0
  200. package/src/core/triage.ts +1 -1
  201. package/src/core/watch-paths.ts +70 -0
  202. package/src/core/wrappers/bash.ts +181 -138
  203. package/src/db/history-repo.ts +31 -18
  204. package/src/db/schema.ts +31 -0
  205. package/src/gui.tsx +5070 -4761
  206. package/src/history.ts +7 -3
  207. package/src/i18n.ts +55 -4
  208. package/src/index.ts +432 -74
  209. package/src/integrations.ts +50 -6
  210. package/src/notifications.ts +465 -18
  211. package/src/profiles.ts +21 -3
  212. package/src/rpc.ts +86 -6
  213. package/src/server.ts +135 -16
  214. package/src/settings.ts +305 -46
  215. package/src/task-transfer.ts +10 -3
  216. package/src/types.ts +24 -5
  217. package/src/workspaces.ts +22 -0
  218. package/dist/gui-experimental.cjs +0 -1
@@ -0,0 +1,230 @@
1
+ # CONCEPT — Верифицируемая локально-первая оркестрация агент-задач
2
+
3
+ > Статус: черновик цели (north star). Рабочее имя пакета — TBD (см. шаг rename).
4
+ > Это документ-направление: любое решение по фиче сверяется с ним.
5
+
6
+ ## TL;DR
7
+
8
+ Локальные модели слабы в открытом творчестве, но компетентны в ограниченной,
9
+ проверяемой работе. Объективная проверка дёшева и надёжна. Поэтому: дешёвая
10
+ локальная модель пытается сделать **максимум проверяемой работы**; объективный
11
+ гейт решает, принято или эскалировать в дорогое облако; каждый исход учит
12
+ систему — роутинг точнее, локальные модели способнее именно под твои задачи.
13
+ Со временем локальный сетап становится личной, приватной, дешёвой и всё более
14
+ умной рабочей силой.
15
+
16
+ Это и есть продукт. Всё остальное — обвязка.
17
+
18
+ ---
19
+
20
+ ## 1. Проблема
21
+
22
+ Разработчику, который хочет автономной agent-работы, сегодня доступны три
23
+ плохих варианта:
24
+
25
+ 1. **Не автоматизировать** — рутина (починить тесты, обновить зависимости,
26
+ бойлерплейт, извлечение, мелкие трансформации) остаётся ручной.
27
+ 2. **Автоматизировать в облаке** — токены на каждый прогон, код уходит наружу,
28
+ нет контроля над тем, что именно исполняется и куда течёт.
29
+ 3. **Автоматизировать локально наивно** — слабая модель молно выдаёт брак,
30
+ падает, двоится; доверия нет, затею бросают.
31
+
32
+ Корень всех трёх: **нет слоя, который делает агент-труд одновременно дешёвым,
33
+ приватным и проверяемо надёжным.**
34
+
35
+ - OpenCode даёт агентов, но не даёт супервизии: нет capability-роутинга,
36
+ объективных гейтов, честной экономии, learning-loop.
37
+ - Облачные оркестраторы дают масштаб, но не приватность и не локальную экономию.
38
+ - Swarm-фреймворки дают коллаборацию, но не надёжность и не экономию.
39
+
40
+ Ниша пуста: **локально-первая, верифицируемая, компаундящаяся оркестрация**.
41
+
42
+ ## 2. Ключевой инсайт
43
+
44
+ Слабость локальных моделей — не приговор, а ограничение, обходимое архитектурой:
45
+
46
+ - Локаль тянет **ограниченные, хорошо scaffolding-нутые, объективно проверяемые**
47
+ задачи. Это и есть масса реальной рутины.
48
+ - **Объективный гейт** (тесты / линт / схема / diff-applies / команда) дёшев и
49
+ не врёт. Он позволяет натравливать локаль на максимум задач: брак ловится и
50
+ эскалируется, а не уезжает в прод.
51
+ - Исходы гейта — **бесплатная разметка**: они учат роутинг («какие типы задач
52
+ локаль тянет») и копят gate-passed датасет для прокачки весов.
53
+
54
+ Проверка — не надзор, а **двигатель экономики и обучения**.
55
+
56
+ ## 3. Что это такое
57
+
58
+ **Фреймворк-супервизор поверх OpenCode**: локальный control plane, который
59
+ принимает миссии (ad-hoc или по расписанию), раскладывает их на шаги с ролями,
60
+ назначает каждый шаг **самому дешёвому способному исполнителю** (локаль →
61
+ облако только при провале гейта), объективно верифицирует результат, честно
62
+ считает экономию и компаундится — с каждой задачей дешевле и умнее под
63
+ конкретного пользователя.
64
+
65
+ Метафора: бригадир смешанной бригады. Дешёвые локальные подмастерья делают
66
+ ограниченную работу под инспекцией; дорогие облачные специалисты вызываются,
67
+ только когда инспекция завалила подмастерье; каждая инспекция делает
68
+ подмастерьев лучше именно в твоих ремёслах.
69
+
70
+ ## 4. Цель и критерии приёмки (north star)
71
+
72
+ Четыре столпа. Любая фича/ADR сверяется с ними; при конфликте порядок такой:
73
+ **надёжно > приватно > дёшево > краткосрочные фичи**, explore — управляемая
74
+ инвестиция «дёшево-сегодня» в «компаунд-завтра».
75
+
76
+ | Столп | Что значит | Метрика |
77
+ |---|---|---|
78
+ | **Дёшево** | локаль закрывает максимум gate-able задач | net-экономия $ (честная контрфактика), local share %, escalation rate, time overhead |
79
+ | **Приватно** | control plane, данные, аудит, triage локальны | % инференса/данных локально; cloud-egress только explicit и залогирован |
80
+ | **Надёжно** | ноль тихих отказов/двойных прогонов/fake-done/порчи репо | trust-инциденты = 0; гейт независим от self-report; полнота аудита |
81
+ | **Компаундится** | success rate и экономия растут под пользователя | тренд local success_rate ↑, eval-lift адаптеров, рост scaffolding-библиотеки |
82
+
83
+ Цель одним предложением: **разработчик оставляет AI-агентам свою рутину —
84
+ дёшево, приватно, надёжно — и его локальный сетап с каждой неделей работает
85
+ лучше и дешевле именно под его задачи.**
86
+
87
+ ## 5. Способности (что он делает)
88
+
89
+ - **Миссия** = цель + scope + явный критерий приёмки (гейт). Без критерия —
90
+ не миссия, а лотерея.
91
+ - **Декомпозиция** на шаги/роли (planner → implementer → reviewer …).
92
+ - **Capability-aware роутинг**: локаль по умолчанию по capability-карте;
93
+ облако — эскалация; explore/exploit баланс (учимся на неопределённых,
94
+ выжимаем на известных).
95
+ - **Объективная верификация** (keystone): провал → эскалация / ретрай / откат;
96
+ никогда «готово» на слово агента.
97
+ - **Честная экономика**: savings ledger (net-контрфактика с учётом эскалаций и
98
+ overhead), токены/стоимость по шагам и моделям.
99
+ - **Полный аудит**: кто, каким инструментом, какой файл, когда, почему
100
+ эскалировали.
101
+ - **Learning-loop**: capability-карта по типам задач → scaffolding/few-shot из
102
+ успешных решений → eval-harness → (staged) LoRA-адаптеры на gate-passed
103
+ датасете.
104
+ - **Автономность**: ad-hoc или расписание; переживает ребут; не двоится; не
105
+ зависает; leases/locks/таймауты.
106
+
107
+ ## 6. Исполнительный цикл (его задачи)
108
+
109
+ 1. Принять миссию + критерий приёмки.
110
+ 2. Разложить на шаги, назначить роли.
111
+ 3. Выбрать исполнителя шага (локаль first по capability-карте).
112
+ 4. Выполнить шаг.
113
+ 5. Прогнать объективный гейт.
114
+ 6. Pass → записать экономию + пример + метку (+ training-record).
115
+ Fail → эскалация / ретрай / откат + метка.
116
+ 7. Собрать артефакт миссии (diff/PR, отчёт, аудит-трейл).
117
+ 8. Отчитаться честно (savings, success rate, эскалации, overhead).
118
+ 9. Обновить роутинг/eval; периодически — дообучить адаптер.
119
+
120
+ ## 7. Архитектура (слои)
121
+
122
+ ```
123
+ [ триггеры: ad-hoc CLI/RPC | scheduler | file | git | mcp-event ] ← обвязка
124
+ │
125
+ [ mission intake: цель + scope + критерий приёмки (гейт) ]
126
+ │
127
+ [ planner: декомпозиция на шаги/роли ]
128
+ │
129
+ [ router: capability-карта → локаль first; explore/exploit ]
130
+ │ │ эскалация
131
+ │ ▼
132
+ │ [ облачные модели (fallback / тяжёлая артиллерия) ]
133
+ ▼
134
+ [ executor: OpenCode-агенты (локальные / облачные) ]
135
+ │
136
+ [ GATE: объективная верификация (tests/lint/schema/diff/cmd) ] ← keystone
137
+ │ pass │ fail
138
+ ▼ ▼
139
+ [ ledger: savings/audit/metrics ] [ escalate / retry / rollback ]
140
+ │
141
+ [ learning: capability-карта → scaffolding → eval → LoRA (staged) ]
142
+ │
143
+ [ control plane: локальный, приватный, аудит, dashboard ]
144
+ ```
145
+
146
+ Локально-первым является **control plane и роутинг**; инференс — гибрид
147
+ (локаль максимум, облако эскалация). Приватность = данные/аудит/управление
148
+ локальны, а не «ни одного облачного токена».
149
+
150
+ ## 8. Границы (чем НЕ является)
151
+
152
+ - Не open-ended AGI-swarm: миссии ограниченные, с явным критерием приёмки.
153
+ - Не замена способной облачной модели на сложном: облако — эскалация.
154
+ - Не отмена человеческого ревью критичного: гейт поднимает пол, не потолок.
155
+ - Не облачный SaaS и не multi-machine: локальный control plane, одна машина.
156
+ - Не «плагин-планировщик»: scheduler/уведомления/аналитика — триггеры и
157
+ обвязка, не ядро.
158
+
159
+ ## 9. Душа: flywheel
160
+
161
+ Больше задач → больше локальных попыток → больше исходов гейта → точнее
162
+ capability-карта и больше примеров → выше local success → больше экономия и
163
+ сильнее адаптеры → ещё больше задач выгодно гнать через локаль.
164
+
165
+ Этот цикл и есть продукт. Персональная, приватная, компаундящаяся capability —
166
+ ров, которого нет ни у статичного облака, ни у OpenCode core, ни у swarm-ов.
167
+
168
+ ## 10. Реальность железа (ограничение, учтённое в дизайне)
169
+
170
+ Целевая стартовая конфигурация — потребительская (пример: RTX 3050 8 ГБ,
171
+ 16 ГБ RAM). Отсюда:
172
+ - инференс локально: QLoRA/квант 3–8B;
173
+ - обучение: только QLoRA 3–4B, low-rank, накопленным gate-passed датасетом,
174
+ пакетами, а не онлайн;
175
+ - поэтому прокачка staged: сначала scaffolding/роутинг (дёшево, сразу),
176
+ веса — когда датасет и железо позволяют.
177
+ Дизайн не зависит от конкретного железа: capability-карта и гейты работают и на
178
+ слабой, и на сильной локали; меняется лишь доля задач, которую тянет локаль.
179
+
180
+ ## 11. Как поймём, что пришли (definition of done концепции)
181
+
182
+ Вертикальный срез работает end-to-end и измеримо:
183
+ 1. ad-hoc миссия с явным гейтом принята и разложена;
184
+ 2. шаги смаршрутированы локаль-first по capability-карте;
185
+ 3. гейт объективно верифицировал; провал экалировался/откатился без тихих
186
+ отказов;
187
+ 4. ledger показал честную net-экономию и escalation rate;
188
+ 5. learning-loop обновил capability-карту и положил пример/scaffolding;
189
+ 6. на фикс-наборе задач за N недель: local success_rate ↑ и net-экономия ↑
190
+ при неизменном качестве (eval не деградировал).
191
+
192
+ Когда 1–6 воспроизводимо — концепция достигнута; всё дальнейшее = масштаб
193
+ (больше типов задач, больше машин, сильнее адаптеры).
194
+
195
+ ## 12. Открытые вопросы / риски (честно)
196
+
197
+ - Качество локального вердикта на пограничных задачах → держим правила/пороги и
198
+ shadow-режим, а не слепую веру модели.
199
+ - Cost of verification (прогоны тестов) → учитывать в net-экономике, кэшировать.
200
+ - Explore может тратить впустую → capped explore-бюджет, bandit по типам задач.
201
+ - Датасет для весов копится медленно → staged-прокачка, не обещать онлайн-LoRA.
202
+ - Prompt-injection даже при gate → гейт + аудит + allowedTools как пол, а не
203
+ потолок; критичное — человеку.
204
+
205
+ ## 13. Стратегия развития: от плагина к фреймворку
206
+
207
+ Наша эволюция строится на двух столпах и постепенной абстракции:
208
+
209
+ ### 13.1 Локальный интеллект
210
+
211
+ Максимум проверяемой работы на локальных моделях с компандингом (обучением на успешных гейтах). Локаль тянет ограниченные, хорошо сформулированные, объективно проверяемые задачи — масса реальной рутины. Объективный гейт (тесты, линт, схема, diff-applies) дёшев и не врёт, поэтому локаль направляется на максимум задач: брак ловится и эскалируется, а не уезжает в прод. Исходы гейта — бесплатная разметка, которая учит роутинг и копит gate-passed датасет.
212
+
213
+ ### 13.2 Мультиагентная оркестрация
214
+
215
+ Ролевая декомпозиция миссий на шаги (planner → implementer → reviewer …). Каждый шаг назначается самому дешёвому способному исполнителю — локаль first, облако только при провале гейта. Облако используется для эскалации сложных задач, обеспечивая экономию и приватность.
216
+
217
+ ### 13.3 Непрерывное улучшение Control Plane
218
+
219
+ Существующий функционал (планировщик, DAG, матрицы, Quality Gates, GUI, аудит) — это фундамент доверия, а не отдельный продукт. Он дорабатывается наравне с ядром: локальность, приватность, наблюдаемость, гарантии отсутствия тихих отказов.
220
+
221
+ ### 13.4 Путь к универсальности
222
+
223
+ - **Этап 1:** глубокая интеграция с OpenCode v2 (текущий).
224
+ - **Этап 2:** абстракция слоя исполнения (Agent Executor Interface).
225
+ - **Этап 3:** универсальный фреймворк оркестрации, совместимый с любым агентом через MCP или стандартные API.
226
+
227
+ ---
228
+
229
+ *Любое изменение в репозитории, которое не двигает хотя бы один столп из §4 и
230
+ не согласуется с §8, — не цель, а шум.*
@@ -0,0 +1,150 @@
1
+ # Кроссплатформенность: Windows → macOS → Linux
2
+
3
+ Плагин больше не привязан к `schtasks`. Планировщик вынесен в абстрактный слой с тремя реализациями,
4
+ а обёртки запуска генерируются под целевую ОС.
5
+
6
+ Translations: [English](../CROSS_PLATFORM.md) · [中文](CROSS_PLATFORM.zh.md)
7
+
8
+ ## Архитектура
9
+
10
+ ```
11
+ src/
12
+ index.ts # инструменты, RPC, жизненный цикл плагина
13
+ gui.tsx # панель GUI (заголовок берётся из RPC)
14
+ server.ts # веб-дашборд (заголовок динамический)
15
+ core/
16
+ scheduler/
17
+ types.ts # SchedulerBackend, CreateTaskOptions, RunTaskResult
18
+ index.ts # фабрика createSchedulerBackend() + getSchedulerTitle()
19
+ windows.ts # WindowsScheduler (schtasks)
20
+ linux.ts # LinuxScheduler (crontab)
21
+ mac.ts # MacScheduler (launchd / LaunchAgents)
22
+ posix.ts # общая база для Linux/macOS (реестр задач)
23
+ registry.ts # персистентный реестр задач POSIX-бэкендов
24
+ logs.ts # чтение логов задач (кроссплатформенно)
25
+ wrappers/
26
+ bash.ts # генератор .sh-обёрток для Linux/macOS
27
+ ps-wrapper.ts # .ps1/.cmd-обёртки для Windows (как раньше)
28
+ record-history.ts # метрики/история + retry/цепочки (через бэкенд)
29
+ cron-to-schtasks.ts # cron → schtasks (только Windows)
30
+ ```
31
+
32
+ ### Интерфейс
33
+
34
+ ```ts
35
+ interface SchedulerBackend {
36
+ readonly platform: NodeJS.Platform;
37
+ readonly title: string; // «Планировщик Windows» / «OpenCode Scheduler»
38
+ createTask(options: CreateTaskOptions): Promise<void>;
39
+ deleteTask(name: string): Promise<void>;
40
+ runTask(name: string): Promise<RunTaskResult>;
41
+ listTasks(): Promise<ScheduledTaskInfo[]>;
42
+ pauseTask(name: string): Promise<void>;
43
+ resumeTask(name: string): Promise<void>;
44
+ }
45
+ ```
46
+
47
+ Фабрика выбирает реализацию по `process.platform`:
48
+ `win32 → WindowsScheduler`, `darwin → MacScheduler`, остальные → `LinuxScheduler`.
49
+
50
+ ## Как работает каждая ОС
51
+
52
+ ### Windows (поведение не изменилось)
53
+ - Задачи регистрируются в Планировщике Windows через `schtasks` в папке `\OpenCode\windows-scheduler\`.
54
+ - Обёртка: `run-task.ps1` + персональный `run-<name>.cmd` в `%APPDATA%\opencode\windows-scheduler\wrapper`.
55
+ - Логи: `%APPDATA%\opencode\windows-scheduler\logs\<name>.log`.
56
+ - cron конвертируется в schtasks (`convertCronToSchTasks`) — поддерживается тот же набор шаблонов.
57
+
58
+ ### Linux
59
+ - Задачи живут в управляемом блоке `crontab`:
60
+ ```
61
+ # >>> opencode-scheduler >>>
62
+ # task: my-task
63
+ */5 * * * * /bin/bash '/…/wrapper/run-my-task.sh' >> '/…/logs/my-task.log' 2>&1
64
+ # <<< opencode-scheduler <<<
65
+ ```
66
+ - Пауза = строка с префиксом `# PAUSED: ` (блок пересобирается из реестра).
67
+ - Задачи с триггером `file` в crontab не попадают — их запускает FileWatchManager плагина.
68
+ - Обёртка: `~/.config/opencode/windows-scheduler/wrapper/run-<name>.sh` (chmod 0755).
69
+ - Полный cron-синтаксис (в отличие от Windows), т.к. crontab понимает его нативно.
70
+ - Удаление/пересборка — только своего блока, остальные строки `crontab` не трогаются.
71
+
72
+ ### macOS
73
+ - Задачи — LaunchAgent-плисты `~/Library/LaunchAgents/com.opencode.scheduler.<name>.plist`.
74
+ - Расписание: `StartInterval` для `* * * * *` и `*/N`, `StartCalendarInterval` для `M * * * *`,
75
+ `M H * * *`, `M H * * D`.
76
+ - Пауза = `launchctl unload -w`, возобновление = `launchctl load -w`.
77
+ - Обёртка — тот же `.sh`, что и на Linux; пути конфигов:
78
+ `~/.config/opencode/windows-scheduler/` (или `$XDG_CONFIG_HOME`).
79
+
80
+ ### Общая POSIX-обёртка (`.sh`)
81
+ - `cd` в рабочую директорию, `opencode run` с промптом из файла.
82
+ - Логи пишутся в файл через `>>` и дублируются метками времени.
83
+ - Блокировка через атомарный `mkdir` — защита от параллельных запусков.
84
+ - Таймаут: дочерний процесс + watchdog (`TERM`, затем `KILL`).
85
+ - Quality Gate: `bash -lc "<команда>"` (аналог `cmd.exe /c` на Windows).
86
+ - Метрики: `node "<record-history.js>" <task> <status> <started> <duration> <error> "-" "-"` —
87
+ тот же контракт, что и в PowerShell-обёртке, поэтому история/метрики/retry/цепочки работают везде.
88
+ - `PATH` дополняется `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`, `~/.bun/bin`.
89
+
90
+ ## Матрица возможностей
91
+
92
+ | Возможность | Windows | Linux | macOS |
93
+ |---|---|---|---|
94
+ | Бэкенд планировщика | `schtasks` | `crontab` | `launchd` LaunchAgents |
95
+ | Нативный cron-поднабор | `* * * * *`, `*/N * * * *` (N ≤ 1439, 60 % N = 0), `M * * * *`, `M H * * *`, `M H * * D` | полный cron | тот же поднабор, что на Windows |
96
+ | Остальные cron-выражения | minute-poll + schedule gate | нативный cron | minute-poll + schedule gate |
97
+ | `*/N` в дне месяца / дне недели | не нативно → poll | нативно | не нативно → poll |
98
+ | Пауза / возобновление | `schtasks /change /disable` / `/enable` | строка `# PAUSED:` в управляемом блоке | `launchctl unload -w` / `load -w` |
99
+ | Файловые триггеры | in-process `FileWatchManager` | так же | так же |
100
+ | Обёртки задач | `.cmd` + `.ps1` | `.sh` | `.sh` |
101
+ | Логи | `%APPDATA%\opencode\windows-scheduler\logs` | `~/.config/opencode/windows-scheduler/logs` | как на Linux |
102
+ | Защита `secrets.key` | `icacls` (только владелец) + `chmod` как fallback | `chmod 0600` | `chmod 0600` |
103
+ | Дашборд | `127.0.0.1`, динамический заголовок | так же | так же |
104
+ | DAG / matrix / quality gates / уведомления | в плагине, не зависят от ОС | так же | так же |
105
+
106
+ ### Компромиссы
107
+
108
+ 1. **Minute-poll.** Cron-выражения вне нативного поднабора и задачи с чужой IANA-зоной
109
+ запускаются планировщиком ОС каждую минуту; `schedule-gate` решает, выполнять ли запуск.
110
+ Цена — один короткоживущий процесс-обёртка на задачу в минуту.
111
+ 2. **`M H */N * *` сознательно не конвертируется в `schtasks /sc DAILY /mo N`.**
112
+ Cron считает дни от 1-го числа каждого месяца и сбрасывается на границе месяца;
113
+ `/mo N` считает дни от даты создания задачи и не сбрасывается. Это не эквивалентные
114
+ расписания, поэтому выражение остаётся в poll-режиме. Нативный вариант потребовал бы
115
+ `MONTHLY` с явным списком `/d`, а не `DAILY /mo N`.
116
+ 3. **DST.** Шлюз работает с локальным настенным временем. Несуществующее время
117
+ (переход весной) пропускается; неоднозначное время (переход осенью) выполняется
118
+ в первом вхождении.
119
+ 4. **`*/N * * * *` на Windows** нативно только при `60 % N = 0` и `N ≤ 1439`.
120
+ Иначе задача уходит в poll-режим: `schtasks /mo N` считает от момента создания,
121
+ а cron — от начала часа.
122
+ 5. **POSIX-обёртки, crontab и launchd не исполнялись на реальных Linux/macOS**
123
+ (см. «Ограничения»); синтаксис и экранирование покрыты только тестами.
124
+
125
+ ## GUI и дашборд
126
+ - Заголовок динамический: на Windows — «Планировщик Windows», на macOS/Linux — «OpenCode Scheduler».
127
+ - Источник заголовка — новый RPC-метод `get_platform` → `{ platform, title }`.
128
+ - Заголовок используется и в панели GUI, и в fallback-панели ошибки, и в `<title>/<h1>` веб-дашборда.
129
+ - Кнопки, статусы, таблица, DAG и метрики не зависят от ОС.
130
+ - Описания инструментов (`schedule_task` и др.) подставляют актуальное название планировщика.
131
+
132
+ ## Сборка и проверки
133
+ - `npm run build` — OK, ошибок нет.
134
+ - `npm run build:gui` — OK (`gui-experimental.cjs`, ~47.7 kB).
135
+ - Проверено в runtime:
136
+ - заголовки для win32/darwin/linux;
137
+ - `cronToLaunchdSchedule` на нескольких выражениях;
138
+ - живой `listTasks()` на Windows — задачи возвращаются короткими именами (без префикса);
139
+ - экранирование `shellQuote` (кавычки, пробелы, кириллица);
140
+ - импорт `dist/index.js` проходит, `dist` не тянет `schtasks.js` напрямую.
141
+
142
+ ## Ограничения и что проверить на реальных машинах
143
+ 1. `.sh`-обёртки и crontab/launchd **не исполнялись** — на текущей Windows-машине нет `bash`/WSL.
144
+ Синтаксис и экранирование проверены вручную; нужен прогон на Linux и macOS.
145
+ 2. cron → launchd поддерживает тот же ограниченный набор шаблонов, что и Windows
146
+ (`* * * * *`, `*/N * * * *`, `M * * * *`, `M H * * *`, `M H * * D`).
147
+ На Linux доступен полный cron.
148
+ 3. Префикс задач Windows (`\OpenCode\windows-scheduler\`) и id плагина сохранены для обратной совместимости.
149
+ 4. `src/schtasks.ts` оставлен как тонкий shim для старых скриптов (`test-create.cjs`, `test-run.cjs`),
150
+ вся логика теперь в `core/scheduler/windows.ts`.
@@ -0,0 +1,146 @@
1
+ # 跨平台:Windows → macOS → Linux
2
+
3
+ 插件已不再绑定 `schtasks`。调度器被抽象成一层接口,有三种实现,运行包装脚本按目标操作系统生成。
4
+
5
+ Translations: [English](../CROSS_PLATFORM.md) · [Русский](CROSS_PLATFORM.ru.md)
6
+
7
+ ## 架构
8
+
9
+ ```
10
+ src/
11
+ index.ts # 工具、RPC、插件生命周期
12
+ gui.tsx # GUI 面板(标题来自 RPC)
13
+ server.ts # Web 仪表盘(动态标题)
14
+ core/
15
+ scheduler/
16
+ types.ts # SchedulerBackend、CreateTaskOptions、RunTaskResult
17
+ index.ts # 工厂 createSchedulerBackend() + getSchedulerTitle()
18
+ windows.ts # WindowsScheduler (schtasks)
19
+ linux.ts # LinuxScheduler (crontab)
20
+ mac.ts # MacScheduler (launchd / LaunchAgents)
21
+ posix.ts # Linux/macOS 共享基类(任务注册表)
22
+ registry.ts # POSIX 后端的持久化任务注册表
23
+ logs.ts # 跨平台任务日志读取
24
+ wrappers/
25
+ bash.ts # Linux/macOS 的 .sh 包装脚本生成器
26
+ ps-wrapper.ts # Windows 的 .ps1/.cmd 包装脚本(未变)
27
+ record-history.ts # 指标/历史 + 重试/链式任务(通过后端)
28
+ cron-to-schtasks.ts # cron → schtasks(仅 Windows)
29
+ ```
30
+
31
+ ### 接口
32
+
33
+ ```ts
34
+ interface SchedulerBackend {
35
+ readonly platform: NodeJS.Platform;
36
+ readonly title: string; // "Windows 任务计划程序" / "OpenCode Scheduler"
37
+ createTask(options: CreateTaskOptions): Promise<void>;
38
+ deleteTask(name: string): Promise<void>;
39
+ runTask(name: string): Promise<RunTaskResult>;
40
+ listTasks(): Promise<ScheduledTaskInfo[]>;
41
+ pauseTask(name: string): Promise<void>;
42
+ resumeTask(name: string): Promise<void>;
43
+ }
44
+ ```
45
+
46
+ 工厂按 `process.platform` 选择实现:
47
+ `win32 → WindowsScheduler`,`darwin → MacScheduler`,其余 → `LinuxScheduler`。
48
+
49
+ ## 各操作系统的运行方式
50
+
51
+ ### Windows(行为未变)
52
+ - 任务通过 `schtasks` 注册到 Windows 任务计划程序的 `\OpenCode\windows-scheduler\` 文件夹。
53
+ - 包装脚本:`run-task.ps1` 加每个任务专属的 `run-<name>.cmd`,位于 `%APPDATA%\opencode\windows-scheduler\wrapper`。
54
+ - 日志:`%APPDATA%\opencode\windows-scheduler\logs\<name>.log`。
55
+ - cron 会转换成 schtasks(`convertCronToSchTasks`)——支持与之前相同的模板集合。
56
+
57
+ ### Linux
58
+ - 任务保存在受管 `crontab` 块中:
59
+ ```
60
+ # >>> opencode-scheduler >>>
61
+ # task: my-task
62
+ */5 * * * * /bin/bash '/…/wrapper/run-my-task.sh' >> '/…/logs/my-task.log' 2>&1
63
+ # <<< opencode-scheduler <<<
64
+ ```
65
+ - 暂停 = 带 `# PAUSED: ` 前缀的行(块会从注册表重建)。
66
+ - `file` 触发器的任务不会进入 crontab——由插件的 FileWatchManager 启动。
67
+ - 包装脚本:`~/.config/opencode/windows-scheduler/wrapper/run-<name>.sh`(chmod 0755)。
68
+ - 支持完整 cron 语法(与 Windows 不同),因为 crontab 原生支持。
69
+ - 删除/重建只触及自己的块,`crontab` 的其他行不受影响。
70
+
71
+ ### macOS
72
+ - 任务是 LaunchAgent plist:`~/Library/LaunchAgents/com.opencode.scheduler.<name>.plist`。
73
+ - 调度:`* * * * *` 和 `*/N` 使用 `StartInterval`,`M * * * *`、`M H * * *`、`M H * * D`
74
+ 使用 `StartCalendarInterval`。
75
+ - 暂停 = `launchctl unload -w`,恢复 = `launchctl load -w`。
76
+ - 包装脚本与 Linux 相同的 `.sh`;配置路径:
77
+ `~/.config/opencode/windows-scheduler/`(或 `$XDG_CONFIG_HOME`)。
78
+
79
+ ### 共享 POSIX 包装脚本(`.sh`)
80
+ - `cd` 到工作目录,用文件中的提示词执行 `opencode run`。
81
+ - 日志通过 `>>` 追加,并带时间戳。
82
+ - 通过原子 `mkdir` 加锁——防止并行运行。
83
+ - 超时:子进程 + 看门狗(先 `TERM`,再 `KILL`)。
84
+ - Quality Gate:`bash -lc "<命令>"`(相当于 Windows 上的 `cmd.exe /c`)。
85
+ - 指标:`node "<record-history.js>" <task> <status> <started> <duration> <error> "-" "-"`——
86
+ 与 PowerShell 包装脚本相同的契约,因此历史/指标/重试/链式任务在各平台通用。
87
+ - `PATH` 追加 `/opt/homebrew/bin`、`/usr/local/bin`、`~/.local/bin`、`~/.bun/bin`。
88
+
89
+ ## 功能矩阵
90
+
91
+ | 能力 | Windows | Linux | macOS |
92
+ |---|---|---|---|
93
+ | 调度后端 | `schtasks` | `crontab` | `launchd` LaunchAgents |
94
+ | 原生 cron 子集 | `* * * * *`、`*/N * * * *`(N ≤ 1439,60 % N = 0)、`M * * * *`、`M H * * *`、`M H * * D` | 完整 cron | 与 Windows 相同的子集 |
95
+ | 其他 cron 表达式 | 分钟轮询 + schedule gate | 原生 cron | 分钟轮询 + schedule gate |
96
+ | 月/周字段中的 `*/N` | 非原生 → 轮询 | 原生 | 非原生 → 轮询 |
97
+ | 暂停 / 恢复 | `schtasks /change /disable` / `/enable` | 托管块中的 `# PAUSED:` 行 | `launchctl unload -w` / `load -w` |
98
+ | 文件触发器 | 进程内 `FileWatchManager` | 相同 | 相同 |
99
+ | 任务包装脚本 | `.cmd` + `.ps1` | `.sh` | `.sh` |
100
+ | 日志 | `%APPDATA%\opencode\windows-scheduler\logs` | `~/.config/opencode/windows-scheduler/logs` | 与 Linux 相同 |
101
+ | `secrets.key` 保护 | `icacls`(仅所有者)+ `chmod` 回退 | `chmod 0600` | `chmod 0600` |
102
+ | 仪表盘 | `127.0.0.1`,动态标题 | 相同 | 相同 |
103
+ | DAG / matrix / quality gates / 通知 | 插件内,与操作系统无关 | 相同 | 相同 |
104
+
105
+ ### 折衷
106
+
107
+ 1. **分钟轮询。** 原生子集之外的 cron 表达式,以及使用非系统 IANA 时区的任务,
108
+ 由操作系统调度器每分钟启动一次;`schedule-gate` 决定是否真正执行。
109
+ 代价是每个任务每分钟一个短生命周期的包装进程。
110
+ 2. **`M H */N * *` 故意不转换为 `schtasks /sc DAILY /mo N`。**
111
+ cron 从每月 1 日开始计数,并在月初重置;`/mo N` 从任务创建日期开始计数,
112
+ 不会在月初重置。两者并不等价,因此该表达式保持轮询模式。
113
+ 若要原生支持,应使用 `MONTHLY` 加显式 `/d` 列表,而不是 `DAILY /mo N`。
114
+ 3. **DST。** 网关按本地墙上时间工作。不存在的时间(春季前进)会被跳过;
115
+ 有歧义的时间(秋季回拨)在第一次出现时执行。
116
+ 4. **Windows 上的 `*/N * * * *`** 仅在 `60 % N = 0` 且 `N ≤ 1439` 时原生支持。
117
+ 否则回退到轮询:`schtasks /mo N` 从创建时刻计数,而 cron 从整点开始计数。
118
+ 5. **POSIX 包装脚本、crontab 和 launchd 尚未在真实 Linux/macOS 主机上执行**
119
+ (见“限制”);语法和转义仅由测试覆盖。
120
+
121
+ ## GUI 与仪表盘
122
+ - 标题是动态的:Windows 上为「Windows 任务计划程序」,macOS/Linux 上为「OpenCode Scheduler」。
123
+ - 标题来自 RPC 方法 `get_platform` → `{ platform, title }`。
124
+ - 标题同时用于 GUI 面板、错误回退面板和仪表盘的 `<title>/<h1>`。
125
+ - 按钮、状态、表格、DAG 和指标与操作系统无关。
126
+ - 工具描述(`schedule_task` 等)会替换为实际调度器名称。
127
+
128
+ ## 构建与检查
129
+ - `npm run build` — 通过,无错误。
130
+ - `npm run build:gui` — 通过(`gui-experimental.cjs`,约 47.7 kB)。
131
+ - 运行时已验证:
132
+ - win32/darwin/linux 的标题;
133
+ - 多个表达式上的 `cronToLaunchdSchedule`;
134
+ - Windows 上真实的 `listTasks()`——返回短任务名(无前缀);
135
+ - `shellQuote` 转义(引号、空格、西里尔字母);
136
+ - `dist/index.js` 可导入,`dist` 不直接引用 `schtasks.js`。
137
+
138
+ ## 限制与需要在真实机器上验证的内容
139
+ 1. `.sh` 包装脚本和 crontab/launchd **从未实际执行**——当前 Windows 机器没有 `bash`/WSL。
140
+ 语法和转义是手工检查的;仍需在 Linux 和 macOS 上跑一遍。
141
+ 2. cron → launchd 支持与 Windows 相同的有限模板集合
142
+ (`* * * * *`、`*/N * * * *`、`M * * * *`、`M H * * *`、`M H * * D`)。
143
+ Linux 上支持完整 cron。
144
+ 3. Windows 任务前缀(`\OpenCode\windows-scheduler\`)和插件 id 为向后兼容而保留。
145
+ 4. `src/schtasks.ts` 保留为旧脚本(`test-create.cjs`、`test-run.cjs`)的薄垫片;
146
+ 所有逻辑现在都在 `core/scheduler/windows.ts`。
package/docs/FAQ.md ADDED
@@ -0,0 +1,52 @@
1
+ # FAQ
2
+
3
+ Frequently asked questions and recovery scenarios. The English version of the
4
+ secrets section is also in [FEATURES.md](FEATURES.md#recovering-a-quarantined-secrets-store).
5
+
6
+ Translations: [Русский](FAQ.ru.md) · [中文](FAQ.zh.md)
7
+
8
+ ## Contents
9
+
10
+ - [Recovering secrets after a `.corrupt-*` quarantine](#recovering-secrets-after-a-corrupt--quarantine)
11
+ - [Webhook triggers: can a request be replayed?](#webhook-triggers-can-a-request-be-replayed)
12
+
13
+ ## Recovering secrets after a `.corrupt-*` quarantine
14
+
15
+ Quarantine triggers when `secrets.json` cannot be parsed (an interrupted write or
16
+ manual editing). The file is **not deleted** — it is renamed to
17
+ `secrets.json.corrupt-<timestamp>` next to the original. This is a side effect of a
18
+ read operation; recovery is **manual by design** so that no automatic rewrite can
19
+ destroy data.
20
+
21
+ Recovery steps:
22
+
23
+ 1. Find the file in the plugin directory: `%APPDATA%\opencode\windows-scheduler\`
24
+ (Windows) or `~/.config/opencode/windows-scheduler/` (macOS/Linux, or
25
+ `$XDG_CONFIG_HOME`).
26
+ 2. Open it in an editor: it is usually truncated JSON. Fix the syntax.
27
+ 3. Copy the fixed file back as `secrets.json` (keep the `.corrupt-*` copy as a
28
+ backup) and verify with `manage_secrets` (`action: "list"`).
29
+ 4. If the file cannot be repaired, re-set the secrets (`manage_secrets`,
30
+ `action: "set"`). Values encrypted with a lost `secrets.key` cannot be recovered
31
+ — re-enter them.
32
+ 5. Rare case: the rename failed and writes stay blocked ("Writing new secrets is
33
+ blocked"). Move the broken file away manually, then re-set the secrets.
34
+
35
+ ## Webhook triggers: can a request be replayed?
36
+
37
+ Yes — in both remaining authentication modes requests are replayable, so replay
38
+ protection is the sender's responsibility:
39
+
40
+ - **Signature without `timestampToleranceSeconds` (= 0, legacy).** The HMAC covers
41
+ only the body, so an intercepted request can be replayed forever. Set a non-zero
42
+ tolerance and send `X-Scheduler-Timestamp`: the signature then covers
43
+ `<timestamp>.<body>` and a request outside the window is rejected.
44
+ - **Token-only mode.** A token is also replayable — the scheduler cannot tell a
45
+ repeat from an attack. If you cannot switch to signatures: keep the token in CI
46
+ secrets, rotate it regularly, issue one token per task, and make the task
47
+ idempotent.
48
+ - **GitHub Actions** does not send `X-Scheduler-Timestamp` itself, so
49
+ `X-Hub-Signature-256` runs in legacy mode. Sign `<timestamp>.<body>` in a separate
50
+ workflow step with the shared secret.
51
+ - The scheduler keeps no replay cache — deduplicating unique requests is the
52
+ sender's responsibility.
package/docs/FAQ.ru.md ADDED
@@ -0,0 +1,53 @@
1
+ # FAQ
2
+
3
+ Частые вопросы и восстановительные сценарии. Английская версия этого раздела —
4
+ в [FEATURES.md](FEATURES.md#recovering-a-quarantined-secrets-store).
5
+
6
+ Translations: [English](FAQ.md) · [中文](FAQ.zh.md)
7
+
8
+ ## Содержание
9
+
10
+ - [Восстановление секретов после карантина `.corrupt-*`](#восстановление-секретов-после-карантина-corrupt-)
11
+ - [Webhook-триггеры: можно ли переиграть запрос (replay)?](#webhook-триггеры-можно-ли-переиграть-запрос-replay)
12
+
13
+ ## Восстановление секретов после карантина `.corrupt-*`
14
+
15
+ Карантин срабатывает, когда `secrets.json` не парсится (обрыв записи,
16
+ ручное редактирование). Файл **не удаляется**, а переименовывается в
17
+ `secrets.json.corrupt-<метка времени>` рядом с оригиналом. Это побочный эффект
18
+ операции чтения — автоматического восстановления нет, чтобы ничто не могло
19
+ затереть данные.
20
+
21
+ Порядок восстановления:
22
+
23
+ 1. Найдите файл в каталоге плагина: `%APPDATA%\opencode\windows-scheduler\`
24
+ (Windows) или `~/.config/opencode/windows-scheduler/` (macOS/Linux,
25
+ либо `$XDG_CONFIG_HOME`).
26
+ 2. Откройте его в редакторе: обычно это обрезанный JSON. Исправьте синтаксис.
27
+ 3. Верните исправленный файл под именем `secrets.json` (копию `.corrupt-*`
28
+ оставьте как бэкап) и проверьте `manage_secrets` (`action: "list"`).
29
+ 4. Если файл не восстанавливается — задайте секреты заново
30
+ (`manage_secrets`, `action: "set"`). Значения, зашифрованные утерянным
31
+ `secrets.key`, восстановить нельзя — только повторный ввод.
32
+ 5. Редкий случай: rename не удался и запись заблокирована
33
+ («Запись новых секретов заблокирована»). Уберите битый файл вручную
34
+ (переместите в сторону), затем задайте секреты заново.
35
+
36
+ ## Webhook-триггеры: можно ли переиграть запрос (replay)?
37
+
38
+ Да, в обоих оставшихся режимах аутентификации запросы replayable — защита от
39
+ повтора лежит на отправителе:
40
+
41
+ - **Подпись без `timestampToleranceSeconds` (= 0, legacy).** HMAC покрывает
42
+ только тело — перехваченный запрос можно переиграть бесконечно. Задайте
43
+ ненулевой tolerance и шлите `X-Scheduler-Timestamp`: подпись будет покрывать
44
+ `<timestamp>.<body>`, и запрос вне окна перестанет приниматься.
45
+ - **Token-only режим.** Токен тоже replayable — планировщик не отличит повтор
46
+ от атаки. Если перейти на подпись нельзя: храните токен в секретах CI,
47
+ регулярно ротируйте, выдавайте по одному на задачу и делайте задачу
48
+ идемпотентной.
49
+ - **GitHub Actions** сам `X-Scheduler-Timestamp` не присылает, поэтому
50
+ `X-Hub-Signature-256` работает в legacy-режиме. Подписывайте
51
+ `<timestamp>.<body>` отдельным шагом workflow общим секретом.
52
+ - Планировщик не ведёт кэш повторов — дедупликация уникальных запросов на
53
+ стороне отправителя.