agent-steward 0.0.5 → 0.0.6

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 (191) hide show
  1. package/CHANGELOG.md +176 -1
  2. package/README.md +9 -7
  3. package/ROADMAP-STRATEGY.md +5 -5
  4. package/ROADMAP.md +107 -17
  5. package/dist/cli.js +5 -0
  6. package/dist/core/analytics.d.ts +6 -0
  7. package/dist/core/analytics.d.ts.map +1 -1
  8. package/dist/core/analytics.js +20 -3
  9. package/dist/core/audit.d.ts +6 -0
  10. package/dist/core/audit.d.ts.map +1 -1
  11. package/dist/core/audit.js +24 -0
  12. package/dist/core/budget.d.ts +118 -0
  13. package/dist/core/budget.d.ts.map +1 -0
  14. package/dist/core/budget.js +206 -0
  15. package/dist/core/cron-to-schtasks.d.ts.map +1 -1
  16. package/dist/core/cron-to-schtasks.js +38 -0
  17. package/dist/core/dry-run.d.ts +26 -1
  18. package/dist/core/dry-run.d.ts.map +1 -1
  19. package/dist/core/dry-run.js +199 -8
  20. package/dist/core/feedback.d.ts +192 -0
  21. package/dist/core/feedback.d.ts.map +1 -0
  22. package/dist/core/feedback.js +426 -0
  23. package/dist/core/gate-integrity.d.ts +36 -0
  24. package/dist/core/gate-integrity.d.ts.map +1 -1
  25. package/dist/core/gate-integrity.js +144 -1
  26. package/dist/core/local-ai.d.ts.map +1 -1
  27. package/dist/core/local-ai.js +7 -3
  28. package/dist/core/matrix.d.ts +8 -0
  29. package/dist/core/matrix.d.ts.map +1 -1
  30. package/dist/core/matrix.js +57 -2
  31. package/dist/core/mission.d.ts +20 -0
  32. package/dist/core/mission.d.ts.map +1 -1
  33. package/dist/core/mission.js +45 -5
  34. package/dist/core/opencode-models.d.ts +2 -2
  35. package/dist/core/opencode-models.d.ts.map +1 -1
  36. package/dist/core/opencode-models.js +28 -21
  37. package/dist/core/opencode-usage.d.ts +35 -0
  38. package/dist/core/opencode-usage.d.ts.map +1 -0
  39. package/dist/core/opencode-usage.js +132 -0
  40. package/dist/core/pipeline-io.d.ts +1 -1
  41. package/dist/core/pipeline-io.d.ts.map +1 -1
  42. package/dist/core/pipeline-io.js +26 -12
  43. package/dist/core/pipeline-map.d.ts +6 -0
  44. package/dist/core/pipeline-map.d.ts.map +1 -1
  45. package/dist/core/pipeline-map.js +12 -0
  46. package/dist/core/ps-wrapper.d.ts +10 -2
  47. package/dist/core/ps-wrapper.d.ts.map +1 -1
  48. package/dist/core/ps-wrapper.js +176 -5
  49. package/dist/core/record-history.d.ts.map +1 -1
  50. package/dist/core/record-history.js +76 -4
  51. package/dist/core/run-mode.d.ts +12 -0
  52. package/dist/core/run-mode.d.ts.map +1 -0
  53. package/dist/core/run-mode.js +17 -0
  54. package/dist/core/scheduler/logs.d.ts +4 -0
  55. package/dist/core/scheduler/logs.d.ts.map +1 -1
  56. package/dist/core/scheduler/logs.js +25 -1
  57. package/dist/core/secrets.d.ts.map +1 -1
  58. package/dist/core/secrets.js +18 -8
  59. package/dist/core/self-analysis.d.ts +32 -2
  60. package/dist/core/self-analysis.d.ts.map +1 -1
  61. package/dist/core/self-analysis.js +38 -27
  62. package/dist/core/shutdown.d.ts +33 -2
  63. package/dist/core/shutdown.d.ts.map +1 -1
  64. package/dist/core/shutdown.js +58 -2
  65. package/dist/core/structured-log.d.ts +30 -0
  66. package/dist/core/structured-log.d.ts.map +1 -1
  67. package/dist/core/structured-log.js +37 -0
  68. package/dist/core/usage-surface.d.ts +25 -0
  69. package/dist/core/usage-surface.d.ts.map +1 -0
  70. package/dist/core/usage-surface.js +41 -0
  71. package/dist/core/wrappers/bash.d.ts +2 -0
  72. package/dist/core/wrappers/bash.d.ts.map +1 -1
  73. package/dist/core/wrappers/bash.js +58 -6
  74. package/dist/db/history-repo.d.ts +32 -0
  75. package/dist/db/history-repo.d.ts.map +1 -1
  76. package/dist/db/history-repo.js +85 -7
  77. package/dist/db/metrics-repo.d.ts +20 -2
  78. package/dist/db/metrics-repo.d.ts.map +1 -1
  79. package/dist/db/metrics-repo.js +33 -11
  80. package/dist/db/migrate.d.ts.map +1 -1
  81. package/dist/db/migrate.js +37 -17
  82. package/dist/db/recovery.d.ts +3 -1
  83. package/dist/db/recovery.d.ts.map +1 -1
  84. package/dist/db/recovery.js +9 -4
  85. package/dist/db/runs-repo.d.ts.map +1 -1
  86. package/dist/db/runs-repo.js +71 -56
  87. package/dist/db/schema.d.ts +2 -2
  88. package/dist/db/schema.d.ts.map +1 -1
  89. package/dist/db/schema.js +70 -1
  90. package/dist/db/templates-repo.d.ts +2 -2
  91. package/dist/db/templates-repo.d.ts.map +1 -1
  92. package/dist/db/templates-repo.js +5 -3
  93. package/dist/history.d.ts +6 -1
  94. package/dist/history.d.ts.map +1 -1
  95. package/dist/history.js +4 -2
  96. package/dist/hook-output.d.ts +2 -0
  97. package/dist/hook-output.d.ts.map +1 -0
  98. package/dist/hook-output.js +31 -0
  99. package/dist/index.d.ts +247 -53
  100. package/dist/index.d.ts.map +1 -1
  101. package/dist/index.js +999 -211
  102. package/dist/notifications.d.ts +31 -2
  103. package/dist/notifications.d.ts.map +1 -1
  104. package/dist/notifications.js +132 -13
  105. package/dist/profiles.d.ts.map +1 -1
  106. package/dist/profiles.js +66 -15
  107. package/dist/rpc.d.ts +108 -0
  108. package/dist/rpc.d.ts.map +1 -1
  109. package/dist/rpc.js +28 -0
  110. package/dist/server.d.ts +17 -2
  111. package/dist/server.d.ts.map +1 -1
  112. package/dist/server.js +77 -12
  113. package/dist/settings.d.ts +42 -0
  114. package/dist/settings.d.ts.map +1 -1
  115. package/dist/settings.js +82 -0
  116. package/dist/task-transfer.d.ts +5 -0
  117. package/dist/task-transfer.d.ts.map +1 -1
  118. package/dist/task-transfer.js +48 -3
  119. package/dist/templates.d.ts +2 -2
  120. package/dist/templates.d.ts.map +1 -1
  121. package/dist/templates.js +3 -3
  122. package/dist/types.d.ts +22 -2
  123. package/dist/types.d.ts.map +1 -1
  124. package/dist/workspaces.d.ts.map +1 -1
  125. package/dist/workspaces.js +34 -11
  126. package/docs/ARCHITECTURE.md +49 -12
  127. package/docs/COMPATIBILITY.md +2 -2
  128. package/docs/EXECUTION-LOOP.md +6 -3
  129. package/docs/FEATURES.md +65 -4
  130. package/docs/FEATURES.zh.md +45 -2
  131. package/docs/QA-A2-GUI-TUI.md +205 -0
  132. package/docs/README.ru.md +3 -3
  133. package/docs/README.zh.md +2 -2
  134. package/gui-experimental.cjs +9 -9
  135. package/locales/en.json +42 -3
  136. package/locales/ru.json +42 -3
  137. package/locales/zh.json +42 -3
  138. package/package.json +15 -2
  139. package/scripts/check-eslint-baseline.mjs +139 -0
  140. package/scripts/gen-test-plan-counters.mjs +117 -0
  141. package/scripts/github-ci-fetch.ps1 +37 -0
  142. package/scripts/pl-commit.ps1 +112 -0
  143. package/scripts/qa-a2-commit.ps1 +104 -0
  144. package/scripts/test-home.mjs +26 -2
  145. package/skills/scheduled-job-best-practices/SKILL.md +95 -1
  146. package/skills/scheduled-job-best-practices/references/recipes.md +139 -0
  147. package/src/cli.ts +5 -0
  148. package/src/core/analytics.ts +27 -4
  149. package/src/core/audit.ts +25 -0
  150. package/src/core/budget.ts +340 -0
  151. package/src/core/cron-to-schtasks.ts +42 -0
  152. package/src/core/dry-run.ts +233 -10
  153. package/src/core/feedback.ts +582 -0
  154. package/src/core/gate-integrity.ts +171 -1
  155. package/src/core/local-ai.ts +7 -3
  156. package/src/core/matrix.ts +63 -2
  157. package/src/core/mission.ts +51 -5
  158. package/src/core/opencode-models.ts +30 -21
  159. package/src/core/opencode-usage.ts +182 -0
  160. package/src/core/pipeline-io.ts +28 -11
  161. package/src/core/pipeline-map.ts +19 -0
  162. package/src/core/ps-wrapper.ts +173 -4
  163. package/src/core/record-history.ts +94 -4
  164. package/src/core/run-mode.ts +19 -0
  165. package/src/core/scheduler/logs.ts +32 -1
  166. package/src/core/secrets.ts +18 -11
  167. package/src/core/self-analysis.ts +75 -29
  168. package/src/core/shutdown.ts +90 -4
  169. package/src/core/structured-log.ts +67 -0
  170. package/src/core/usage-surface.ts +70 -0
  171. package/src/core/wrappers/bash.ts +60 -5
  172. package/src/db/history-repo.ts +153 -19
  173. package/src/db/metrics-repo.ts +38 -11
  174. package/src/db/migrate.ts +57 -32
  175. package/src/db/recovery.ts +10 -4
  176. package/src/db/runs-repo.ts +113 -61
  177. package/src/db/schema.ts +70 -1
  178. package/src/db/templates-repo.ts +5 -3
  179. package/src/gui.tsx +261 -5
  180. package/src/history.ts +10 -3
  181. package/src/hook-output.ts +39 -0
  182. package/src/index.ts +1407 -345
  183. package/src/notifications.ts +189 -39
  184. package/src/profiles.ts +72 -16
  185. package/src/rpc.ts +30 -0
  186. package/src/server.ts +107 -23
  187. package/src/settings.ts +120 -0
  188. package/src/task-transfer.ts +59 -6
  189. package/src/templates.ts +3 -3
  190. package/src/types.ts +23 -2
  191. package/src/workspaces.ts +37 -14
