minicode-ai 0.11.0 → 0.13.0

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 (221) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/LICENSE +21 -21
  3. package/README.md +4 -4
  4. package/cli/args.ts +46 -0
  5. package/cli/commands/acp.ts +163 -10
  6. package/cli/commands/config.ts +33 -18
  7. package/cli/commands/daemon.ts +515 -0
  8. package/cli/commands/exec.ts +145 -53
  9. package/cli/commands/openwork.ts +986 -0
  10. package/cli/commands/sessions.ts +4 -1
  11. package/cli/commands/stats.ts +34 -4
  12. package/cli/commands.ts +217 -2
  13. package/cli/index.ts +146 -14
  14. package/cli/recovery-warning.ts +115 -0
  15. package/cli/router.ts +32 -1
  16. package/cli/setup.ts +2332 -171
  17. package/cli/tui.ts +113 -7
  18. package/docs/OUTPUT_ARCHITECTURE_AUDIT.md +489 -0
  19. package/docs/OUTPUT_EVENT_MODEL.md +289 -0
  20. package/docs/OUTPUT_IMPLEMENTATION_PLAN.md +391 -0
  21. package/docs/OUTPUT_PROTOCOL_SPEC.md +285 -0
  22. package/docs/OUTPUT_RENDERING_SPEC.md +248 -0
  23. package/docs/OUTPUT_UX_RULES.md +449 -0
  24. package/docs/PLAN_UIUX_V6.md +2 -2
  25. package/docs/README.md +4 -3
  26. package/docs/TERMINAL_CONTRACT.md +278 -66
  27. package/docs/architecture.md +89 -7
  28. package/docs/changelog.md +1 -1
  29. package/docs/choosing-mode.md +2 -2
  30. package/docs/cli.md +9 -5
  31. package/docs/concepts.md +1 -1
  32. package/docs/contributing.md +9 -2
  33. package/docs/environment.md +6 -2
  34. package/docs/exec.md +46 -5
  35. package/docs/memory-sessions.md +2 -0
  36. package/docs/policy-sandbox.md +1 -1
  37. package/docs/pricing-budget.md +1 -1
  38. package/docs/quickstart.md +2 -2
  39. package/docs/repl.md +6 -2
  40. package/docs/security-model.md +1 -1
  41. package/docs/security.md +1 -1
  42. package/docs/skills.md +2 -2
  43. package/docs/terminal.md +9 -5
  44. package/docs/tools.md +1 -1
  45. package/package.json +35 -5
  46. package/src/app/session.ts +261 -15
  47. package/src/app/tool-layer.ts +94 -7
  48. package/src/daemon/approvals.ts +361 -0
  49. package/src/daemon/capability.ts +145 -0
  50. package/src/daemon/children.ts +142 -0
  51. package/src/daemon/client.ts +267 -0
  52. package/src/daemon/control.ts +350 -0
  53. package/src/daemon/discovery.ts +234 -0
  54. package/src/daemon/feed.ts +155 -0
  55. package/src/daemon/framing.ts +94 -0
  56. package/src/daemon/host.ts +316 -0
  57. package/src/daemon/protocol.ts +217 -0
  58. package/src/daemon/resource.ts +170 -0
  59. package/src/daemon/sanitize.ts +57 -0
  60. package/src/daemon/server.ts +627 -0
  61. package/src/daemon/store.ts +317 -0
  62. package/src/daemon/subscription.ts +270 -0
  63. package/src/daemon/telemetry.ts +81 -0
  64. package/src/hooks/run.ts +12 -1
  65. package/src/lib/atomic-write.ts +29 -3
  66. package/src/lib/db-path.ts +26 -0
  67. package/src/lib/keystore.ts +544 -42
  68. package/src/lib/net.ts +43 -1
  69. package/src/lib/safe-open.ts +116 -1
  70. package/src/lib/session-id.ts +15 -0
  71. package/src/lsp/client.ts +123 -5
  72. package/src/mcp/client.ts +139 -17
  73. package/src/mcp/server.ts +177 -50
  74. package/src/mcp/transport.ts +16 -19
  75. package/src/memory/vector.ts +770 -55
  76. package/src/policy/allowlist.ts +14 -2
  77. package/src/policy/bash-guard.ts +105 -10
  78. package/src/policy/compaction.ts +82 -5
  79. package/src/policy/consequence-engine.ts +220 -0
  80. package/src/policy/context.ts +132 -0
  81. package/src/policy/executor.ts +187 -121
  82. package/src/policy/no-progress.ts +559 -0
  83. package/src/policy/permission.ts +4 -8
  84. package/src/policy/pricing.ts +17 -3
  85. package/src/policy/scrub.ts +69 -2
  86. package/src/policy/tool-contract.ts +515 -0
  87. package/src/policy/usage.ts +310 -24
  88. package/src/policy/verifier.ts +6 -3
  89. package/src/policy/work-mode.ts +182 -0
  90. package/src/presentation/adapter.ts +533 -26
  91. package/src/presentation/events.ts +151 -0
  92. package/src/presentation/model.ts +180 -27
  93. package/src/presentation/projection.ts +858 -0
  94. package/src/presentation/reducer.ts +645 -310
  95. package/src/presentation/store.ts +12 -7
  96. package/src/providers/anthropic.ts +18 -10
  97. package/src/providers/responses.ts +17 -7
  98. package/src/runtime/capability.ts +409 -0
  99. package/src/runtime/child-execution.ts +274 -0
  100. package/src/runtime/composition.ts +958 -0
  101. package/src/runtime/dispatch.ts +591 -0
  102. package/src/runtime/execution-backend.ts +632 -0
  103. package/src/runtime/execution-events.ts +272 -0
  104. package/src/runtime/execution-id.ts +230 -0
  105. package/src/runtime/execution-journal.ts +926 -0
  106. package/src/runtime/execution-kernel.ts +456 -0
  107. package/src/runtime/execution-registry.ts +379 -0
  108. package/src/runtime/process-supervision.ts +276 -0
  109. package/src/runtime/production-execution.ts +551 -0
  110. package/src/runtime/production-runtime.ts +217 -0
  111. package/src/runtime/recovery-safety.ts +70 -0
  112. package/src/runtime/recovery.ts +477 -0
  113. package/src/runtime/runtime-capabilities.ts +179 -0
  114. package/src/runtime/runtime-diagnostics.ts +141 -0
  115. package/src/runtime/runtime-host.ts +365 -0
  116. package/src/runtime/runtime-status-facts.ts +222 -0
  117. package/src/runtime/runtime-status-provider.ts +74 -0
  118. package/src/runtime/runtime-status.ts +459 -0
  119. package/src/runtime/runtime-task-admission.ts +101 -0
  120. package/src/runtime/supervisor.ts +444 -0
  121. package/src/session/authority.ts +168 -0
  122. package/src/session/checkpoint.ts +88 -1
  123. package/src/session/context-adapter.ts +251 -0
  124. package/src/session/context-assembly.ts +242 -0
  125. package/src/session/context-identity.ts +389 -0
  126. package/src/session/context-projection.ts +248 -0
  127. package/src/session/context-selector.ts +500 -0
  128. package/src/session/cross-session-adoption.ts +249 -0
  129. package/src/session/full-history-fold.ts +171 -0
  130. package/src/session/identity.ts +192 -0
  131. package/src/session/journal.ts +805 -102
  132. package/src/session/open-work-intent.ts +732 -0
  133. package/src/session/open-work.ts +767 -0
  134. package/src/session/pending-tools.ts +94 -0
  135. package/src/session/persistence.ts +3569 -127
  136. package/src/session/runtime-header.ts +208 -0
  137. package/src/session/shadow-git.ts +13 -5
  138. package/src/session/verification.ts +1623 -0
  139. package/src/task/assignment.ts +136 -0
  140. package/src/task/autonomous-adapter.ts +168 -0
  141. package/src/task/autonomous-context.ts +630 -0
  142. package/src/task/autonomous-policy.ts +490 -0
  143. package/src/task/continuity.ts +179 -0
  144. package/src/task/execution-cancellation.ts +165 -0
  145. package/src/task/graph-validate.ts +379 -0
  146. package/src/task/graph.ts +305 -0
  147. package/src/task/identity.ts +230 -0
  148. package/src/task/model.ts +417 -0
  149. package/src/task/production-scheduler.ts +293 -0
  150. package/src/task/readiness.ts +229 -0
  151. package/src/task/scheduler-observability.ts +387 -0
  152. package/src/task/scheduler.ts +1197 -0
  153. package/src/task/scheduling-policy.ts +165 -0
  154. package/src/task/session-authority.ts +148 -0
  155. package/src/task/session-ownership.ts +211 -0
  156. package/src/task/store.ts +2887 -0
  157. package/src/task/sync.ts +343 -0
  158. package/src/task/trigger.ts +260 -0
  159. package/src/tools/bash.ts +377 -211
  160. package/src/tools/code_run.ts +1 -1
  161. package/src/tools/delete_file.ts +1 -1
  162. package/src/tools/edit.ts +33 -6
  163. package/src/tools/evidence.ts +30 -0
  164. package/src/tools/git.ts +4 -4
  165. package/src/tools/glob.ts +12 -3
  166. package/src/tools/grep.ts +1 -1
  167. package/src/tools/lsp.ts +4 -4
  168. package/src/tools/mcp_call.ts +11 -4
  169. package/src/tools/memory.ts +153 -18
  170. package/src/tools/move_file.ts +1 -1
  171. package/src/tools/patch.ts +1 -1
  172. package/src/tools/read_file.ts +1 -1
  173. package/src/tools/read_image.ts +1 -1
  174. package/src/tools/submit_result.ts +1 -1
  175. package/src/tools/task.ts +437 -41
  176. package/src/tools/todo.ts +662 -35
  177. package/src/tools/web_fetch.ts +4 -2
  178. package/src/tools/web_search.ts +9 -3
  179. package/src/tools/write_file.ts +1 -1
  180. package/src/ui/assistant/simple.ts +123 -50
  181. package/src/ui/assistant/turn-status.ts +17 -3
  182. package/src/ui/contract.ts +184 -0
  183. package/src/ui/footer.ts +54 -18
  184. package/src/ui/i18n/en.ts +62 -6
  185. package/src/ui/i18n/id.ts +62 -6
  186. package/src/ui/input/prompt-engine.ts +120 -25
  187. package/src/ui/render/errors.ts +39 -1
  188. package/src/ui/render/markdown-table.ts +455 -0
  189. package/src/ui/render/markdown.ts +22 -1
  190. package/src/ui/render/table-grid.ts +184 -0
  191. package/src/ui/render/table.ts +15 -76
  192. package/src/ui/runtime/screen.ts +7 -2
  193. package/src/ui/runtime/statusline.ts +25 -6
  194. package/src/ui/tui/app.ts +598 -133
  195. package/src/ui/tui/transcript.ts +531 -89
  196. package/vendor/minicore/VENDOR.md +1 -1
  197. package/vendor/minicore/src/core/budget.ts +25 -25
  198. package/vendor/minicore/src/core/compact.ts +75 -75
  199. package/vendor/minicore/src/core/errors.ts +59 -59
  200. package/vendor/minicore/src/core/events.ts +73 -73
  201. package/vendor/minicore/src/core/executor.ts +139 -139
  202. package/vendor/minicore/src/core/history.ts +31 -31
  203. package/vendor/minicore/src/core/index.ts +41 -41
  204. package/vendor/minicore/src/core/loop.ts +355 -355
  205. package/vendor/minicore/src/core/permission.ts +22 -22
  206. package/vendor/minicore/src/core/provider.ts +39 -39
  207. package/vendor/minicore/src/core/recovery.ts +35 -35
  208. package/vendor/minicore/src/core/session.ts +327 -327
  209. package/vendor/minicore/src/core/snapshot.ts +146 -146
  210. package/vendor/minicore/src/core/tokens.ts +107 -107
  211. package/vendor/minicore/src/core/tool.ts +115 -115
  212. package/vendor/minicore/src/core/types.ts +50 -50
  213. package/vendor/minicore/src/providers/openai-compat.ts +417 -417
  214. package/AGENTS.md +0 -45
  215. package/PLAN.md +0 -491
  216. package/docs/ARCHITECTURE.html +0 -1248
  217. package/docs/CONTROL-PLANE-MAP.md +0 -139
  218. package/docs/HARNESS.md +0 -150
  219. package/docs/SUMMARY.md +0 -52
  220. package/docs/UI_RENDER_PIPELINE.md +0 -165
  221. package/docs/USAGE.md +0 -11
