@bitkyc08/opencodex 2.100.2 → 2.100.3

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 (561) hide show
  1. package/README.md +1 -1
  2. package/bin/ocx.mjs +32 -18
  3. package/gui/dist/assets/{App-COo8Yopd.css → App-BGP8I0V4.css} +1 -1
  4. package/gui/dist/assets/App-Dnb6VMsP.js +59 -0
  5. package/gui/dist/assets/{Tray-BcaI-VCr.js → Tray-BV4ms9U9.js} +1 -1
  6. package/gui/dist/assets/{brand-mark-DU-0Vdkr.js → brand-mark-XOLJbomA.js} +1 -1
  7. package/gui/dist/assets/index-DCdXsMyZ.js +105 -0
  8. package/gui/dist/assets/{index-DJEkIDAi.css → index-DQtCRNAw.css} +1 -1
  9. package/gui/dist/assets/{segment-thumb-features-e9A_FogJ.js → segment-thumb-features-DXSidY6D.js} +1 -1
  10. package/gui/dist/classic/assets/App-DA-scMPq.js +58 -0
  11. package/gui/dist/classic/assets/{Tray-DT146AhS.js → Tray-BrHaVRAq.js} +1 -1
  12. package/gui/dist/classic/assets/index-BqOaGLf5.js +105 -0
  13. package/gui/dist/classic/assets/{quota-summary-CakPe9Ni.js → quota-summary-Dy5_wfTT.js} +1 -1
  14. package/gui/dist/classic/index.html +1 -1
  15. package/gui/dist/index.html +2 -2
  16. package/native/ocx-child/Cargo.toml +9 -0
  17. package/native/ocx-child/src/cli.rs +402 -20
  18. package/native/ocx-child/src/codex_home.rs +98 -14
  19. package/native/ocx-child/src/daemon.rs +2 -1
  20. package/native/ocx-child/src/lib.rs +3 -0
  21. package/native/ocx-child/src/link_ws.rs +2598 -0
  22. package/native/ocx-child/src/link_ws_advert.rs +346 -0
  23. package/native/ocx-child/src/link_ws_frame.rs +749 -0
  24. package/native/ocx-child/src/parity.rs +5 -1
  25. package/native/ocx-child/src/platform.rs +152 -6
  26. package/native/ocx-child/src/relay.rs +150 -19
  27. package/package.json +3 -3
  28. package/src/adapters/anthropic/advisor-tool.ts +176 -0
  29. package/src/adapters/anthropic/beta-body-pairs.ts +6 -0
  30. package/src/adapters/anthropic/client-identity.ts +3 -1
  31. package/src/adapters/anthropic/passthrough.ts +9 -3
  32. package/src/adapters/anthropic.ts +31 -14
  33. package/src/adapters/client-fingerprint.ts +3 -3
  34. package/src/adapters/cursor/discovery.ts +17 -0
  35. package/src/adapters/cursor/native-exec-desktop.ts +2 -1
  36. package/src/adapters/cursor/native-exec-shell.ts +2 -1
  37. package/src/adapters/cursor/protobuf-request.ts +8 -8
  38. package/src/adapters/cursor.ts +7 -6
  39. package/src/adapters/google-antigravity-wire.ts +7 -5
  40. package/src/adapters/google-wire-compiler.ts +2 -2
  41. package/src/adapters/google.ts +9 -2
  42. package/src/adapters/kiro/payload.ts +7 -4
  43. package/src/adapters/kiro/reasoning.ts +44 -1
  44. package/src/adapters/kiro/structured-output.ts +10 -8
  45. package/src/adapters/kiro-tools.ts +61 -15
  46. package/src/adapters/openai-chat/destination-policy.ts +16 -0
  47. package/src/adapters/openai-chat/reasoning-replay.ts +4 -1
  48. package/src/adapters/zed.ts +3 -0
  49. package/src/advisor/consult.ts +15 -4
  50. package/src/advisor/context.ts +12 -3
  51. package/src/advisor/runtime.ts +35 -5
  52. package/src/advisor/settings.ts +8 -0
  53. package/src/advisor/synthetic-tool.ts +21 -8
  54. package/src/bridge/response-json.ts +11 -2
  55. package/src/bridge/sse.ts +43 -8
  56. package/src/claude/auth-detect.ts +21 -33
  57. package/src/claude/desktop-3p.ts +11 -5
  58. package/src/claude/desktop-gateway-state.ts +2 -0
  59. package/src/claude/desktop-remote-store-artifact.ts +14 -3
  60. package/src/claude/desktop-remote-store.ts +24 -4
  61. package/src/claude/inbound-content-options.ts +31 -16
  62. package/src/claude/outbound.ts +13 -3
  63. package/src/cli/account-api.ts +17 -1
  64. package/src/cli/account-auth.ts +54 -21
  65. package/src/cli/account-key-quota.ts +34 -5
  66. package/src/cli/account.ts +4 -2
  67. package/src/cli/advisor.ts +7 -4
  68. package/src/cli/alias.ts +38 -1
  69. package/src/cli/capabilities-access-remote.ts +128 -3
  70. package/src/cli/capabilities-accounts.ts +3 -3
  71. package/src/cli/capabilities-agents-routing.ts +17 -10
  72. package/src/cli/capabilities-base.ts +41 -16
  73. package/src/cli/capabilities-integrations.ts +2 -2
  74. package/src/cli/capabilities-provider-models.ts +18 -2
  75. package/src/cli/capabilities-route-to.ts +43 -0
  76. package/src/cli/capabilities.ts +2 -0
  77. package/src/cli/capability-contracts.ts +1 -1
  78. package/src/cli/claude-desktop.ts +30 -11
  79. package/src/cli/claude.ts +17 -3
  80. package/src/cli/codex-launcher.ts +3 -1
  81. package/src/cli/codex-shim-autorestore.ts +5 -42
  82. package/src/cli/config-command.ts +14 -1
  83. package/src/cli/config-root-startup.ts +34 -0
  84. package/src/cli/connect.ts +88 -16
  85. package/src/cli/desktop-runtime-guidance.ts +1 -1
  86. package/src/cli/disconnect-runtime.ts +168 -0
  87. package/src/cli/dispatch.ts +54 -12
  88. package/src/cli/export-command.ts +1 -1
  89. package/src/cli/gui-pair-client.ts +6 -3
  90. package/src/cli/gui.ts +10 -5
  91. package/src/cli/help-catalog.ts +11 -0
  92. package/src/cli/help.ts +4 -3
  93. package/src/cli/index.ts +83 -92
  94. package/src/cli/inspect.ts +11 -2
  95. package/src/cli/integrations.ts +26 -1
  96. package/src/cli/link-capture.ts +64 -0
  97. package/src/cli/link-child-ops.ts +218 -40
  98. package/src/cli/link-cleanup.ts +8 -5
  99. package/src/cli/link-diagnostics.ts +67 -0
  100. package/src/cli/link-enrollment.ts +158 -12
  101. package/src/cli/link-operations.ts +52 -0
  102. package/src/cli/link-recover.ts +152 -0
  103. package/src/cli/link-routes.ts +87 -0
  104. package/src/cli/link-status-child.ts +44 -1
  105. package/src/cli/link-status-traffic.ts +34 -0
  106. package/src/cli/link.ts +314 -37
  107. package/src/cli/message-command.ts +1 -1
  108. package/src/cli/message-mcp-command.ts +23 -10
  109. package/src/cli/models-runtime.ts +3 -3
  110. package/src/cli/opencode.ts +3 -1
  111. package/src/cli/pi-sync.ts +35 -0
  112. package/src/cli/preflight-exemptions.ts +46 -0
  113. package/src/cli/registry.ts +28 -12
  114. package/src/cli/restart-failure.ts +5 -2
  115. package/src/cli/root.ts +5 -1
  116. package/src/cli/route-to.ts +172 -0
  117. package/src/cli/runtime-api.ts +5 -8
  118. package/src/cli/status.ts +3 -1
  119. package/src/cli/stop-approval.ts +66 -19
  120. package/src/cli/stop-report.ts +23 -0
  121. package/src/cli/stop-windows-checked.ts +304 -0
  122. package/src/cli/sync-command.ts +70 -15
  123. package/src/cli/sync-fanout.ts +74 -19
  124. package/src/cli/sync-flags.ts +40 -3
  125. package/src/cli/sync-link-status.ts +18 -2
  126. package/src/cli/sync-update-guard.ts +7 -2
  127. package/src/cli/system-restart-client.ts +3 -2
  128. package/src/cli/uninstall-plan.ts +77 -5
  129. package/src/cli/uninstall-stop.ts +152 -0
  130. package/src/cli/v2-input.ts +10 -6
  131. package/src/cli/v2-local-output.ts +3 -2
  132. package/src/cli/v2-runtime.ts +10 -3
  133. package/src/cli/v2.ts +22 -7
  134. package/src/client/connect.ts +321 -34
  135. package/src/client/link-home-features.ts +27 -0
  136. package/src/client/link-home.ts +92 -4
  137. package/src/client/link-ingress.ts +21 -3
  138. package/src/client/link-join.ts +12 -2
  139. package/src/client/link-parity-reporter.ts +60 -6
  140. package/src/client/link-relay-transport.ts +161 -36
  141. package/src/client/link-relay.ts +150 -6
  142. package/src/client/link-request-compression.ts +84 -0
  143. package/src/client/link-state.ts +11 -5
  144. package/src/client/link-status.ts +39 -1
  145. package/src/client/link-teardown.ts +1 -0
  146. package/src/client/link-tunnel.ts +56 -5
  147. package/src/client/link-websocket-limits.ts +89 -0
  148. package/src/client/link-websocket.ts +586 -0
  149. package/src/client/link-ws-advertisement.ts +100 -0
  150. package/src/client/link-ws-framer.ts +241 -0
  151. package/src/client/link-ws-transport.ts +177 -0
  152. package/src/client/machine-api.ts +13 -2
  153. package/src/client/machine-listener.ts +48 -7
  154. package/src/client/route-intent-apply.ts +293 -0
  155. package/src/client/route-intent-file-originals.ts +97 -0
  156. package/src/client/route-intent-native-originals.ts +201 -0
  157. package/src/client/route-intent-watch.ts +141 -0
  158. package/src/client/runtime-restart.ts +127 -5
  159. package/src/client/runtime.ts +61 -15
  160. package/src/client/state.ts +30 -0
  161. package/src/client/sync-expectation.ts +36 -2
  162. package/src/client/sync-runtime.ts +7 -0
  163. package/src/clients/config-export/alias-selectors.ts +63 -40
  164. package/src/clients/config-export/contracts.ts +2 -0
  165. package/src/clients/config-export/nested-selectors.ts +42 -0
  166. package/src/clients/config-export.ts +22 -3
  167. package/src/codex/account-store.ts +12 -3
  168. package/src/codex/account-usability.ts +13 -0
  169. package/src/codex/auth-api/account-list.ts +29 -3
  170. package/src/codex/auth-collision.ts +23 -22
  171. package/src/codex/auth-context.ts +21 -6
  172. package/src/codex/catalog/gather-capture.ts +8 -2
  173. package/src/codex/catalog/parsing.ts +7 -3
  174. package/src/codex/catalog/provider-models.ts +54 -15
  175. package/src/codex/catalog/retained-sync.ts +2 -1
  176. package/src/codex/catalog/routed-gather.ts +1 -1
  177. package/src/codex/catalog-auto-refresh.ts +11 -0
  178. package/src/codex/cli-update-job.ts +35 -13
  179. package/src/codex/convergence.ts +2 -2
  180. package/src/codex/desktop-compatibility/native-identity.ts +4 -8
  181. package/src/codex/features.ts +2 -2
  182. package/src/codex/history-provider.ts +31 -0
  183. package/src/codex/inject/multi-agent-v2.ts +9 -3
  184. package/src/codex/inject/paginated-openai-compat.ts +54 -1
  185. package/src/codex/inject/plan.ts +20 -2
  186. package/src/codex/inject.ts +2 -0
  187. package/src/codex/journal-config-restore.ts +217 -0
  188. package/src/codex/journal.ts +75 -6
  189. package/src/codex/main-account.ts +23 -30
  190. package/src/codex/native-main-auth-file.ts +104 -0
  191. package/src/codex/native-profile-manager.ts +4 -3
  192. package/src/codex/native-profile-store.ts +3 -61
  193. package/src/codex/orca-import.ts +10 -1
  194. package/src/codex/quota-history.ts +13 -0
  195. package/src/codex/quota-window-conflict.ts +103 -0
  196. package/src/codex/quota.ts +23 -1
  197. package/src/codex/subagent-model-fallback.ts +3 -1
  198. package/src/codex/websocket-activity.ts +171 -16
  199. package/src/codex/websocket-registry.ts +11 -4
  200. package/src/combos/cooldown-store.ts +25 -5
  201. package/src/combos/failover.ts +330 -2
  202. package/src/config/dashboard-trusted-proxy.ts +83 -0
  203. package/src/config/diagnostics.ts +28 -0
  204. package/src/config/feature-flags.ts +9 -0
  205. package/src/config/live-reconcile.ts +10 -1
  206. package/src/config/load-degrade.ts +12 -1
  207. package/src/config/multi-agent-surface.ts +28 -5
  208. package/src/config/pending-teardown.ts +60 -3
  209. package/src/config/process-state.ts +175 -4
  210. package/src/config/provider-validation.ts +4 -4
  211. package/src/config/schema/config-schema.ts +6 -0
  212. package/src/config/schema/leaf-validators.ts +9 -2
  213. package/src/config/windows-process-command-line.ts +107 -0
  214. package/src/generated/compatibility-version.json +948 -392
  215. package/src/generated/model-metadata.ts +1 -1
  216. package/src/images/loop.ts +3 -0
  217. package/src/integrations/model-name-guard.ts +25 -0
  218. package/src/integrations/route-intent-catalog.ts +26 -0
  219. package/src/integrations/route-intent-connected.ts +262 -0
  220. package/src/integrations/route-intent-contract.ts +55 -0
  221. package/src/integrations/route-intent-disconnect.ts +109 -0
  222. package/src/integrations/route-intent-initial.ts +64 -0
  223. package/src/integrations/route-intent-state.ts +117 -0
  224. package/src/integrations/route-intent-tick.ts +65 -0
  225. package/src/integrations/route-intent.ts +212 -0
  226. package/src/integrations/writer.ts +44 -11
  227. package/src/lib/client-retry-after.ts +29 -0
  228. package/src/lib/config-ownership.ts +13 -0
  229. package/src/lib/desktop-gui-origin.ts +28 -0
  230. package/src/lib/errors.ts +1 -1
  231. package/src/lib/gui-pair-capability.ts +2 -1
  232. package/src/lib/messages-error-body.ts +4 -1
  233. package/src/lib/outbound-credential-registry.ts +362 -4
  234. package/src/lib/paced-stream.ts +34 -0
  235. package/src/lib/passive-key-fetch-proof.ts +30 -0
  236. package/src/lib/passive-read.ts +5 -0
  237. package/src/lib/process-control.ts +76 -12
  238. package/src/lib/redact.ts +84 -8
  239. package/src/lib/state-store-registrations.ts +11 -0
  240. package/src/lib/state-store-sweeper.ts +4 -0
  241. package/src/lib/supervisor-markers.ts +18 -0
  242. package/src/lib/terminal-safe-text.ts +58 -0
  243. package/src/lib/translator-budget.ts +3 -2
  244. package/src/lib/upstream-retry.ts +14 -4
  245. package/src/link/alias-lock.ts +119 -0
  246. package/src/link/child-activity.ts +28 -2
  247. package/src/link/child-binary-cache-fill.d.mts +50 -0
  248. package/src/link/child-binary-cache-fill.mjs +494 -0
  249. package/src/link/child-binary-cache-start.ts +73 -0
  250. package/src/link/child-binary-source.ts +12 -5
  251. package/src/link/child-gated-ocx.ts +29 -11
  252. package/src/link/child-observations.ts +2 -1
  253. package/src/link/child-observe.ts +2 -2
  254. package/src/link/child-ops-engine.ts +159 -91
  255. package/src/link/child-ops-host.ts +138 -0
  256. package/src/link/child-ops-runners.ts +319 -0
  257. package/src/link/child-ops-scheduler.ts +207 -0
  258. package/src/link/child-ops-types.ts +89 -0
  259. package/src/link/child-parity.ts +23 -4
  260. package/src/link/child-policy.ts +93 -0
  261. package/src/link/child-update-contract.ts +12 -3
  262. package/src/link/codex-settings.ts +1 -1
  263. package/src/link/compatibility.ts +18 -1
  264. package/src/link/diagnostics-read.ts +163 -0
  265. package/src/link/diagnostics.ts +20 -7
  266. package/src/link/explicit-route.ts +209 -0
  267. package/src/link/link-recover.ts +113 -0
  268. package/src/link/management-routes.ts +3 -1
  269. package/src/link/operation-recovery-slot.ts +44 -0
  270. package/src/link/operations-journal.ts +408 -0
  271. package/src/link/peer-report.ts +1 -1
  272. package/src/link/relay-auth.ts +14 -0
  273. package/src/link/remote-plant.ts +152 -14
  274. package/src/link/remote-platform.ts +21 -10
  275. package/src/link/remote-probe.ts +11 -3
  276. package/src/link/remote-windows.ts +50 -10
  277. package/src/link/request-compression.ts +30 -0
  278. package/src/link/residual-recovery.ts +54 -0
  279. package/src/link/retirement.ts +128 -0
  280. package/src/link/route-intent-watch.ts +41 -0
  281. package/src/link/route-intent.ts +209 -0
  282. package/src/link/route-proof.ts +82 -0
  283. package/src/link/route-rounds.ts +579 -0
  284. package/src/link/route-select.ts +95 -0
  285. package/src/link/route-trust.ts +96 -0
  286. package/src/link/ssh-argv.ts +172 -24
  287. package/src/link/ssh-capture-redact.ts +253 -0
  288. package/src/link/ssh-capture.ts +497 -0
  289. package/src/link/ssh-runner.ts +141 -14
  290. package/src/link/status-projection.ts +87 -0
  291. package/src/link/store.ts +54 -1
  292. package/src/link/supervisor.ts +543 -55
  293. package/src/link/sync-fanout-classify.ts +16 -0
  294. package/src/link/sync-then-restart.ts +65 -0
  295. package/src/link/tombstones.ts +209 -0
  296. package/src/link/traffic.ts +178 -0
  297. package/src/link/ws-activity-holds.ts +474 -0
  298. package/src/local-credentials/publication-fence.ts +20 -1
  299. package/src/messaging/mcp-queue-rpc.ts +1 -1
  300. package/src/messaging/mcp-queue-server.ts +16 -1
  301. package/src/messaging/mcp-resume-tools.ts +25 -0
  302. package/src/messaging/remote-enrollment.ts +3 -3
  303. package/src/messaging/remote-tunnels.ts +2 -2
  304. package/src/messaging/resume-permissions.ts +27 -0
  305. package/src/messaging/rpc.ts +46 -2
  306. package/src/oauth/anthropic-continuity.ts +23 -7
  307. package/src/oauth/anthropic-routing.ts +5 -2
  308. package/src/oauth/anthropic.ts +22 -2
  309. package/src/oauth/claude-keychain-read.ts +78 -68
  310. package/src/oauth/index.ts +24 -6
  311. package/src/oauth/local-token-detect.ts +8 -29
  312. package/src/oauth/login-cli-errors.ts +5 -1
  313. package/src/oauth/login-cli.ts +33 -18
  314. package/src/oauth/login-flow-state.ts +26 -3
  315. package/src/oauth/meta-muse.ts +1 -1
  316. package/src/oauth/store.ts +7 -0
  317. package/src/oauth/xai.ts +248 -14
  318. package/src/protocols/contract.ts +4 -0
  319. package/src/protocols/encoders/messages.ts +1 -0
  320. package/src/providers/alias-template.ts +48 -0
  321. package/src/providers/anthropic-billing-ownership.ts +2 -0
  322. package/src/providers/anthropic-output-caps.ts +46 -0
  323. package/src/providers/anthropic-reset-grant-ledger.ts +9 -3
  324. package/src/providers/antigravity-effort-families.ts +11 -3
  325. package/src/providers/antigravity-models.ts +32 -9
  326. package/src/providers/antigravity-wire-snapshot.ts +3 -2
  327. package/src/providers/api-key-pause.ts +3 -0
  328. package/src/providers/api-key-resolve.ts +49 -7
  329. package/src/providers/api-key-response-ownership.ts +2 -0
  330. package/src/providers/api-key-selection.ts +51 -9
  331. package/src/providers/api-keys.ts +6 -2
  332. package/src/providers/cache-affinity-identity.ts +73 -0
  333. package/src/providers/cache-affinity.ts +256 -0
  334. package/src/providers/default-aliases.ts +98 -20
  335. package/src/providers/google-vertex-model-discovery.ts +510 -0
  336. package/src/providers/key-failover.ts +123 -8
  337. package/src/providers/key-store.ts +3 -3
  338. package/src/providers/kiro-models.ts +3 -5
  339. package/src/providers/label.ts +31 -5
  340. package/src/providers/mistral-transport.ts +17 -4
  341. package/src/providers/model-rename-fields.ts +3 -0
  342. package/src/providers/muse-key-quota.ts +14 -6
  343. package/src/providers/new-model-policy-runtime.ts +17 -4
  344. package/src/providers/new-model-policy.ts +30 -4
  345. package/src/providers/passive-key-observation.ts +252 -0
  346. package/src/providers/quota/account-cache.ts +2 -1
  347. package/src/providers/quota/anthropic-cooldown-recovery-worker.ts +121 -0
  348. package/src/providers/quota/passive-key-limits.ts +272 -0
  349. package/src/providers/quota/passive-wire-model.ts +126 -0
  350. package/src/providers/quota/report-cache.ts +61 -2
  351. package/src/providers/quota-key-accounts.ts +11 -6
  352. package/src/providers/quota-types.ts +18 -0
  353. package/src/providers/quota.ts +11 -12
  354. package/src/providers/registry/entries-core.ts +34 -16
  355. package/src/providers/registry/entries-extended.ts +32 -0
  356. package/src/providers/registry/model-seeds.ts +35 -0
  357. package/src/providers/resolved-model-policy.ts +7 -0
  358. package/src/providers/routed-config.ts +8 -3
  359. package/src/providers/xai-transport.ts +3 -0
  360. package/src/remote/features.ts +17 -0
  361. package/src/responses/anthropic-progress.ts +10 -4
  362. package/src/responses/citation-markers.ts +231 -0
  363. package/src/responses/spill-store.ts +5 -1
  364. package/src/responses/state/replay-input.ts +50 -0
  365. package/src/responses/state/replay-owner.ts +24 -0
  366. package/src/responses/state/snapshot-codec.ts +9 -0
  367. package/src/responses/state/spill-queue.ts +1 -0
  368. package/src/responses/state.ts +42 -60
  369. package/src/router.ts +2 -2
  370. package/src/routing/home-route-capture.ts +123 -0
  371. package/src/routing/home-route-intent.ts +200 -0
  372. package/src/routing/route-intent-state.ts +178 -0
  373. package/src/routing/route-to-live-settings.ts +35 -0
  374. package/src/routing/route-to-local.ts +145 -0
  375. package/src/routing/route-to-status.ts +94 -0
  376. package/src/routing/route-to-sync-child.ts +32 -0
  377. package/src/server/adapter-resolve.ts +21 -1
  378. package/src/server/admitted-http-turn.ts +3 -0
  379. package/src/server/auth-cors.ts +98 -0
  380. package/src/server/bare-upstream-error.ts +220 -0
  381. package/src/server/chat-native.ts +14 -5
  382. package/src/server/claude-messages.ts +6 -4
  383. package/src/server/codex-model-list.ts +2 -1
  384. package/src/server/configured-credentials.ts +37 -5
  385. package/src/server/gui-desktop-authorization.ts +36 -0
  386. package/src/server/gui-pair-delivery.ts +6 -3
  387. package/src/server/gui-session.ts +10 -1
  388. package/src/server/inbound-body-admission.ts +17 -4
  389. package/src/server/index/link-listener.ts +190 -12
  390. package/src/server/index/link-management.ts +15 -1
  391. package/src/server/index/link-relay-sessions.ts +87 -8
  392. package/src/server/index/link-websocket-limits.ts +136 -0
  393. package/src/server/index/link-websocket.ts +692 -0
  394. package/src/server/index/optional-listeners.ts +97 -7
  395. package/src/server/index/route-intent-watch.ts +47 -0
  396. package/src/server/index/serve-contract.ts +86 -0
  397. package/src/server/index/serve-options.ts +35 -86
  398. package/src/server/index/startup-warnings.ts +8 -2
  399. package/src/server/index/websocket-handler.ts +26 -4
  400. package/src/server/index.ts +12 -2
  401. package/src/server/inference/client-encoder-delivery.ts +2 -0
  402. package/src/server/inspection-tee.ts +39 -2
  403. package/src/server/lifecycle.ts +2 -0
  404. package/src/server/link-turn.ts +137 -0
  405. package/src/server/management/advisor-routes.ts +10 -2
  406. package/src/server/management/agent-settings-routes.ts +50 -16
  407. package/src/server/management/anthropic-reset-grant-routes.ts +1 -1
  408. package/src/server/management/context.ts +9 -2
  409. package/src/server/management/desktop-authorization.ts +41 -0
  410. package/src/server/management/desktop-compatibility-routes.ts +9 -8
  411. package/src/server/management/desktop-compatibility-runtime-routes.ts +3 -2
  412. package/src/server/management/desktop-compatibility-settings-routes.ts +5 -3
  413. package/src/server/management/home-integration-decision.ts +89 -0
  414. package/src/server/management/integration-routes.ts +208 -81
  415. package/src/server/management/link-child-ops-routes.ts +145 -43
  416. package/src/server/management/link-child-preflight.ts +31 -0
  417. package/src/server/management/link-diagnostics-route.ts +29 -0
  418. package/src/server/management/link-enrollment.ts +199 -47
  419. package/src/server/management/link-operation.ts +609 -0
  420. package/src/server/management/link-recover-route.ts +103 -0
  421. package/src/server/management/link-route-edit.ts +173 -0
  422. package/src/server/management/link-route-request.ts +62 -0
  423. package/src/server/management/link-route-state.ts +83 -7
  424. package/src/server/management/link-routes.ts +553 -51
  425. package/src/server/management/link-traffic-status.ts +13 -0
  426. package/src/server/management/model-routes.ts +122 -36
  427. package/src/server/management/model-rows.ts +2 -1
  428. package/src/server/management/native-integration-routes.ts +176 -70
  429. package/src/server/management/oauth-account-routes.ts +36 -13
  430. package/src/server/management/protocol-routes.ts +7 -0
  431. package/src/server/management/provider-completion-test.ts +4 -4
  432. package/src/server/management/provider-overwrite-carry.ts +11 -0
  433. package/src/server/management/provider-routes.ts +64 -61
  434. package/src/server/management/provider-routing-quota.ts +45 -0
  435. package/src/server/management/route-registry.ts +22 -3
  436. package/src/server/management/route-to-routes.ts +257 -0
  437. package/src/server/management/system-restart.ts +4 -2
  438. package/src/server/management/usage-aggregate-cache.ts +101 -66
  439. package/src/server/management-api.ts +17 -3
  440. package/src/server/management-auth.ts +13 -1
  441. package/src/server/messages-native-preflight.ts +27 -4
  442. package/src/server/messages-native.ts +17 -5
  443. package/src/server/persistent-gui-session.ts +6 -3
  444. package/src/server/proxy-liveness.ts +33 -6
  445. package/src/server/relay-eager.ts +36 -12
  446. package/src/server/relay.ts +183 -116
  447. package/src/server/request-body-facts.ts +48 -0
  448. package/src/server/request-decompress.ts +65 -2
  449. package/src/server/request-log-account-rotation.ts +6 -0
  450. package/src/server/request-log-attempt-usage.ts +69 -0
  451. package/src/server/request-log-cache-affinity.ts +60 -0
  452. package/src/server/request-log-conversation.ts +45 -2
  453. package/src/server/request-log-terminal-status.ts +210 -24
  454. package/src/server/request-log.ts +71 -79
  455. package/src/server/responses/adapter-continuation.ts +2 -1
  456. package/src/server/responses/adapter-delivery.ts +2 -0
  457. package/src/server/responses/adapter-dispatch.ts +5 -7
  458. package/src/server/responses/advisor-plan-slot.ts +33 -1
  459. package/src/server/responses/advisor-question.ts +21 -0
  460. package/src/server/responses/advisor-slot.ts +10 -3
  461. package/src/server/responses/bare-namespace-aliases.ts +18 -0
  462. package/src/server/responses/buffered-sse-json.ts +9 -3
  463. package/src/server/responses/code-mode-collab-surface.ts +11 -0
  464. package/src/server/responses/codex-tool-catalog.ts +156 -0
  465. package/src/server/responses/combo-required-tool-fulfillments.ts +4 -2
  466. package/src/server/responses/combo-stream-preflight.ts +557 -54
  467. package/src/server/responses/compact.ts +32 -8
  468. package/src/server/responses/core-codex-account.ts +17 -3
  469. package/src/server/responses/core-combo-failure.ts +8 -0
  470. package/src/server/responses/core-combo.ts +32 -4
  471. package/src/server/responses/core-errors.ts +5 -2
  472. package/src/server/responses/core-lifetime.ts +3 -2
  473. package/src/server/responses/core-normalize.ts +3 -1
  474. package/src/server/responses/core-options.ts +6 -0
  475. package/src/server/responses/core.ts +2 -0
  476. package/src/server/responses/fetch-helpers.ts +15 -10
  477. package/src/server/responses/native-replay-guard.ts +57 -0
  478. package/src/server/responses/opengateway-completion-guard.ts +10 -4
  479. package/src/server/responses/outbound-request-body.ts +29 -0
  480. package/src/server/responses/passthrough-completion.ts +105 -8
  481. package/src/server/responses/passthrough-delivery.ts +31 -11
  482. package/src/server/responses/passthrough-dispatch.ts +74 -73
  483. package/src/server/responses/policy-fallback.ts +13 -1
  484. package/src/server/responses/request-prepare.ts +50 -6
  485. package/src/server/responses/request-transport.ts +10 -3
  486. package/src/server/responses/reset-replay.ts +46 -2
  487. package/src/server/responses/run-turn-execution.ts +2 -0
  488. package/src/server/responses/sidecar-execution.ts +14 -0
  489. package/src/server/responses/terminal-error-redaction.ts +222 -25
  490. package/src/server/responses/ws-upstream.ts +2 -2
  491. package/src/server/sse-payload-rewrite.ts +3 -2
  492. package/src/server/stop-service-route.ts +85 -0
  493. package/src/server/system-env-shell.ts +12 -1
  494. package/src/server/system-env.ts +5 -3
  495. package/src/server/windows-tcp-drop.ts +21 -4
  496. package/src/server/workflow-refusal.ts +8 -0
  497. package/src/server/ws-bridge.ts +191 -12
  498. package/src/service/cli-windows-stop.ts +189 -0
  499. package/src/service/cli.ts +41 -12
  500. package/src/service/disconnected-client-restart.ts +60 -0
  501. package/src/service/guarded-manager-target.ts +18 -1
  502. package/src/service/health.ts +99 -6
  503. package/src/service/launchd.ts +84 -31
  504. package/src/service/orchestration.ts +418 -91
  505. package/src/service/repair.ts +223 -6
  506. package/src/service/restart-proxy-stop.ts +79 -0
  507. package/src/service/service-child-ownership.ts +6 -2
  508. package/src/service/windows-checked-stop-live.ts +467 -0
  509. package/src/service/windows-checked-stop.ts +435 -0
  510. package/src/service/windows-command-line-token.ts +23 -0
  511. package/src/service/windows-guarded-manager.ts +77 -34
  512. package/src/service/windows-ops.ts +38 -56
  513. package/src/service/windows-process-evidence.ts +292 -0
  514. package/src/service/windows-process-native.ts +262 -0
  515. package/src/service/windows-service-stop.ts +321 -0
  516. package/src/service/windows-stop-binding.ts +187 -0
  517. package/src/service/windows-stop-budget.ts +123 -0
  518. package/src/service/windows-stop-confirm.ts +158 -0
  519. package/src/service/windows-stop-deadline.ts +56 -0
  520. package/src/service.ts +2 -2
  521. package/src/types/config.ts +42 -18
  522. package/src/types/link.ts +20 -0
  523. package/src/types/multi-agent.ts +13 -0
  524. package/src/types/provider.ts +47 -2
  525. package/src/types/request.ts +4 -0
  526. package/src/types.ts +3 -0
  527. package/src/update/guarded-runtime-ops.ts +5 -7
  528. package/src/update/index.ts +25 -10
  529. package/src/update/install-detection.mjs +3 -1
  530. package/src/update/job-pinned-start.ts +2 -0
  531. package/src/update/job-windows-restart.ts +19 -32
  532. package/src/update/job.ts +12 -5
  533. package/src/update/npm-install.d.mts +11 -0
  534. package/src/update/npm-install.mjs +44 -7
  535. package/src/update/orchestrated-entry.ts +1 -1
  536. package/src/update/orchestrated-node-driver.mjs +3 -2
  537. package/src/update/orchestrated-pnpm.d.mts +4 -0
  538. package/src/update/orchestrated-pnpm.mjs +50 -6
  539. package/src/update/orchestrated-session.d.mts +3 -1
  540. package/src/update/orchestrated-session.mjs +21 -6
  541. package/src/update/pnpm-global-install.d.mts +21 -3
  542. package/src/update/pnpm-global-install.mjs +322 -19
  543. package/src/update/pnpm-store-layout.mjs +46 -0
  544. package/src/update/sync-update-mutex.d.mts +3 -2
  545. package/src/update/sync-update-mutex.mjs +57 -8
  546. package/src/update/transactional-install.d.mts +3 -1
  547. package/src/update/transactional-install.mjs +545 -12
  548. package/src/update/windows-installer-marker.d.mts +1 -0
  549. package/src/update/windows-installer-marker.mjs +44 -0
  550. package/src/usage/expected-prices.ts +8 -0
  551. package/src/usage/filter-index.ts +326 -77
  552. package/src/usage/ledger-scanner.ts +15 -0
  553. package/src/usage/link-log-fields.ts +48 -0
  554. package/src/usage/log.ts +43 -2
  555. package/src/usage/request-body.ts +37 -0
  556. package/src/web-search/loop.ts +3 -0
  557. package/gui/dist/assets/App-BpJOzw4F.js +0 -59
  558. package/gui/dist/assets/index-Bbor_y80.js +0 -94
  559. package/gui/dist/classic/assets/App-BrIlUiLc.js +0 -58
  560. package/gui/dist/classic/assets/index-DyJHagvT.js +0 -94
  561. package/src/server/management/desktop-compatibility-authorization.ts +0 -12