@@ -0,0 +1,112 @@
1
+ # Post-flight commit+push for one QA-findings task (Деталь 1.5 / 1.6).
2
+ # Called by agent-steward's afterScript. Commits ONLY the files owned by the task
3
+ # and only when that task's quality gate wrote its own success marker.
4
+ # Generalizes scripts/qa-a2-commit.ps1: the marker is a parameter, so parallel
5
+ # tasks cannot consume each other's gate signal.
6
+ # PL-41: the commit itself is pathspec-limited — `git commit -m <msg> -- <files>`
7
+ # — so foreign staged changes never enter this task's commit. Plain
8
+ # `git add -- <files>` is NOT enough: `git add` stages only our files, but a bare
9
+ # `git commit -m <msg>` commits the WHOLE index, so anything another process
10
+ # staged in the meantime (or left staged before this run) would be swept into the
11
+ # commit. The `--` pathspec restricts the commit to the task's own file list
12
+ # regardless of what else sits in the index.
13
+ param(
14
+ [Parameter(Mandatory = $true)][string]$Message,
15
+ [Parameter(Mandatory = $true)][string]$Files,
16
+ [Parameter(Mandatory = $true)][string]$Marker
17
+ )
18
+
19
+ $ErrorActionPreference = 'Stop'
20
+ $root = Split-Path -Parent $PSScriptRoot
21
+ Set-Location -LiteralPath $root
22
+ $logFile = Join-Path $root 'pl-commit.log'
23
+ $markerPath = Join-Path $root $Marker
24
+
25
+ function Log([string]$text) {
26
+ Add-Content -LiteralPath $logFile -Value ("{0} {1}" -f (Get-Date -Format o), $text)
27
+ }
28
+
29
+ # git writes progress/errors to stderr; PowerShell 7 with ErrorActionPreference=Stop
30
+ # turns that into a terminating ErrorRecord even when push succeeds. Capture the
31
+ # real exit code instead (QA-A2/PL-7.1 lesson).
32
+ function Invoke-Git([string]$what, [string[]]$arguments) {
33
+ $old = $ErrorActionPreference
34
+ $ErrorActionPreference = 'Continue'
35
+ try {
36
+ $output = & git @arguments 2>&1
37
+ $code = $LASTEXITCODE
38
+ foreach ($line in $output) { Log ("[{0}] {1}" -f $what, [string]$line) }
39
+ return $code
40
+ }
41
+ finally {
42
+ $ErrorActionPreference = $old
43
+ }
44
+ }
45
+
46
+ try {
47
+ $gateOk = Test-Path -LiteralPath $markerPath
48
+ if ($gateOk) {
49
+ Remove-Item -LiteralPath $markerPath -Force
50
+ }
51
+ if (-not $gateOk) {
52
+ Log "SKIP (quality gate did not pass): $Message"
53
+ exit 0
54
+ }
55
+
56
+ $fileList = @($Files -split ';' | Where-Object { $_ } | ForEach-Object { $_.Trim() })
57
+ if ($fileList.Count -eq 0) {
58
+ Log "SKIP (no files): $Message"
59
+ exit 0
60
+ }
61
+
62
+ if ((Invoke-Git 'add' (@('add', '--') + $fileList)) -ne 0) {
63
+ Log "FAIL add: $Message"
64
+ exit 1
65
+ }
66
+ $old = $ErrorActionPreference
67
+ $ErrorActionPreference = 'Continue'
68
+ try { $nothing = git diff --cached --quiet; $cleanCode = $LASTEXITCODE }
69
+ finally { $ErrorActionPreference = $old }
70
+ if ($cleanCode -eq 0) {
71
+ Log "SKIP (nothing to commit): $Message"
72
+ exit 0
73
+ }
74
+
75
+ if ((Invoke-Git 'commit' (@('commit', '-m', $Message, '--') + $fileList)) -ne 0) {
76
+ Log "FAIL commit: $Message"
77
+ exit 1
78
+ }
79
+
80
+ $pushed = $false
81
+ for ($attempt = 1; $attempt -le 3; $attempt++) {
82
+ if ((Invoke-Git "push#$attempt" @('push', 'origin', 'dev')) -eq 0) {
83
+ $pushed = $true
84
+ break
85
+ }
86
+ Start-Sleep -Seconds 3
87
+ }
88
+ if (-not $pushed) {
89
+ # A parallel task may have pushed our commit already — verify before failing.
90
+ $null = Invoke-Git 'fetch' @('fetch', 'origin', 'dev')
91
+ $old = $ErrorActionPreference
92
+ $ErrorActionPreference = 'Continue'
93
+ try {
94
+ $local = (& git rev-parse HEAD 2>$null).Trim()
95
+ $remote = (& git rev-parse origin/dev 2>$null).Trim()
96
+ }
97
+ finally { $ErrorActionPreference = $old }
98
+ if ($local -and $local -eq $remote) {
99
+ $pushed = $true
100
+ Log "push: remote already contains HEAD (concurrent push)"
101
+ }
102
+ }
103
+ if (-not $pushed) {
104
+ Log "FAIL push: $Message"
105
+ exit 1
106
+ }
107
+ Log "OK: $Message"
108
+ }
109
+ catch {
110
+ Log "ERROR: $($_.Exception.Message)"
111
+ exit 1
112
+ }
@@ -0,0 +1,104 @@
1
+ # QA-A2 — post-flight commit+push for a single epic subtask.
2
+ # Called by agent-steward's afterScript. Commits ONLY the files owned by the task
3
+ # and only when the quality gate wrote its success marker (qa-a2-gate.passed).
4
+ param(
5
+ [Parameter(Mandatory = $true)][string]$Message,
6
+ [Parameter(Mandatory = $true)][string]$Files
7
+ )
8
+
9
+ $ErrorActionPreference = 'Stop'
10
+ $root = Split-Path -Parent $PSScriptRoot
11
+ Set-Location -LiteralPath $root
12
+ $logFile = Join-Path $root 'qa-a2-commit.log'
13
+ $marker = Join-Path $root 'qa-a2-gate.passed'
14
+
15
+ function Log([string]$text) {
16
+ Add-Content -LiteralPath $logFile -Value ("{0} {1}" -f (Get-Date -Format o), $text)
17
+ }
18
+
19
+ # Native git writes progress/errors to stderr. With ErrorActionPreference=Stop
20
+ # PowerShell 7 turns that into a terminating ErrorRecord ("To https://...").
21
+ # Temporarily relax the preference and capture the real exit code instead.
22
+ function Invoke-Git([string]$what, [string[]]$arguments) {
23
+ $old = $ErrorActionPreference
24
+ $ErrorActionPreference = 'Continue'
25
+ try {
26
+ $output = & git @arguments 2>&1
27
+ $code = $LASTEXITCODE
28
+ foreach ($line in $output) { Log ("[{0}] {1}" -f $what, [string]$line) }
29
+ return $code
30
+ }
31
+ finally {
32
+ $ErrorActionPreference = $old
33
+ }
34
+ }
35
+
36
+ try {
37
+ $gateOk = Test-Path -LiteralPath $marker
38
+ if ($gateOk) {
39
+ Remove-Item -LiteralPath $marker -Force
40
+ }
41
+ if (-not $gateOk) {
42
+ Log "SKIP (quality gate did not pass): $Message"
43
+ exit 0
44
+ }
45
+
46
+ $fileList = @($Files -split ';' | Where-Object { $_ } | ForEach-Object { $_.Trim() })
47
+ if ($fileList.Count -eq 0) {
48
+ Log "SKIP (no files): $Message"
49
+ exit 0
50
+ }
51
+
52
+ if ((Invoke-Git 'add' (@('add', '--') + $fileList)) -ne 0) {
53
+ Log "FAIL add: $Message"
54
+ exit 1
55
+ }
56
+ $old = $ErrorActionPreference
57
+ $ErrorActionPreference = 'Continue'
58
+ try { $nothing = git diff --cached --quiet; $cleanCode = $LASTEXITCODE }
59
+ finally { $ErrorActionPreference = $old }
60
+ if ($cleanCode -eq 0) {
61
+ Log "SKIP (nothing to commit): $Message"
62
+ exit 0
63
+ }
64
+
65
+ # PL-41: pathspec commit — only this task's files enter the commit; a bare
66
+ # `git commit -m` would commit the whole index including foreign staged changes.
67
+ if ((Invoke-Git 'commit' (@('commit', '-m', $Message, '--') + $fileList)) -ne 0) {
68
+ Log "FAIL commit: $Message"
69
+ exit 1
70
+ }
71
+
72
+ $pushed = $false
73
+ for ($attempt = 1; $attempt -le 3; $attempt++) {
74
+ if ((Invoke-Git "push#$attempt" @('push', 'origin', 'dev')) -eq 0) {
75
+ $pushed = $true
76
+ break
77
+ }
78
+ Start-Sleep -Seconds 3
79
+ }
80
+ if (-not $pushed) {
81
+ # A concurrent task may have pushed our commit already — verify before failing.
82
+ $null = Invoke-Git 'fetch' @('fetch', 'origin', 'dev')
83
+ $old = $ErrorActionPreference
84
+ $ErrorActionPreference = 'Continue'
85
+ try {
86
+ $local = (& git rev-parse HEAD 2>$null).Trim()
87
+ $remote = (& git rev-parse origin/dev 2>$null).Trim()
88
+ }
89
+ finally { $ErrorActionPreference = $old }
90
+ if ($local -and $local -eq $remote) {
91
+ $pushed = $true
92
+ Log "push: remote already contains HEAD (concurrent push)"
93
+ }
94
+ }
95
+ if (-not $pushed) {
96
+ Log "FAIL push: $Message"
97
+ exit 1
98
+ }
99
+ Log "OK: $Message"
100
+ }
101
+ catch {
102
+ Log "ERROR: $($_.Exception.Message)"
103
+ exit 1
104
+ }
@@ -18,6 +18,22 @@ import path from "node:path";
18
18
 
