@thready-web/dsh-bot-plugin 0.1.0-beta.2 → 0.1.0-beta.4

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.
@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
2
2
  import { sha256 } from "./fs-safe.js";
3
3
  import { toolError } from "./errors.js";
4
4
  import { createTicketBook } from "./work-tickets.js";
5
- import { decideAdmission, budgetTrip, estimateWorkerBudget, DEFAULT_WORK_BUDGET } from "./work-admit.js";
5
+ import { decideAdmission, budgetTrip, estimateWorkerBudget, DEFAULT_WORK_BUDGET, effectiveWorkLimits, } from "./work-admit.js";
6
6
  import { messageIdOf, pushInput, pushNotice, reasonKindOf, reconcileInputs, reconcileNotices, renderNotice, } from "./work-ledger.js";
7
7
  const KINDS = new Set(['progress', 'question', 'artifact', 'result', 'failure']);
8
8
  const LABEL = {
@@ -15,6 +15,8 @@ const LABEL = {
15
15
  cancelled: 'cancelled',
16
16
  failed: 'failed',
17
17
  };
18
+ /** Message id prefix of the inbox notice sent after a main-session budget trip. */
19
+ export const BUDGET_NOTICE_PREFIX = 'foundations-budget:';
18
20
  /**
19
21
  * Host-side ticket protocol. The model is not called from here.
20
22
  * Native inbox delivery stays in `options.push` / `options.pendingIds`.
@@ -24,10 +26,15 @@ const LABEL = {
24
26
  export function createWorkRuntime(store, engine, options = {}) {
25
27
  const now = options.now ?? (() => new Date());
26
28
  const limits = { ...DEFAULT_WORK_BUDGET, ...options.budget };
29
+ const slots = effectiveWorkLimits(limits);
27
30
  const pid = options.pid ?? process.pid;
28
31
  const resident = options.resident !== false;
29
32
  const book = createTicketBook(store.db, store.root, now);
30
33
  const inflight = new Set();
34
+ /** Ticket ids currently in ensureChild / flush, so a tick cannot start the same ticket twice. */
35
+ const starting = new Set();
36
+ /** In-flight startReserved promises, so a later promoteQueued can join them. */
37
+ const startingPromises = new Map();
31
38
  /** @type {Map<string, { messageId: string, turn: number | null, seq: number | null }>} */
32
39
  const turns = new Map();
33
40
  /** @type {Map<string, string>} */
@@ -36,6 +43,8 @@ export function createWorkRuntime(store, engine, options = {}) {
36
43
  const arms = new Map();
37
44
  /** @type {Map<string, number>} */
38
45
  const holds = new Map();
46
+ const admitting = new Set();
47
+ const budgetWaiters = new Map();
39
48
  const schedule = options.schedule ??
40
49
  ((fn, ms) => {
41
50
  const timer = setTimeout(fn, ms);
@@ -73,8 +82,11 @@ export function createWorkRuntime(store, engine, options = {}) {
73
82
  releaseHold,
74
83
  tick,
75
84
  admit,
85
+ promoteQueued,
76
86
  observeSession,
77
87
  observeClaimed,
88
+ gateStep,
89
+ waitForBudget,
78
90
  isWorkerSession,
79
91
  summaries: (owner) => book.summaries(owner),
80
92
  detail: (id) => book.detail(id),
@@ -89,6 +101,171 @@ export function createWorkRuntime(store, engine, options = {}) {
89
101
  function isWorkerSession(sessionId) {
90
102
  return book.attemptForChild(sessionId) != null;
91
103
  }
104
+ /**
105
+ * A running slot is free when both the per-bot and global running caps have room.
106
+ * needs_user does not occupy a running slot.
107
+ * @param {string} owner
108
+ */
109
+ function hasSlot(owner) {
110
+ return book.countSlots(owner) < slots.perBot && book.countGlobalSlots() < slots.global;
111
+ }
112
+ /**
113
+ * Queue room is separate from running slots. The combined unfinished cap is
114
+ * slots + queue, so parked needs_user tickets cannot grow without bound.
115
+ * @param {string} owner
116
+ */
117
+ function canQueue(owner) {
118
+ return (book.countQueued(owner) < slots.perBotQueue &&
119
+ book.countGlobalQueued() < slots.globalQueue &&
120
+ book.countActive(owner) < slots.perBot + slots.perBotQueue &&
121
+ book.countGlobal() < slots.global + slots.globalQueue);
122
+ }
123
+ /**
124
+ * @param {string} owner
125
+ * @returns {'start' | 'queue' | 'refuse'}
126
+ */
127
+ function underCombinedCap(owner) {
128
+ return (book.countActive(owner) < slots.perBot + slots.perBotQueue &&
129
+ book.countGlobal() < slots.global + slots.globalQueue);
130
+ }
131
+ /**
132
+ * @param {string} owner
133
+ * @returns {'start' | 'queue' | 'refuse'}
134
+ */
135
+ function decideDispatch(owner) {
136
+ // needs_user does not occupy a running slot, but it still counts as unfinished.
137
+ // A free slot must not admit a new ticket once the combined cap is full.
138
+ if (!underCombinedCap(owner))
139
+ return 'refuse';
140
+ if (hasSlot(owner))
141
+ return 'start';
142
+ if (canQueue(owner))
143
+ return 'queue';
144
+ return 'refuse';
145
+ }
146
+ /**
147
+ * Create the child if needed and flush the current briefing or supply.
148
+ * @param {Record<string, any>} ticket
149
+ */
150
+ async function startReserved(ticket) {
151
+ if (!resident) {
152
+ return { ...publicDispatch(ticket), flush: 'pending', resident: false, message: 'Only a resident host continues' };
153
+ }
154
+ if (starting.has(ticket.id)) {
155
+ return startingPromises.get(ticket.id) ?? publicDispatch(book.ticket(ticket.id) ?? ticket, { flush: 'pending' });
156
+ }
157
+ starting.add(ticket.id);
158
+ const run = (async () => {
159
+ const current = book.ticket(ticket.id);
160
+ if (!current)
161
+ return toolError('NOT_FOUND', 'No such ticket.');
162
+ if (current.status === 'cancelled' || current.status === 'failed' || current.status === 'delivered') {
163
+ return publicDispatch(current);
164
+ }
165
+ const created = await ensureChild(current);
166
+ if (created.error)
167
+ return created.error;
168
+ if (created.rejected)
169
+ return publicDispatch(created.ticket ?? book.ticket(ticket.id) ?? current);
170
+ const liveAfterStart = book.ticket(ticket.id);
171
+ if (!liveAfterStart ||
172
+ liveAfterStart.status === 'cancelled' ||
173
+ liveAfterStart.status === 'failed' ||
174
+ liveAfterStart.status === 'delivered') {
175
+ return publicDispatch(liveAfterStart ?? current);
176
+ }
177
+ const input = await store.write('work', () => {
178
+ const live = book.ticket(ticket.id);
179
+ const liveAttempt = book.attempt(live.active_attempt_id);
180
+ if (liveAttempt?.current_input_id) {
181
+ const existing = book.input(liveAttempt.current_input_id);
182
+ if (existing)
183
+ return existing;
184
+ }
185
+ const text = book.readBriefing(live.briefing_hash);
186
+ return book.insertInput({
187
+ ticketId: live.id,
188
+ attemptId: liveAttempt.id,
189
+ revision: live.briefing_revision,
190
+ kind: 'briefing',
191
+ text,
192
+ });
193
+ });
194
+ if (input.flush_status === 'accepted') {
195
+ return publicDispatch(book.ticket(ticket.id), { flush: 'accepted', nativeMessageId: input.native_message_id });
196
+ }
197
+ const flushed = await pushInput(book, input, deps);
198
+ return publicDispatch(book.ticket(ticket.id), {
199
+ flush: flushWord(flushed),
200
+ nativeMessageId: input.native_message_id,
201
+ });
202
+ })();
203
+ startingPromises.set(ticket.id, run);
204
+ try {
205
+ return await run;
206
+ }
207
+ finally {
208
+ starting.delete(ticket.id);
209
+ startingPromises.delete(ticket.id);
210
+ }
211
+ }
212
+ /**
213
+ * Start waiting tickets that now fit a slot. Awaits only starts this call
214
+ * launched, so a hung createChild from an earlier call cannot deadlock
215
+ * later ticks or cancel. The earlier promise stays owned until it finishes
216
+ * and is then attached or cleaned up.
217
+ */
218
+ async function promoteQueued() {
219
+ if (!resident)
220
+ return { started: [] };
221
+ const started = [];
222
+ const launched = [];
223
+ const launch = (ticket) => {
224
+ if (!ticket?.id || starting.has(ticket.id))
225
+ return;
226
+ started.push(ticket.id);
227
+ launched.push(startReserved(ticket).catch(error => {
228
+ options.log?.('warn', `session-foundations: startReserved failed ticket=${ticket.id} ${error instanceof Error ? error.message : String(error)}`);
229
+ return error;
230
+ }));
231
+ };
232
+ for (const ticket of book.heldStarts())
233
+ launch(ticket);
234
+ for (;;) {
235
+ const claimed = await store.write('work', () => {
236
+ for (const ticket of book.nextPromotable()) {
237
+ if (book.slotHeld(ticket))
238
+ continue;
239
+ if (ticket.status !== 'accepted' && ticket.status !== 'needs_user')
240
+ continue;
241
+ if (!hasSlot(ticket.owner_session_id))
242
+ continue;
243
+ return book.reserveSlot(ticket.id);
244
+ }
245
+ return null;
246
+ });
247
+ if (!claimed)
248
+ break;
249
+ launch(claimed);
250
+ }
251
+ await Promise.all(launched);
252
+ // Join in-flight starts that are still allowed to attach. Do not join a
253
+ // hung createChild after the ticket has already been cancelled, failed, or
254
+ // expired, so a later tick can free the slot and start the next waiter.
255
+ const pending = [...startingPromises.entries()]
256
+ .filter(([id]) => {
257
+ const ticket = book.ticket(id);
258
+ return (ticket != null && ticket.status !== 'failed' && ticket.status !== 'cancelled' && ticket.status !== 'delivered');
259
+ })
260
+ .map(([, promise]) => promise);
261
+ await Promise.all(pending);
262
+ return { started };
263
+ }
264
+ function schedulePromote() {
265
+ void promoteQueued().catch(error => {
266
+ options.log?.('warn', `session-foundations: promoteQueued failed ${error instanceof Error ? error.message : String(error)}`);
267
+ });
268
+ }
92
269
  /**
93
270
  * @param {string} owner
94
271
  * @param {Record<string, unknown>} args
@@ -116,50 +293,40 @@ export function createWorkRuntime(store, engine, options = {}) {
116
293
  return { replay: existing };
117
294
  }
118
295
  }
119
- if (book.countActive(owner) >= limits.perBot || book.countGlobal() >= limits.global) {
296
+ const decision = decideDispatch(owner);
297
+ if (decision === 'refuse') {
120
298
  return {
121
- error: toolError('BUDGET', 'Unfinished tickets already hit the host concurrency limit, so no row was created.'),
299
+ error: toolError('BUDGET', 'Unfinished tickets already hit the host slot and queue limits, so no row was created.'),
122
300
  };
123
301
  }
124
- return {
125
- created: book.insertAccepted({
126
- owner,
127
- briefing,
128
- idempotencyKey: key,
129
- correlationId: correlationOf(owner, args.correlationId),
130
- budget,
131
- }),
132
- };
302
+ const created = book.insertAccepted({
303
+ owner,
304
+ briefing,
305
+ idempotencyKey: key,
306
+ correlationId: correlationOf(owner, args.correlationId),
307
+ budget,
308
+ });
309
+ if (decision === 'start')
310
+ book.reserveSlot(created.ticket.id);
311
+ return { created, start: decision === 'start' };
133
312
  });
134
313
  if (prepared.error)
135
314
  return prepared.error;
136
315
  if (prepared.replay)
137
316
  return publicDispatch(prepared.replay, { replayed: true });
138
317
  const ticket = prepared.created.ticket;
318
+ if (!prepared.start) {
319
+ return publicDispatch(book.ticket(ticket.id), {
320
+ flush: 'pending',
321
+ queued: true,
322
+ childSessionId: null,
323
+ nativeMessageId: null,
324
+ });
325
+ }
139
326
  if (!resident) {
140
327
  return { ...publicDispatch(ticket), flush: 'pending', resident: false, message: 'Only a resident host continues' };
141
328
  }
142
- const created = await ensureChild(ticket);
143
- if (created.error)
144
- return created.error;
145
- const input = await store.write('work', () => {
146
- const current = book.ticket(ticket.id);
147
- const attempt = book.attempt(current.active_attempt_id);
148
- if (attempt?.current_input_id)
149
- return book.input(attempt.current_input_id);
150
- return book.insertInput({
151
- ticketId: current.id,
152
- attemptId: attempt.id,
153
- revision: current.briefing_revision,
154
- kind: 'briefing',
155
- text: briefing,
156
- });
157
- });
158
- const flushed = await pushInput(book, input, deps);
159
- return publicDispatch(book.ticket(ticket.id), {
160
- flush: flushWord(flushed),
161
- nativeMessageId: input.native_message_id,
162
- });
329
+ return startReserved(ticket);
163
330
  }
164
331
  /**
165
332
  * @param {string} owner
@@ -190,9 +357,28 @@ export function createWorkRuntime(store, engine, options = {}) {
190
357
  if (found.error)
191
358
  return found.error;
192
359
  const expected = revisionOf(args.expectedRevision);
193
- const advanced = await store.write('work', () => book.advanceGeneration(found.ticket.id, expected, kind, text));
360
+ const advanced = await store.write('work', () => {
361
+ const result = book.advanceGeneration(found.ticket.id, expected, kind, text);
362
+ if (result.error)
363
+ return result;
364
+ // A supply into needs_user must take a running slot. If none is free, keep
365
+ // the input durable and start it when promoteQueued reserves one.
366
+ if (kind === 'supply' && result.ticket.status === 'needs_user' && !hasSlot(owner)) {
367
+ return { ...result, queued: true };
368
+ }
369
+ if (kind === 'supply' && result.ticket.status === 'needs_user')
370
+ book.reserveSlot(result.ticket.id);
371
+ return result;
372
+ });
194
373
  if (advanced.error)
195
374
  return toolError(advanced.error, advanced.message ?? 'Changing the generation failed.');
375
+ if (advanced.queued) {
376
+ return publicDispatch(book.ticket(found.ticket.id), {
377
+ flush: 'pending',
378
+ queued: true,
379
+ nativeMessageId: advanced.input.native_message_id,
380
+ });
381
+ }
196
382
  if (!resident)
197
383
  return { ...publicDispatch(advanced.ticket), flush: 'pending', message: 'Only a resident host continues' };
198
384
  const flushed = await pushInput(book, advanced.input, deps);
@@ -217,12 +403,15 @@ export function createWorkRuntime(store, engine, options = {}) {
217
403
  if (cancelled.error)
218
404
  return toolError(cancelled.error, cancelled.message ?? 'Cancel failed.');
219
405
  const child = cancelled.ticket.child_session_id;
406
+ if (child)
407
+ closeBudgetWait(child);
220
408
  if (resident && child && options.cancel) {
221
- await options.cancel(child, { keepInbox: note !== '' });
409
+ await options.cancel(child, { keepInbox: note !== '', reason: 'ticket-cancel' });
222
410
  }
223
411
  if (resident && note !== '' && cancelled.input)
224
412
  await pushInput(book, cancelled.input, deps);
225
413
  await removeUnclaimed(owner, cancelled.ticket.id);
414
+ schedulePromote();
226
415
  return {
227
416
  ok: true,
228
417
  ticketId: cancelled.ticket.id,
@@ -244,29 +433,88 @@ export function createWorkRuntime(store, engine, options = {}) {
244
433
  const failed = await store.write('work', () => book.failRunning(found.ticket.id, 'grant-denied'));
245
434
  const child = failed?.child_session_id;
246
435
  const state = child ? arms.get(child) : null;
436
+ if (child)
437
+ closeBudgetWait(child);
247
438
  if (state) {
248
439
  state.closing = true;
249
440
  state.clear?.();
250
441
  }
251
442
  if (resident && child && options.cancel)
252
- await options.cancel(child, { keepInbox: false });
443
+ await options.cancel(child, { keepInbox: false, reason: 'grant-denied' });
444
+ schedulePromote();
253
445
  return { ok: true, ticketId: found.ticket.id, ticketStatus: 'failed', denied: true };
254
446
  }
447
+ const live = found.ticket.child_session_id ? arms.get(found.ticket.child_session_id) : null;
448
+ if (live?.role === 'worker')
449
+ saveQuota(found.ticket.child_session_id, live);
255
450
  const added = await store.write('work', () => book.extendBudget(found.ticket.id, {
256
451
  wallMs: typeof args.wallMs === 'number' ? args.wallMs : undefined,
257
452
  maxTokens: typeof args.maxTokens === 'number' ? args.maxTokens : undefined,
258
453
  }, { wallMs: limits.workerWallMs, maxTokens: limits.workerMaxTokens }));
259
454
  if (added.error)
260
- return toolError(added.error, added.message ?? 'No budget was added.');
455
+ return { ...toolError(added.error, added.message ?? 'No budget was added.'), ...quotaFeedback(found.ticket.id) };
261
456
  const child = added.ticket.child_session_id;
262
457
  if (child)
263
458
  releaseArm(child, added.budget);
459
+ let resumedInput = null;
460
+ const quota = quotaOf(added.ticket.id);
461
+ if (child &&
462
+ !arms.has(child) &&
463
+ quota?.waiting &&
464
+ options.resumePaused &&
465
+ resident &&
466
+ options.push &&
467
+ ['started', 'enqueued'].includes(added.ticket.status) &&
468
+ added.budget.maxTokens > quota.tokens &&
469
+ added.budget.wallMs > quota.activeMs &&
470
+ quota.tokens < limits.workerMaxTokens &&
471
+ quota.activeMs < limits.workerWallMs &&
472
+ !(await isChildLive(child))) {
473
+ resumedInput = await store.write('work', () => {
474
+ const fresh = book.ticket(added.ticket.id);
475
+ if (!fresh ||
476
+ !['started', 'enqueued'].includes(fresh.status) ||
477
+ fresh.active_attempt_id !== added.ticket.active_attempt_id)
478
+ return null;
479
+ const current = quotaOf(fresh.id);
480
+ if (!current?.waiting)
481
+ return null;
482
+ if (current.resumeInputId)
483
+ return book.input(current.resumeInputId);
484
+ // A detached native turn ended (possibly disposed). Advance only the
485
+ // input generation, not the attempt/fence/session, so replay of that
486
+ // old turn/end cannot finalize a new pending result.
487
+ store.db
488
+ .prepare('UPDATE work_tickets SET revision = revision + 1, briefing_revision = briefing_revision + 1, updated_at = ? WHERE id = ?')
489
+ .run(now().toISOString(), fresh.id);
490
+ const input = book.insertInput({
491
+ ticketId: fresh.id,
492
+ attemptId: fresh.active_attempt_id,
493
+ revision: fresh.briefing_revision + 1,
494
+ kind: 'supply',
495
+ text: '[foundations:budget-resume] Budget was explicitly granted. Continue the SAME ticket from durable history; do not repeat completed effects. Inspect current state before continuing. This is a new host turn after detachment, not a new task.',
496
+ });
497
+ writeQuota(fresh.id, { ...current, resumeInputId: input.id });
498
+ return input;
499
+ });
500
+ if (resumedInput)
501
+ await pushInput(book, resumedInput, deps);
502
+ }
264
503
  return {
265
504
  ok: true,
266
505
  ticketId: added.ticket.id,
267
- ticketStatus: added.ticket.status,
506
+ ticketStatus: book.ticket(added.ticket.id)?.status ?? added.ticket.status,
507
+ briefingRevision: book.ticket(added.ticket.id)?.briefing_revision,
268
508
  wallMs: added.budget.wallMs,
269
509
  maxTokens: added.budget.maxTokens,
510
+ hostCeilingTokens: limits.workerMaxTokens,
511
+ hostCeilingWallMs: limits.workerWallMs,
512
+ ...quotaFeedback(added.ticket.id),
513
+ continuation: resumedInput
514
+ ? 'same-session-new-turn'
515
+ : child && arms.has(child)
516
+ ? 'same-turn'
517
+ : 'awaiting-host-turn',
270
518
  };
271
519
  }
272
520
  async function retry(owner, args) {
@@ -276,19 +524,27 @@ export function createWorkRuntime(store, engine, options = {}) {
276
524
  if (found.error)
277
525
  return found.error;
278
526
  const expected = revisionOf(args.expectedRevision);
279
- const retried = await store.write('work', () => book.insertRetry(found.ticket.id, expected));
527
+ const retried = await store.write('work', () => {
528
+ const result = book.insertRetry(found.ticket.id, expected);
529
+ if (result.error)
530
+ return result;
531
+ if (!hasSlot(owner))
532
+ return { ...result, queued: true };
533
+ book.reserveSlot(result.ticket.id);
534
+ return result;
535
+ });
280
536
  if (retried.error)
281
537
  return toolError(retried.error, retried.message ?? 'Retry failed.');
538
+ if (retried.queued) {
539
+ return publicDispatch(book.ticket(retried.ticket.id), {
540
+ flush: 'pending',
541
+ queued: true,
542
+ nativeMessageId: retried.input?.native_message_id ?? null,
543
+ });
544
+ }
282
545
  if (!resident)
283
546
  return { ...publicDispatch(retried.ticket), flush: 'pending', message: 'Only a resident host continues' };
284
- const ensured = await ensureChild(retried.ticket);
285
- if (ensured.error)
286
- return ensured.error;
287
- const flushed = await pushInput(book, retried.input, deps);
288
- return publicDispatch(book.ticket(retried.ticket.id), {
289
- flush: flushWord(flushed),
290
- nativeMessageId: retried.input.native_message_id,
291
- });
547
+ return startReserved(book.ticket(retried.ticket.id));
292
548
  }
293
549
  /**
294
550
  * @param {string} owner
@@ -425,9 +681,9 @@ export function createWorkRuntime(store, engine, options = {}) {
425
681
  async function tick() {
426
682
  await reconcileInputs(book, deps);
427
683
  await reconcileNotices(book, deps);
428
- await store.write('work', () => {
429
- book.expireQuiet();
430
- });
684
+ await renewLiveLeases();
685
+ const expired = await store.write('work', () => book.expireQuiet());
686
+ await stopExpiredChildren(expired);
431
687
  for (const owner of book.ownerIds()) {
432
688
  if (engine.isBot(owner))
433
689
  await admit(owner);
@@ -436,11 +692,137 @@ export function createWorkRuntime(store, engine, options = {}) {
436
692
  await reconcileChild(child);
437
693
  for (const owner of book.ownerIds())
438
694
  await reconcileOwner(owner);
695
+ await promoteQueued();
696
+ }
697
+ /**
698
+ * Renew the lease of a started worker that is still alive, so a silent
699
+ * model or tool turn longer than leaseMs does not false-expire it.
700
+ */
701
+ async function renewLiveLeases() {
702
+ const renewals = [];
703
+ for (const child of book.childIds()) {
704
+ const attempt = book.attemptForChild(child);
705
+ if (!attempt || (attempt.status !== 'started' && attempt.status !== 'enqueued'))
706
+ continue;
707
+ if (!(await isChildLive(child)))
708
+ continue;
709
+ renewals.push(attempt.id);
710
+ }
711
+ if (renewals.length === 0)
712
+ return;
713
+ await store.write('work', () => {
714
+ const until = new Date(now().getTime() + limits.leaseMs).toISOString();
715
+ for (const id of renewals) {
716
+ const attempt = book.attempt(id);
717
+ if (!attempt || (attempt.status !== 'started' && attempt.status !== 'enqueued'))
718
+ continue;
719
+ book.touchLease(id, until, typeof attempt.lease_observed_seq === 'number' ? attempt.lease_observed_seq : null);
720
+ }
721
+ });
722
+ }
723
+ /**
724
+ * @param {string} sessionId
725
+ */
726
+ async function isChildLive(sessionId) {
727
+ if (options.childPresent) {
728
+ try {
729
+ if (!(await options.childPresent(sessionId)))
730
+ return false;
731
+ }
732
+ catch {
733
+ return false;
734
+ }
735
+ }
736
+ else if (!options.snapshot) {
737
+ return false;
738
+ }
739
+ if (!options.snapshot)
740
+ return true;
741
+ try {
742
+ const events = await options.snapshot(sessionId);
743
+ return !latestTurnEnded(events);
744
+ }
745
+ catch {
746
+ return false;
747
+ }
748
+ }
749
+ /**
750
+ * @param {Array<{ ticketId: string, reason: string, childSessionId?: string | null }>} expired
751
+ */
752
+ async function stopExpiredChildren(expired) {
753
+ if (!Array.isArray(expired) || expired.length === 0)
754
+ return;
755
+ for (const item of expired) {
756
+ const child = item.childSessionId;
757
+ if (!child || !options.cancel)
758
+ continue;
759
+ const state = arms.get(child);
760
+ if (state) {
761
+ state.closing = true;
762
+ state.clear?.();
763
+ }
764
+ try {
765
+ await options.cancel(child, { keepInbox: false, reason: `worker-expire:${item.reason}` });
766
+ }
767
+ catch {
768
+ /* best-effort stop; the ledger already failed the ticket */
769
+ }
770
+ }
771
+ }
772
+ /**
773
+ * @param {Record<string, any>} event
774
+ */
775
+ function eventText(event) {
776
+ if (typeof event.text === 'string' && event.text !== '')
777
+ return event.text;
778
+ return book.detail(event.ticket_id)?.events?.find(item => item.event_id === event.event_id)?.text ?? '';
779
+ }
780
+ /**
781
+ * @param {Record<string, any>} event
782
+ */
783
+ function isExtensionAsk(event) {
784
+ return event.kind === 'progress' && eventText(event).startsWith('[foundations:extension]');
785
+ }
786
+ /**
787
+ * Extension asks are decision-required: they may starve-bypass notice-open,
788
+ * user-pending, and delivery-open. Ordinary progress does not.
789
+ * @param {Record<string, any>} event
790
+ */
791
+ function isDecisionRequiredEvent(event) {
792
+ return event.kind === 'question' || event.kind === 'result' || event.kind === 'failure' || isExtensionAsk(event);
793
+ }
794
+ /**
795
+ * @param {Record<string, any>} ticket
796
+ */
797
+ function isFinishedTicket(ticket) {
798
+ const status = String(ticket.status);
799
+ return status === 'failed' || status === 'cancelled' || status === 'delivered';
439
800
  }
440
801
  /**
441
802
  * @param {string} owner
442
803
  */
443
804
  async function admit(owner) {
805
+ if (admitting.has(owner))
806
+ return { admitted: false, reason: 'admission-inflight' };
807
+ admitting.add(owner);
808
+ try {
809
+ return await admitOnce(owner);
810
+ }
811
+ finally {
812
+ admitting.delete(owner);
813
+ }
814
+ }
815
+ function currentExtension(event) {
816
+ const ticket = book.ticket(event.ticket_id);
817
+ if (!ticket || !['started', 'enqueued'].includes(ticket.status))
818
+ return false;
819
+ const budget = JSON.parse(ticket.budget_json);
820
+ if (budget.extension !== 'open')
821
+ return false;
822
+ const latest = book.detail(ticket.id)?.events.filter(isExtensionAsk).at(-1);
823
+ return latest?.event_id === event.event_id;
824
+ }
825
+ async function admitOnce(owner) {
444
826
  const wake = book.pendingWake(owner);
445
827
  if (wake.events.length === 0 && wake.cancels.length === 0)
446
828
  return { admitted: false, reason: 'empty' };
@@ -453,15 +835,17 @@ export function createWorkRuntime(store, engine, options = {}) {
453
835
  }
454
836
  const terminalTimes = [];
455
837
  for (const event of wake.events) {
456
- if ((event.kind === 'question' || event.kind === 'result' || event.kind === 'failure') &&
457
- event.apply_status === 'applied') {
838
+ if (event.apply_status === 'applied' &&
839
+ isDecisionRequiredEvent(event) &&
840
+ (!isExtensionAsk(event) || currentExtension(event))) {
458
841
  terminalTimes.push(Date.parse(event.created_at));
459
842
  }
460
843
  }
461
844
  for (const ticket of wake.cancels)
462
845
  terminalTimes.push(Date.parse(ticket.updated_at));
846
+ const urgent = wake.events.filter(event => isExtensionAsk(event) && currentExtension(event));
463
847
  const heldUntil = holds.get(owner);
464
- if (heldUntil != null && now().getTime() < heldUntil)
848
+ if (!urgent.length && heldUntil != null && now().getTime() < heldUntil)
465
849
  return { admitted: false, reason: 'interrupt-hold' };
466
850
  if (heldUntil != null)
467
851
  holds.delete(owner);
@@ -476,21 +860,24 @@ export function createWorkRuntime(store, engine, options = {}) {
476
860
  terminalSince: terminalTimes.length === 0 ? null : Math.min(...terminalTimes),
477
861
  starveMs: limits.starveMs,
478
862
  });
479
- if (!decision.admit)
863
+ if (!urgent.length && !decision.admit)
480
864
  return { admitted: false, ...decision };
481
865
  const nativeId = randomUUID();
482
866
  const items = [];
483
- for (const event of wake.events) {
867
+ for (const event of urgent.length ? urgent : wake.events) {
484
868
  const ticket = book.ticket(event.ticket_id);
485
869
  if (!ticket)
486
870
  continue;
871
+ // A grant cannot revive a finished ticket, so drop a stale extension ask.
872
+ if (isExtensionAsk(event) && !currentExtension(event))
873
+ continue;
487
874
  items.push({
488
875
  ticketId: ticket.id,
489
876
  eventId: event.event_id,
490
877
  line: noticeLine(ticket, event),
491
878
  });
492
879
  }
493
- for (const ticket of wake.cancels) {
880
+ for (const ticket of urgent.length ? [] : wake.cancels) {
494
881
  items.push({
495
882
  ticketId: ticket.id,
496
883
  eventId: `cancel:${ticket.cancel_requested_revision}`,
@@ -500,10 +887,24 @@ export function createWorkRuntime(store, engine, options = {}) {
500
887
  if (items.length === 0)
501
888
  return { admitted: false, reason: 'empty' };
502
889
  await store.write('work', () => {
503
- book.insertNotices(nativeId, owner, items);
890
+ // Revalidate after the write queue: a grant/cancel may have raced admission.
891
+ const valid = items.filter(item => item.eventId.startsWith('cancel:') ||
892
+ (!book.event(item.eventId)?.notice_id &&
893
+ (!isExtensionAsk(book.event(item.eventId) ?? {}) || currentExtension(book.event(item.eventId)))));
894
+ items.splice(0, items.length, ...valid);
895
+ if (items.length)
896
+ book.insertNotices(nativeId, owner, items);
504
897
  });
898
+ if (!items.length)
899
+ return { admitted: false, reason: 'superseded' };
505
900
  const flushed = await pushNotice(book, nativeId, owner, renderNotice(items.map(item => item.line)), 0, deps);
506
- return { admitted: true, nativeMessageId: nativeId, flush: flushWord(flushed), ...decision };
901
+ return {
902
+ ...decision,
903
+ admitted: true,
904
+ reason: urgent.length ? 'budget-decision' : decision.reason,
905
+ nativeMessageId: nativeId,
906
+ flush: flushWord(flushed),
907
+ };
507
908
  }
508
909
  /**
509
910
  * Progress stays a status line. Result and failure carry the body so the
@@ -516,6 +917,8 @@ export function createWorkRuntime(store, engine, options = {}) {
516
917
  const head = `${ticket.id} ${status} (${LABEL[status] ?? status}) rev ${ticket.briefing_revision} ${event.kind}`;
517
918
  const text = book.detail(ticket.id)?.events?.find(item => item.event_id === event.event_id)?.text ?? '';
518
919
  if (text.startsWith('[foundations:extension]')) {
920
+ if (isFinishedTicket(ticket))
921
+ return head;
519
922
  return [head, `eventId: ${event.event_id}`, text].join('\n');
520
923
  }
521
924
  if (event.kind !== 'result' && event.kind !== 'failure')
@@ -560,8 +963,15 @@ export function createWorkRuntime(store, engine, options = {}) {
560
963
  wakeTurns.set(`${sessionId}:${event.data.turn}`, nativeId);
561
964
  }
562
965
  }
563
- if (event.type === 'turn/end')
966
+ if (event.type === 'turn/end') {
967
+ if (isWorkerSession(sessionId) && event.data?.reason?.reason?.kind === 'user') {
968
+ const attempt = book.attemptForChild(sessionId);
969
+ if (attempt)
970
+ book.markCancelled(attempt.ticket_id, null, 'Worker cancelled by user.');
971
+ closeBudgetWait(sessionId);
972
+ }
564
973
  applyTurnEnd(sessionId, event.data?.turn ?? null, reasonKindOf(event));
974
+ }
565
975
  if (isWorkerSession(sessionId) && typeof event.seq === 'number') {
566
976
  const attempt = book.attemptForChild(sessionId);
567
977
  if (attempt && (attempt.status === 'started' || attempt.status === 'enqueued')) {
@@ -578,6 +988,8 @@ export function createWorkRuntime(store, engine, options = {}) {
578
988
  if (book.inputByNative(messageId))
579
989
  turns.set(sessionId, { messageId, turn, seq: null });
580
990
  book.setNoticeObserve(messageId, 'claimed');
991
+ if (turn != null && book.noticeIds(sessionId).has(messageId))
992
+ wakeTurns.set(`${sessionId}:${turn}`, messageId);
581
993
  }
582
994
  /**
583
995
  * @param {Record<string, any>} ticket
@@ -588,17 +1000,29 @@ export function createWorkRuntime(store, engine, options = {}) {
588
1000
  if (!options.createChild)
589
1001
  return { error: publicDispatch(ticket, { flush: 'pending' }) };
590
1002
  const sessionId = `worker-${ticket.id}`;
1003
+ const attemptId = ticket.active_attempt_id;
1004
+ const fencingToken = book.attempt(attemptId)?.fencing_token ?? 1;
591
1005
  try {
592
1006
  const created = await options.createChild({
593
1007
  sessionId,
594
1008
  ownerSessionId: ticket.owner_session_id,
595
1009
  ticketId: ticket.id,
596
- fencingToken: book.attempt(ticket.active_attempt_id)?.fencing_token ?? 1,
1010
+ fencingToken,
597
1011
  });
598
1012
  const child = typeof created === 'string' && created !== '' ? created : sessionId;
1013
+ const saved = await store.write('work', () => book.setChildIfEmpty(ticket.id, child, { attemptId, fencingToken }));
1014
+ if (!saved?.attached) {
1015
+ try {
1016
+ if (options.cancel)
1017
+ await options.cancel(child, { keepInbox: false, reason: 'stale-start' });
1018
+ }
1019
+ catch {
1020
+ /* best-effort cleanup of a late or fenced child */
1021
+ }
1022
+ return { rejected: true, ticket: saved?.ticket ?? book.ticket(ticket.id) ?? ticket };
1023
+ }
599
1024
  engine.ensureSession(child);
600
- const saved = await store.write('work', () => book.setChildIfEmpty(ticket.id, child));
601
- return { ticket: saved };
1025
+ return { ticket: saved.ticket };
602
1026
  }
603
1027
  catch {
604
1028
  return {
@@ -675,11 +1099,13 @@ export function createWorkRuntime(store, engine, options = {}) {
675
1099
  briefingRevision: fresh.briefing_revision,
676
1100
  status: dispatched && flush === 'accepted' ? 'enqueued' : 'accepted',
677
1101
  ticketStatus: fresh.status,
1102
+ ...quotaFeedback(fresh.id),
678
1103
  childSessionId: extra.childSessionId === null ? null : fresh.child_session_id,
679
1104
  fencingToken: attempt?.fencing_token ?? null,
680
1105
  nativeMessageId: extra.nativeMessageId === undefined ? (input?.native_message_id ?? null) : extra.nativeMessageId,
681
1106
  flush,
682
1107
  replayed: extra.replayed === true,
1108
+ queued: extra.queued === true || (fresh.status === 'accepted' && !book.slotHeld(fresh)),
683
1109
  };
684
1110
  }
685
1111
  function project(ticket) {
@@ -718,6 +1144,7 @@ export function createWorkRuntime(store, engine, options = {}) {
718
1144
  const found = book.detail(input.ticket_id);
719
1145
  if (!found)
720
1146
  return;
1147
+ let released = false;
721
1148
  for (const event of found.events) {
722
1149
  if (event.attempt_id !== input.attempt_id)
723
1150
  continue;
@@ -726,7 +1153,10 @@ export function createWorkRuntime(store, engine, options = {}) {
726
1153
  if (event.apply_status !== 'pending_completion')
727
1154
  continue;
728
1155
  book.applyTerminal(event.event_id, reason);
1156
+ released = true;
729
1157
  }
1158
+ if (released)
1159
+ void promoteQueued().catch(() => { });
730
1160
  }
731
1161
  /**
732
1162
  * @param {string} sessionId
@@ -757,7 +1187,7 @@ export function createWorkRuntime(store, engine, options = {}) {
757
1187
  const nativeId = byTurn.get(event.data?.turn);
758
1188
  if (!nativeId)
759
1189
  continue;
760
- turns.set(sessionId, { messageId: nativeId, turn: event.data?.turn ?? null, seq: null });
1190
+ // Historical turn endings must not overwrite the latest live input binding.
761
1191
  const input = book.inputByNative(nativeId);
762
1192
  if (!input)
763
1193
  continue;
@@ -855,6 +1285,13 @@ export function createWorkRuntime(store, engine, options = {}) {
855
1285
  return;
856
1286
  }
857
1287
  const state = arms.get(sessionId);
1288
+ if (role === 'main' &&
1289
+ state &&
1290
+ (event.type === 'user/message' || event.type === 'agent/inbox/claimed') &&
1291
+ (messageIdOf(event) ?? '').startsWith(BUDGET_NOTICE_PREFIX)) {
1292
+ state.budgetNotice = true;
1293
+ return;
1294
+ }
858
1295
  if (event.type === 'assistant/message' && role === 'worker' && state) {
859
1296
  const seq = typeof event.seq === 'number' ? event.seq : null;
860
1297
  if (seq != null && state.lastSeq != null && seq <= state.lastSeq)
@@ -864,6 +1301,7 @@ export function createWorkRuntime(store, engine, options = {}) {
864
1301
  state.tokens += total;
865
1302
  if (seq != null)
866
1303
  state.lastSeq = seq;
1304
+ saveQuota(sessionId, state);
867
1305
  consider(sessionId, state, false);
868
1306
  }
869
1307
  return;
@@ -873,8 +1311,72 @@ export function createWorkRuntime(store, engine, options = {}) {
873
1311
  const live = state ?? arm(sessionId, event.data?.turn ?? 0, role);
874
1312
  const step = Number(event.data?.step);
875
1313
  live.steps = Number.isFinite(step) ? Math.max(live.steps, step) : live.steps + 1;
876
- if (role === 'main')
877
- consider(sessionId, live, false);
1314
+ // The main step cap is enforced in gateStep (agent/pre-step), before the next
1315
+ // step starts. Cancelling here would abort a turn whose last step already
1316
+ // ended naturally and record it as aborted.
1317
+ }
1318
+ /**
1319
+ * `agent/pre-step` gate for a bot main session. Refuses the next step once the
1320
+ * turn has used its step or wall budget. A turn whose last step ended without
1321
+ * a tool call never reaches this gate, so it still ends `completed`.
1322
+ * Messages claimed for this step (a user steer) always enter: dropping them on
1323
+ * a refusal would lose user input.
1324
+ * @param {string} sessionId
1325
+ * @param {{ turn?: number, step?: number, claimed?: number }} position
1326
+ */
1327
+ function gateStep(sessionId, position = {}) {
1328
+ if (budgetRole(sessionId) !== 'main')
1329
+ return { kind: 'enter' };
1330
+ const state = arms.get(sessionId);
1331
+ if (!state || state.role !== 'main' || state.closing)
1332
+ return { kind: 'enter' };
1333
+ if ((position.claimed ?? 0) > 0)
1334
+ return { kind: 'enter' };
1335
+ const elapsed = Math.max(0, now().getTime() - state.startedAt);
1336
+ const reason = budgetTrip({
1337
+ steps: state.steps,
1338
+ elapsedMs: elapsed,
1339
+ maxSteps: state.limits.maxSteps,
1340
+ wallMs: state.limits.wallMs,
1341
+ });
1342
+ if (reason !== 'steps' && reason !== 'wall')
1343
+ return { kind: 'enter' };
1344
+ const trip = tripMain(sessionId, state, reason, elapsed, 'pre-step');
1345
+ return { kind: 'reject', trip };
1346
+ }
1347
+ /**
1348
+ * Record, log, and announce one main-session budget trip.
1349
+ * @param {string} sessionId
1350
+ * @param {BudgetArm} state
1351
+ * @param {'steps' | 'wall'} reason
1352
+ * @param {number} elapsed
1353
+ * @param {'pre-step' | 'timer'} via
1354
+ */
1355
+ function tripMain(sessionId, state, reason, elapsed, via) {
1356
+ const trip = {
1357
+ reason,
1358
+ cause: `main-budget:${reason}`,
1359
+ turn: state.turn,
1360
+ steps: state.steps,
1361
+ elapsedMs: elapsed,
1362
+ maxSteps: state.limits.maxSteps,
1363
+ wallMs: state.limits.wallMs,
1364
+ via,
1365
+ notify: !state.budgetNotice,
1366
+ };
1367
+ if (state.tripped)
1368
+ return { ...trip, notify: false };
1369
+ state.tripped = true;
1370
+ options.log?.('warn', `session-foundations: main budget ${trip.cause} session=${sessionId} turn=${trip.turn} steps=${trip.steps}/${trip.maxSteps} elapsedMs=${trip.elapsedMs}/${trip.wallMs} via=${via}`, { sessionId, ...trip });
1371
+ if (trip.notify) {
1372
+ try {
1373
+ options.onMainBudget?.(sessionId, trip);
1374
+ }
1375
+ catch {
1376
+ /* the notice is best effort; the log line above stays */
1377
+ }
1378
+ }
1379
+ return trip;
878
1380
  }
879
1381
  /**
880
1382
  * @param {string} sessionId
@@ -906,7 +1408,8 @@ export function createWorkRuntime(store, engine, options = {}) {
906
1408
  return { ok: true };
907
1409
  }
908
1410
  /**
909
- * A dispatch or a host tool leaves the chat budget and uses the short cap.
1411
+ * A dispatch or a host tool moves the turn onto the `main*` cap. The cap can
1412
+ * only tighten: with the defaults (main == chat) this changes nothing.
910
1413
  * @param {string} sessionId
911
1414
  */
912
1415
  function tightenMain(sessionId) {
@@ -914,11 +1417,15 @@ export function createWorkRuntime(store, engine, options = {}) {
914
1417
  if (!state || state.role !== 'main' || state.tight || state.closing || state.tripped)
915
1418
  return;
916
1419
  state.tight = true;
1420
+ const maxSteps = Math.min(state.limits.maxSteps, limits.mainMaxSteps);
1421
+ const wallMs = Math.min(state.limits.wallMs, limits.mainWallMs);
1422
+ if (maxSteps === state.limits.maxSteps && wallMs === state.limits.wallMs)
1423
+ return;
917
1424
  state.limits = {
918
1425
  ...state.limits,
919
- maxSteps: limits.mainMaxSteps,
920
- wallMs: limits.mainWallMs,
921
- ceilingWall: limits.mainWallMs,
1426
+ maxSteps,
1427
+ wallMs,
1428
+ ceilingWall: wallMs,
922
1429
  };
923
1430
  state.clear?.();
924
1431
  const elapsed = Math.max(0, now().getTime() - state.startedAt);
@@ -949,29 +1456,50 @@ export function createWorkRuntime(store, engine, options = {}) {
949
1456
  }
950
1457
  : workerCaps(sessionId);
951
1458
  const state = {
1459
+ attemptId: role === 'worker' ? (book.attemptForChild(sessionId)?.id ?? null) : null,
952
1460
  turn,
953
- startedAt: previous?.startedAt ?? now().getTime(),
1461
+ startedAt: role === 'worker' ? now().getTime() : (previous?.startedAt ?? now().getTime()),
954
1462
  steps: 0,
955
- tokens: previous?.tokens ?? 0,
956
- lastSeq: previous?.lastSeq ?? null,
1463
+ tokens: role === 'worker' ? 0 : (previous?.tokens ?? 0),
1464
+ lastSeq: role === 'worker' ? null : (previous?.lastSeq ?? null),
957
1465
  role,
958
1466
  tight: false,
959
1467
  limits: caps,
960
1468
  tripped: false,
1469
+ budgetNotice: false,
961
1470
  extensionOpen: false,
962
1471
  closing: false,
1472
+ pausedAt: null,
1473
+ atBoundary: false,
963
1474
  clear: () => { },
964
1475
  };
965
- const elapsed = Math.max(0, now().getTime() - state.startedAt);
1476
+ if (role === 'worker') {
1477
+ const attempt = book.attemptForChild(sessionId);
1478
+ const quota = attempt ? quotaOf(attempt.ticket_id) : null;
1479
+ if (quota) {
1480
+ state.tokens = quota.tokens ?? 0;
1481
+ state.lastSeq = quota.lastSeq ?? null;
1482
+ const elapsed = (quota.activeMs ?? 0) + (quota.runningSince == null ? 0 : Math.max(0, now().getTime() - quota.runningSince));
1483
+ state.startedAt = now().getTime() - elapsed;
1484
+ if (quota.waiting) {
1485
+ state.pausedAt = now().getTime();
1486
+ state.atBoundary = true;
1487
+ }
1488
+ }
1489
+ }
1490
+ const elapsed = Math.max(0, (state.pausedAt != null && state.atBoundary ? state.pausedAt : now().getTime()) - state.startedAt);
966
1491
  state.extensionOpen = previous?.extensionOpen === true || caps.extensionOpen === true;
967
- const target = state.extensionOpen ? caps.ceilingWall : caps.wallMs;
968
- state.clear = schedule(() => {
969
- const live = arms.get(sessionId);
970
- if (!live || live !== state || live.closing)
971
- return;
972
- consider(sessionId, live, true);
973
- }, Math.max(1, target - elapsed));
1492
+ const target = caps.wallMs;
1493
+ if (state.pausedAt == null)
1494
+ state.clear = schedule(() => {
1495
+ const live = arms.get(sessionId);
1496
+ if (!live || live !== state || live.closing)
1497
+ return;
1498
+ consider(sessionId, live, true);
1499
+ }, Math.max(1, target - elapsed));
974
1500
  arms.set(sessionId, state);
1501
+ if (role === 'worker')
1502
+ saveQuota(sessionId, state);
975
1503
  return state;
976
1504
  }
977
1505
  /**
@@ -1014,39 +1542,24 @@ export function createWorkRuntime(store, engine, options = {}) {
1014
1542
  if (state.closing)
1015
1543
  return;
1016
1544
  if (state.role === 'main') {
1017
- const elapsed = fromTimer ? state.limits.wallMs : now().getTime() - state.startedAt;
1018
- const reason = budgetTrip({
1019
- steps: state.steps,
1020
- elapsedMs: elapsed,
1021
- maxSteps: state.limits.maxSteps,
1022
- wallMs: state.limits.wallMs,
1023
- });
1024
- if (!reason || state.tripped)
1545
+ // Step caps are enforced by gateStep before the next step. Only the wall
1546
+ // timer stops a step that is still running; the arm is cleared on
1547
+ // turn/end, so a finished turn is never cancelled here.
1548
+ if (!fromTimer || state.tripped)
1025
1549
  return;
1026
- state.tripped = true;
1027
- Promise.resolve(options.cancel?.(sessionId, { keepInbox: true })).catch(() => { });
1028
- return;
1029
- }
1030
- const elapsed = Math.max(0, now().getTime() - state.startedAt);
1031
- if (state.tokens >= state.limits.ceilingTokens || elapsed >= state.limits.ceilingWall) {
1032
- finishWorker(sessionId, state, state.tokens >= state.limits.ceilingTokens && elapsed < state.limits.ceilingWall ? 'tokens' : 'wall');
1550
+ const elapsed = Math.max(state.limits.wallMs, now().getTime() - state.startedAt);
1551
+ const trip = tripMain(sessionId, state, 'wall', elapsed, 'timer');
1552
+ Promise.resolve(options.cancel?.(sessionId, { keepInbox: true, reason: trip.cause })).catch(() => { });
1033
1553
  return;
1034
1554
  }
1035
- if (state.extensionOpen)
1555
+ if (state.pausedAt != null)
1036
1556
  return;
1557
+ const elapsed = Math.max(0, now().getTime() - state.startedAt);
1037
1558
  const overWall = fromTimer || elapsed >= state.limits.wallMs;
1038
1559
  const overTokens = state.tokens >= state.limits.maxTokens;
1039
1560
  if (!overWall && !overTokens)
1040
1561
  return;
1041
- if (overWall && state.limits.wallMs < state.limits.ceilingWall) {
1042
- askForQuota(sessionId, state, 'wall', elapsed);
1043
- return;
1044
- }
1045
- if (overTokens && state.limits.maxTokens < state.limits.ceilingTokens) {
1046
- askForQuota(sessionId, state, 'tokens', elapsed);
1047
- return;
1048
- }
1049
- finishWorker(sessionId, state, overTokens ? 'tokens' : 'wall');
1562
+ askForQuota(sessionId, state, overTokens ? 'tokens' : 'wall', elapsed);
1050
1563
  }
1051
1564
  /**
1052
1565
  * @param {string} sessionId
@@ -1057,13 +1570,15 @@ export function createWorkRuntime(store, engine, options = {}) {
1057
1570
  function askForQuota(sessionId, state, reason, elapsed) {
1058
1571
  state.extensionOpen = true;
1059
1572
  state.clear?.();
1060
- watchHostCeiling(sessionId, state);
1573
+ state.pausedAt = now().getTime();
1574
+ state.atBoundary = false;
1575
+ saveQuota(sessionId, state, reason);
1061
1576
  const attempt = book.attemptForChild(sessionId);
1062
1577
  if (!attempt)
1063
1578
  return;
1064
1579
  const ticket = book.ticket(attempt.ticket_id);
1065
1580
  if (!ticket || ticket.status === 'failed' || ticket.status === 'cancelled' || ticket.status === 'delivered') {
1066
- finishWorker(sessionId, state, reason);
1581
+ closeBudgetWait(sessionId);
1067
1582
  return;
1068
1583
  }
1069
1584
  const marked = book.markExtensionOpen(ticket.id);
@@ -1076,7 +1591,10 @@ export function createWorkRuntime(store, engine, options = {}) {
1076
1591
  `granted wall ms: ${state.limits.wallMs}`,
1077
1592
  `tokens used: ${state.tokens}`,
1078
1593
  `granted tokens: ${state.limits.maxTokens}`,
1079
- 'Do not mark the ticket failed. Call foundations_grant to add budget. wallMs and maxTokens are amounts to add. Pass deny=true to refuse the grant.',
1594
+ `host ceiling tokens: ${state.limits.ceilingTokens}; host ceiling active wall ms: ${state.limits.ceilingWall}`,
1595
+ `required total tokens: ${state.tokens + 1}; required total active wall ms: ${elapsed + 1}`,
1596
+ 'Worker is waiting for budget at the next safe loop boundary. It will not dispatch another step until sufficient budget is granted. Budget wait does not expire.',
1597
+ 'Call foundations_grant with amounts to ADD, sufficient to exceed current cumulative usage. Host ceilings cannot be raised by this tool; at a host ceiling an explicit deny/cancel is required. Pass deny=true to stop. Do not redispatch a replacement ticket.',
1080
1598
  ].join('\n');
1081
1599
  book.insertEvent({
1082
1600
  ticketId: ticket.id,
@@ -1088,74 +1606,192 @@ export function createWorkRuntime(store, engine, options = {}) {
1088
1606
  applyStatus: 'applied',
1089
1607
  });
1090
1608
  }
1091
- /**
1092
- * After a quota request, the worker keeps running until the host ceiling.
1093
- * An early timer is rearmed. It does not fail the ticket by itself.
1094
- * @param {string} sessionId
1095
- * @param {{ startedAt: number, limits: { ceilingWall: number }, closing: boolean, clear: () => void }} state
1096
- */
1097
- function watchHostCeiling(sessionId, state) {
1098
- const elapsed = Math.max(0, now().getTime() - state.startedAt);
1099
- state.clear = schedule(() => {
1100
- const live = arms.get(sessionId);
1101
- if (!live || live !== state || live.closing)
1102
- return;
1103
- const at = Math.max(0, now().getTime() - live.startedAt);
1104
- if (at >= live.limits.ceilingWall) {
1105
- finishWorker(sessionId, live, 'wall');
1106
- return;
1107
- }
1108
- watchHostCeiling(sessionId, live);
1109
- }, Math.max(1000, state.limits.ceilingWall - elapsed));
1110
- }
1111
- /**
1112
- * @param {string} sessionId
1113
- * @param {{ closing: boolean, clear: () => void }} state
1114
- * @param {string} reason
1115
- */
1116
- function finishWorker(sessionId, state, reason) {
1117
- if (state.closing)
1118
- return;
1119
- state.closing = true;
1120
- state.clear?.();
1121
- Promise.resolve(options.cancel?.(sessionId, { keepInbox: false })).catch(() => { });
1122
- const attempt = book.attemptForChild(sessionId);
1123
- if (attempt)
1124
- book.failRunning(attempt.ticket_id, reason);
1125
- }
1126
1609
  /**
1127
1610
  * @param {string} sessionId
1128
1611
  * @param {{ wallMs: number, maxTokens: number }} budget
1129
1612
  */
1130
1613
  function releaseArm(sessionId, budget) {
1131
1614
  const state = arms.get(sessionId);
1132
- if (!state || state.role !== 'worker' || state.closing)
1615
+ const attempt = book.attemptForChild(sessionId);
1616
+ if (!attempt)
1133
1617
  return;
1134
- state.extensionOpen = false;
1618
+ const quota = quotaOf(attempt.ticket_id);
1619
+ if (!state || state.role !== 'worker' || state.closing) {
1620
+ // A detached turn stays parked until the grant path queues a durable continuation.
1621
+ if (quota)
1622
+ writeQuota(attempt.ticket_id, { ...quota, waiting: true, runningSince: null });
1623
+ return;
1624
+ }
1135
1625
  state.limits.wallMs = budget.wallMs;
1136
1626
  state.limits.maxTokens = budget.maxTokens;
1627
+ const elapsed = Math.max(0, (state.pausedAt != null && state.atBoundary ? state.pausedAt : now().getTime()) - state.startedAt);
1628
+ if (state.tokens >= budget.maxTokens ||
1629
+ elapsed >= budget.wallMs ||
1630
+ state.tokens >= state.limits.ceilingTokens ||
1631
+ elapsed >= state.limits.ceilingWall) {
1632
+ state.extensionOpen = true;
1633
+ if (state.pausedAt == null)
1634
+ state.pausedAt = now().getTime();
1635
+ state.clear();
1636
+ saveQuota(sessionId, state);
1637
+ book.markExtensionOpen(attempt.ticket_id);
1638
+ return;
1639
+ }
1640
+ state.extensionOpen = false;
1641
+ state.startedAt = now().getTime() - elapsed;
1642
+ state.pausedAt = null;
1643
+ state.atBoundary = false;
1137
1644
  state.clear?.();
1138
- const elapsed = Math.max(0, now().getTime() - state.startedAt);
1645
+ saveQuota(sessionId, state);
1139
1646
  state.clear = schedule(() => {
1140
- const live = arms.get(sessionId);
1141
- if (!live || live !== state || live.closing)
1142
- return;
1143
- consider(sessionId, live, true);
1647
+ if (arms.get(sessionId) === state && !state.closing)
1648
+ consider(sessionId, state, true);
1144
1649
  }, Math.max(1, budget.wallMs - elapsed));
1145
- if (state.tokens >= budget.maxTokens || elapsed >= budget.wallMs)
1146
- consider(sessionId, state, false);
1650
+ for (const resolve of budgetWaiters.get(sessionId) ?? [])
1651
+ resolve(true);
1652
+ budgetWaiters.delete(sessionId);
1653
+ }
1654
+ function quotaOf(ticketId) {
1655
+ try {
1656
+ return JSON.parse(book.ticket(ticketId)?.budget_json ?? '{}').quota ?? null;
1657
+ }
1658
+ catch {
1659
+ return null;
1660
+ }
1661
+ }
1662
+ function writeQuota(ticketId, quota) {
1663
+ const ticket = book.ticket(ticketId);
1664
+ if (!ticket)
1665
+ return;
1666
+ const budget = JSON.parse(ticket.budget_json);
1667
+ budget.quota = quota;
1668
+ store.db
1669
+ .prepare('UPDATE work_tickets SET budget_json = ?, updated_at = ? WHERE id = ?')
1670
+ .run(JSON.stringify(budget), now().toISOString(), ticketId);
1671
+ }
1672
+ function saveQuota(sessionId, state, reason) {
1673
+ const attempt = book.attemptForChild(sessionId);
1674
+ if (!attempt || attempt.id !== state.attemptId)
1675
+ return;
1676
+ const activeMs = Math.max(0, (state.pausedAt != null && state.atBoundary ? state.pausedAt : now().getTime()) - state.startedAt);
1677
+ writeQuota(attempt.ticket_id, {
1678
+ tokens: state.tokens,
1679
+ lastSeq: state.lastSeq,
1680
+ activeMs,
1681
+ runningSince: state.pausedAt == null ? now().getTime() : null,
1682
+ waiting: state.pausedAt != null,
1683
+ phase: state.atBoundary ? 'waiting' : 'requested',
1684
+ reason: state.pausedAt == null
1685
+ ? undefined
1686
+ : state.tokens >= state.limits.ceilingTokens || activeMs >= state.limits.ceilingWall
1687
+ ? 'host-ceiling'
1688
+ : (reason ?? quotaOf(attempt.ticket_id)?.reason),
1689
+ });
1690
+ }
1691
+ function quotaFeedback(ticketId) {
1692
+ const quota = quotaOf(ticketId);
1693
+ const budget = JSON.parse(book.ticket(ticketId)?.budget_json ?? '{}');
1694
+ return {
1695
+ waitingBudget: quota?.waiting === true,
1696
+ budgetReason: quota?.reason ?? null,
1697
+ usedTokens: quota?.tokens ?? 0,
1698
+ activeElapsedMs: quota?.activeMs ?? 0,
1699
+ requiredMaxTokens: (quota?.tokens ?? 0) + 1,
1700
+ requiredWallMs: (quota?.activeMs ?? 0) + 1,
1701
+ minimumAdditionalTokens: Math.max(0, (quota?.tokens ?? 0) + 1 - (budget.maxTokens ?? 0)),
1702
+ minimumAdditionalWallMs: Math.max(0, (quota?.activeMs ?? 0) + 1 - (budget.wallMs ?? 0)),
1703
+ hostTokenHeadroom: Math.max(0, limits.workerMaxTokens - (quota?.tokens ?? 0)),
1704
+ hostWallHeadroomMs: Math.max(0, limits.workerWallMs - (quota?.activeMs ?? 0)),
1705
+ };
1706
+ }
1707
+ function closeBudgetWait(sessionId) {
1708
+ const state = arms.get(sessionId);
1709
+ if (state) {
1710
+ state.closing = true;
1711
+ state.clear();
1712
+ }
1713
+ for (const resolve of budgetWaiters.get(sessionId) ?? [])
1714
+ resolve(false);
1715
+ budgetWaiters.delete(sessionId);
1716
+ }
1717
+ /** Awaiting this official pre-step waterfall suspends admission, not the turn. */
1718
+ async function waitForBudget(sessionId, signal) {
1719
+ if (!isWorkerSession(sessionId))
1720
+ return true;
1721
+ const attempt = book.attemptForChild(sessionId);
1722
+ const ticket = attempt ? book.ticket(attempt.ticket_id) : null;
1723
+ if (!ticket || isFinishedTicket(ticket) || signal?.aborted)
1724
+ return false;
1725
+ const state = arms.get(sessionId) ?? arm(sessionId, 0, 'worker');
1726
+ if (state.closing)
1727
+ return false;
1728
+ consider(sessionId, state, false);
1729
+ if (state.pausedAt == null)
1730
+ return true;
1731
+ if (!state.atBoundary) {
1732
+ // The already-admitted request/tool batch may finish; account for that
1733
+ // active time before freezing the clock at this safe loop boundary.
1734
+ state.pausedAt = now().getTime();
1735
+ state.atBoundary = true;
1736
+ saveQuota(sessionId, state);
1737
+ }
1738
+ const caps = workerCaps(sessionId);
1739
+ releaseArm(sessionId, caps);
1740
+ if (state.pausedAt == null)
1741
+ return true;
1742
+ return new Promise(resolve => {
1743
+ const waiters = budgetWaiters.get(sessionId) ?? new Set();
1744
+ const done = (allowed) => {
1745
+ signal?.removeEventListener('abort', aborted);
1746
+ waiters.delete(done);
1747
+ if (!waiters.size)
1748
+ budgetWaiters.delete(sessionId);
1749
+ resolve(allowed);
1750
+ };
1751
+ const aborted = () => done(false);
1752
+ waiters.add(done);
1753
+ budgetWaiters.set(sessionId, waiters);
1754
+ signal?.addEventListener('abort', aborted, { once: true });
1755
+ if (signal?.aborted)
1756
+ done(false);
1757
+ });
1147
1758
  }
1148
1759
  /**
1149
1760
  * @param {string} sessionId
1150
1761
  */
1151
1762
  function clearBudget(sessionId) {
1152
1763
  const state = arms.get(sessionId);
1764
+ if (state?.role === 'worker')
1765
+ saveQuota(sessionId, state);
1153
1766
  if (!state)
1154
1767
  return;
1155
1768
  state.clear?.();
1156
1769
  arms.delete(sessionId);
1157
1770
  }
1158
1771
  }
1772
+ /**
1773
+ * A later turn/end for every started turn means the child is idle.
1774
+ * No turn at all, or an open turn, means it may still be running.
1775
+ * @param {Array<Record<string, any>>} events
1776
+ */
1777
+ function latestTurnEnded(events) {
1778
+ const open = new Set();
1779
+ let sawTurn = false;
1780
+ for (const event of events) {
1781
+ const turn = event.data?.turn;
1782
+ if (turn == null)
1783
+ continue;
1784
+ if (event.type === 'turn/start' || event.type === 'user/message') {
1785
+ sawTurn = true;
1786
+ open.add(turn);
1787
+ }
1788
+ else if (event.type === 'turn/end') {
1789
+ sawTurn = true;
1790
+ open.delete(turn);
1791
+ }
1792
+ }
1793
+ return sawTurn && open.size === 0;
1794
+ }
1159
1795
  /**
1160
1796
  * @param {unknown} value
1161
1797
  */