@@ -267,6 +267,11 @@ const KIMI_K31_PRICING = KIMI_K3_PRICING;
267
267
  // (subscription quota / CNY tiers), so every GLM row below is verified-derived:
268
268
  // the numbers are the verified z.ai list prices shown as estimates.
269
269
  const ZAI_PRICING = "https://docs.z.ai/guides/overview/pricing (official USD table, 2026-09-13; cacheWrite=0 — cache storage is limited-time free on both z.ai and bigmodel.cn)";
270
+ // Morph Ultra is subscription-billed ($200/month, no token meter), so these are the vendor's
271
+ // published per-token list prices shown as estimates, never the amount Ultra actually charges.
272
+ const MORPH_ULTRA_PRICING = "https://www.morphllm.com/pricing (list price; Morph Ultra is subscription-billed with no token meter)";
273
+ const MORPH_KIMI_K31: Cost4 = { input: 2.5, output: 14, cacheRead: 0.29, cacheWrite: 0 };
274
+ const MORPH_DSV41_FLASH: Cost4 = { input: 0.12, output: 0.8, cacheRead: 0.008, cacheWrite: 0 };
270
275
  const ZAI_CODING_PLAN_NOTE = "z.ai list price shown as estimate; GLM Coding Plan is subscription-billed";
271
276
  const BIGMODEL_NOTE = "z.ai international list price shown as estimate; domestic bigmodel.cn billing is CNY tiered (docs.bigmodel.cn/cn/guide/start/pricing)";