19
19
  const DEFAULT_ATTEMPTS = 6;
20
20
 
21
+ // На Windows SQLite/дашборд могут держать файлы до выхода процесса. Вместо
22
+ // предупреждения в чистом прогоне откладываем последнюю попытку на `exit`,
23
+ // когда все дескрипторы уже закрыты (QA-P3.4).
24
+ const deferredCleanups = new Set();
25
+ function scheduleDeferredCleanup(target) {
26
+ if (deferredCleanups.has(target)) return;
27
+ deferredCleanups.add(target);
28
+ process.once("exit", () => {
29
+ try {
30
+ fs.rmSync(target, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
31
+ } catch {
32
+ // best effort: временный каталог не должен ломать выход процесса
33
+ }
34
+ });
35
+ }
36
+
21
37
  function sleepSync(ms) {
22
38
  // Синхронная пауза без внешних зависимостей (для тестов с fs.rmSync).
23
39
  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
@@ -55,7 +71,11 @@ export function removeTestHomeSync(target, { attempts = DEFAULT_ATTEMPTS, warn =
55
71
  } catch (err) {
56
72
  if (err?.code === "ENOENT") return true;
57
73
  if (attempt === attempts) {
58
- if (warn) console.warn(`Не удалось удалить временный каталог ${target}: ${String(err)}`);
74
+ if (process.platform === "win32") {
75
+ scheduleDeferredCleanup(target);
76
+ } else if (warn) {
77
+ console.warn(`Не удалось удалить временный каталог ${target}: ${String(err)}`);
78
+ }
59
79
  return false;
60
80
  }
61
81
  sleepSync(100 * attempt);
@@ -73,7 +93,11 @@ export async function removeTestHome(target, { attempts = DEFAULT_ATTEMPTS, warn
73
93
  } catch (err) {
74
94
  if (err?.code === "ENOENT") return true;
75
95
  if (attempt === attempts) {
76
- if (warn) console.warn(`Не удалось удалить временный каталог ${target}: ${String(err)}`);
96
+ if (process.platform === "win32") {
97
+ scheduleDeferredCleanup(target);
98
+ } else if (warn) {
99
+ console.warn(`Не удалось удалить временный каталог ${target}: ${String(err)}`);
100
+ }
77
101
  return false;
78
102
  }
79
103
  await new Promise((resolve) => setTimeout(resolve, 100 * attempt));
@@ -30,10 +30,40 @@ summary, last run.
30
30
  | "Same work in N repositories" | `matrix.workspaceIds` | One definition, isolated clones, aggregated status |
31
31
  | "A then B then C" | `dependsOn` + `nextTaskOnSuccess` / `nextTaskOnError` | Explicit DAG, failures stop the line |
32
32
  | "Try again if it fails" | `retryCount` + `retryDelay` | Handles flaky networks and rate limits |
33
+ | "Once a month / once a year" | `schedule_task` with `M H D M *` | Native `MONTHLY` (with `/m` for a fixed month), no minute polling |
34
+
35
+ **Cron-to-OS limitation (QV-10).** Windows Task Scheduler expresses `MINUTE`,
36
+ `HOURLY`, `DAILY`, `WEEKLY` and `MONTHLY`. Expressions outside this subset (lists,
37
+ ranges, `*/N` on day-of-month/weekday, a foreign IANA timezone) fall back to a
38
+ one-minute OS poll with a schedule gate in the wrapper. A yearly cron such as
39
+ `0 4 1 1 *` is now converted natively to `MONTHLY /d 1 /m JANUARY /st 04:00`,
40
+ so the OS does not tick every minute for a task that runs once a year.
41
+
42
+ `triggerType: "mcp-event"` (as well as `file`/`git`) is event-driven, but it **still
43
+ registers an enabled OS placeholder entry**: `ONCE 31.12.2099 00:00`, Status `Ready`
44
+ (`src/core/scheduler/windows.ts`, the non-cron branch). The OS never fires it on its own;
45
+ the entry exists only so manual start (`schtasks /run`), DAG dependencies and `runMatrix`
46
+ have an OS object to run, and it is removed together with the task by `delete_task`.
47
+ A fresh task `QV1-live-mcp-os-probe` with `mcpEvent:{server:'qv1probe',event:'qv1.live.probe'}`
48
+ was verified in `schtasks` on 20.11.2026 (QV-1) — the `31.12.2099` date is intentional,
49
+ not an artifact of a paused task.
50
+
51
+ **Child run surface (QV-8).** The task wrapper exports `AGENT_STEWARD_CHILD_RUN=1`
52
+ before `opencode run` (PowerShell restores the previous value in `finally`). When the
53
+ plugin is loaded with that marker it skips V2/V1 registration: no scheduler tools, RPC,
54
+ skill or dashboard in the child process. A controlled check measured the tool registry at
55
+ 30 tools in the parent vs 0 in child mode. This prevents a scheduled agent from seeing
56
+ the same 30 tools recursively and racing the parent for the dashboard port.
33
57
 
34
58
  Do not use a 5-field cron for a one-off reminder. Do not build a pipeline with chained
35
59
  prompts inside a single task when `dependsOn` exists: a failed step would be invisible.
36
60
 
61
+ **Task names (PL-9.1).** `schedule_task` validates the name: letters (including Cyrillic),
62
+ digits, space, dot, underscore and an **ASCII hyphen `-`** are allowed. The em dash `—`
63
+ and round brackets `()` are **rejected**. Rewrite the title with words and `-` before
64
+ creating the task so the original name is not silently replaced:
65
+ `QA-A2 - Full plugin typing epic`, not `Задача QA-A2 — Полная типизация (эпик)`.
66
+
37
67
  ## 3. Write prompts that survive without context
38
68
 
39
69
  Every run starts from a clean slate: no chat history, no memory of the previous run, nobody
@@ -53,6 +83,35 @@ reports/nightly-api.md with the failing test names and the commit you started fr
53
83
  Never ask the agent to "ask the user" in a scheduled prompt — nobody is there. If a decision
54
84
  is genuinely ambiguous, tell it to stop and write the question into the report.
55
85
 
86
+ ### Prompt template for planning-document updates (PL-3.1)
87
+
88
+ When a prompt asks the agent to close tasks in `ROADMAP.md`, keep `TEST-PLAN.md` or
89
+ write a CHANGELOG entry, put the exact line format and the artifact checklist into
90
+ the prompt itself — do not rely on the agent to guess them:
91
+
92
+ ````text
93
+ Roadmap line format (copy verbatim, one line per closed subtask):
94
+ - [x] <ID> <title>: <files> — <P0|P1|P2|P3>. Действие: <what to do>
95
+
96
+ Rule: wrap every EXISTING file path in backticks, e.g.
97
+ - [x] TP-6 test plan gate: `test-test-plan.mjs`, `scripts/gen-test-plan-counters.mjs` — P3. Действие: ...
98
+ Never invent a file: a path that does not exist must not appear as an artifact and must
99
+ not be given backticks. Verify each path before writing the line.
100
+
101
+ Artifact checklist (copy into the prompt and tick before reporting done):
102
+ - [ ] ROADMAP.md: closed lines removed (or [x] only if the doc explicitly keeps them),
103
+ no duplicate of a closed ID remains.
104
+ - [ ] CHANGELOG.md: one entry per closed detail/subtask with the ID and the result.
105
+ - [ ] TEST-PLAN.md: §5 row for each existing `test-*.mjs`, filename in backticks;
106
+ no row for a missing file; counters match the code.
107
+ - [ ] reports/<name>.md: report written with statuses, verification commands and results.
108
+ - [ ] Verification commands actually run (build / target test / lint baseline).
109
+ ````
110
+
111
+ This is the concrete form of items 4–5 above: "Verification" and "Output" must be
112
+ machine-checkable, not a wish. A line for a non-existent `test-feedback.mjs` is worse
113
+ than a missing line, because the gate then checks a file that will never appear.
114
+
56
115
  ## 4. Safety defaults
57
116
 
58
117
  - **Least privilege**: the default `hybrid` policy already denies `shell` and `question`; keep it
@@ -60,6 +119,12 @@ is genuinely ambiguous, tell it to stop and write the question into the report.
60
119
  for `shell` just to run `git commit`, a build or tests — put those in `qualityGate`/`afterScript`,
61
120
  which the wrapper runs outside the agent. If a job truly needs shell, list `shell` in
62
121
  `allowedTools` (or set `legacyShell: true` for a migrated task) and explain why.
122
+ - **Self-check prompts (PL-2.1/PL-2.2)**: decide the tool policy at creation time. If the prompt
123
+ says "run `node`", "`npm test`", "`pytest`" or otherwise verifies its own work, then either put
124
+ `shell` into `allowedTools` immediately, or move every such check into `qualityGate`/`afterScript`
125
+ so the wrapper runs it. Leaving shell denied while demanding a self-check produces
126
+ `tool.blocked` in the audit log and a "verified" report that verified nothing. `dry_run` warns
127
+ about this combination.
63
128
  - **Timeout**: always set `timeoutSeconds` for jobs that call networks or models. Default
64
129
  timeouts are a safety net, not a plan.
65
130
  - **Quality Gate**: pass `qualityGate` whenever a machine-checkable success criterion exists
@@ -102,6 +167,24 @@ Rules of thumb:
102
167
  starts.
103
168
  - `nextTaskOnSuccess` / `nextTaskOnError` chain a single follow-up run; use them for
104
169
  notifications and rollbacks.
170
+ - **One transition, one mechanism (PL-5.1/PL-5.2).** For a linear `A → B` step use
171
+ **either** `A.nextTaskOnSuccess = "B"` **or** `B.dependsOn = ["A"]`, never both.
172
+ If both describe the same transition, `B` is triggered twice when `A` finishes — once
173
+ as the chain target and once as a DAG dependent — producing duplicate runs. `dry_run`
174
+ warns about this overlap, and the recorder now de-duplicates targets by name, but the
175
+ configuration itself should be fixed.
176
+ - **A dependency completion is an event, not a one-shot latch (PL-40).** A task with two
177
+ parents (`dependsOn: [A, B]`) is started whenever either parent finishes while all
178
+ parents' latest records are successful — so two completions can mean two runs. A stale
179
+ success also satisfies the gate. The dependent's own `startedAt` only suppresses a
180
+ re-trigger when it is newer than the newest dependency `finishedAt`. If you need
181
+ exactly one follow-up run, use `nextTaskOnSuccess` (a single-parent chain) instead of
182
+ a multi-parent `dependsOn`.
183
+ - **Worktree snapshot for Quality Gate (PL-25).** When a task has a machine-checkable gate,
184
+ the wrapper snapshots `HEAD` plus guarded-path status at task start into a sibling
185
+ `*.worktree.json` and verifies it immediately before the gate. Foreign uncommitted edits
186
+ in `src/` during the run fail closed: the gate is skipped and the run is marked as an
187
+ error. Override guarded paths with `AGENT_STEWARD_GATE_GUARD_PATHS` (`|`/`;` separated).
105
188
  - Keep chains short and named by intent (`deploy` → `smoke-tests` → `notify-release`).
106
189
  - Cycles and self-dependencies are rejected; if a chain grows past 4–5 nodes, consider one
107
190
  task with an explicit internal checklist instead.
@@ -122,6 +205,11 @@ Rules of thumb:
122
205
  `timeout`, `partial`.
123
206
  - `get_task_logs` with `lines` — tail of the wrapper log; use it to distinguish model failure,
124
207
  Quality Gate failure, timeout and lock-skip.
208
+ - Structured journal (`logs/runs.jsonl`, `hook.output` events, PL-7.2): post-flight stdout
209
+ and stderr are stored in **separate** fields with the real `postFlightExitCode`. Git writes
210
+ progress/diagnostics to stderr even on success, so compare the exit code and stdout — do
211
+ not treat a non-empty stderr as a failed push. See `references/recipes.md` §11 for the
212
+ commit/push wrapper that makes this reliable.
125
213
  - Matrix problems: `matrix_control` with `action: "results"` for counters, `action: "cancel"`
126
214
  to stop pending clones, `action: "cleanup"` to remove clones whose parent is gone.
127
215
  - A timeout usually means the prompt is too broad. Split it or raise `timeoutSeconds`
@@ -136,6 +224,9 @@ Rules of thumb:
136
224
  | `* * * * *` with a heavy prompt | Runs overlap, lock-skips, cost spikes | Realistic interval + timeout |
137
225
  | Prompt depending on chat context | Nonsense output at 03:00 | Self-contained prompt with paths |
138
226
  | No Quality Gate on a "fixer" job | Broken code reported as success | `qualityGate: "npm test"` |
227
+ | `nextTaskOnSuccess` and `dependsOn` for one transition | Duplicate runs of the same step | Keep one mechanism only (PL-5.1/PL-5.2) |
228
+ | Prompt demands `node`/tests but shell is denied | `tool.blocked`, fake "verified" report | `shell` in `allowedTools` or checks in `qualityGate`/`afterScript` |
229
+ | Closed task left in `ROADMAP.md` with a missing/incorrect file name | Gate checks a file that does not exist | Exact line format + artifact checklist in the prompt (PL-3.1) |
139
230
  | Matrix with 20 workspaces, no concurrency cap | Machine and API saturation | `matrix.concurrency: 2–4` |
140
231
  | Secrets inside the prompt | Leak into DB, logs and dashboard | Env vars or files |
141
232
  | Deleting a matrix parent's clone by hand | Orphaned history, broken aggregate | `update_task` on the parent |
@@ -147,9 +238,12 @@ Before saying the job is done, confirm:
147
238
 
148
239
  - [ ] `list_tasks` checked; no duplicate exists.
149
240
  - [ ] Trigger type matches the need (cron / file / MCP event).
150
- - [ ] Prompt states goal, scope, constraints, verification and output.
241
+ - [ ] Prompt states goal, scope, constraints, verification and output; for doc updates it
242
+ includes the exact line format and the artifact checklist from §3 (PL-3.1).
151
243
  - [ ] `timeoutSeconds` set; `qualityGate` set when checkable.
152
244
  - [ ] `allowedTools` / `deniedTools` follow least privilege; shell is absent unless justified.
245
+ If the prompt demands a self-check, shell is in `allowedTools` or the check lives in
246
+ `qualityGate`/`afterScript` — never both "no shell" and "verify with node/tests" (PL-2.1).
153
247
  - [ ] Matrix: workspaces correct, concurrency capped, failure mode justified.
154
248
  - [ ] `dry_run` reviewed.
155
249
  - [ ] One successful `run_task_now` with clean `get_history`.
@@ -161,3 +161,142 @@ fail-open, and shadow mode makes false skips visible. Only disable shadow mode
161
161
  after the shadow report shows no false positives. See `docs/LOCAL-AI.md` for
162
162
  model tiers by RAM, `OLLAMA_CONTEXT_LENGTH` troubleshooting and the full JSON
163
163
  report format.
164
+
165
+ ## 9. Restarting a `once` task after a plugin reload (PL-1.2)
166
+
167
+ While the plugin is unloading, `run_task_now` refuses new launches with the structured
168
+ error `PLUGIN_SHUTTING_DOWN` (`message` + `hint`: retry after restart, or use a force
169
+ marker / delayed start). For a `once` task already registered in Windows Task Scheduler,
170
+ the OS can start it without the MCP gate:
171
+
172
+ ```powershell
173
+ # 1. Plain OS trigger (no force marker needed if the schedule gate is not involved):
174
+ schtasks /run /tn "<task name>"
175
+ # Equivalent modern cmdlet:
176
+ Start-ScheduledTask -TaskName "<task name>"
177
+
178
+ # 2. If the wrapper might be skipped by its cron/window gate, put the force marker
179
+ # in the task locks directory first (slug = task name lowercased, spaces -> '-'):
180
+ New-Item -ItemType File -Force -Path "locks/<slug>.lock.force" | Out-Null
181
+ Start-ScheduledTask -TaskName "<task name>"
182
+ ```
183
+
184
+ Notes and warnings:
185
+
186
+ - The wrapper removes `locks/<slug>.lock.force` after the run **and** on failure. If the
187
+ OS refuses to start, delete the marker yourself — a stale marker can allow a later
188
+ scheduled tick out of turn.
189
+ - **Never combine both paths in one recovery.** `schtasks /run` plus a manual
190
+ `run_task_now` (or two `Start-ScheduledTask` calls) creates duplicate runs: locks are
191
+ per task name, so the second start can be accepted for the next tick.
192
+ - Verify exactly one run: `get_history({ taskName: "<task name>" })` must show a single
193
+ new `running`/`success` record, and `get_task_logs` must not contain a lock-skip for the
194
+ same interval. Check again after the plugin restarts — a reload must not leave a second run.
195
+ - Check `nextTaskOnSuccess` / `nextTaskOnError` chains explicitly. They are recorded by a
196
+ separate process, so the follow-up task can fire after the OS-started run. Look for the
197
+ chained task in `get_history`; do **not** re-run the parent to "make the chain happen" —
198
+ that is the classic way to get a duplicate chain entry.
199
+
200
+ Why: the OS trigger is the documented escape hatch for the shutdown gate; the force marker
201
+ only bypasses the schedule gate, and both need a duplicate check plus a chain check.
202
+
203
+ ## 10. Safe cleanup in `beforeScript` (PL-6.1)
204
+
205
+ `Remove-Item -ErrorAction SilentlyContinue` returns exit code **1** when the file is already
206
+ absent. A non-zero pre-flight code cancels the run with `Pre-flight script failed` and fires
207
+ a false compensator. Guard the existence check and finish with an explicit `exit 0`:
208
+
209
+ ```powershell
210
+ if (Test-Path -LiteralPath '<path>') { Remove-Item -LiteralPath '<path>' -Force }; exit 0
211
+ ```
212
+
213
+ Rules:
214
+
215
+ - Use `-LiteralPath`, not `-Path`, so brackets and wildcards in the path are literal.
216
+ - Keep the guard and `exit 0` in the same script; for several paths repeat the guard for each
217
+ and put a single `exit 0` at the end.
218
+ - In a Bash pre-flight the equivalent is `rm -f "<path>"` followed by `exit 0`.
219
+ - The wrapper only sees the process exit code — it cannot tell "cleanup skipped, nothing to
220
+ do" from "cleanup failed". Make the script say `0` for the first case explicitly.
221
+
222
+ ## 11. Reliable commit + push from `afterScript` (PL-7.1)
223
+
224
+ Proven pattern from `scripts/qa-a2-commit.ps1`. Native Git writes progress and diagnostics
225
+ to **stderr**; under PowerShell 7 with `$ErrorActionPreference = 'Stop'` that becomes a
226
+ terminating error even when the push succeeded. Relax the preference only around Git calls,
227
+ capture `$LASTEXITCODE`, retry, and verify the remote before declaring failure.
228
+
229
+ ```powershell
230
+ $ErrorActionPreference = 'Stop'
231
+ Set-Location -LiteralPath $root
232
+
233
+ function Invoke-Git([string]$what, [string[]]$gitArgs) {
234
+ $old = $ErrorActionPreference
235
+ $ErrorActionPreference = 'Continue' # stderr diagnostics are not terminating errors
236
+ try {
237
+ $output = & git @gitArgs 2>&1 # capture/suppress stderr
238
+ $code = $LASTEXITCODE # the REAL exit code
239
+ foreach ($line in $output) { Write-Output ("[{0}] {1}" -f $what, [string]$line) }
240
+ return $code
241
+ } finally { $ErrorActionPreference = $old }
242
+ }
243
+
244
+ if ((Invoke-Git 'add' (@('add', '--') + $fileList)) -ne 0) { exit 1 }
245
+
246
+ # "nothing to commit" = success, not an error
247
+ $old = $ErrorActionPreference
248
+ $ErrorActionPreference = 'Continue'
249
+ try { $nothing = git diff --cached --quiet; $clean = $LASTEXITCODE }
250
+ finally { $ErrorActionPreference = $old }
251
+ if ($clean -eq 0) { exit 0 }
252
+
253
+ if ((Invoke-Git 'commit' @('commit', '-m', $Message)) -ne 0) { exit 1 }
254
+
255
+ $pushed = $false
256
+ for ($attempt = 1; $attempt -le 3; $attempt++) { # 3 retries
257
+ if ((Invoke-Git "push#$attempt" @('push', 'origin', 'dev')) -eq 0) { $pushed = $true; break }
258
+ Start-Sleep -Seconds 3
259
+ }
260
+ if (-not $pushed) {
261
+ # A parallel task may already have pushed our commit: verify before failing.
262
+ $null = Invoke-Git 'fetch' @('fetch', 'origin', 'dev')
263
+ $old = $ErrorActionPreference
264
+ $ErrorActionPreference = 'Continue'
265
+ try {
266
+ $local = (& git rev-parse HEAD 2>$null).Trim()
267
+ $remote = (& git rev-parse origin/dev 2>$null).Trim()
268
+ } finally { $ErrorActionPreference = $old }
269
+ if ($local -and $local -eq $remote) { $pushed = $true } # HEAD/origin/dev agree
270
+ }
271
+ exit $(if ($pushed) { 0 } else { 1 })
272
+ ```
273
+
274
+ Notes:
275
+
276
+ - Gate the commit on a real Quality Gate success marker before `git add` (see the source
277
+ script); never commit untested files just because the afterScript ran.
278
+ - Commit **only** the files owned by the task, never `git add -A`.
279
+ - With the structured journal, read `postFlightExitCode` and the separate
280
+ `postFlightStdout` / `postFlightStderr` fields (`hook.output` events) instead of treating a
281
+ non-empty stderr as a failure (PL-7.2).
282
+
283
+ ## 13. Which lint command is a real gate? (PL-22)
284
+
285
+ `npm run lint` runs plain ESLint and exits 0 even with hundreds of warnings — it is
286
+ **informational** (colored diagnostics in the editor). The real CI gate is
287
+ `npm run lint:baseline`, which fails when the warning count exceeds the committed baseline.
288
+ `npm run lint:strict` (`eslint src --max-warnings=0`) is an opt-in target for a fully cleaned
289
+ tree; do not put it in a required gate while the baseline is non-zero.
290
+
291
+ ## 12. Pin the commit your Quality Gate trusts (PL-8.1)
292
+
293
+ During a multi-hour DAG a parallel task can commit to the same branch. `npm test` in the gate
294
+ then fails on counter drift (`test-docs.mjs`) although this task's code is correct. `dry_run`
295
+ warns when the working directory's HEAD is newer than the task's `createdAt`. Before running
296
+ such a job:
297
+
298
+ - Record the starting HEAD and require it in the gate, e.g.
299
+ `qualityGate: "git diff --quiet <sha> && npm test"` (adapt quoting to your shell), so a
300
+ foreign commit fails the gate deterministically instead of mid-run.
301
+ - Or run the job in an isolated worktree / serialize writers to `src/`.
302
+ - Re-check `git status` and `dry_run` immediately before the gate on a shared branch.
package/src/cli.ts CHANGED
@@ -389,6 +389,11 @@ async function main(argv: string[]): Promise<number> {
389
389
  return 2;
390
390
  }
391
391
  switch (command) {
392
+ case "--help":
393
+ case "-h":
394
+ case "help":
395
+ console.log(USAGE);
396
+ return 0;
392
397
  case "validate":
393
398
  return runValidate(rest);
394
399
  case "apply":
@@ -31,6 +31,8 @@ export interface AnalyticsRecord {
31
31
  export interface AnalyticsTaskRef {
32
32
  name: string;
33
33
  matrixParentId?: string | null;
34
+ /** Экономика v2 (E-2): лимит токенов на запуск (0/undefined — без лимита). */
35
+ tokenBudget?: number;
34
36
  }
35
37
 
36
38
  export interface DailyBucket {
@@ -58,6 +60,10 @@ export interface TaskAnalyticsRow {
58
60
  /** Задача — клон матрицы (matrixParentId задан). */
59
61
  isMatrixClone: boolean;
60
62
  matrixParentId: string | null;
63
+ /** Экономика v2 (E-2): лимит токенов на запуск (0 — без лимита). */
64
+ tokenBudget?: number;
65
+ /** Сумма токенов за период превысила лимит на задачу. */
66
+ tokenBudgetExceeded?: boolean;
61
67
  }
62
68
 
63
69
  export interface MatrixAnalyticsRow {
@@ -187,13 +193,18 @@ export function buildAnalytics(
187
193
  });
188
194
  }
189
195
 
190
- const byTask = new Map<string, TaskAnalyticsRow>();
196
+ const byTask = new Map<string, TaskAnalyticsRow & { maxRunTokens: number }>();
191
197
  const byModel = new Map<string, ModelAnalyticsRow>();
192
198
  const byError = new Map<string, ErrorAnalyticsRow>();
193
199
  const cloneParent = new Map<string, string>();
200
+ const taskTokenBudget = new Map<string, number>();
194
201
  for (const task of options.tasks ?? []) {
195
202
  const parentId = task.matrixParentId?.trim();
196
203
  if (parentId) cloneParent.set(task.name.toLowerCase(), parentId);
204
+ const budget = Number(task.tokenBudget);
205
+ if (Number.isFinite(budget) && budget > 0) {
206
+ taskTokenBudget.set(task.name.toLowerCase(), budget);
207
+ }
197
208
  }
198
209
 
199
210
  let totalsTotal = 0;
@@ -257,7 +268,11 @@ export function buildAnalytics(
257
268
  costUsd: 0,
258
269
  isMatrixClone: cloneParent.has(taskKey),
259
270
  matrixParentId: cloneParent.get(taskKey) ?? null,
271
+ tokenBudget: taskTokenBudget.get(taskKey),
272
+ tokenBudgetExceeded: false,
273
+ maxRunTokens: 0,
260
274
  };
275
+ existing.maxRunTokens = Math.max(existing.maxRunTokens, tokens);
261
276
  existing.total += 1;
262
277
  if (status === "success") existing.success += 1;
263
278
  else existing.error += 1;
@@ -277,9 +292,12 @@ export function buildAnalytics(
277
292
 
278
293
  // Топ ошибок: группируем по тексту, чтобы дайджест показывал частые причины.
279
294
  if (status !== "success" && status !== "partial") {
295
+ // QA-P1.5: легаси-записи успешных запусков содержат "-" вместо текста
296
+ // ошибки. Такой маркер не является сообщением и не должен попадать в топ.
297
+ const rawError = typeof record.error === "string" ? record.error.trim() : "";
280
298
  const message =
281
- typeof record.error === "string" && record.error.trim()
282
- ? record.error.trim().slice(0, 160)
299
+ rawError && rawError !== "-"
300
+ ? rawError.slice(0, 160)
283
301
  : "(без текста)";
284
302
  const errorRow = byError.get(message) ?? {
285
303
  message,
@@ -298,11 +316,16 @@ export function buildAnalytics(
298
316
  }
299
317
 
300
318
  const tasks = [...byTask.values()]
301
- .map((row) => ({
319
+ .map(({ maxRunTokens, ...row }) => ({
302
320
  ...row,
303
321
  successRate: percent(row.success, row.total),
304
322
  avgDurationMs: Math.round(row.avgDurationMs),
305
323
  costUsd: Math.round(row.costUsd * 1e6) / 1e6,
324
+ // E-2: бюджет задаётся на один запуск, поэтому флаг выставляем по
325
+ // максимальному расходу токенов за запуск, а не по сумме за период.
326
+ tokenBudgetExceeded: row.tokenBudget
327
+ ? maxRunTokens > row.tokenBudget
328
+ : false,
306
329
  }))
307
330
  .sort((a, b) => b.total - a.total || a.taskName.localeCompare(b.taskName));
308
331