minicode-ai 0.11.1 → 0.13.1

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 (222) hide show
  1. package/CHANGELOG.md +95 -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/minicode.js +6 -0
  15. package/cli/recovery-warning.ts +115 -0
  16. package/cli/router.ts +32 -1
  17. package/cli/setup.ts +2332 -171
  18. package/cli/tui.ts +113 -7
  19. package/docs/OUTPUT_ARCHITECTURE_AUDIT.md +489 -0
  20. package/docs/OUTPUT_EVENT_MODEL.md +289 -0
  21. package/docs/OUTPUT_IMPLEMENTATION_PLAN.md +391 -0
  22. package/docs/OUTPUT_PROTOCOL_SPEC.md +285 -0
  23. package/docs/OUTPUT_RENDERING_SPEC.md +248 -0
  24. package/docs/OUTPUT_UX_RULES.md +449 -0
  25. package/docs/PLAN_UIUX_V6.md +2 -2
  26. package/docs/README.md +4 -3
  27. package/docs/TERMINAL_CONTRACT.md +278 -71
  28. package/docs/architecture.md +89 -7
  29. package/docs/changelog.md +1 -1
  30. package/docs/choosing-mode.md +2 -2
  31. package/docs/cli.md +9 -5
  32. package/docs/concepts.md +1 -1
  33. package/docs/contributing.md +9 -2
  34. package/docs/environment.md +6 -2
  35. package/docs/exec.md +46 -5
  36. package/docs/memory-sessions.md +2 -0
  37. package/docs/policy-sandbox.md +1 -1
  38. package/docs/pricing-budget.md +1 -1
  39. package/docs/quickstart.md +2 -2
  40. package/docs/repl.md +6 -2
  41. package/docs/security-model.md +1 -1
  42. package/docs/security.md +1 -1
  43. package/docs/skills.md +2 -2
  44. package/docs/terminal.md +9 -5
  45. package/docs/tools.md +1 -1
  46. package/package.json +36 -6
  47. package/src/app/session.ts +261 -15
  48. package/src/app/tool-layer.ts +94 -7
  49. package/src/daemon/approvals.ts +361 -0
  50. package/src/daemon/capability.ts +145 -0
  51. package/src/daemon/children.ts +142 -0
  52. package/src/daemon/client.ts +267 -0
  53. package/src/daemon/control.ts +350 -0
  54. package/src/daemon/discovery.ts +234 -0
  55. package/src/daemon/feed.ts +155 -0
  56. package/src/daemon/framing.ts +94 -0
  57. package/src/daemon/host.ts +316 -0
  58. package/src/daemon/protocol.ts +217 -0
  59. package/src/daemon/resource.ts +170 -0
  60. package/src/daemon/sanitize.ts +57 -0
  61. package/src/daemon/server.ts +627 -0
  62. package/src/daemon/store.ts +317 -0
  63. package/src/daemon/subscription.ts +270 -0
  64. package/src/daemon/telemetry.ts +81 -0
  65. package/src/hooks/run.ts +12 -1
  66. package/src/lib/atomic-write.ts +29 -3
  67. package/src/lib/db-path.ts +26 -0
  68. package/src/lib/keystore.ts +544 -42
  69. package/src/lib/net.ts +43 -1
  70. package/src/lib/safe-open.ts +116 -1
  71. package/src/lib/session-id.ts +15 -0
  72. package/src/lsp/client.ts +123 -5
  73. package/src/mcp/client.ts +139 -17
  74. package/src/mcp/server.ts +177 -50
  75. package/src/mcp/transport.ts +16 -19
  76. package/src/memory/vector.ts +770 -55
  77. package/src/policy/allowlist.ts +14 -2
  78. package/src/policy/bash-guard.ts +105 -10
  79. package/src/policy/compaction.ts +82 -5
  80. package/src/policy/consequence-engine.ts +220 -0
  81. package/src/policy/context.ts +132 -0
  82. package/src/policy/executor.ts +187 -121
  83. package/src/policy/no-progress.ts +559 -0
  84. package/src/policy/permission.ts +4 -8
  85. package/src/policy/pricing.ts +17 -3
  86. package/src/policy/scrub.ts +69 -2
  87. package/src/policy/tool-contract.ts +515 -0
  88. package/src/policy/usage.ts +310 -24
  89. package/src/policy/verifier.ts +6 -3
  90. package/src/policy/work-mode.ts +182 -0
  91. package/src/presentation/adapter.ts +533 -26
  92. package/src/presentation/events.ts +151 -0
  93. package/src/presentation/model.ts +180 -27
  94. package/src/presentation/projection.ts +858 -0
  95. package/src/presentation/reducer.ts +645 -310
  96. package/src/presentation/store.ts +12 -7
  97. package/src/providers/anthropic.ts +18 -10
  98. package/src/providers/responses.ts +2 -2
  99. package/src/runtime/capability.ts +409 -0
  100. package/src/runtime/child-execution.ts +274 -0
  101. package/src/runtime/composition.ts +958 -0
  102. package/src/runtime/dispatch.ts +591 -0
  103. package/src/runtime/execution-backend.ts +632 -0
  104. package/src/runtime/execution-events.ts +272 -0
  105. package/src/runtime/execution-id.ts +230 -0
  106. package/src/runtime/execution-journal.ts +926 -0
  107. package/src/runtime/execution-kernel.ts +456 -0
  108. package/src/runtime/execution-registry.ts +379 -0
  109. package/src/runtime/process-supervision.ts +276 -0
  110. package/src/runtime/production-execution.ts +551 -0
  111. package/src/runtime/production-runtime.ts +217 -0
  112. package/src/runtime/recovery-safety.ts +70 -0
  113. package/src/runtime/recovery.ts +477 -0
  114. package/src/runtime/runtime-capabilities.ts +179 -0
  115. package/src/runtime/runtime-diagnostics.ts +141 -0
  116. package/src/runtime/runtime-host.ts +365 -0
  117. package/src/runtime/runtime-status-facts.ts +222 -0
  118. package/src/runtime/runtime-status-provider.ts +74 -0
  119. package/src/runtime/runtime-status.ts +459 -0
  120. package/src/runtime/runtime-task-admission.ts +101 -0
  121. package/src/runtime/supervisor.ts +444 -0
  122. package/src/session/authority.ts +168 -0
  123. package/src/session/checkpoint.ts +88 -1
  124. package/src/session/context-adapter.ts +251 -0
  125. package/src/session/context-assembly.ts +242 -0
  126. package/src/session/context-identity.ts +389 -0
  127. package/src/session/context-projection.ts +248 -0
  128. package/src/session/context-selector.ts +500 -0
  129. package/src/session/cross-session-adoption.ts +249 -0
  130. package/src/session/full-history-fold.ts +171 -0
  131. package/src/session/identity.ts +192 -0
  132. package/src/session/journal.ts +805 -102
  133. package/src/session/open-work-intent.ts +732 -0
  134. package/src/session/open-work.ts +767 -0
  135. package/src/session/pending-tools.ts +94 -0
  136. package/src/session/persistence.ts +3569 -127
  137. package/src/session/runtime-header.ts +208 -0
  138. package/src/session/shadow-git.ts +13 -5
  139. package/src/session/verification.ts +1623 -0
  140. package/src/task/assignment.ts +136 -0
  141. package/src/task/autonomous-adapter.ts +168 -0
  142. package/src/task/autonomous-context.ts +630 -0
  143. package/src/task/autonomous-policy.ts +490 -0
  144. package/src/task/continuity.ts +179 -0
  145. package/src/task/execution-cancellation.ts +165 -0
  146. package/src/task/graph-validate.ts +379 -0
  147. package/src/task/graph.ts +305 -0
  148. package/src/task/identity.ts +230 -0
  149. package/src/task/model.ts +417 -0
  150. package/src/task/production-scheduler.ts +293 -0
  151. package/src/task/readiness.ts +229 -0
  152. package/src/task/scheduler-observability.ts +387 -0
  153. package/src/task/scheduler.ts +1197 -0
  154. package/src/task/scheduling-policy.ts +165 -0
  155. package/src/task/session-authority.ts +148 -0
  156. package/src/task/session-ownership.ts +211 -0
  157. package/src/task/store.ts +2887 -0
  158. package/src/task/sync.ts +343 -0
  159. package/src/task/trigger.ts +260 -0
  160. package/src/tools/bash.ts +377 -211
  161. package/src/tools/code_run.ts +1 -1
  162. package/src/tools/delete_file.ts +1 -1
  163. package/src/tools/edit.ts +33 -6
  164. package/src/tools/evidence.ts +30 -0
  165. package/src/tools/git.ts +4 -4
  166. package/src/tools/glob.ts +12 -3
  167. package/src/tools/grep.ts +1 -1
  168. package/src/tools/lsp.ts +4 -4
  169. package/src/tools/mcp_call.ts +11 -4
  170. package/src/tools/memory.ts +153 -18
  171. package/src/tools/move_file.ts +1 -1
  172. package/src/tools/patch.ts +1 -1
  173. package/src/tools/read_file.ts +1 -1
  174. package/src/tools/read_image.ts +1 -1
  175. package/src/tools/submit_result.ts +1 -1
  176. package/src/tools/task.ts +437 -41
  177. package/src/tools/todo.ts +662 -35
  178. package/src/tools/web_fetch.ts +4 -2
  179. package/src/tools/web_search.ts +9 -3
  180. package/src/tools/write_file.ts +1 -1
  181. package/src/ui/assistant/simple.ts +123 -50
  182. package/src/ui/assistant/turn-status.ts +17 -3
  183. package/src/ui/contract.ts +184 -0
  184. package/src/ui/footer.ts +52 -19
  185. package/src/ui/i18n/en.ts +58 -6
  186. package/src/ui/i18n/id.ts +58 -6
  187. package/src/ui/input/prompt-engine.ts +120 -25
  188. package/src/ui/render/errors.ts +39 -1
  189. package/src/ui/render/markdown-table.ts +455 -0
  190. package/src/ui/render/markdown.ts +22 -1
  191. package/src/ui/render/table-grid.ts +184 -0
  192. package/src/ui/render/table.ts +15 -76
  193. package/src/ui/runtime/screen.ts +7 -2
  194. package/src/ui/runtime/statusline.ts +25 -6
  195. package/src/ui/tui/app.ts +507 -169
  196. package/src/ui/tui/transcript.ts +531 -89
  197. package/vendor/minicore/VENDOR.md +1 -1
  198. package/vendor/minicore/src/core/budget.ts +25 -25
  199. package/vendor/minicore/src/core/compact.ts +75 -75
  200. package/vendor/minicore/src/core/errors.ts +59 -59
  201. package/vendor/minicore/src/core/events.ts +73 -73
  202. package/vendor/minicore/src/core/executor.ts +139 -139
  203. package/vendor/minicore/src/core/history.ts +31 -31
  204. package/vendor/minicore/src/core/index.ts +41 -41
  205. package/vendor/minicore/src/core/loop.ts +355 -355
  206. package/vendor/minicore/src/core/permission.ts +22 -22
  207. package/vendor/minicore/src/core/provider.ts +39 -39
  208. package/vendor/minicore/src/core/recovery.ts +35 -35
  209. package/vendor/minicore/src/core/session.ts +327 -327
  210. package/vendor/minicore/src/core/snapshot.ts +146 -146
  211. package/vendor/minicore/src/core/tokens.ts +107 -107
  212. package/vendor/minicore/src/core/tool.ts +115 -115
  213. package/vendor/minicore/src/core/types.ts +50 -50
  214. package/vendor/minicore/src/providers/openai-compat.ts +417 -417
  215. package/AGENTS.md +0 -45
  216. package/PLAN.md +0 -491
  217. package/docs/ARCHITECTURE.html +0 -1248
  218. package/docs/CONTROL-PLANE-MAP.md +0 -139
  219. package/docs/HARNESS.md +0 -150
  220. package/docs/SUMMARY.md +0 -52
  221. package/docs/UI_RENDER_PIPELINE.md +0 -169
  222. package/docs/USAGE.md +0 -11