272
277
  // 260804: Qwen3.8-Max shipped as a stable model and Qwen published a per-token rate, which
@@ -520,6 +525,9 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
520
525
  { provider: "opencode-go", modelId: "deepseek-v4.1-flash", cost4: DEEPSEEK_V41_FLASH, source: `peak-window list rate applied to the OpenCode Go surface (off-peak 0.15/0.60 + cache-hit 0.003 not baked in); ${DEEPSEEK_PRICING}`, verifiedAt: "2026-09-17", status: "verified-derived" },
521
526
  { provider: "opencode-go", modelId: "glm-5.3-flash", cost4: GLM_53_FLASH, source: `z.ai list price applied to the OpenCode Go surface as an estimate; ${ZAI_PRICING}`, verifiedAt: "2026-09-17", status: "verified-derived" },
522
527
  { provider: "opencode-go", modelId: "muse-spark-1.3-contributor", cost4: META_MUSE_SPARK_13_CONTRIBUTOR, source: `Meta Model API Contributor-tier price applied to the OpenCode Go surface as an estimate; ${META_SPARK_CONTRIBUTOR_SOURCE}`, verifiedAt: "2026-09-17", status: "verified-derived" },
528
+ // Morph Ultra — subscription-billed, so the vendor list price is an estimate only.
529
+ { provider: "morph", modelId: "morph-kimik31", cost4: MORPH_KIMI_K31, source: MORPH_ULTRA_PRICING, verifiedAt: "2026-11-13", status: "verified-derived" },
530
+ { provider: "morph", modelId: "morph-dsv41flash-1017", cost4: MORPH_DSV41_FLASH, source: MORPH_ULTRA_PRICING, verifiedAt: "2026-11-13", status: "verified-derived" },
523
531
  // Cursor Auto router — Cursor's published fixed token price (verified).