@@ -0,0 +1,387 @@
1
+ // PHASE 6AB - SCHEDULER OPERATOR OBSERVABILITY.
2
+ //
3
+ // WHY A SEPARATE MODULE
4
+ //
5
+ // Phase 6AA proved the enablement gate is correct and that `--enable-scheduler`
6
+ // produces a real, authority-holding Scheduler - and that every one of the ten-plus
7
+ // `SchedulerEvent` variants and four `TriggerEvent` variants was constructed and
8
+ // then DISCARDED, because production passed no sink to either constructor.
9
+ //
10
+ // This module is the missing sink, reduced to the smallest thing that answers the
11
+ // nine questions §7 asks:
12
+ //
13
+ // 1. Is Scheduler enabled? -> `probe()` / OFF state
14
+ // 2. Did it acquire authority? -> active flag (start() throws without a lease)
15
+ // 3. Did a trigger occur? -> trigger:* events
16
+ // 4. Which task was selected? -> task:selected
17
+ // 5. Did execution start? -> task:execution_started
18
+ // 6. Did execution return? -> task:execution_completed / _abandoned
19
+ // 7. Was it cancelled? -> task:execution_completed{ok:false} + cycle reason
20
+ // 8. Did authority disappear? -> cycle:stopped{reason:"authority-lost"}
21
+ // 9. Did the Scheduler stop? -> explicit noteStopped() from the stop route
22
+ //
23
+ // [DESIGN DECISION] NO new event type is introduced and NO existing event is
24
+ // reinterpreted. Every answer above is already present in the two event unions as
25
+ // 6T defined them; 6AA's finding was that nothing was listening, not that the
26
+ // vocabulary was insufficient. Adding an event would have been a semantic change
27
+ // to a layer §23 puts out of scope.
28
+ //
29
+ // [DESIGN DECISION] The probe is authoritative; events are a refinement. An
30
+ // operator asking "is it on?" must never be told "idle" by a stale in-memory
31
+ // counter while the handle says the Scheduler is stopped - or "running" while the
32
+ // handle was never constructed at all. So `state()` takes the handle first and
33
+ // only consults `hint` for the distinction between idle, executing and error.
34
+ //
35
+ // [DESIGN DECISION] Nothing here throws and nothing here awaits. A diagnostic that
36
+ // can crash a cycle is worse than a missing diagnostic - the same rule 6T applied
37
+ // to `Scheduler.emit` and `TriggerCoordinator.emit`, applied once more here so
38
+ // the three layers cannot disagree about who is allowed to fail.
39
+
40
+ import type { CycleStop, SchedulerEvent } from "./scheduler.ts"
41
+ import type { TriggerEvent } from "./trigger.ts"
42
+
43
+ /**
44
+ * [PHASE 6AB][DESIGN DECISION] The four operator-visible conditions §7 requires,
45
+ * plus the error case. This is the whole of the public observability contract:
46
+ * an operator never reads a counter to answer "is it working", only this.
47
+ */
48
+ export type SchedulerOperatorState =
49
+ /** Gate shut. No Scheduler exists, nothing is constructed, nothing can be fired. */
50
+ | "OFF"
51
+ /** Constructed, holds authority, no cycle in flight. Waiting for a trigger. */
52
+ | "ON_IDLE"
53
+ /** A cycle is in flight, or autonomous execution is running. */
54
+ | "ON_EXECUTING"
55
+ /** Constructed once, no longer active: operator stop, shutdown, or lost authority. */
56
+ | "ON_STOPPED"
57
+ /** A cycle failed, or the graph was invalid. Authority may still be held. */
58
+ | "ON_ERROR"
59
+
60
+ /** The minimum a caller must expose for the probe to be meaningful. */
61
+ export interface SchedulerProbe {
62
+ readonly enabled: boolean
63
+ readonly constructed: boolean
64
+ isActive(): boolean
65
+ }
66
+
67
+ /** Bounded in-memory activity log. An observation, never a durable fact. */
68
+ export interface SchedulerNotice {
69
+ readonly at: number
70
+ readonly line: string
71
+ }
72
+
73
+ export interface SchedulerStatusSnapshot {
74
+ readonly state: SchedulerOperatorState
75
+ /** Counts since process start. Deliberately not persisted - see module header. */
76
+ readonly counts: Readonly<{
77
+ triggersRequested: number
78
+ evaluations: number
79
+ coalesced: number
80
+ refused: number
81
+ executions: number
82
+ failures: number
83
+ }>
84
+ /** Set when the state is ON_ERROR, so an operator sees the cause not the class. */
85
+ readonly lastError: string | null
86
+ readonly lastTaskId: string | null
87
+ readonly lastCycleStop: string | null
88
+ readonly recent: readonly SchedulerNotice[]
89
+ }
90
+
91
+ const MAX_NOTICES = 40
92
+
93
+ /**
94
+ * The operator projection. One instance per process, owned by the composition
95
+ * root - never stored in TaskStore, TaskGraph or any durable state, because none
96
+ * of it is a fact about the world.
97
+ */
98
+ export class SchedulerObservability {
99
+ private hint: "idle" | "executing" | "error" | "stopped" = "idle"
100
+ private stoppedReason: string | null = null
101
+ private lastError: string | null = null
102
+ private lastTaskId: string | null = null
103
+ private lastCycleStop: string | null = null
104
+ private notices: SchedulerNotice[] = []
105
+ private sink: ((line: string) => void) | null = null
106
+ private counts = {
107
+ triggersRequested: 0,
108
+ evaluations: 0,
109
+ coalesced: 0,
110
+ refused: 0,
111
+ executions: 0,
112
+ failures: 0,
113
+ }
114
+
115
+ /**
116
+ * The presentation hook. Set by the TUI driver AFTER construction.
117
+ *
118
+ * [PHASE 6AB][DESIGN DECISION] Set late on purpose. `createProductionScheduler`
119
+ * is awaited inside `createCliSession`, which runs BEFORE the Transcript
120
+ * exists, so a sink wired at construction could only ever write into a
121
+ * half-initialised UI. Anything emitted before a sink attaches is retained in
122
+ * the bounded log and still reachable through `status()`, so early events are
123
+ * delayed rather than lost.
124
+ */
125
+ onSchedulerNotice(handler: ((line: string) => void) | null): void {
126
+ this.sink = handler
127
+ }
128
+
129
+ /** True once the composition root constructed a real (non-inert) handle. */
130
+ private enabled(probe: SchedulerProbe | null): boolean {
131
+ return probe?.enabled === true && probe.constructed
132
+ }
133
+
134
+ /** Absorbs one SchedulerEvent. Never throws. */
135
+ noteSchedulerEvent(event: SchedulerEvent): void {
136
+ try {
137
+ switch (event.kind) {
138
+ case "task:recovered":
139
+ this.record(`recovered ${event.taskIds.length} interrupted attempt(s)`)
140
+ break
141
+
142
+ case "task:selected":
143
+ this.lastTaskId = event.taskId
144
+ this.hint = "executing"
145
+ this.record(`selected ${event.taskId}`)
146
+ break
147
+
148
+ case "task:claimed":
149
+ this.hint = "executing"
150
+ this.lastTaskId = event.taskId
151
+ this.record(`claimed ${event.taskId} (revision ${event.revision})`)
152
+ break
153
+
154
+ case "task:claim_rejected":
155
+ // A refused claim is NORMAL - it is the stale race working. It is
156
+ // reported, never escalated to an error state.
157
+ this.record(`claim rejected for ${event.taskId}: ${event.outcome}`)
158
+ break
159
+
160
+ case "task:dispatch_started":
161
+ this.hint = "executing"
162
+ this.lastTaskId = event.taskId
163
+ this.record(`dispatch started for ${event.taskId}`)
164
+ break
165
+
166
+ case "task:execution_started":
167
+ this.hint = "executing"
168
+ this.counts.executions++
169
+ this.lastTaskId = event.taskId
170
+ this.record(`executing ${event.taskId}`)
171
+ break
172
+
173
+ case "task:execution_completed":
174
+ this.record(`execution finished for ${event.taskId}: ok=${String(event.ok)}`)
175
+ break
176
+
177
+ case "task:execution_abandoned":
178
+ // The attempt ended but nothing durable could be recorded. Distinct from
179
+ // a failure: the task is intact and a later owner may retry it.
180
+ this.counts.failures++
181
+ this.lastError = `execution abandoned (${event.outcome})`
182
+ this.hint = "error"
183
+ this.record(`execution abandoned for ${event.taskId}: ${event.outcome}`)
184
+ break
185
+
186
+ case "cycle:invalid_graph":
187
+ this.counts.failures++
188
+ this.lastError = "task graph is invalid"
189
+ this.hint = "error"
190
+ this.record("cycle refused: invalid task graph")
191
+ break
192
+
193
+ case "cycle:stopped":
194
+ this.record(this.describeCycleStop(event.reason))
195
+ // [PHASE 6AB][DESIGN DECISION] ONLY the two reasons 6Q/6X document as
196
+ // "self-disposed" may set the stopped hint. Every other reason merely
197
+ // ended a cycle.
198
+ //
199
+ // Inferring stop from, say, `ownership-unavailable` would make
200
+ // `/scheduler status` assert "STOPPED" while `isActive()` said true -
201
+ // an operator told a falsehood by a diagnostic, which is the one
202
+ // failure mode observability exists to prevent. Where self-disposal
203
+ // actually happened the probe reports it anyway, and the probe is
204
+ // authoritative.
205
+ if (event.reason === "authority-lost" || event.reason === "session-superseded") {
206
+ this.hint = "stopped"
207
+ this.stoppedReason = String(event.reason)
208
+ this.lastError = "session authority was lost"
209
+ } else if (event.reason === "ownership-unavailable") {
210
+ // Authority could not be taken. Recorded as a fault, NOT as a stop.
211
+ this.counts.failures++
212
+ this.lastError = "session authority is held by another process"
213
+ this.hint = "error"
214
+ } else {
215
+ this.hint = "idle"
216
+ }
217
+ break
218
+ }
219
+ } catch {
220
+ // Observability is not authority. A malformed event must not take the
221
+ // cycle down; the count of failures here is itself not worth recording.
222
+ }
223
+ }
224
+
225
+ /** Absorbs one TriggerEvent. Never throws. */
226
+ noteTriggerEvent(event: TriggerEvent): void {
227
+ try {
228
+ switch (event.kind) {
229
+ case "trigger:evaluated":
230
+ this.counts.evaluations++
231
+ this.hint = "executing"
232
+ this.record(`trigger evaluated (${event.source})`)
233
+ break
234
+
235
+ case "trigger:coalesced":
236
+ this.counts.coalesced++
237
+ this.record(`trigger coalesced into running cycle (${event.source})`)
238
+ break
239
+
240
+ case "trigger:refused":
241
+ this.counts.refused++
242
+ this.record(`trigger refused: ${event.outcome} (${event.source})`)
243
+ break
244
+
245
+ case "trigger:cycle_failed":
246
+ this.counts.failures++
247
+ this.lastError = event.detail
248
+ this.hint = "error"
249
+ this.record(`cycle failed: ${event.detail}`)
250
+ break
251
+ }
252
+ } catch {
253
+ /* deliberately swallowed - same rule as noteSchedulerEvent */
254
+ }
255
+ }
256
+
257
+ /**
258
+ * Called by the production stop route, not by the event stream.
259
+ *
260
+ * `Scheduler.stop()` releases authority and does not emit a `cycle:stopped` of
261
+ * its own, so without this note an operator who ran `/scheduler stop` would see
262
+ * the state flip from the probe while the activity log's last line described
263
+ * something older. The reason is recorded so the log explains the transition.
264
+ */
265
+ noteStopped(reason: string): void {
266
+ try {
267
+ this.hint = "stopped"
268
+ this.stoppedReason = reason
269
+ this.record(`scheduler stopped (${reason})`)
270
+ } catch {
271
+ /* deliberately swallowed */
272
+ }
273
+ }
274
+
275
+ /**
276
+ * [PHASE 6AB] Derive the operator state.
277
+ *
278
+ * Order matters and is the whole point: OFF first (a null or inert probe means
279
+ * the gate is shut and every event-derived hint is meaningless), then the live
280
+ * active flag (authoritative for stopped), then the event hint.
281
+ */
282
+ state(probe: SchedulerProbe | null): SchedulerOperatorState {
283
+ if (!this.enabled(probe)) return "OFF"
284
+ const p = probe as SchedulerProbe
285
+ if (!p.isActive()) return "ON_STOPPED"
286
+ if (this.hint === "stopped") return "ON_STOPPED"
287
+ if (this.hint === "executing") return "ON_EXECUTING"
288
+ if (this.hint === "error") return "ON_ERROR"
289
+ return "ON_IDLE"
290
+ }
291
+
292
+ status(probe: SchedulerProbe | null): SchedulerStatusSnapshot {
293
+ return {
294
+ state: this.state(probe),
295
+ counts: { ...this.counts },
296
+ lastError: this.lastError,
297
+ lastTaskId: this.lastTaskId,
298
+ lastCycleStop: this.lastCycleStop,
299
+ recent: [...this.notices],
300
+ }
301
+ }
302
+
303
+ /** Why the scheduler stopped, when it did. `null` while it is still active. */
304
+ get stopReason(): string | null {
305
+ return this.stoppedReason
306
+ }
307
+
308
+ /**
309
+ * Why the most recent cycle ended, or `null` if none has ended yet.
310
+ *
311
+ * [PHASE 6AB] Public because the operator command needs to distinguish
312
+ * "evaluated, found nothing" from "evaluated, did something" WITHOUT
313
+ * re-deriving it from a counter. That distinction is the whole value of the
314
+ * `run` output; a count of evaluations alone cannot express it.
315
+ */
316
+ get lastCycleStopReason(): string | null {
317
+ return this.lastCycleStop
318
+ }
319
+
320
+ private describeCycleStop(reason: CycleStop): string {
321
+ this.lastCycleStop = String(reason)
322
+ switch (reason) {
323
+ case "no-candidates":
324
+ return "cycle finished: no ready task"
325
+ case "invalid-graph":
326
+ return "cycle finished: invalid task graph"
327
+ case "claim-rejected-stale":
328
+ return "cycle finished: claim rejected (stale)"
329
+ case "claim-not-found":
330
+ return "cycle finished: task disappeared before claim"
331
+ case "claim-wrong-state":
332
+ return "cycle finished: task was no longer claimable"
333
+ case "ownership-unavailable":
334
+ return "cycle finished: session authority held by another process"
335
+ case "already-dispatched":
336
+ return "cycle finished: work already dispatched"
337
+ case "not-running":
338
+ return "cycle finished: scheduler not running"
339
+ case "contended":
340
+ return "cycle finished: contended with another owner (no claim taken)"
341
+ case "pre-cancelled":
342
+ return "cycle finished: cancelled before evaluation"
343
+ case "session-superseded":
344
+ return "cycle finished: session superseded; scheduler self-disposed"
345
+ case "authority-lost":
346
+ return "cycle finished: session authority lost; scheduler self-disposed"
347
+ default:
348
+ return `cycle finished: ${String(reason)}`
349
+ }
350
+ }
351
+
352
+ private record(line: string): void {
353
+ const notice: SchedulerNotice = { at: Date.now(), line }
354
+ this.notices.push(notice)
355
+ if (this.notices.length > MAX_NOTICES) this.notices.splice(0, this.notices.length - MAX_NOTICES)
356
+ // A throwing presentation sink must not propagate back into the cycle that
357
+ // emitted the event - the third and last application of the same rule.
358
+ try {
359
+ this.sink?.(line)
360
+ } catch {
361
+ /* deliberately swallowed */
362
+ }
363
+ }
364
+ }
365
+
366
+ /**
367
+ * Human-readable, locale-free rendering of the four operator states.
368
+ *
369
+ * [PHASE 6AB][DESIGN DECISION] Deliberately NOT localised. This string is not UI
370
+ * prose - it is the value an operator compares against when deciding whether to
371
+ * intervene, and it is asserted verbatim by the production-path tests. The
372
+ * bilingual command help that surrounds it is localised normally.
373
+ */
374
+ export function describeOperatorState(state: SchedulerOperatorState): string {
375
+ switch (state) {
376
+ case "OFF":
377
+ return "scheduler OFF (not enabled for this process)"
378
+ case "ON_IDLE":
379
+ return "scheduler ON, idle (holds authority, waiting for /scheduler run)"
380
+ case "ON_EXECUTING":
381
+ return "scheduler ON, executing a cycle"
382
+ case "ON_STOPPED":
383
+ return "scheduler ON but STOPPED (no further scheduling; restart to re-enable)"
384
+ case "ON_ERROR":
385
+ return "scheduler ON, last cycle failed"
386
+ }
387
+ }