@@ -0,0 +1,1197 @@
1
+ // Phase 6C — Scheduler core: headless, dependency-injected, single-session,
2
+ // serial. NEW ARCHITECTURE.
3
+ //
4
+ // Implements the Phase 6A design lock. NOT wired into production: nothing in
5
+ // src/ constructs a Scheduler, and this module imports nothing that could.
6
+ //
7
+ // ── WHAT IT IS ───────────────────────────────────────────────────────────────
8
+ //
9
+ // Three questions have three owners, kept strictly apart:
10
+ //
11
+ // TaskGraph "what is executable right now, and why?" (read-only)
12
+ // Scheduler "what do we attempt next, and under what lifecycle/recovery rules?"
13
+ // TaskStore "what is durably true?" (sole writer)
14
+ //
15
+ // ── WHAT IT DELIBERATELY DOES NOT DO ─────────────────────────────────────────
16
+ //
17
+ // * no SQLite, no bun:sqlite, no TaskStore internals
18
+ // * no readiness reimplementation — `readyTasks()` is consumed verbatim
19
+ // * no graph semantics, no dependency derivation, no blocker inference
20
+ // * never writes COMPLETED, never verifies, never manufactures evidence
21
+ // * never calls parallelExecutor, tools, providers or permissions
22
+ // * no retry policy, no lease, no heartbeat, no priority, no fairness
23
+ // * no message-history or transcript reads for task truth
24
+ // * presentation_events is never an input
25
+ //
26
+ // ── SHAPE PROVENANCE ─────────────────────────────────────────────────────────
27
+ //
28
+ // HISTORICAL DESIGN EVIDENCE (recovered `p77-repro.ts` call sites) justifies the
29
+ // SHAPE only: `new Scheduler(sessionId, { store, runTurn, instruction })`,
30
+ // `discover()`, `getActiveClaim()`. Those are signatures a test once used. They
31
+ // are not evidence of any behaviour, and none is inferred from them.
32
+ //
33
+ // NOT adopted, having no evidence anywhere: `canExecute`, `blockingDeps`,
34
+ // `topological`, `sourceRevision`. Those names appeared in a brief and were
35
+ // never found in any artifact; 5A recorded them as unsourced.
36
+ //
37
+ // ── V1 DEPLOYMENT INVARIANT ──────────────────────────────────────────────────
38
+ //
39
+ // A session must not be concurrently driven by independent Scheduler instances
40
+ // across OS processes. Session ownership is process-local (Phase 6B) and cannot
41
+ // see another OS process, so this module does not pretend to prevent it. It
42
+ // prevents concurrent ownership *within* a process, and refuses to act when
43
+ // ownership is uncertain.
44
+
45
+ import {
46
+ type ContinuityClass,
47
+ type ContinuityContext,
48
+ type ContinuityEvidence,
49
+ type ContinuityGate,
50
+ classifyContinuity,
51
+ } from "./continuity.ts"
52
+ import {
53
+ type CancelReason,
54
+ type ExecutionHandle,
55
+ newExecutionHandle,
56
+ type PerTurnCancellation,
57
+ } from "./execution-cancellation.ts"
58
+ import { TaskGraph } from "./graph.ts"
59
+ import { type ClaimOutcome, TaskError, type TaskSnapshot } from "./model.ts"
60
+ import { selectTask } from "./scheduling-policy.ts"
61
+ import { newOwnerToken, SESSION_LEASE_MS, SESSION_RENEW_INTERVAL_MS } from "./session-authority.ts"
62
+ import type { SessionOwner } from "./session-ownership.ts"
63
+
64
+ // Re-exported so a composition root needs one import to wire a cancellation-aware
65
+ // bridge, and so the Scheduler's public vocabulary stays in one file.
66
+ export type { CancelReason, ExecutionHandle } from "./execution-cancellation.ts"
67
+
68
+ import {
69
+ acquireSessionOwnership,
70
+ ownsSession,
71
+ releaseSessionOwnership,
72
+ } from "./session-ownership.ts"
73
+ import type { AttemptRecordOutcome, TaskStore } from "./store.ts"
74
+
75
+ // ── lifecycle ────────────────────────────────────────────────────────────────
76
+
77
+ export type SchedulerState = "CREATED" | "RUNNING" | "IDLE" | "STOPPING" | "STOPPED"
78
+
79
+ /** Why a cycle ended. Never inferred from events. */
80
+ export type CycleStop =
81
+ | "no-candidates"
82
+ | "invalid-graph"
83
+ | "claim-rejected-stale"
84
+ | "claim-not-found"
85
+ | "claim-wrong-state"
86
+ | "ownership-unavailable"
87
+ | "already-dispatched"
88
+ | "not-running"
89
+ /**
90
+ * [PHASE 6T] The runtime was already busy when the cycle was evaluated.
91
+ *
92
+ * NON-CONSUMING, and that is the entire point of the outcome. No claim, no
93
+ * generation, no owner, no attempt lineage. The task is left exactly as it was
94
+ * and the next trigger re-evaluates it.
95
+ */
96
+ | "contended"
97
+ /** [PHASE 6T] Contention was known before evaluation began; nothing was read. */
98
+ | "pre-cancelled"
99
+ /**
100
+ * [PHASE 6T] The session this instance was serving no longer exists in the
101
+ * lifetime it started for. Self-disposed; ownership released for a replacement.
102
+ */
103
+ | "session-superseded"
104
+ /** [PHASE 6X] Cross-process authority was lost; the instance self-disposed. */
105
+ | "authority-lost"
106
+
107
+ /** Why a work item could not be handed to the agent loop. */
108
+ export type DispatchFailure =
109
+ | "scheduler-not-running"
110
+ | "bridge-threw"
111
+ | "bridge-not-callable"
112
+ /**
113
+ * [PHASE 6Q] The turn ended but no active claim identified which generation it
114
+ * belonged to, so no lineage was recorded. Distinct from a persistence error:
115
+ * the instance stays usable, which is the whole point.
116
+ */
117
+ | "attempt-unidentified"
118
+
119
+ export type ExecutionObservation =
120
+ /** The turn returned. `ok` is an OBSERVATION, not a verdict on the work. */
121
+ | { readonly kind: "returned"; readonly ok: boolean; readonly detail?: string }
122
+ /** The turn threw or rejected. The attempt WAS established. */
123
+ | { readonly kind: "rejected"; readonly detail: string }
124
+
125
+ /**
126
+ * The work item handed to the agent loop.
127
+ *
128
+ * Contains exactly the three locked fields, and nothing derived from message
129
+ * history: the composition root decides how to run it.
130
+ */
131
+ export interface SchedulerWorkItem {
132
+ readonly taskId: string
133
+ readonly title: string
134
+ readonly instruction: string
135
+ readonly sessionId: string
136
+ }
137
+
138
+ /**
139
+ * The injected execution bridge. Scheduler authorizes; this runs.
140
+ *
141
+ * A `dispatch-failed` (a synchronous throw before the promise exists) means the
142
+ * attempt was never established, which is materially different from a rejected
143
+ * turn. Scheduler must not fake that distinction with an invented flag — it is
144
+ * derived from whether the call returned a promise at all.
145
+ */
146
+ export type RunTurn = (
147
+ work: SchedulerWorkItem,
148
+ /**
149
+ * [PHASE 6T] The per-execution cancellation handle for THIS dispatch.
150
+ *
151
+ * Optional so every existing bridge keeps compiling unchanged. A bridge that
152
+ * ignores it simply cannot be cancelled mid-turn — which is a capability gap,
153
+ * not a correctness gap, and the composition root chooses whether to close it.
154
+ */
155
+ active?: ExecutionHandle,
156
+ ) => Promise<ExecutionObservation> | ExecutionObservation
157
+
158
+ /**
159
+ * Observations. Strictly one-way: they are emitted, never consumed. Scheduler
160
+ * state is never reconstructed from them.
161
+ */
162
+ export type SchedulerEvent =
163
+ | { readonly kind: "task:recovered"; readonly taskIds: readonly string[] }
164
+ | { readonly kind: "task:selected"; readonly taskId: string }
165
+ | { readonly kind: "task:claimed"; readonly taskId: string; readonly revision: number }
166
+ | {
167
+ readonly kind: "task:claim_rejected"
168
+ readonly taskId: string
169
+ readonly outcome: ClaimOutcome
170
+ }
171
+ | { readonly kind: "task:dispatch_started"; readonly taskId: string }
172
+ | { readonly kind: "task:execution_started"; readonly taskId: string }
173
+ | { readonly kind: "task:execution_completed"; readonly taskId: string; readonly ok: boolean }
174
+ /**
175
+ * [PHASE 6Q] The attempt ended but its completion could NOT be recorded, because
176
+ * the session was deleted under it or a later generation superseded it. Nothing
177
+ * was written; the task is left for the next owner to decide.
178
+ */
179
+ | {
180
+ readonly kind: "task:execution_abandoned"
181
+ readonly taskId: string
182
+ readonly outcome: AttemptRecordOutcome
183
+ }
184
+ /**
185
+ * [P13.3 Stage C] A stranded generation was deliberately NOT reconciled.
186
+ *
187
+ * `class` is the retry-safety classification, `reason` names the missing
188
+ * proof. This is an observation only: the durable record is untouched, which
189
+ * is exactly what HOLD/REQUIRES_VERIFIER mean.
190
+ */
191
+ | {
192
+ readonly kind: "task:continuity_held"
193
+ readonly taskId: string
194
+ readonly class: ContinuityClass
195
+ readonly reason: string
196
+ }
197
+ | { readonly kind: "cycle:invalid_graph" }
198
+ | { readonly kind: "cycle:stopped"; readonly reason: CycleStop }
199
+
200
+ export interface SchedulerOptions {
201
+ readonly store: TaskStore
202
+ readonly runTurn: RunTurn
203
+ /** The instruction template handed to the agent loop with every work item. */
204
+ readonly instruction: string
205
+ /** Optional observation sink. Absence means events are dropped, not queued. */
206
+ readonly onEvent?: (event: SchedulerEvent) => void
207
+ /** Optional cancellation the composition root owns. Scheduler never invents one. */
208
+ readonly cancellation?: { readonly isCancelled: () => boolean }
209
+ /**
210
+ * [PHASE 6X] Pre-existing authority token, when the composition root owns the
211
+ * lease. Omit and the Scheduler mints its own at start().
212
+ */
213
+ readonly authorityToken?: string
214
+ /**
215
+ * [P13.3 Stage C] Retry-safety evidence for automatic reconciliation.
216
+ *
217
+ * ABSENT = HOLD. The Scheduler cannot prove that re-running arbitrary work is
218
+ * free of duplicate external effects, so it must not revert a stranded
219
+ * generation on lineage alone. A composition root that CAN prove it (the
220
+ * production autonomous bridge, whose tool scope is the 6S read-only matrix)
221
+ * supplies the evidence here.
222
+ */
223
+ readonly continuity?: ContinuityGate
224
+ }
225
+
226
+ export interface ActiveClaim {
227
+ readonly taskId: string
228
+ /**
229
+ * The revision AFTER the accepted claim. Never the pre-claim revision, never
230
+ * the graph's revision, never a timestamp, never `sourceMaxRevision` -
231
+ * a release must address the state the claim actually produced.
232
+ */
233
+ readonly claimRevision: number
234
+ /**
235
+ * [PHASE 6I] The EXECUTION GENERATION created by the accepted claim, returned
236
+ * by `claimTask` from the same atomic statement that set `IN_PROGRESS`.
237
+ *
238
+ * This is the identity an attempt belongs to, and it is deliberately NOT the
239
+ * revision: `claimRevision` changes on every unrelated task write, which is
240
+ * exactly what let a stale completion protect a later generation (6G D1).
241
+ * `execGeneration` advances only when a claim is accepted.
242
+ */
243
+ readonly execGeneration: number
244
+ /**
245
+ * [PHASE 6Q] The session INCARNATION the claim was made under.
246
+ *
247
+ * `taskId` is allocated per session and restarts at `t1`, so a session deleted
248
+ * and recreated under the same id has task ids indistinguishable from the
249
+ * deleted ones - and a `execGeneration` that a fresh claim can legitimately
250
+ * match. This token is how a late execution recognises that the row it is
251
+ * about to touch belongs to a DIFFERENT session lifetime. Deletion bumps it.
252
+ */
253
+ readonly sessionIncarnation: number
254
+ }
255
+
256
+ export class SchedulerError extends Error {
257
+ readonly reason: string
258
+ constructor(reason: string, message: string) {
259
+ super(message)
260
+ this.name = "SchedulerError"
261
+ this.reason = reason
262
+ }
263
+ }
264
+
265
+ export class Scheduler {
266
+ readonly sessionId: string
267
+
268
+ private readonly store: TaskStore
269
+ private readonly runTurn: RunTurn
270
+ private readonly instruction: string
271
+ private readonly onEvent: ((e: SchedulerEvent) => void) | undefined
272
+ private readonly cancellation: { readonly isCancelled: () => boolean } | undefined
273
+ /** [P13.3 Stage C] Null = no proof, so reconciliation holds (fail closed). */
274
+ private readonly continuity: ContinuityGate | null
275
+
276
+ private state: SchedulerState = "CREATED"
277
+ private owner: SessionOwner | null = null
278
+ private claim: ActiveClaim | null = null
279
+
280
+ /**
281
+ * [PHASE 6T] The cancellation handle for the turn currently in flight, or null.
282
+ *
283
+ * One at a time, because V1 is serial — the same guarantee `inFlight` provides
284
+ * for cycles. Replacing it rather than stacking is deliberate: a second handle
285
+ * could only mean a second concurrent turn, which this Scheduler never starts.
286
+ */
287
+ private active: PerTurnCancellation | null = null
288
+
289
+ /**
290
+ * [PHASE 6T] The session incarnation this instance started under.
291
+ *
292
+ * [DESIGN DECISION] 6Q taught the Scheduler to self-dispose when a lineage
293
+ * write comes back `TASK_GONE`/`SESSION_SUPERSEDED` — but that only happens on
294
+ * the CLAIM path, while a turn is ending. A scheduler that is merely IDLE when
295
+ * its session is deleted never writes anything, never learns, and keeps
296
+ * holding the process-local ownership token, which wedges every replacement:
297
+ * a recreated session cannot start, because a dead instance still owns it.
298
+ * Proved by probe before this fix.
299
+ *
300
+ * The fix reuses 6Q's own fact rather than inventing a liveness mechanism: the
301
+ * incarnation is captured at `start()` and compared at the top of every cycle.
302
+ * If it moved, this session was deleted or superseded, and the instance's work
303
+ * is meaningless. This STRENGTHENS 6Q — same durable evidence, checked at cycle
304
+ * granularity instead of only at lineage-write time — and it is the answer to
305
+ * 6T's requirement that a Scheduler never need a restart because of stale
306
+ * internal ownership.
307
+ */
308
+ private incarnationAtStart: number | null = null
309
+
310
+ // -- [PHASE 6X] cross-process authority ---------------------------------------
311
+ /** The durable lease token for THIS authority. Null until start(). */
312
+ private authorityToken: string | null = null
313
+ /** Set when a lease is lost; from then on this instance must not schedule. */
314
+ private authorityLost = false
315
+ /** Renewal heartbeat. unref'd, and cleared on every stop path. */
316
+ private renewTimer: ReturnType<typeof setInterval> | null = null
317
+
318
+ /**
319
+ * V1 is SERIAL. A cycle in progress makes any further call wait for it, which
320
+ * is why N concurrent `cycle()` calls can never produce two dispatches. This
321
+ * is the Scheduler serializing ITSELF — TaskStore is not asked to do it.
322
+ */
323
+ private inFlight: Promise<CycleResult> | null = null
324
+
325
+ constructor(sessionId: string, opts: SchedulerOptions) {
326
+ this.sessionId = sessionId
327
+ this.store = opts.store
328
+ this.runTurn = opts.runTurn
329
+ this.instruction = opts.instruction
330
+ this.onEvent = opts.onEvent
331
+ this.cancellation = opts.cancellation
332
+ this.continuity = opts.continuity ?? null
333
+ // P2.2: token otoritas milik composition root (satu penulis per boot).
334
+ // Tanpa ini opsi authorityToken mati (selalu mint sendiri) dan sesi +
335
+ // scheduler-nya saling menolak lease. Bukan redesign protokol: acquire/
336
+ // renew/release/holds tak berubah; hanya sumber token disatukan.
337
+ this.authorityToken = opts.authorityToken ?? null
338
+ }
339
+
340
+ // ── lifecycle ──────────────────────────────────────────────────────────────
341
+
342
+ getLifecycle(): SchedulerState {
343
+ return this.state
344
+ }
345
+
346
+ /**
347
+ * Acquire session ownership, then begin scheduling.
348
+ *
349
+ * Idempotent while running. Refused after STOPPED: a stopped Scheduler never
350
+ * begins new work, and a silent no-op would make a dead subsystem look alive.
351
+ *
352
+ * Fails closed when ownership is unavailable — a competing in-process owner
353
+ * blocks this instance rather than being worked around.
354
+ */
355
+ start(): void {
356
+ if (this.state === "STOPPED") {
357
+ throw new SchedulerError("stopped", "scheduler is STOPPED and cannot be restarted")
358
+ }
359
+ if (this.state === "RUNNING" || this.state === "IDLE") return
360
+
361
+ if (this.owner === null) {
362
+ const owner = acquireSessionOwnership(this.sessionId, "scheduler")
363
+ if (owner === null) {
364
+ // Another owner exists in this process. Fail closed; do not guess.
365
+ this.state = "STOPPED"
366
+ throw new SchedulerError(
367
+ "ownership-unavailable",
368
+ `session ${this.sessionId} is already owned in this process`,
369
+ )
370
+ }
371
+ this.owner = owner
372
+ // [PHASE 6W/6X] Remember which lifetime of this session we are serving, so a
373
+ // deletion that happens while we sit idle cannot go unnoticed.
374
+ this.incarnationAtStart = this.store.getSessionIncarnation(this.sessionId)
375
+ }
376
+
377
+ // [PHASE 6X] DURABLE, CROSS-PROCESS AUTHORITY.
378
+ //
379
+ // [DESIGN DECISION] Acquired HERE, before any cycle can run, and it is what
380
+ // closes FINDING-02. F02 required TWO reconcilers to coexist on one session;
381
+ // process-local ownership cannot see another OS process, so a second process
382
+ // used to sail past it and revert the first one's live execution. This is a
383
+ // single atomic statement, so a race has exactly one winner.
384
+ //
385
+ // The token is generated per `start()` and is never a PID or an object
386
+ // identity, so a restarted process can never present its predecessor's token.
387
+ const token = this.authorityToken ?? newOwnerToken()
388
+ this.authorityToken = token
389
+ const acquired = this.store.acquireSessionAuthority(this.sessionId, token, SESSION_LEASE_MS)
390
+ if (acquired === "REFUSED_LEASE_HELD") {
391
+ // Fail CLOSED, and release the process-local token we just took so the loser
392
+ // leaves nothing half-installed.
393
+ if (this.owner !== null) {
394
+ releaseSessionOwnership(this.sessionId, this.owner, "stopped")
395
+ this.owner = null
396
+ }
397
+ this.state = "STOPPED"
398
+ throw new SchedulerError(
399
+ "ownership-unavailable",
400
+ `session ${this.sessionId} already has a valid autonomous lease held by another process`,
401
+ )
402
+ }
403
+
404
+ // [PHASE 6X] Renewal while the scheduler is live. `unref()` so it never keeps
405
+ // the process alive on its own, and cleared on every stop path.
406
+ this.renewTimer = setInterval(() => {
407
+ if (this.authorityToken === null) return
408
+ if (
409
+ this.store.renewSessionAuthority(this.sessionId, this.authorityToken, SESSION_LEASE_MS) ===
410
+ "AUTHORITY_LOST"
411
+ ) {
412
+ this.loseAuthority()
413
+ }
414
+ }, SESSION_RENEW_INTERVAL_MS)
415
+ this.renewTimer.unref?.()
416
+
417
+ this.state = "RUNNING"
418
+ }
419
+
420
+ /**
421
+ * [PHASE 6X] Authority lost: a lease expired and someone else took it, or the
422
+ * session was deleted out from under us.
423
+ *
424
+ * [DESIGN DECISION] Fail closed IMMEDIATELY and loudly. The alternative —
425
+ * carrying on and discovering the loss at the next write — would mean scheduling
426
+ * without authority in the meantime, which is exactly what F02 exploited. We
427
+ * cancel the in-flight turn because continuing to spend a provider on work we
428
+ * may no longer write is worse than stopping; 6Q's incarnation check remains the
429
+ * durable backstop if the turn completes anyway.
430
+ */
431
+ private loseAuthority(): void {
432
+ if (this.state === "STOPPED") return
433
+ this.authorityLost = true
434
+ this.emit({ kind: "cycle:stopped", reason: "authority-lost" })
435
+ this.cancelActive("emergency-stop")
436
+ this.disposeSelf()
437
+ }
438
+
439
+ /** True only while this instance still holds valid cross-process authority. */
440
+ hasAuthority(): boolean {
441
+ if (this.authorityToken === null || this.authorityLost) return false
442
+ return this.store.holdsSessionAuthority(this.sessionId, this.authorityToken)
443
+ }
444
+
445
+ /**
446
+ * Prevent future dispatch. Does NOT cancel tasks, does NOT delete, does NOT
447
+ * silently release an in-flight claim, and writes no durable state merely
448
+ * because stopping happened. Safe to call repeatedly.
449
+ *
450
+ * STOPPED is not CANCELLED. A claimed task stays IN_PROGRESS until some
451
+ * legitimate transition (a verifier, an operator, or a later reconciliation by
452
+ * an owner) moves it.
453
+ */
454
+ async stop(): Promise<void> {
455
+ if (this.state === "STOPPED" || this.state === "STOPPING") return
456
+ this.state = "STOPPING"
457
+ // [PHASE 6T] Ask the live turn to stop, THEN let the cycle finish unwinding.
458
+ //
459
+ // The await below is what makes this a graceful stop rather than a crash-like
460
+ // one: the abort gives the turn a chance to unwind and release its resources
461
+ // before we return, so the attempt can still be recorded as an attempt. The
462
+ // durable outcome does not depend on this succeeding — 6Q's reconciliation
463
+ // covers a turn that never came back.
464
+ this.cancelActive("scheduler-stopped")
465
+ // Let an in-flight cycle finish so a dispatch is never half-abandoned.
466
+ if (this.inFlight !== null) {
467
+ try {
468
+ await this.inFlight
469
+ } catch {
470
+ // An in-flight failure is already reported through the cycle result.
471
+ }
472
+ }
473
+ this.state = "STOPPED"
474
+ this.releaseAuthority()
475
+ if (this.owner !== null) {
476
+ releaseSessionOwnership(this.sessionId, this.owner, "stopped")
477
+ this.owner = null
478
+ }
479
+ }
480
+
481
+ getActiveClaim(): ActiveClaim | null {
482
+ return this.claim
483
+ }
484
+
485
+ /**
486
+ * [PHASE 6T] The handle for the turn in flight, or null when nothing is running.
487
+ *
488
+ * Exposed so a lifecycle owner can observe cancellation state without being able
489
+ * to fabricate it. Cancelling is `cancelActive`.
490
+ */
491
+ getActiveExecution(): ExecutionHandle | null {
492
+ return this.active
493
+ }
494
+
495
+ /**
496
+ * [PHASE 6T] CANCEL THE TURN IN FLIGHT.
497
+ *
498
+ * Returns true when there was something to cancel. Safe to call repeatedly and
499
+ * safe to call when nothing is running — it simply reports that there was
500
+ * nothing to do.
501
+ *
502
+ * [DESIGN DECISION] This CANCELS, it does not RELEASE. The task stays
503
+ * IN_PROGRESS and keeps its generation: cancelling the work is not the same as
504
+ * declaring the work finished, and a cancelled task is moved by a legitimate
505
+ * authority (a verifier, an operator, or a later reconciliation), never by the
506
+ * thing that stopped it. Writing a status here would be exactly the scheduler
507
+ * inventing a verdict, which 6C/6I forbade.
508
+ *
509
+ * This is the LIVE half of the cancellation story. 6Q's incarnation check remains
510
+ * the durable half and is untouched: cancelling cannot be relied on (the turn may
511
+ * be blocked in a syscall the abort cannot reach, or the process may die first),
512
+ * so the write-time protection stays.
513
+ */
514
+ cancelActive(reason: CancelReason): boolean {
515
+ const handle = this.active
516
+ if (handle === null) return false
517
+ handle.cancel(reason)
518
+ return true
519
+ }
520
+
521
+ /**
522
+ * [PHASE 6Q] Synchronously end this instance because its session is gone.
523
+ *
524
+ * Releases the process-local ownership token and moves to `STOPPED`, so a
525
+ * replacement Scheduler for a recreated session can acquire it.
526
+ *
527
+ * Deliberately NOT `stop()`: that awaits the in-flight cycle, and the only
528
+ * caller of this method is the in-flight cycle itself, so awaiting it would
529
+ * deadlock. Synchronous disposal is the only correct shape at this point.
530
+ */
531
+ /**
532
+ * [PHASE 6X] Stop renewing and give the lease back — but only if it is still
533
+ * OURS. A stale instance whose lease was taken over must not clear the
534
+ * successor's authority (6X section 8).
535
+ */
536
+ private releaseAuthority(): void {
537
+ if (this.renewTimer !== null) {
538
+ clearInterval(this.renewTimer)
539
+ this.renewTimer = null
540
+ }
541
+ if (this.authorityToken !== null) {
542
+ this.store.releaseSessionAuthority(this.sessionId, this.authorityToken)
543
+ this.authorityToken = null
544
+ }
545
+ }
546
+
547
+ private disposeSelf(): void {
548
+ // [PHASE 6X] Give the lease back here too, not just in stop(). 6Q's whole
549
+ // point is that a self-disposed instance must leave the session USABLE, and
550
+ // a retained lease would lock the replacement out for a full lease period.
551
+ // Safe on the authority-lost path as well: release is token-guarded, so a
552
+ // stale instance can only ever fail to release, never evict its successor.
553
+ this.releaseAuthority()
554
+ if (this.state === "STOPPED") return
555
+ // [PHASE 6T] Stop the WORK as well as the instance.
556
+ //
557
+ // 6Q made a late return harmless; it did not stop the turn from running. Now
558
+ // that a cancellation handle exists, session deletion asks the live execution
559
+ // to stop, which is the invariant 6T requires: deletion should end autonomous
560
+ // work as early as the runtime permits, with 6Q's incarnation check still
561
+ // there as the final boundary if the request is ignored or arrives too late.
562
+ //
563
+ // Ordering matters: cancel BEFORE releasing ownership, so nothing can start a
564
+ // replacement and race this instance's dying turn.
565
+ this.cancelActive("session-deleted")
566
+ // [PHASE 6X] ...and give the lease back, for the same reason: a superseded
567
+ // session must be immediately schedulable by its replacement. Ordering is
568
+ // unchanged - cancel first, then release.
569
+ this.releaseAuthority()
570
+ this.state = "STOPPED"
571
+ this.incarnationAtStart = null
572
+ if (this.owner !== null) {
573
+ releaseSessionOwnership(this.sessionId, this.owner, "stopped")
574
+ this.owner = null
575
+ }
576
+ }
577
+
578
+ // ── the cycle ──────────────────────────────────────────────────────────────
579
+
580
+ /**
581
+ * One cycle. Serialized: concurrent callers join the in-flight cycle rather
582
+ * than starting a second one.
583
+ */
584
+ async cycle(): Promise<CycleResult> {
585
+ if (this.inFlight !== null) {
586
+ // Join the running cycle. This is the whole of V1 concurrency control.
587
+ return this.inFlight
588
+ }
589
+ const run = this.runCycle().finally(() => {
590
+ this.inFlight = null
591
+ })
592
+ this.inFlight = run
593
+ return run
594
+ }
595
+
596
+ private async runCycle(): Promise<CycleResult> {
597
+ if (this.state !== "RUNNING" && this.state !== "IDLE") {
598
+ return { stop: "not-running", dispatched: null, recovered: [] }
599
+ }
600
+
601
+ // [PHASE 6T] IS THIS SESSION STILL THE ONE I STARTED FOR?
602
+ //
603
+ // Checked before anything else, because every later step assumes the task
604
+ // namespace still means something. A session that was deleted underneath us is
605
+ // not "an empty queue" — it is a queue that no longer exists, and treating the
606
+ // two alike is what left an idle Scheduler holding ownership forever.
607
+ //
608
+ // Uses 6Q's incarnation, so it works across processes with no registry and no
609
+ // notification from the deletion path.
610
+ if (this.incarnationAtStart !== null) {
611
+ const current = this.store.getSessionIncarnation(this.sessionId)
612
+ if (current !== this.incarnationAtStart) {
613
+ this.emit({ kind: "cycle:stopped", reason: "session-superseded" })
614
+ this.disposeSelf()
615
+ return { stop: "session-superseded", dispatched: null, recovered: [] }
616
+ }
617
+ }
618
+
619
+ // [PHASE 6X] THE RECONCILIATION BOUNDARY.
620
+ //
621
+ // [DESIGN DECISION] This is the heart of the F02 fix, so it gates every durable
622
+ // effect - before reconciliation, before readiness, before a claim. A Scheduler
623
+ // that has lost its cross-process lease must not touch durable state at all, and
624
+ // `reconcile()` is precisely the code that reverts other people's work.
625
+ //
626
+ // Deliberately AFTER the 6T incarnation check, and that ordering is the point.
627
+ // A deleted-and-recreated session also stops us holding the lease, because the
628
+ // lease is keyed by (session, incarnation) - but "the session I serve was
629
+ // deleted" is the true cause and it has its own accurate diagnosis, release
630
+ // ordering and 6Q backstop. Reporting that as `authority-lost` would be a lie
631
+ // about WHY we stopped, and it would also point at the wrong suspect.
632
+ // `authority-lost` therefore means exactly one thing: our lease is gone and the
633
+ // session is still ours, so another process is the live owner.
634
+ if (!this.hasAuthority()) {
635
+ if (!this.authorityLost) this.loseAuthority()
636
+ return { stop: "authority-lost", dispatched: null, recovered: [] }
637
+ }
638
+
639
+ // [PHASE 6T] CAPACITY, checked BEFORE anything durable happens.
640
+ //
641
+ // [DESIGN DECISION] This is the cheap half of the contention policy and it
642
+ // costs nothing: if the runtime is known to be busy, the cycle stops before it
643
+ // reads a snapshot, builds a graph, or attempts a claim. A trigger that cannot
644
+ // be serviced must not leave a mark — 6O's requirement that "contention is
645
+ // indistinguishable from a real attempt" is satisfied here by not acting at
646
+ // all.
647
+ //
648
+ // It is NOT sufficient on its own: a probe is a read, and another process (or
649
+ // another session) can take the slot between this check and the claim. The
650
+ // atomic capacity predicate inside `claimTask` is the half that actually
651
+ // holds. This one just avoids the wasted work in the overwhelmingly common
652
+ // case of a live user turn.
653
+ if (this.cancellation?.isCancelled() === true) {
654
+ this.emit({ kind: "cycle:stopped", reason: "pre-cancelled" })
655
+ return { stop: "pre-cancelled", dispatched: null, recovered: [] }
656
+ }
657
+
658
+ // 1. Reconciliation first, so a cycle never plans around stranded work.
659
+ const recovered = this.reconcile()
660
+
661
+ // [P13.3 Stage C] The guards at the top of the cycle were true when the pass
662
+ // STARTED. Reconciliation is a durable mutation, and a lease or incarnation can
663
+ // move while it runs. Re-verify before this cycle is allowed to claim or
664
+ // dispatch: a cached "authority held" is never permission to keep going.
665
+ if (
666
+ this.incarnationAtStart !== null &&
667
+ this.store.getSessionIncarnation(this.sessionId) !== this.incarnationAtStart
668
+ ) {
669
+ this.emit({ kind: "cycle:stopped", reason: "session-superseded" })
670
+ this.disposeSelf()
671
+ return { stop: "session-superseded", dispatched: null, recovered }
672
+ }
673
+ if (!this.hasAuthority()) {
674
+ if (!this.authorityLost) this.loseAuthority()
675
+ return { stop: "authority-lost", dispatched: null, recovered }
676
+ }
677
+
678
+ // An active claim means work is already associated with this Scheduler. Do
679
+ // not select anything else.
680
+ if (this.claim !== null) {
681
+ return { stop: "already-dispatched", dispatched: null, recovered }
682
+ }
683
+
684
+ // 2. Fresh snapshot. 3. Fresh graph. Never cached across cycles: a claim
685
+ // changes revision, so the graph is stale the moment it is used.
686
+ const snapshot: TaskSnapshot = this.store.getSnapshot(this.sessionId)
687
+ const graph = new TaskGraph(snapshot)
688
+
689
+ // 4. An invalid graph aborts the cycle. No dispatch, no claim.
690
+ if (!graph.validity().valid) {
691
+ this.emit({ kind: "cycle:invalid_graph" })
692
+ return { stop: "invalid-graph", dispatched: null, recovered }
693
+ }
694
+
695
+ // 5. Readiness is CONSUMED, never recomputed.
696
+ const ready = graph.readyTasks()
697
+
698
+ this.state = "IDLE"
699
+
700
+ // 6. Selection is a NAMED POLICY, not an expression.
701
+ //
702
+ // [PHASE 6T] This used to read `ready[0]` inline. That was the same
703
+ // behaviour, but nothing recorded that it WAS a policy, so there was no place
704
+ // to state what selection guarantees and no single function to point a
705
+ // property test at. Routing through `selectTask` makes ORDER ASC -> ID ASC a
706
+ // decision that can be read, argued and mutated, rather than a coincidence
707
+ // of array indexing.
708
+ //
709
+ // The policy does NOT re-derive readiness; it is handed the graph's answer and
710
+ // only chooses among it. A second readiness implementation here is the way a
711
+ // scheduler starts disagreeing with its own graph.
712
+ const selection = selectTask(ready, snapshot)
713
+ const taskId = selection.taskId
714
+ if (taskId === null) {
715
+ this.emit({
716
+ kind: "cycle:stopped",
717
+ reason: selection.reason === "no-ready-tasks" ? "no-candidates" : "no-candidates",
718
+ })
719
+ return { stop: "no-candidates", dispatched: null, recovered }
720
+ }
721
+ this.emit({ kind: "task:selected", taskId })
722
+
723
+ // 7. Re-read the authoritative row. The graph's view is NOT currency.
724
+ const current = this.store.getTask(this.sessionId, taskId)
725
+ if (current === null) {
726
+ this.emit({ kind: "task:claim_rejected", taskId, outcome: "NOT_FOUND" })
727
+ this.emit({ kind: "cycle:stopped", reason: "claim-not-found" })
728
+ return { stop: "claim-not-found", dispatched: null, recovered }
729
+ }
730
+
731
+ // 8. Atomic, revision-guarded claim. Never retried in a loop, never slept on.
732
+ //
733
+ // [PHASE 6T] `exclusive: true` adds the capacity predicate to this same
734
+ // statement, so losing the slot to another executor is reported exactly like
735
+ // losing the revision race: the row is untouched, and no generation is spent.
736
+ const claimResult = this.store.claimTask(this.sessionId, taskId, current.revision, {
737
+ exclusive: true,
738
+ })
739
+ if (claimResult.outcome !== "CLAIM_ACCEPTED") {
740
+ this.emit({ kind: "task:claim_rejected", taskId, outcome: claimResult.outcome })
741
+ const stop: CycleStop =
742
+ claimResult.outcome === "CLAIM_REJECTED_STALE"
743
+ ? "claim-rejected-stale"
744
+ : claimResult.outcome === "NOT_FOUND"
745
+ ? "claim-not-found"
746
+ : claimResult.outcome === "CLAIM_REJECTED_BUSY"
747
+ ? "contended"
748
+ : "claim-wrong-state"
749
+ this.emit({ kind: "cycle:stopped", reason: stop })
750
+ return { stop, dispatched: null, recovered }
751
+ }
752
+
753
+ // 9. Record the POST-claim revision. This is the release currency.
754
+ const accepted = claimResult.task
755
+ if (accepted === null) {
756
+ // Cannot happen: a 1-row UPDATE always leaves a readable row. Treat as a
757
+ // persistence inconsistency rather than pretending it is fine.
758
+ throw new SchedulerError("persistence", "claim accepted but task is unreadable")
759
+ }
760
+ this.claim = {
761
+ taskId,
762
+ claimRevision: accepted.revision,
763
+ execGeneration: claimResult.execGeneration,
764
+ sessionIncarnation: claimResult.sessionIncarnation,
765
+ }
766
+ this.emit({ kind: "task:claimed", taskId, revision: accepted.revision })
767
+
768
+ // 10. Dispatch through the injected bridge only.
769
+ const dispatched = await this.dispatch({
770
+ taskId,
771
+ title: accepted.title,
772
+ instruction: this.instruction,
773
+ sessionId: this.sessionId,
774
+ })
775
+ return {
776
+ stop: dispatched.ok ? "already-dispatched" : "already-dispatched",
777
+ dispatched,
778
+ recovered,
779
+ }
780
+ }
781
+
782
+ private async dispatch(work: SchedulerWorkItem): Promise<DispatchResult> {
783
+ // [PHASE 6T] One cleanup point for the per-turn handle.
784
+ //
785
+ // `dispatchTracked` has seven terminal returns and more will be added over
786
+ // time; clearing the handle in each of them is exactly the kind of thing that
787
+ // rots silently when a path is missed. A `finally` makes "the handle never
788
+ // outlives its turn" a structural property instead of a per-branch intention.
789
+ try {
790
+ return await this.dispatchTracked(work)
791
+ } finally {
792
+ this.active?.dispose()
793
+ this.active = null
794
+ }
795
+ }
796
+
797
+ private async dispatchTracked(work: SchedulerWorkItem): Promise<DispatchResult> {
798
+ // An injected cancellation contract may refuse NEW work. It cannot abort an
799
+ // in-flight agent loop — that ability is the composition root's, not ours.
800
+ if (
801
+ this.state === "STOPPING" ||
802
+ this.state === "STOPPED" ||
803
+ this.cancellation?.isCancelled() === true
804
+ ) {
805
+ // Stop (or cancellation) happened after the claim. The claim is NOT
806
+ // silently released; the task stays IN_PROGRESS for a legitimate authority
807
+ // to move. Cancelling is not releasing.
808
+ return {
809
+ ok: false,
810
+ failure: "scheduler-not-running",
811
+ observation: null,
812
+ released: false,
813
+ lineage: "NOT_ATTEMPTED",
814
+ }
815
+ }
816
+ this.emit({ kind: "task:dispatch_started", taskId: work.taskId })
817
+
818
+ // [PHASE 6T] Create the per-execution cancellation handle and publish it
819
+ // BEFORE the bridge is called, so a cancel racing dispatch is recorded rather
820
+ // than lost. The bridge attaches its abort function; if cancellation already
821
+ // happened, `attach` fires immediately.
822
+ //
823
+ // Held on the instance, not in a closure, so `cancelActive()` can reach it.
824
+ // Cleared on every terminal path below, so a dead turn is never retained.
825
+ const handle = newExecutionHandle()
826
+ this.active = handle
827
+
828
+ let produced: Promise<ExecutionObservation> | ExecutionObservation
829
+ try {
830
+ produced = this.runTurn(work, handle)
831
+ } catch (e) {
832
+ // A. Dispatch/setup failure: the attempt was NEVER established. The claim
833
+ // is released back to PENDING so the task is not stranded by our own
834
+ // inability to start it.
835
+ const detail = e instanceof Error ? e.message : String(e)
836
+ this.emit({ kind: "task:execution_completed", taskId: work.taskId, ok: false })
837
+ const released = this.releaseClaim("dispatch-failed")
838
+ return {
839
+ ok: false,
840
+ failure: "bridge-threw",
841
+ observation: { kind: "rejected", detail },
842
+ released,
843
+ lineage: "NOT_ATTEMPTED",
844
+ }
845
+ }
846
+
847
+ if (
848
+ !(produced instanceof Promise) &&
849
+ typeof (produced as ExecutionObservation)?.kind !== "string"
850
+ ) {
851
+ const released = this.releaseClaim("dispatch-failed")
852
+ return {
853
+ ok: false,
854
+ failure: "bridge-not-callable",
855
+ observation: null,
856
+ released,
857
+ lineage: "NOT_ATTEMPTED",
858
+ }
859
+ }
860
+
861
+ this.emit({ kind: "task:execution_started", taskId: work.taskId })
862
+
863
+ // B. Execution began. Its outcome is an OBSERVATION. Scheduler does not
864
+ // decide whether the work succeeded and never writes COMPLETED.
865
+ let observation: ExecutionObservation
866
+ try {
867
+ observation = await produced
868
+ } catch (e) {
869
+ observation = { kind: "rejected", detail: e instanceof Error ? e.message : String(e) }
870
+ }
871
+ this.emit({
872
+ kind: "task:execution_completed",
873
+ taskId: work.taskId,
874
+ ok: observation.kind === "returned" && observation.ok,
875
+ })
876
+
877
+ // [PHASE 6I] Record that this EXECUTION GENERATION's attempt ended, before
878
+ // dropping the in-memory claim.
879
+ //
880
+ // The generation is the one the accepted claim created. It is NOT the
881
+ // revision, and it is NOT re-read from the task: inferring lineage from
882
+ // mutable task state is precisely the confusion 6G D1 exposed. An
883
+ // unrelated write that bumped `revision` after the claim cannot change
884
+ // what is recorded here.
885
+ //
886
+ // `observation.ok` is deliberately NOT consulted. A rejected turn and a
887
+ // successful turn are both "an attempt ended"; conflating them with
888
+ // success is the bug this replaces. EXECUTION != VERIFICATION !=
889
+ // COMPLETION.
890
+ //
891
+ // [PHASE 6Q] THE CLAIM IS RELEASED ON EVERY TERMINAL PATH.
892
+ //
893
+ // This is the fix for 6N F2, and the reason it is a restructure rather than
894
+ // a try/catch. Previously the claim was cleared on ONE line AFTER the
895
+ // lineage write, so any failure in between - above all the "session was
896
+ // deleted under this execution" case - escaped `cycle()` with the claim
897
+ // still set. `runCycle` returns `already-dispatched` whenever a claim
898
+ // exists, and `stop()` had already been passed, so the instance was
899
+ // permanently wedged AND still held session ownership, which prevented any
900
+ // replacement from starting.
901
+ //
902
+ // The attempt HAS ended at this point, whatever the store says about
903
+ // recording it. So the bookkeeping is settled first, unconditionally, and
904
+ // the lineage write is a pure side effect whose result is reported rather
905
+ // than allowed to strand the instance.
906
+ const generation = this.claim
907
+ this.claim = null
908
+ if (generation === null) {
909
+ // The claim was cleared while the turn was in flight. We no longer know
910
+ // which generation this was, so recording one would be a guess. Refuse to
911
+ // fabricate evidence - and return rather than throw, so an unidentified
912
+ // attempt can never become a lifecycle wedge either.
913
+ this.emit({ kind: "task:execution_completed", taskId: work.taskId, ok: false })
914
+ return {
915
+ ok: observation.kind === "returned" && observation.ok,
916
+ failure: "attempt-unidentified",
917
+ observation,
918
+ released: true,
919
+ lineage: "TASK_GONE",
920
+ }
921
+ }
922
+ const lineage = this.store.recordAttemptReturned(
923
+ this.sessionId,
924
+ generation.taskId,
925
+ generation.execGeneration,
926
+ generation.sessionIncarnation,
927
+ )
928
+ if (lineage !== "RECORDED") {
929
+ // The attempt ended but its completion was NOT recorded. This is now an
930
+ // ordinary, classified outcome - the session was deleted under this
931
+ // execution, or a later generation superseded it. Nothing was written, so
932
+ // the task is left exactly as it was and the next owner decides its fate.
933
+ this.emit({ kind: "task:execution_abandoned", taskId: generation.taskId, outcome: lineage })
934
+ }
935
+ if (lineage === "TASK_GONE" || lineage === "SESSION_SUPERSEDED") {
936
+ // [PHASE 6Q] The session this Scheduler was executing FOR no longer exists
937
+ // (or exists as a different lifetime). That is durable evidence, learned
938
+ // from the store rather than announced by anyone, so it works across
939
+ // processes without a registry and without the deletion path having to know
940
+ // that any Scheduler exists.
941
+ //
942
+ // Self-dispose: release the session ownership token and become STOPPED, so
943
+ // a REPLACEMENT Scheduler can start. Without this the instance stayed IDLE
944
+ // but kept the ownership, which is precisely the second half of 6N F2.
945
+ //
946
+ // `stop()` cannot be used here: it awaits the in-flight cycle, and this IS
947
+ // the in-flight cycle, so awaiting it would deadlock.
948
+ this.disposeSelf()
949
+ }
950
+ return {
951
+ ok: observation.kind === "returned" && observation.ok,
952
+ failure: null,
953
+ observation,
954
+ released: true,
955
+ lineage,
956
+ }
957
+ }
958
+
959
+ /**
960
+ * Revert THIS Scheduler's own claim from IN_PROGRESS back to PENDING using the
961
+ * POST-claim revision. Only justified for the case the design locked: the
962
+ * claim succeeded but dispatch could not be established, so the task is
963
+ * stranded by our own failure to start it.
964
+ *
965
+ * Never used because execution returned an error, because stop() was called,
966
+ * or because verification is pending — those belong to other authorities.
967
+ */
968
+ private releaseClaim(why: "dispatch-failed"): boolean {
969
+ const active = this.claim
970
+ if (active === null) return false
971
+ // The reason is an observation, not a durable fact: it tells an operator why
972
+ // the task went back to PENDING without inventing a status for it.
973
+ this.emit({ kind: "cycle:stopped", reason: "claim-wrong-state" })
974
+ void why
975
+ const result = this.store.reconcileStranded(
976
+ this.sessionId,
977
+ active.taskId,
978
+ active.claimRevision,
979
+ {
980
+ ownsSession: ownsSession(this.sessionId, this.owner),
981
+ },
982
+ )
983
+ this.claim = null
984
+ return result.outcome === "RECONCILED"
985
+ }
986
+
987
+ // ── reconciliation ──────────────────────────────────────────────────────────
988
+
989
+ /**
990
+ * Revert stranded in-flight tasks. Runs at the START of every cycle — the P77
991
+ * lesson, where a scheduler went IDLE with no in-process path back.
992
+ *
993
+ * Ownership-aware and fail-closed: without positively-held ownership this
994
+ * refuses rather than guessing, because reverting live work is worse than
995
+ * leaving it stranded.
996
+ *
997
+ * [PHASE 6F] The decision is made on EVIDENCE, not on status. The old rule
998
+ * reverted every `IN_PROGRESS` row that was not this Scheduler's current
999
+ * in-memory claim — which, because the claim is cleared after every dispatch,
1000
+ * reverted the Scheduler's own freshly completed work and re-executed it
1001
+ * forever. A generation may be reverted only when it has no completion
1002
+ * marker.
1003
+ *
1004
+ * [P13.3 Stage C] NO MARKER IS NOT PROOF OF NO SIDE EFFECT. A crashed attempt
1005
+ * may already have written files or run commands; a new attempt would repeat
1006
+ * them. Every candidate is therefore classified before the store is asked to
1007
+ * revert it, and only SAFE_TO_RETRY (evidence-backed retry safety, e.g. a
1008
+ * bridge whose entire tool scope is read-only) proceeds. Without a continuity
1009
+ * gate the result is HOLD: the record is preserved and the next cycle
1010
+ * re-evaluates. Reconcile still never writes COMPLETED and never dispatches.
1011
+ */
1012
+ reconcile(): readonly string[] {
1013
+ // [PHASE 6X] No authority, no reconciliation. Unconditionally: this is the single
1014
+ // function that reverts another party's in-flight work, and it is exactly what
1015
+ // FINDING-02 used.
1016
+ if (!this.hasAuthority()) {
1017
+ if (!this.authorityLost) this.loseAuthority()
1018
+ return []
1019
+ }
1020
+ const owned = ownsSession(this.sessionId, this.owner)
1021
+ if (!owned) {
1022
+ this.emit({ kind: "cycle:stopped", reason: "ownership-unavailable" })
1023
+ return []
1024
+ }
1025
+ const snapshot = this.store.getSnapshot(this.sessionId)
1026
+ const stranded: string[] = []
1027
+ const incarnationMatches =
1028
+ this.incarnationAtStart === null ||
1029
+ this.store.getSessionIncarnation(this.sessionId) === this.incarnationAtStart
1030
+
1031
+ // [P13.3 Stage C] ONE evidence read per reconcile pass, and only when there
1032
+ // is at least one in-flight candidate. The provider may probe the runtime,
1033
+ // storage and journal; doing that for an empty queue would be pure cost.
1034
+ let evidence: ContinuityEvidence | null = null
1035
+ const evidenceForPass = (): ContinuityEvidence => {
1036
+ if (evidence !== null) return evidence
1037
+ evidence = this.continuityEvidence({
1038
+ ownsSession: owned,
1039
+ authorityHeld: true,
1040
+ incarnationMatches,
1041
+ })
1042
+ return evidence
1043
+ }
1044
+
1045
+ for (const task of snapshot.tasks) {
1046
+ // Only the two in-flight states are ever targets. Terminal and operator
1047
+ // states are untouched by construction, not by a later check.
1048
+ if (task.status !== "IN_PROGRESS" && task.status !== "VERIFYING") continue
1049
+ // Never revert the task this Scheduler is actively executing.
1050
+ if (this.claim?.taskId === task.id) continue
1051
+
1052
+ // [PHASE 6I] Read the two durable facts separately. TaskStore remains the
1053
+ // owner of the atomic lineage predicate below; these reads are only the
1054
+ // INPUT to the retry-safety classification, never a replacement for it.
1055
+ const lineage = this.store.getExecutionLineage(this.sessionId, task.id)
1056
+ if (lineage === null) continue
1057
+
1058
+ // [PHASE 6I] An attempt newer than its execution is impossible. Preserve
1059
+ // the store's loud invariant instead of silently classifying it: guessing
1060
+ // which side is wrong either strands live work or re-runs finished work.
1061
+ if (
1062
+ lineage.attemptGeneration !== null &&
1063
+ lineage.attemptGeneration > lineage.execGeneration
1064
+ ) {
1065
+ throw new TaskError(
1066
+ "TASK_PERSISTENCE_FAILURE",
1067
+ `attempt generation ${lineage.attemptGeneration} exceeds execution generation ${lineage.execGeneration} for ${this.sessionId}/${task.id}`,
1068
+ )
1069
+ }
1070
+
1071
+ const ownership = this.store.getExecutionOwnership(this.sessionId, task.id)
1072
+ if (ownership === null) continue
1073
+
1074
+ const verdict = classifyContinuity(
1075
+ {
1076
+ status: task.status,
1077
+ executionOwner: ownership.executionOwner,
1078
+ execGeneration: lineage.execGeneration,
1079
+ attemptGeneration: lineage.attemptGeneration,
1080
+ ownsSession: owned,
1081
+ authorityHeld: true,
1082
+ incarnationMatches,
1083
+ },
1084
+ evidenceForPass(),
1085
+ )
1086
+
1087
+ // [P13.3 Stage C] Only SAFE_TO_RETRY returns to the claim/dispatch cycle.
1088
+ // HOLD and REQUIRES_VERIFIER both leave the durable record untouched; the
1089
+ // next cycle re-evaluates, so recovery is never "dropped".
1090
+ if (!verdict.mayReconcile) {
1091
+ this.emit({
1092
+ kind: "task:continuity_held",
1093
+ taskId: task.id,
1094
+ class: verdict.class,
1095
+ reason: verdict.reason,
1096
+ })
1097
+ continue
1098
+ }
1099
+
1100
+ // [P13.3 Stage C] Re-verify IMMEDIATELY before the durable mutation. The
1101
+ // evidence was read earlier in this pass; a lease/incarnation that moved in
1102
+ // between must not authorise a revert with the old token. Stop the pass and
1103
+ // let TaskStore keep its record untouched.
1104
+ if (!this.hasAuthority()) {
1105
+ this.loseAuthority()
1106
+ break
1107
+ }
1108
+ if (
1109
+ this.incarnationAtStart !== null &&
1110
+ this.store.getSessionIncarnation(this.sessionId) !== this.incarnationAtStart
1111
+ ) {
1112
+ this.disposeSelf()
1113
+ break
1114
+ }
1115
+
1116
+ // [PHASE 6I] The lineage decision belongs to TaskStore, which owns both
1117
+ // generation columns and can make it in ONE atomic guarded statement. The
1118
+ // Scheduler contributes ownership and nothing else: it does not compare
1119
+ // generations here, and has no rule of its own.
1120
+ //
1121
+ // This is what closes 6G D1. The decision cannot be influenced by an
1122
+ // unrelated task write, because `exec_generation` advances only on an
1123
+ // accepted claim - not by the title, order, dependency, evidence or status
1124
+ // writes that also advance `revision`. A stale snapshot still loses here.
1125
+ const result = this.store.reconcileIfNoCompletedAttempt(
1126
+ this.sessionId,
1127
+ task.id,
1128
+ task.revision,
1129
+ {
1130
+ ownsSession: owned,
1131
+ },
1132
+ )
1133
+ if (result.outcome === "RECONCILED") stranded.push(task.id)
1134
+ }
1135
+ if (stranded.length > 0) this.emit({ kind: "task:recovered", taskIds: stranded })
1136
+ return stranded
1137
+ }
1138
+
1139
+ /**
1140
+ * [P13.3 Stage C] Evidence for one reconcile pass, fail-closed.
1141
+ *
1142
+ * No gate and a throwing gate are the same verdict: evidence is MISSING.
1143
+ * Treating an unavailable provider as permission would turn a monitoring
1144
+ * failure into duplicate execution.
1145
+ */
1146
+ private continuityEvidence(ctx: ContinuityContext): ContinuityEvidence {
1147
+ if (this.continuity === null) {
1148
+ return {
1149
+ resume: false,
1150
+ missing: ["continuity-gate-missing"],
1151
+ admission: "REFUSE",
1152
+ retrySafety: "UNPROVEN",
1153
+ }
1154
+ }
1155
+ try {
1156
+ return this.continuity.evidence(ctx)
1157
+ } catch {
1158
+ return {
1159
+ resume: false,
1160
+ missing: ["continuity-gate-error"],
1161
+ admission: "REFUSE",
1162
+ retrySafety: "UNPROVEN",
1163
+ }
1164
+ }
1165
+ }
1166
+
1167
+ private emit(event: SchedulerEvent): void {
1168
+ // A throwing sink must never take the Scheduler down; observations are not
1169
+ // authority and cannot be load-bearing.
1170
+ try {
1171
+ this.onEvent?.(event)
1172
+ } catch {
1173
+ /* deliberately swallowed: an observer cannot be allowed to fail a cycle */
1174
+ }
1175
+ }
1176
+ }
1177
+
1178
+ export interface DispatchResult {
1179
+ readonly ok: boolean
1180
+ readonly failure: DispatchFailure | null
1181
+ readonly observation: ExecutionObservation | null
1182
+ readonly released: boolean
1183
+ /**
1184
+ * [PHASE 6Q] What became of the completion marker. `RECORDED` in the normal
1185
+ * case; anything else means the session was deleted or superseded underneath
1186
+ * this execution and NOTHING was written. `NOT_ATTEMPTED` is the pre-attempt
1187
+ * shape: the bridge was never successfully entered, so there was never an
1188
+ * attempt whose completion could be recorded.
1189
+ */
1190
+ readonly lineage: AttemptRecordOutcome | "NOT_ATTEMPTED"
1191
+ }
1192
+
1193
+ export interface CycleResult {
1194
+ readonly stop: CycleStop
1195
+ readonly dispatched: DispatchResult | null
1196
+ readonly recovered: readonly string[]
1197
+ }