524
532
  { provider: "cursor", modelId: "auto", cost4: { input: 1.25, output: 6, cacheRead: 0.25, cacheWrite: 1.25 }, source: "https://docs.cursor.com/account/pricing + https://cursor.com/blog/aug-2025-pricing", verifiedAt: "2026-07-20", status: "verified" },
525
533
  // Z.AI GLM family — the zai bundle's rows are all-zero upstream, and the four
@@ -77,7 +77,13 @@ import { USAGE_CODEX_CLIENT_LABELS, type UsageSourceFilter } from "./source-filt
77
77
  import { usageAttributions } from "./summary";
78
78
  import type { UsageTimeWindow } from "./time-range";
79
79
 
80
- export const USAGE_FILTER_INDEX_SCHEMA_VERSION = 4;
80
+ /**
81
+ * Bumped to 5 when the candidate indexes moved `byte_offset` ahead of every other ordered column.
82
+ * The shape of `usage_rows` is unchanged, but a version 4 projection carries indexes that cannot
83
+ * deliver the pager's order; the derived tables are recreated and rebuilt from the ledger rather
84
+ * than migrated, so no stale index survives to re-introduce the per-page sort.
85
+ */
86
+ export const USAGE_FILTER_INDEX_SCHEMA_VERSION = 5;
81
87
  export const USAGE_FILTER_INDEX_DB_FILENAME = "usage-filter-index.sqlite";
82
88
  /** Rows per SQLite transaction during ingest; also the peak pending-row allocation. */
83
89
  export const USAGE_FILTER_INDEX_INSERT_BATCH = 500;
@@ -91,8 +97,26 @@ const SQLITE_BUSY_TIMEOUT_MS = 250;
91
97
  const RETAINED_WAL_LIMIT_BYTES = 4 * 1024 * 1024;
92
98
  const BATCH_BUSY_RETRIES = 3;
93
99
  const BATCH_BUSY_RETRY_MS = 5;
100
+ // Contention is retried briefly and then degrades to the streaming read, which answers the same
101
+ // request from the ledger. A longer wait only holds a dashboard request (and, through SQLite's
102
+ // synchronous busy timeout, the event loop) behind another writer.
94
103
  const BUSY_RETRY_DELAYS_MS = [10, 25, 50] as const;
104
+ // A rebuild-required error resolves as soon as the competing publish settles, so it retries on
105
+ // the original short schedule instead of parking behind the long busy backoff.
106
+ const REBUILD_RETRY_DELAYS_MS = [10, 25, 50] as const;
95
107
 
108
+ /**
109
+ * The candidate tables and their indexes.
110
+ *
111
+ * Every candidate branch pages in ascending `byte_offset` with `byte_offset > cursor`, so the
112
+ * ordered column must follow each equality prefix with nothing ordered-by-varying in between. A
113
+ * `(generation, timestamp, byte_offset)` index cannot satisfy that order without sorting the whole
114
+ * candidate range on every page, which made a deep page cost seconds instead of the streaming
115
+ * scan's fraction of one. The window filter is therefore a residual predicate over
116
+ * `idx_usage_rows_window`, whose monotonic cursor makes the scan one amortized pass. The same rule
117
+ * is why `idx_usage_attr_provider_offset` and `idx_usage_attr_model_offset` exist: a lone provider
118
+ * or model equality, like a lone client equality, still has to deliver `byte_offset` in order.
119
+ */
96
120
  const SCHEMA_DDL = `
97
121
  CREATE TABLE IF NOT EXISTS ${META_TABLE} (
98
122
  key TEXT PRIMARY KEY,
@@ -111,11 +135,11 @@ CREATE TABLE IF NOT EXISTS usage_rows (
111
135
  PRIMARY KEY (generation, byte_offset)
112
136
  ) WITHOUT ROWID;
113
137
 
114
- CREATE INDEX IF NOT EXISTS idx_usage_rows_ts ON usage_rows(generation, timestamp, byte_offset);
115
- CREATE INDEX IF NOT EXISTS idx_usage_rows_key ON usage_rows(generation, api_key_id, timestamp, byte_offset);
116
- CREATE INDEX IF NOT EXISTS idx_usage_rows_client ON usage_rows(generation, client, timestamp, byte_offset);
117
- CREATE INDEX IF NOT EXISTS idx_usage_rows_admission ON usage_rows(generation, admission_kind, api_key_id, byte_offset);
118
- CREATE INDEX IF NOT EXISTS idx_usage_rows_unattributable ON usage_rows(generation, unattributable);
138
+ CREATE INDEX IF NOT EXISTS idx_usage_rows_window ON usage_rows(generation, byte_offset, timestamp);
139
+ CREATE INDEX IF NOT EXISTS idx_usage_rows_key ON usage_rows(generation, api_key_id, byte_offset);
140
+ CREATE INDEX IF NOT EXISTS idx_usage_rows_client ON usage_rows(generation, client, byte_offset, surface);
141
+ CREATE INDEX IF NOT EXISTS idx_usage_rows_admission ON usage_rows(generation, admission_kind, byte_offset, api_key_id);
142
+ CREATE INDEX IF NOT EXISTS idx_usage_rows_unattributable ON usage_rows(generation, unattributable, byte_offset);
119
143
 
120
144
  CREATE TABLE IF NOT EXISTS usage_attributions (
121
145
  generation TEXT NOT NULL,
@@ -126,7 +150,8 @@ CREATE TABLE IF NOT EXISTS usage_attributions (
126
150
  ) WITHOUT ROWID;
127
151
 
128
152
  CREATE INDEX IF NOT EXISTS idx_usage_attr_provider ON usage_attributions(generation, provider, model, byte_offset);
129
- CREATE INDEX IF NOT EXISTS idx_usage_attr_model ON usage_attributions(generation, model, provider, byte_offset);
153
+ CREATE INDEX IF NOT EXISTS idx_usage_attr_provider_offset ON usage_attributions(generation, provider, byte_offset, model);
154
+ CREATE INDEX IF NOT EXISTS idx_usage_attr_model_offset ON usage_attributions(generation, model, byte_offset, provider);
130
155
 
131
156
  CREATE TABLE IF NOT EXISTS usage_filter_index_writers (
132
157
  generation TEXT PRIMARY KEY,
@@ -184,6 +209,17 @@ export class UsageFilterIndexHomeChangedError extends Error {
184
209
  }
185
210
  }
186
211
 
212
+ /**
213
+ * A candidate page could not be read from the index after the reader was handed out. The
214
+ * projection cannot serve this query, so the caller streams the ledger instead of failing.
215
+ */
216
+ export class UsageFilterIndexPageError extends Error {
217
+ constructor(readonly pageError: unknown) {
218
+ super("usage filter index candidate page could not be read");
219
+ this.name = "UsageFilterIndexPageError";
220
+ }
221
+ }
222
+
187
223
  /**
188
224
  * A retained filtered projection read this generation. A full rebuild replaces every offset,
189
225
  * so a projection from an older generation must be discarded even when the file identity and
@@ -220,8 +256,15 @@ export interface UsageFilterIndexQuery {
220
256
 
221
257
  export interface UsageFilterCandidateRead {
222
258
  snapshot: UsageFilterIndexSnapshot;
223
- /** Ascending row-start offsets selected by the index. */
224
- offsets: number[];
259
+ /** Number of candidates returned by pages consumed so far. */
260
+ candidateRows: number;
261
+ /** Returns the next bounded page of ascending row-start offsets. */
262
+ nextPage(): number[];
263
+ /**
264
+ * Closes the database handle. Pages are not read from one long snapshot: each `nextPage()`
265
+ * re-checks schema and generation inside its own short transaction.
266
+ */
267
+ close(): void;
225
268
  }
226
269
 
227
270
  /**
@@ -264,6 +307,12 @@ export interface UsageFilterIndexTestHooks {
264
307
  afterRefresh?: (info: { dbPath: string }) => void;
265
308
  /** Runs when a read met another writer's lock, before its back-off and retry. */
266
309
  beforeBusyRetry?: (info: { dbPath: string; attempt: number }) => void;
310
+ /**
311
+ * Runs instead of the real back-off before a retry, with the delay the caller would use.
312
+ * Returning `true` means the hook supplied the wait; a test can then advance its own clock
313
+ * instead of racing a real timer. Returning nothing keeps the production delay.
314
+ */
315
+ beforeRetryDelay?: (info: { dbPath: string; attempt: number; delayMs: number }) => boolean | void;
267
316
  }
268
317
 
269
318
  interface IndexMeta {
@@ -1145,10 +1194,29 @@ async function refreshUsageFilterIndex(
1145
1194
  }
1146
1195
  }
1147
1196
 
1148
- function buildCandidateSelect(
1197
+ interface CandidateBranch {
1198
+ /** Stable branch name; used to label a page statement in diagnostics and `EXPLAIN` seams. */
1199
+ label: string;
1200
+ sql: string;
1201
+ values: Array<string | number>;
1202
+ }
1203
+
1204
+ /**
1205
+ * One branch of the candidate select. `paged` adds the keyset bound `byte_offset > ?`; the caller
1206
+ * appends the cursor value at the end of each branch's values.
1207
+ *
1208
+ * Every branch is served by an index whose key order is `(generation, <equality prefix>,
1209
+ * byte_offset, ...)`, so `ORDER BY byteOffset` walks the index and the `LIMIT` stops the scan.
1210
+ * That is the whole point of the split: a compound `UNION` cannot keep that order, because
1211
+ * SQLite sorts each compound operand, so the previous single-statement pager re-materialized and
1212
+ * sorted the entire candidate range on every page. The branches are merged in JS by offset
1213
+ * instead, which keeps the one ascending-order contract the accumulator and the tests rely on.
1214
+ */
1215
+ function candidateBranches(
1149
1216
  query: UsageFilterIndexQuery,
1150
1217
  snapshot: UsageFilterIndexSnapshot,
1151
- ): { sql: string; values: Array<string | number> } {
1218
+ paged: boolean,
1219
+ ): CandidateBranch[] {
1152
1220
  const attrClauses: string[] = [];
1153
1221
  const attrValues: Array<string | number> = [];
1154
1222
  const rowClauses: string[] = [];
@@ -1182,13 +1250,15 @@ function buildCandidateSelect(
1182
1250
  const client = query.sourceFilter?.client;
1183
1251
  // Each alternative is its own index-friendly predicate. Keeping the Codex and unknown
1184
1252
  // expansions as an OR inside one scan made SQLite walk the whole generation; as separate
1185
- // branches each one searches the client index.
1253
+ // branches each one searches the client index. The Codex roster is expanded one label per
1254
+ // branch for the same reason a pager needs it: `client IN (...)` matches across several key
1255
+ // values, so SQLite cannot also deliver ascending `byte_offset` from the index and sorts the
1256
+ // whole match set on every page. Separate equalities keep each branch a single ordered seek.
1186
1257
  const clientAlternatives: Array<{ clauses: string[]; values: Array<string | number> }> = [];
1187
1258
  if (client === "codex") {
1188
- clientAlternatives.push({
1189
- clauses: [`r.client IN (${USAGE_CODEX_CLIENT_LABELS.map(() => "?").join(", ")})`],
1190
- values: [...USAGE_CODEX_CLIENT_LABELS],
1191
- });
1259
+ for (const label of USAGE_CODEX_CLIENT_LABELS) {
1260
+ clientAlternatives.push({ clauses: ["r.client = ?"], values: [label] });
1261
+ }
1192
1262
  // Mirrors matchesUsageSource: legacy Codex-surface rows are included too.
1193
1263
  clientAlternatives.push({ clauses: ["r.client IS NULL AND r.surface IS NULL"], values: [] });
1194
1264
  } else if (client === "unknown") {
@@ -1205,11 +1275,15 @@ function buildCandidateSelect(
1205
1275
  rowClauses.push("r.timestamp >= ? AND r.timestamp <= ?");
1206
1276
  rowValues.push(query.window.since, query.window.until);
1207
1277
  }
1208
- if (query.afterOffset !== undefined) {
1278
+ // A paged read starts every branch cursor at the append offset instead (see candidatePager): a
1279
+ // second lower bound on the same column makes SQLite seek from afterOffset on every page.
1280
+ if (query.afterOffset !== undefined && !paged) {
1209
1281
  rowClauses.push("r.byte_offset >= ?");
1210
1282
  rowValues.push(query.afterOffset);
1211
1283
  }
1212
- rowClauses.push("r.byte_offset <= ?");
1284
+ // The indexed offset is where the next unindexed row starts. Pages run in separate
1285
+ // transactions, so a concurrent refresh can index a row at exactly that offset mid-read.
1286
+ rowClauses.push("r.byte_offset < ?");
1213
1287
  rowValues.push(snapshot.indexedOffset);
1214
1288
  const alternativeSql = clientAlternatives
1215
1289
  .map(alternative => alternative.clauses.length > 0 ? `(${alternative.clauses.join(" AND ")})` : "")
@@ -1223,38 +1297,51 @@ function buildCandidateSelect(
1223
1297
  // estimate prefers the row primary key, which examines every row in the ledger even when
1224
1298
  // one API key or client matches a handful.
1225
1299
  const baseIndex = rowAccessIndexWithoutClient(query);
1226
- const branches = clientAlternatives.map(alternative => {
1300
+ const cursor = paged ? " AND r.byte_offset > ?" : "";
1301
+ return clientAlternatives.map((alternative, ordinal) => {
1227
1302
  const index = alternative.clauses.length > 0 ? "idx_usage_rows_client" : baseIndex;
1228
1303
  const clauses = [...rowClauses, ...alternative.clauses];
1229
1304
  return {
1230
- sql: `SELECT r.byte_offset AS byteOffset FROM usage_rows r${index ? ` INDEXED BY ${index}` : ""} WHERE r.generation = ? AND ${clauses.join(" AND ")}`,
1305
+ label: `row[${ordinal}]${index ? ` ${index}` : " primary key"}`,
1306
+ sql: `SELECT r.byte_offset AS byteOffset FROM usage_rows r${index ? ` INDEXED BY ${index}` : ""} WHERE r.generation = ? AND ${clauses.join(" AND ")}${cursor}`,
1231
1307
  values: [snapshot.generation, ...rowValues, ...alternative.values],
1232
1308
  };
1233
1309
  });
1234
- return {
1235
- sql: `${branches.map(branch => branch.sql).join(" UNION ")} ORDER BY byteOffset`,
1236
- values: branches.flatMap(branch => branch.values),
1237
- };
1238
1310
  }
1239
1311
  // Drive from the attribution index rather than scanning the row range: SQLite's default
1240
1312
  // estimate otherwise prefers the row primary key, which examines every row in the ledger.
1241
- const attrIndex = query.provider === null ? "idx_usage_attr_model" : "idx_usage_attr_provider";
1313
+ // A provider+model equality pair uses the tight `(provider, model, byte_offset)` index; a lone
1314
+ // provider or model still needs an offset-ordered index or the page would sort every match.
1315
+ const attrIndex = query.provider !== null && query.model !== null
1316
+ ? "idx_usage_attr_provider"
1317
+ : query.provider !== null
1318
+ ? "idx_usage_attr_provider_offset"
1319
+ : "idx_usage_attr_model_offset";
1242
1320
  // Rows with no usable attribution are selected too: the accumulator is what decides, and a
1243
1321
  // hand-edited row with a missing model must fail a provider/model filter exactly as the
1244
1322
  // streaming read does rather than disappear from the result.
1245
- return {
1246
- sql: `SELECT DISTINCT a.byte_offset AS byteOffset FROM usage_attributions a INDEXED BY ${attrIndex} WHERE a.generation = ? AND ${attrClauses.join(" AND ")} AND a.byte_offset <= ? AND EXISTS (SELECT 1 FROM usage_rows r WHERE r.generation = a.generation AND r.byte_offset = a.byte_offset AND ${rowSql}) UNION SELECT r.byte_offset AS byteOffset FROM usage_rows r INDEXED BY idx_usage_rows_unattributable WHERE r.generation = ? AND r.unattributable = 1 AND ${rowSql} ORDER BY byteOffset`,
1247
- values: [
1248
- snapshot.generation,
1249
- ...attrValues,
1250
- snapshot.indexedOffset,
1251
- ...rowValues,
1252
- ...clientAlternatives.flatMap(alternative => alternative.values),
1253
- snapshot.generation,
1254
- ...rowValues,
1255
- ...clientAlternatives.flatMap(alternative => alternative.values),
1256
- ],
1257
- };
1323
+ return [
1324
+ {
1325
+ label: `attribution ${attrIndex}`,
1326
+ sql: `SELECT DISTINCT a.byte_offset AS byteOffset FROM usage_attributions a INDEXED BY ${attrIndex} WHERE a.generation = ? AND ${attrClauses.join(" AND ")} AND a.byte_offset < ? AND EXISTS (SELECT 1 FROM usage_rows r WHERE r.generation = a.generation AND r.byte_offset = a.byte_offset AND ${rowSql})${paged ? " AND a.byte_offset > ?" : ""}`,
1327
+ values: [
1328
+ snapshot.generation,
1329
+ ...attrValues,
1330
+ snapshot.indexedOffset,
1331
+ ...rowValues,
1332
+ ...clientAlternatives.flatMap(alternative => alternative.values),
1333
+ ],
1334
+ },
1335
+ {
1336
+ label: "unattributable",
1337
+ sql: `SELECT r.byte_offset AS byteOffset FROM usage_rows r INDEXED BY idx_usage_rows_unattributable WHERE r.generation = ? AND r.unattributable = 1 AND ${rowSql}${paged ? " AND r.byte_offset > ?" : ""}`,
1338
+ values: [
1339
+ snapshot.generation,
1340
+ ...rowValues,
1341
+ ...clientAlternatives.flatMap(alternative => alternative.values),
1342
+ ],
1343
+ },
1344
+ ];
1258
1345
  }
1259
1346
 
1260
1347
  /** The index that answers the non-client part of a row-only filter. */
@@ -1263,18 +1350,132 @@ function rowAccessIndexWithoutClient(query: UsageFilterIndexQuery): string | nul
1263
1350
  const device = query.sourceFilter?.device;
1264
1351
  if (device?.kind === "no-key" || device?.kind === "key") return "idx_usage_rows_key";
1265
1352
  if (device?.kind === "unconfigured") return "idx_usage_rows_admission";
1266
- if (query.window) return "idx_usage_rows_ts";
1353
+ // The window is a residual predicate over a byte-offset-ordered index rather than a seek into
1354
+ // a timestamp-ordered one. A timestamp prefix cannot also deliver ascending `byte_offset`
1355
+ // without sorting, so the choice is a sort of every match on every page or one monotonic pass
1356
+ // over the generation's index entries; the latter is what a streaming scan would cost anyway.
1357
+ if (query.window) return "idx_usage_rows_window";
1267
1358
  return null;
1268
1359
  }
1269
1360
 
1270
- function selectCandidates(
1361
+ export const CANDIDATE_PAGE_SIZE = 2_000;
1362
+
1363
+ /**
1364
+ * The page statements behind the candidate pager: each branch seeks from the page cursor and
1365
+ * stops at the page size, so a late page reads at most `CANDIDATE_PAGE_SIZE` rows per branch and
1366
+ * never sorts. The pager merges the branch pages by offset; the cursor value is appended at the
1367
+ * end of each branch's values, followed by the page size, when the statement runs.
1368
+ */
1369
+ function candidatePageStatements(
1370
+ query: UsageFilterIndexQuery,
1371
+ snapshot: UsageFilterIndexSnapshot,
1372
+ ): Array<{ label: string; sql: string; values: Array<string | number> }> {
1373
+ return candidateBranches(query, snapshot, true).map(branch => ({
1374
+ label: branch.label,
1375
+ sql: `${branch.sql} ORDER BY byteOffset LIMIT ?`,
1376
+ values: branch.values,
1377
+ }));
1378
+ }
1379
+
1380
+ /**
1381
+ * Keyset pager over the candidate select: bounded pages, each validated in its own transaction.
1382
+ *
1383
+ * Each branch is its own statement so its index order supplies `ORDER BY byteOffset`, and each
1384
+ * keeps its own fetch cursor plus the rows it fetched but the last page did not need. Those rows
1385
+ * are carried into the next page instead of being fetched again: the whole read therefore touches
1386
+ * each candidate about once, bounded by one page of surplus per branch, and never grows with the
1387
+ * number of pages already served. Merging the branch heads yields one ascending, de-duplicated
1388
+ * page; an offset that appears in two branches is emitted once because every head at that value is
1389
+ * consumed together.
1390
+ */
1391
+ function candidatePager(
1271
1392
  db: Database,
1272
1393
  snapshot: UsageFilterIndexSnapshot,
1273
1394
  query: UsageFilterIndexQuery,
1274
- ): number[] {
1275
- const { sql, values } = buildCandidateSelect(query, snapshot);
1276
- const rows = db.query(sql).all(...values) as Array<{ byteOffset: number }>;
1277
- return rows.map(row => row.byteOffset);
1395
+ ): Pick<UsageFilterCandidateRead, "candidateRows" | "nextPage"> {
1396
+ // An append read starts at its offset; the cursor is exclusive, so start one byte before it.
1397
+ const startCursor = (query.afterOffset ?? 0) - 1;
1398
+ const branches = candidatePageStatements(query, snapshot).map(branch => ({
1399
+ statement: db.query(branch.sql),
1400
+ values: branch.values,
1401
+ /** Ascending matches fetched after `fetchCursor` but not yet returned. */
1402
+ pending: [] as number[],
1403
+ /** Read position in `pending`; advancing it keeps draining linear instead of shifting. */
1404
+ head: 0,
1405
+ /** The last offset this branch fetched; each branch bounds its own next fetch by it. */
1406
+ fetchCursor: startCursor,
1407
+ exhausted: false,
1408
+ }));
1409
+ let cursor = startCursor;
1410
+ const pager = {
1411
+ candidateRows: 0,
1412
+ /**
1413
+ * Returns the next bounded page of ascending offsets, re-validating schema and generation
1414
+ * inside its own transaction; a changed generation throws `UsageLedgerRebuildRequiredError`.
1415
+ */
1416
+ nextPage(): number[] {
1417
+ try {
1418
+ db.exec("BEGIN");
1419
+ const meta = readMeta(db);
1420
+ if (meta.schemaVersion !== USAGE_FILTER_INDEX_SCHEMA_VERSION
1421
+ || meta.generation !== snapshot.generation) {
1422
+ throw new UsageLedgerRebuildRequiredError("content_changed");
1423
+ }
1424
+ const offsets: number[] = [];
1425
+ while (offsets.length < CANDIDATE_PAGE_SIZE) {
1426
+ // Refill only a branch that ran dry, so a candidate fetched once is never fetched again.
1427
+ for (const branch of branches) {
1428
+ if (branch.head < branch.pending.length || branch.exhausted) continue;
1429
+ branch.pending.length = 0;
1430
+ branch.head = 0;
1431
+ const rows = branch.statement.all(
1432
+ ...branch.values,
1433
+ branch.fetchCursor,
1434
+ CANDIDATE_PAGE_SIZE,
1435
+ ) as Array<{ byteOffset: number }>;
1436
+ let accepted = 0;
1437
+ for (const row of rows) {
1438
+ // A branch that ignored its own bound cannot re-offer an already fetched offset.
1439
+ if (row.byteOffset <= branch.fetchCursor) continue;
1440
+ branch.fetchCursor = row.byteOffset;
1441
+ branch.pending.push(row.byteOffset);
1442
+ accepted += 1;
1443
+ }
1444
+ // A short page is the end; so is a page that made no progress, which stops a branch
1445
+ // that returns the same rows from spinning the merge without advancing the cursor.
1446
+ if (rows.length < CANDIDATE_PAGE_SIZE || accepted === 0) branch.exhausted = true;
1447
+ }
1448
+ let lowest: number | null = null;
1449
+ for (const branch of branches) {
1450
+ const value = branch.pending[branch.head];
1451
+ if (value !== undefined && (lowest === null || value < lowest)) lowest = value;
1452
+ }
1453
+ if (lowest === null) break;
1454
+ // Consume every head holding that offset, which de-duplicates across branches.
1455
+ for (const branch of branches) {
1456
+ if (branch.pending[branch.head] === lowest) branch.head += 1;
1457
+ }
1458
+ // Defensive: the merge only moves forward, so a rewind is a branch contract violation.
1459
+ if (lowest > cursor) {
1460
+ cursor = lowest;
1461
+ offsets.push(lowest);
1462
+ }
1463
+ }
1464
+ db.exec("COMMIT");
1465
+ pager.candidateRows += offsets.length;
1466
+ return offsets;
1467
+ } catch (error) {
1468
+ try { db.exec("ROLLBACK"); } catch { /* nothing to roll back */ }
1469
+ // A generation change keeps the rebuild retry; every other index-side failure means
1470
+ // this projection cannot serve the page, so the caller streams the ledger instead.
1471
+ if (error instanceof UsageLedgerRebuildRequiredError) throw error;
1472
+ // Paging cannot repair a damaged projection; ask the next active refresh to rebuild it.
1473
+ if (isCorruptError(error)) requestUsageFilterIndexRebuild();
1474
+ throw new UsageFilterIndexPageError(error);
1475
+ }
1476
+ },
1477
+ };
1478
+ return pager;
1278
1479
  }
1279
1480
 
1280
1481
  /** A published generation with a nonzero row count must actually hold rows. */
@@ -1283,6 +1484,10 @@ function hasPublishedRows(db: Database, generation: string): boolean {
1283
1484
  .get(generation) !== null;
1284
1485
  }
1285
1486
 
1487
+ /**
1488
+ * Refreshes the projection, then returns a paged reader for the published generation. Throws
1489
+ * `UsageLedgerRebuildRequiredError` when the published meta moved under the open.
1490
+ */
1286
1491
  async function readActive(
1287
1492
  dir: string,
1288
1493
  path: string,
@@ -1304,22 +1509,28 @@ async function readActive(
1304
1509
  ingestedRows: refreshed.ingestedRows,
1305
1510
  ingestPasses: refreshed.ingestPasses,
1306
1511
  };
1307
- const offsets = selectCandidates(db, snapshot, query);
1308
- if (offsets.length === 0 && meta.indexedRows > 0 && !hasPublishedRows(db, meta.generation)) {
1512
+ if (meta.indexedRows > 0 && !hasPublishedRows(db, meta.generation)) {
1309
1513
  // The published generation claims rows it no longer has. Never serve that as a
1310
1514
  // complete zero; drop the projection and rebuild. The refresh alone cannot see this
1311
1515
  // (the cursor and identity still match), so the rebuild must be requested explicitly.
1312
1516
  requestUsageFilterIndexRebuild();
1313
1517
  throw new UsageLedgerRebuildRequiredError("content_changed");
1314
1518
  }
1519
+ const pager = candidatePager(db, snapshot, query);
1315
1520
  db.exec("COMMIT");
1316
- return { snapshot, offsets };
1521
+ return {
1522
+ snapshot,
1523
+ get candidateRows() { return pager.candidateRows; },
1524
+ nextPage: () => pager.nextPage(),
1525
+ close: () => db.close(),
1526
+ };
1317
1527
  } catch (error) {
1318
1528
  try { db.exec("ROLLBACK"); } catch { /* nothing to roll back */ }
1319
1529
  throw error;
1320
1530
  }
1321
- } finally {
1531
+ } catch (error) {
1322
1532
  db.close();
1533
+ throw error;
1323
1534
  }
1324
1535
  }
1325
1536
 
@@ -1343,26 +1554,34 @@ export async function readUsageFilterCandidates(
1343
1554
  return await readActive(dir, path, query);
1344
1555
  } catch (error) {
1345
1556
  if (error instanceof UsageFilterIndexSourceError) throw error;
1346
- if (error instanceof UsageFilterIndexForeignError
1347
- || error instanceof UnsafeSqlitePathError
1348
- || error instanceof UsageFilterIndexHomeChangedError) {
1557
+ // A changed home never heals on a re-check; every later open targets the new directory.
1558
+ if (error instanceof UsageFilterIndexHomeChangedError) {
1349
1559
  return null;
1350
1560
  }
1351
- if (error instanceof UsageLedgerRebuildRequiredError) {
1352
- const delay = BUSY_RETRY_DELAYS_MS[attempt];
1561
+ // A foreign classification or unsafe-path flag can still be a transient view: the file at
1562
+ // this path can be replaced mid-flight, or a sidecar appears or vanishes mid-stat while
1563
+ // another writer transacts. Give them the short re-check schedule before degrading, exactly
1564
+ // like a moved publish.
1565
+ if (error instanceof UsageLedgerRebuildRequiredError
1566
+ || error instanceof UsageFilterIndexForeignError
1567
+ || error instanceof UnsafeSqlitePathError) {
1568
+ const delay = REBUILD_RETRY_DELAYS_MS[attempt];
1353
1569
  if (delay === undefined) return null;
1354
- await new Promise<void>(resolve => setTimeout(resolve, delay));
1570
+ if (testHooks?.beforeRetryDelay?.({ dbPath: path, attempt, delayMs: delay }) !== true) {
1571
+ await new Promise<void>(resolve => setTimeout(resolve, delay));
1572
+ }
1355
1573
  continue;
1356
1574
  }
1357
1575
  if (isBusyError(error)) {
1358
- // Contention, including a peer still creating the projection, is waited out rather than
1359
- // read as a foreign file. The bound is four busy timeouts (the fourth attempt has no
1360
- // back-off) plus these delays, about 1.1 s, before the request falls back to the
1361
- // streaming read.
1576
+ // Contention, including a peer still creating the projection, is waited out briefly rather
1577
+ // than read as a foreign file. The bound is the BUSY_RETRY_DELAYS_MS sum (85 ms) plus up to
1578
+ // four busy timeouts before the request falls back to the streaming read.
1362
1579
  const delay = BUSY_RETRY_DELAYS_MS[attempt];
1363
1580
  if (delay === undefined) return null;
1364
1581
  testHooks?.beforeBusyRetry?.({ dbPath: path, attempt });
1365
- await new Promise<void>(resolve => setTimeout(resolve, delay));
1582
+ if (testHooks?.beforeRetryDelay?.({ dbPath: path, attempt, delayMs: delay }) !== true) {
1583
+ await new Promise<void>(resolve => setTimeout(resolve, delay));
1584
+ }
1366
1585
  continue;
1367
1586
  }
1368
1587
  // Any other index-side failure (permissions, disk full, a corrupt file) degrades to the
@@ -1396,16 +1615,21 @@ export async function readUsageFilterCandidatesPassive(
1396
1615
  || !tables.has("usage_rows")
1397
1616
  || !tables.has("usage_attributions")
1398
1617
  || !tables.has("usage_filter_index_writers")) {
1399
- return null;
1618
+ throw new UsageFilterIndexForeignError();
1400
1619
  }
1401
1620
  db.exec("BEGIN");
1402
1621
  try {
1403
1622
  const meta = readMeta(db);
1404
1623
  const revision = currentUsageLogRevision();
1405
- if (meta.schemaVersion !== USAGE_FILTER_INDEX_SCHEMA_VERSION || !meta.generation) return null;
1406
- if (usageLogIdentityKey(meta.revision) !== usageLogIdentityKey(revision)) return null;
1407
- if (!revision || meta.indexedOffset !== revision.size) return null;
1408
- if (usageLogRevisionKey(meta.revision) !== usageLogRevisionKey(revision)) return null;
1624
+ if (meta.schemaVersion !== USAGE_FILTER_INDEX_SCHEMA_VERSION || !meta.generation) {
1625
+ throw new UsageLedgerRebuildRequiredError("content_changed");
1626
+ }
1627
+ if (usageLogIdentityKey(meta.revision) !== usageLogIdentityKey(revision)
1628
+ || !revision
1629
+ || meta.indexedOffset !== revision.size
1630
+ || usageLogRevisionKey(meta.revision) !== usageLogRevisionKey(revision)) {
1631
+ throw new UsageLedgerRebuildRequiredError("content_changed");
1632
+ }
1409
1633
  const snapshot = snapshotFrom(meta, 0, 0);
1410
1634
  // The exact revision match above already proves the ledger is the one indexed; the
1411
1635
  // empty read keeps the passive path on the same validation as the active one.
@@ -1417,33 +1641,58 @@ export async function readUsageFilterCandidatesPassive(
1417
1641
  expectedProcessedThroughDigest: snapshot.processedThroughDigest,
1418
1642
  expectedFileSize: snapshot.revision?.size,
1419
1643
  });
1420
- const offsets = selectCandidates(db, snapshot, query);
1421
- if (offsets.length === 0 && meta.indexedRows > 0 && !hasPublishedRows(db, meta.generation)) {
1644
+ if (meta.indexedRows > 0 && !hasPublishedRows(db, meta.generation)) {
1422
1645
  // Same guard as the active read: a published generation that lost its rows must not
1423
1646
  // be reported as a complete zero.
1424
- return null;
1647
+ throw new UsageLedgerRebuildRequiredError("content_changed");
1425
1648
  }
1426
- return { snapshot, offsets };
1427
- } finally {
1428
- try { db.exec("COMMIT"); } catch { /* read-only transaction */ }
1649
+ const pager = candidatePager(db, snapshot, query);
1650
+ db.exec("COMMIT");
1651
+ return {
1652
+ snapshot,
1653
+ get candidateRows() { return pager.candidateRows; },
1654
+ nextPage: () => pager.nextPage(),
1655
+ close: () => db.close(),
1656
+ };
1657
+ } catch (error) {
1658
+ try { db.exec("ROLLBACK"); } catch { /* read-only transaction */ }
1659
+ throw error;
1429
1660
  }
1430
1661
  } catch {
1431
- return null;
1432
- } finally {
1662
+ try { db.exec("ROLLBACK"); } catch { /* transaction may not have started */ }
1433
1663
  db.close();
1664
+ return null;
1434
1665
  }
1435
1666
  }
1436
1667
 
1437
- /** Test seam: the SQLite plan for one filter's candidate select. */
1438
- export function usageFilterCandidatePlan(query: UsageFilterIndexQuery): string[] {
1668
+ /**
1669
+ * Test seam: the SQLite plan for one filter's candidate statements, one labeled block per branch.
1670
+ * `paged` explains the statement the pager actually runs, including its keyset bound and `LIMIT`;
1671
+ * the unpaged form is the same branch without the cursor. Neither form may sort: an index-ordered
1672
+ * branch is the contract that keeps a page proportional to its page size rather than to the
1673
+ * candidate set.
1674
+ */
1675
+ export function usageFilterCandidatePlan(
1676
+ query: UsageFilterIndexQuery,
1677
+ options: { paged?: boolean } = {},
1678
+ ): string[] {
1439
1679
  const path = indexPathForCurrentHome();
1440
1680
  const db = new Database(path, { readonly: true });
1441
1681
  try {
1442
1682
  const meta = readMeta(db);
1443
1683
  const snapshot = snapshotFrom(meta, 0, 0);
1444
- const { sql, values } = buildCandidateSelect(query, snapshot);
1445
- const rows = db.query(`EXPLAIN QUERY PLAN ${sql}`).all(...values) as Array<{ detail: string }>;
1446
- return rows.map(row => row.detail);
1684
+ const statements = options.paged
1685
+ ? candidatePageStatements(query, snapshot)
1686
+ : candidateBranches(query, snapshot, false)
1687
+ .map(branch => ({ label: branch.label, sql: branch.sql, values: branch.values }));
1688
+ return statements.flatMap(statement => {
1689
+ const params = options.paged
1690
+ ? [...statement.values, 0, CANDIDATE_PAGE_SIZE]
1691
+ : statement.values;
1692
+ const rows = db.query(`EXPLAIN QUERY PLAN ${statement.sql}`).all(...params) as
1693
+ Array<{ detail: string }>;
1694
+ return [`-- ${statement.label}`, ...rows.map(row => row.detail)];
1695
+ });
1447
1696
  } finally {
1448
1697
  db.close();
1449
1698
  }
@@ -20,6 +20,7 @@ export const USAGE_LEDGER_ROW_READ_WINDOW_BYTES = 64 * 1024;
20
20
  // one unterminated line an unbounded allocation.
21
21
  export const USAGE_LEDGER_MAX_LINE_BYTES = 1024 * 1024;
22
22
  export const USAGE_LEDGER_BOUNDARY_DIGEST_BYTES = 64 * 1024;
23
+ const MAX_SCAN_SLICE_MS = 8;
23
24
 
24
25
  export interface ScanUsageLedgerOptions {
25
26
  signal?: AbortSignal;
@@ -289,6 +290,7 @@ export async function scanUsageLedgerCooperatively(
289
290
  let bytesRead = 0;
290
291
  let bytesSinceYield = 0;
291
292
  let linesSinceYield = 0;
293
+ let lastYieldAt = performance.now();
292
294
  let processedThroughBytes = startAtBytes;
293
295
  const capturedHash = createHash("sha256");
294
296
  const committedTail = new RollingByteWindow(USAGE_LEDGER_BOUNDARY_DIGEST_BYTES);
@@ -395,11 +397,24 @@ export async function scanUsageLedgerCooperatively(
395
397
  }
396
398
  lineLength = 0;
397
399
  cursor = newline + 1;
400
+ // Bytes do not bound normalization/aggregation time on a busy host. Let
401
+ // network callbacks, timers and cancellation run even within the final chunk.
402
+ // Only elapsed time triggers this yield: a row count here would yield several
403
+ // times per chunk of cheap rows and slow a cold scan (the chunk boundary below
404
+ // keeps the row limit). setTimeout, unlike setImmediate, lets due timers run.
405
+ if (performance.now() - lastYieldAt >= MAX_SCAN_SLICE_MS) {
406
+ await new Promise<void>(resolve => setTimeout(resolve, 0));
407
+ throwIfAborted(options.signal);
408
+ lastYieldAt = performance.now();
409
+ bytesSinceYield = 0;
410
+ linesSinceYield = 0;
411
+ }
398
412
  }
399
413
 
400
414
  if (position < scanEnd
401
415
  && (bytesSinceYield >= USAGE_LEDGER_READ_CHUNK_BYTES || linesSinceYield >= 1_000)) {
402
416
  await new Promise<void>(resolve => setTimeout(resolve, 0));
417
+ lastYieldAt = performance.now();
403
418
  bytesSinceYield = 0;
404
419
  linesSinceYield = 0;
405
420
  }