gcf-board 0.21.0 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -16,7 +16,8 @@ import { briefError, runCli } from './cli.js';
16
16
  import { alive, broadcast } from './events.js';
17
17
  import { HttpError } from './http-error.js';
18
18
  import { homeDir } from './registry.js';
19
- import { askUsage } from './usage.js';
19
+ import { accountSettings, lastReading, reserveOfReading } from 'gcf-session';
20
+ import { askUsage, needUsageWhen, onUsageRead } from './usage.js';
20
21
  // The source runs relay.ts, the package its build beside this file.
21
22
  const RELAY = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? 'relay.ts' : 'relay.js', import.meta.url));
22
23
  const flightsDir = () => path.join(homeDir(), 'runs');
@@ -28,8 +29,26 @@ const BEAT_STALE_MS = 90_000;
28
29
  // A board that stops leaves its runs going: killing one would lose its integrate step.
29
30
  const active = new Set();
30
31
  const queues = new Map();
32
+ // The projects whose folder a click build holds: a run now would only be refused, and a refused
33
+ // run stalls the queue and turns the autopilot off. They wait for it instead.
34
+ const clickBuilds = new Set();
35
+ /** Run a click build with the project's runs held back; they go when it ends. */
36
+ export async function whileClickBuilds(p, build) {
37
+ clickBuilds.add(p.name);
38
+ try {
39
+ return await build();
40
+ }
41
+ finally {
42
+ clickBuilds.delete(p.name);
43
+ advance(p.name);
44
+ setImmediate(() => void pilot(p.name));
45
+ }
46
+ }
31
47
  // Projects whose queue waits after a failure the next run would repeat (`stalled`).
32
48
  const paused = new Set();
49
+ // The projects the operator holds (Hold-Plan d20): no queued or autopilot run starts; the
50
+ // operator's own Run goes at once. Apart from `paused`: Release resumes the queue, nothing else.
51
+ const projectHolds = new Set();
33
52
  // The paused projects whose pause the usage limit set: a run that ended paused by it (AD-19).
34
53
  const limitPaused = new Set();
35
54
  // When the usage limit that paused a project's queue resets, ISO; none when it was not one.
@@ -66,6 +85,7 @@ function save() {
66
85
  const names = new Set([
67
86
  ...queues.keys(),
68
87
  ...paused,
88
+ ...projectHolds,
69
89
  ...reports.keys(),
70
90
  ...acts.keys(),
71
91
  ...pilots.keys(),
@@ -77,8 +97,11 @@ function save() {
77
97
  continue;
78
98
  projects[name] = {
79
99
  path: where,
80
- queue: (queues.get(name) ?? []).map(({ entry: _e, p: _p, ...q }) => q),
81
- paused_by: runsOf(name).paused_by,
100
+ // `waiting` stays behind: a board started again tries it, the dependency may have ended.
101
+ queue: (queues.get(name) ?? []).map(({ entry: _e, p: _p, waiting: _w, ...q }) => q),
102
+ // The queue's own pause; the hold beside it, so a restart keeps both.
103
+ paused_by: paused.has(name) ? (limitPaused.has(name) ? 'limit' : 'failure') : null,
104
+ held: projectHolds.has(name),
82
105
  paused_until: pausedUntil.get(name) ?? null,
83
106
  reports: reports.get(name) ?? [],
84
107
  acts: acts.get(name) ?? [],
@@ -179,6 +202,7 @@ function queuedOf(v) {
179
202
  harness: v.harness,
180
203
  ...(v.fresh === true ? { fresh: true } : {}),
181
204
  ...(v.waitLimit === true ? { waitLimit: true } : {}),
205
+ ...(typeof v.waited === 'string' ? { waited: v.waited } : {}),
182
206
  ...(agent ? { agent } : {}),
183
207
  };
184
208
  }
@@ -207,6 +231,8 @@ function restore(entry, p) {
207
231
  queues.set(p.name, queue.map((q) => ({ ...q, entry, p })));
208
232
  if (s.paused_by === 'limit' || s.paused_by === 'failure')
209
233
  paused.add(p.name);
234
+ if (s.paused_by === 'hold' || s.held === true)
235
+ projectHolds.add(p.name);
210
236
  if (s.paused_by === 'limit')
211
237
  limitPaused.add(p.name);
212
238
  const until = s.paused_by === 'limit' ? s.paused_until : null;
@@ -236,13 +262,15 @@ export function runsOf(project) {
236
262
  queued: (queues.get(project) ?? []).flatMap((q) => q.ids),
237
263
  // The pick a queued item goes with, by its id: only the ones that have one.
238
264
  queued_with: Object.fromEntries((queues.get(project) ?? []).flatMap((q) => q.agent && (q.agent.model || q.agent.effort) ? q.ids.map((id) => [id, q.agent]) : [])),
239
- paused: paused.has(project),
240
- // Why it waits: a run the usage limit ended paused, or a failure; the operator resumes it.
241
- paused_by: (paused.has(project)
242
- ? limitPaused.has(project)
243
- ? 'limit'
244
- : 'failure'
245
- : null),
265
+ paused: paused.has(project) || projectHolds.has(project),
266
+ // Why it waits: the operator's hold, a run the usage limit ended paused, or a failure.
267
+ paused_by: (projectHolds.has(project)
268
+ ? 'hold'
269
+ : paused.has(project)
270
+ ? limitPaused.has(project)
271
+ ? 'limit'
272
+ : 'failure'
273
+ : null),
246
274
  // When the usage limit that paused it resets, ISO: none for a pause of another kind.
247
275
  paused_until: paused.has(project) ? (pausedUntil.get(project) ?? null) : null,
248
276
  reports: reports.get(project) ?? [],
@@ -256,6 +284,7 @@ export function forgetProject(project) {
256
284
  forgotten.add(r);
257
285
  queues.delete(project);
258
286
  paused.delete(project);
287
+ projectHolds.delete(project);
259
288
  limitPaused.delete(project);
260
289
  pausedUntil.delete(project);
261
290
  reports.delete(project);
@@ -297,14 +326,138 @@ function limited(run, result) {
297
326
  function advance(project) {
298
327
  if (adopting.has(project))
299
328
  return;
300
- if (paused.has(project) || activeRuns(project).some((r) => r.mode === 'main'))
329
+ if (paused.has(project) || projectHolds.has(project) || clickBuilds.has(project))
330
+ return;
331
+ if (activeRuns(project).some((r) => r.mode === 'main'))
332
+ return;
333
+ const queue = queues.get(project) ?? [];
334
+ const at = queue.findIndex((q) => !q.waiting);
335
+ if (at < 0)
301
336
  return;
302
- const next = queues.get(project)?.shift();
303
- if (!next)
337
+ // The quota at its reserve: the queue waits for a reading under it (Hold-Plan d11).
338
+ const reserve = reserveStand(project);
339
+ if (reserve) {
340
+ if (!reserveWaits.has(project))
341
+ trace(project, 'queue-reserve', reserve.text);
342
+ reserveWaits.add(project);
304
343
  return;
344
+ }
345
+ reserveWaits.delete(project);
346
+ const [next] = queue.splice(at, 1);
305
347
  trace(project, 'queue-run', `the queue starts ${next.ids.join(', ')}`);
306
348
  // Nobody clicked it now: it waits while the usage limit's reset is ahead.
307
- spawnRun({ ...next, waitLimit: true }, next.mode);
349
+ spawnRun({ ...next, waitLimit: true, queued: true }, next.mode);
350
+ }
351
+ // The projects a run reported stopped by the reserve: the board does not know the run's model,
352
+ // so it judges every model's week until a reading under the reserve in all (Codex review).
353
+ const reserveStrict = new Set();
354
+ // The projects whose queue waits on the quota's reserve: a new reading wakes them.
355
+ const reserveWaits = new Set();
356
+ /**
357
+ * Why automation stands on the quota's reserve, by the account's last reading (Hold-Plan d10,
358
+ * d11): the 5-hour window's wait or the week's stop; null to go, as with no reading.
359
+ */
360
+ function reserveStand(project) {
361
+ const strict = reserveStrict.has(project);
362
+ const reading = lastReading();
363
+ // A run said the reserve stops it: no reading, or a failed one, tells the board nothing new.
364
+ if (strict && (!reading || reading.failed))
365
+ return { kind: 'limit', text: reserveText({ weekly: true }) };
366
+ const model = strict ? '*' : null;
367
+ const d = reserveOfReading(reading, model, accountSettings().quota_reserve_pct);
368
+ if ('go' in d) {
369
+ reserveStrict.delete(project);
370
+ return null;
371
+ }
372
+ return {
373
+ kind: 'limit',
374
+ text: reserveText('stop' in d ? d.reserve : { until: d.until.toISOString() }),
375
+ };
376
+ }
377
+ /**
378
+ * A queued run the reserve stopped (Codex review): its held items go back to the queue's head
379
+ * and the queue waits as the autopilot does, so it is not drained run after refused run.
380
+ */
381
+ function requeueReserved(q, result) {
382
+ const held = (result?.items ?? []).filter((i) => i.held === 'reserve').map((i) => i.id);
383
+ if (!q.queued || !held.length)
384
+ return;
385
+ const project = q.p.name;
386
+ reserveStrict.add(project);
387
+ reserveWaits.add(project);
388
+ const { waitLimit: _w, queued: _q, pilot: _p, ...back } = q;
389
+ queues.set(project, [{ ...back, ids: held }, ...(queues.get(project) ?? [])]);
390
+ trace(project, 'queue-reserve', `${held.join(', ')} back in the queue: the quota is at its reserve`);
391
+ }
392
+ /** A reading came: the queues and the autopilots the reserve held look again. */
393
+ export function reserveRead() {
394
+ for (const project of [...reserveWaits])
395
+ advance(project);
396
+ for (const [project, s] of pilots)
397
+ if (s.on && s.stop?.kind === 'limit')
398
+ void pilot(project);
399
+ }
400
+ onUsageRead(reserveRead);
401
+ // The reserve needs readings with no page open: a standing automation waits for them (d11).
402
+ needUsageWhen(() => reserveWaits.size > 0 || [...pilots.values()].some((s) => s.on && s.stop?.kind === 'limit'));
403
+ /** What waits on a dependency is tried again; whether anything did. */
404
+ function clearWaiting(project) {
405
+ const queue = queues.get(project) ?? [];
406
+ const any = queue.some((q) => q.waiting);
407
+ for (const q of queue)
408
+ delete q.waiting;
409
+ return any;
410
+ }
411
+ /**
412
+ * Something may have ended a dependency with no run of this board: a move, an edit of `depends`.
413
+ * shortcut: a console's move is seen at the next run's end or restart; watch `gcf/` if one bites.
414
+ */
415
+ export function retryWaiting(project) {
416
+ if (clearWaiting(project))
417
+ advance(project);
418
+ }
419
+ /**
420
+ * The queue's run the gate refused on a dependency not done: that card stays at the queue's head,
421
+ * passed over until something may have ended it, the rest of its batch goes on. No failure: the
422
+ * queue does not pause.
423
+ */
424
+ function keepWaiting(q, waits, gate) {
425
+ const { queued: _queued, ...entry } = q;
426
+ const others = q.ids.filter((id) => id !== waits.id);
427
+ queues.set(q.p.name, [
428
+ { ...entry, ids: [waits.id], waiting: true, waited: gate },
429
+ ...(others.length ? [{ ...entry, ids: others, waited: undefined }] : []),
430
+ ...(queues.get(q.p.name) ?? []),
431
+ ]);
432
+ }
433
+ /**
434
+ * The operator holds the project, or releases it (Hold-Plan d20): the harness keeps the mark
435
+ * (`gcf-harness hold --project`), so its runs' sessions hand over; the autopilot goes off; the
436
+ * queue waits. Release lifts the hold and resumes the queue; the autopilot stays off.
437
+ */
438
+ export async function holdProject(entry, p, harness, on) {
439
+ const args = [harness, 'hold', '--project', ...(on ? [] : ['--release'])];
440
+ const r = await runCli(entry, p.path, args);
441
+ if (!r.ok)
442
+ throw new Error(`${harness} hold: ${briefError(r.err || r.out)}`);
443
+ paths.set(p.name, p.path);
444
+ if (on) {
445
+ projectHolds.add(p.name);
446
+ const s = pilots.get(p.name);
447
+ if (s?.on)
448
+ s.on = false;
449
+ trace(p.name, 'project-held', 'the operator held the project');
450
+ }
451
+ else {
452
+ projectHolds.delete(p.name);
453
+ trace(p.name, 'project-released', 'the operator released the project');
454
+ // Release lifts the hold, nothing else: a pause for a failure or the limit stays (review 6).
455
+ clearWaiting(p.name);
456
+ advance(p.name);
457
+ }
458
+ save();
459
+ changed(p.name);
460
+ return runsOf(p.name);
308
461
  }
309
462
  /** The operator resumes a paused queue (after fixing what stopped it). */
310
463
  export function resumeQueue(project) {
@@ -313,6 +466,7 @@ export function resumeQueue(project) {
313
466
  paused.delete(project);
314
467
  limitPaused.delete(project);
315
468
  pausedUntil.delete(project);
469
+ clearWaiting(project);
316
470
  advance(project);
317
471
  changed(project);
318
472
  }
@@ -375,9 +529,10 @@ function spawnRun(q, mode) {
375
529
  // The board says where it goes: it queued it by that mode (an item's own, the run's pick). A
376
530
  // card session works the main checkout too, with no item yet.
377
531
  const args = q.kind === 'card'
378
- ? [entry, harness, 'card', ...ids, '--json']
532
+ ? [entry, harness, 'card', ...ids, '--json', ...(q.waitLimit ? ['--wait-limit'] : [])]
379
533
  : [entry, harness, 'run', ...ids, '--json', '--mode', mode];
380
- // A card session takes none of a run's flags: `gcf-harness card` knows only --agent, --json.
534
+ // A card session takes none of a run's flags: `gcf-harness card` knows --agent, --json and,
535
+ // for the autopilot, --wait-limit (Hold-Plan d11).
381
536
  if (q.kind !== 'card') {
382
537
  if (q.fresh)
383
538
  args.push('--fresh');
@@ -415,6 +570,8 @@ function spawnRun(q, mode) {
415
570
  effort,
416
571
  ...(q.kind ? { kind: q.kind } : {}),
417
572
  ...(q.pilot ? { pilot: true } : {}),
573
+ ...(q.queued ? { queued: true } : {}),
574
+ ...(q.waited ? { waited: q.waited } : {}),
418
575
  };
419
576
  try {
420
577
  if (relay.pid) {
@@ -485,16 +642,28 @@ function land(q, run, rid, live, message = '') {
485
642
  message = "the run's relay ended without a result";
486
643
  // A run of a project removed meanwhile only reports: it pauses nothing.
487
644
  const kept = !forgotten.has(run);
645
+ if (kept)
646
+ requeueReserved(q, result);
488
647
  const stop = kept && mode === 'main' && queues.get(p.name)?.length && stalled(ok, result);
489
648
  if (stop) {
490
649
  paused.add(p.name);
491
650
  limitPaused.delete(p.name);
492
651
  pausedUntil.delete(p.name);
493
652
  }
653
+ // A dependency not done: the queue's card stays. Any other end may have done it.
654
+ const waits = kept && q.queued ? result?.waits : undefined;
655
+ const sameWords = Boolean(waits) && q.waited === result?.gate;
656
+ if (waits) {
657
+ keepWaiting(q, waits, result?.gate ?? '');
658
+ if (!sameWords)
659
+ trace(p.name, 'queue-waits', result?.gate ?? '');
660
+ }
661
+ const retried = kept && !result?.waits && clearWaiting(p.name);
494
662
  const note = !kept
495
663
  ? ''
496
664
  : [
497
665
  live ? '' : 'it ended while the board was stopped',
666
+ waits ? `${waits.id} stays in the queue` : '',
498
667
  limited(q, result) ||
499
668
  (stop ? 'the queue is paused: fix the cause, then resume it on the board' : ''),
500
669
  ]
@@ -524,11 +693,11 @@ function land(q, run, rid, live, message = '') {
524
693
  err: (brief + message).trim(),
525
694
  note,
526
695
  };
527
- // A project removed meanwhile has no board to show it on.
528
- if (kept)
696
+ // A project removed meanwhile has no board to show it on; the same refusal again says nothing.
697
+ if (kept && !sameWords)
529
698
  reports.set(p.name, [...(reports.get(p.name) ?? []), report].slice(-KEEP_REPORTS));
530
699
  // The checkout is free now, for whatever queue the name has: a project added back meanwhile.
531
- if (mode === 'main')
700
+ if (mode === 'main' || retried)
532
701
  advance(p.name);
533
702
  if (kept && q.pilot)
534
703
  piloted(p.name, ok, result);
@@ -625,6 +794,8 @@ export function adoptRuns(entry, p) {
625
794
  ...{ entry, p, ids: f.ids, mode: f.mode, harness: f.harness, agent },
626
795
  ...(f.kind === 'card' ? { kind: 'card' } : {}),
627
796
  ...(f.pilot ? { pilot: true } : {}),
797
+ ...(f.queued ? { queued: true } : {}),
798
+ ...(f.waited ? { waited: f.waited } : {}),
628
799
  };
629
800
  active.add(run);
630
801
  flights.set(rid, run);
@@ -695,7 +866,8 @@ export function startRun(entry, p, ids, mode = 'worktree', fresh = false, harnes
695
866
  busyCheck(p, ids);
696
867
  const { active: going } = runsOf(p.name);
697
868
  // A paused queue holds a new main run too: it would repeat the failure, and jump the queue.
698
- if (mode === 'main' && (paused.has(p.name) || going.some((r) => r.mode === 'main'))) {
869
+ const held = paused.has(p.name) || clickBuilds.has(p.name);
870
+ if (mode === 'main' && (held || going.some((r) => r.mode === 'main'))) {
699
871
  queues.set(p.name, [
700
872
  ...(queues.get(p.name) ?? []),
701
873
  { entry, p, ids, mode, fresh, harness, agent },
@@ -708,9 +880,10 @@ export function startRun(entry, p, ids, mode = 'worktree', fresh = false, harnes
708
880
  const pilots = new Map();
709
881
  // The projects whose autopilot is asking the harness now: one ask at a time.
710
882
  const piloting = new Set();
711
- // The batch size the autopilot asks for.
883
+ // The batch size the autopilot asks for. A main-mode plan runs its first card only: the run's
884
+ // end calls pilot() again, which reads the switch, loose work and the milestone before the next.
712
885
  const PILOT_BATCH = 3;
713
- const STOPS = ['play', 'empty', 'idle', 'dirty', 'no-move', 'error'];
886
+ const STOPS = ['play', 'empty', 'idle', 'dirty', 'no-move', 'error', 'limit', 'hold'];
714
887
  const savedPilot = ({ on, stop, guard, harness }) => ({
715
888
  on,
716
889
  stop,
@@ -818,8 +991,11 @@ function piloted(project, ok, result) {
818
991
  return off('error', `its run ended with no result${result?.gate ? ` (${result.gate})` : ''}`);
819
992
  // A stop is the operator's word: the autopilot takes it, it does not start the item again.
820
993
  const stopped = items.filter((i) => /stopped/.test(`${i.result ?? ''} ${i.error ?? ''}`));
821
- // A timeout or a usage limit cut a session a rerun is meant to go on with.
822
- const cut = (i) => i.limit_resets !== undefined || /timed out/.test(`${i.result ?? ''} ${i.error ?? ''}`);
994
+ // A timeout or a usage limit cut a session a rerun is meant to go on with; so did a Hold or
995
+ // the quota's reserve (Hold-Plan d9, d11): paused, not stopped.
996
+ const cut = (i) => i.limit_resets !== undefined ||
997
+ Boolean(i.held) ||
998
+ /timed out/.test(`${i.result ?? ''} ${i.error ?? ''}`);
823
999
  // `skipped`: no session looked at it, so its next ask is no repeat of this one.
824
1000
  const none = items.filter((i) => !MOVED.test(i.result ?? 'merged') && !cut(i) && i.result !== 'skipped');
825
1001
  for (const i of none)
@@ -829,11 +1005,29 @@ function piloted(project, ok, result) {
829
1005
  const failed = items.filter((i) => ['error', 'conflict'].includes(i.result ?? ''));
830
1006
  if (!ok || failed.length)
831
1007
  return off('error', `a run failed${failed.length ? `: ${failed.map((i) => i.id).join(', ')}` : ''}`);
1008
+ // The folder could not change hands (harness 0.23): the next ask would meet the same refusal.
1009
+ const refused = items.find((i) => i.result === 'skipped' && i.left?.length);
1010
+ if (refused)
1011
+ return off('dirty', refused.reason ?? `${refused.id} did not start`);
832
1012
  if (none.length && none.length === items.filter((i) => i.result !== 'skipped').length)
833
- off('no-move', `a run of ${items.map((i) => i.id).join(', ')} made no move`);
1013
+ return off('no-move', `a run of ${items.map((i) => i.id).join(', ')} made no move`);
1014
+ // The quota's reserve held it: the autopilot stands on the limit, it stays on, until a reading
1015
+ // newer than this one (the run knows its model's week, the board does not; review 2).
1016
+ if (items.some((i) => i.held === 'reserve')) {
1017
+ reserveStrict.add(project);
1018
+ stand(project, { kind: 'limit', text: reserveText(items.find((i) => i.reserve)?.reserve) });
1019
+ }
834
1020
  }
835
- /** Whether the project is idle for the autopilot: no run, no queue, no pause. */
836
- const idle = (project) => !paused.has(project) && !activeRuns(project).length && !queues.get(project)?.length;
1021
+ /** Why the autopilot stands on the quota's reserve, as the header says it. */
1022
+ export const reserveText = (r) => r?.weekly
1023
+ ? "the quota is at its reserve: the automation stands until the week's reset"
1024
+ : `the quota is at its reserve: the automation waits for the reset${r?.until ? ` at ${r.until}` : ''}`;
1025
+ /** Whether the project is idle for the autopilot: no run, no queue to go, no pause. */
1026
+ const idle = (project) => !paused.has(project) &&
1027
+ !projectHolds.has(project) &&
1028
+ !clickBuilds.has(project) &&
1029
+ !activeRuns(project).length &&
1030
+ !queues.get(project)?.some((q) => !q.waiting);
837
1031
  /** Main's loose work outside gcf/ a main batch would carry; none when the gate cannot say. */
838
1032
  async function looseOf(s, ids) {
839
1033
  const g = await runCli(s.entry, s.p.path, [s.harness, 'gate', '--each', ...ids, '--json']);
@@ -854,6 +1048,10 @@ async function pilot(project) {
854
1048
  const s = pilots.get(project);
855
1049
  if (!s?.on || piloting.has(project) || adopting.has(project) || !idle(project))
856
1050
  return;
1051
+ // The quota at its reserve: it stands, still on, and a reading under it starts it (d11).
1052
+ const reserve = reserveStand(project);
1053
+ if (reserve)
1054
+ return stand(project, reserve);
857
1055
  piloting.add(project);
858
1056
  try {
859
1057
  const skip = guardedOf(s);
@@ -879,7 +1077,7 @@ async function pilot(project) {
879
1077
  stand(project, null);
880
1078
  trace(project, 'autopilot-card', `the autopilot cards ${plan.units.join(', ')}`);
881
1079
  const q = { entry, p, ids: plan.units, mode: 'main', harness };
882
- spawnRun({ ...q, kind: 'card', pilot: true }, 'main');
1080
+ spawnRun({ ...q, kind: 'card', pilot: true, waitLimit: true }, 'main');
883
1081
  changed(project);
884
1082
  return;
885
1083
  }
@@ -911,8 +1109,9 @@ async function pilot(project) {
911
1109
  if (!s.on || !idle(project))
912
1110
  return;
913
1111
  stand(project, null);
914
- trace(project, 'autopilot-run', `the autopilot runs ${plan.ids.join(', ')}`);
915
- spawnRun({ entry, p, ids: plan.ids, mode, harness, pilot: true, waitLimit: true }, mode);
1112
+ const ids = mode === 'main' ? plan.ids.slice(0, 1) : plan.ids;
1113
+ trace(project, 'autopilot-run', `the autopilot runs ${ids.join(', ')}`);
1114
+ spawnRun({ entry, p, ids, mode, harness, pilot: true, waitLimit: true }, mode);
916
1115
  changed(project);
917
1116
  }
918
1117
  finally {
@@ -189,6 +189,42 @@ function commitsOf(dir, id) {
189
189
  const lines = git(dir, 'log', '--format=%h %s', '-n', '500', '-F', `--grep=${id}`).split('\n');
190
190
  return lines.filter((l) => word.test(l.slice(l.indexOf(' ') + 1))).slice(0, CONTEXT_LINES);
191
191
  }
192
+ /**
193
+ * Whether a card waiting for play can be played, in the words a chat answers from: this thread is
194
+ * not the run that built it, and without these facts it would say another agent did the work.
195
+ */
196
+ function playLines(board, item) {
197
+ if (!['awaiting-verdict', 'unplayed'].includes(item.status) || board.play === undefined)
198
+ return [];
199
+ if (board.play === null)
200
+ return [
201
+ '',
202
+ 'To play it: how to play is not set up (no `play:` in gcf/config.yml), so it has no build.',
203
+ "If the project's AGENTS.md says how the game builds and starts, call propose_play_setup.",
204
+ '',
205
+ ];
206
+ const b = item.build;
207
+ const targets = board.play.targets.map((t) => `${t.name} (${t.open})`).join(', ') || 'none';
208
+ const said = b?.building
209
+ ? 'its build is being made now.'
210
+ : b?.ok
211
+ ? `its build is ready: commit ${b.commit ?? 'unknown'}, built ${b.built_at}, ` +
212
+ `${b.source === 'click' ? 'by hand, so it may hold later cards' : 'by its run'}.`
213
+ : 'it has no build yet.';
214
+ const running = board.play.running?.id === item.id
215
+ ? [`It plays now on ${board.play.running.target}: ${board.play.running.open}.`]
216
+ : [];
217
+ return [
218
+ '',
219
+ `To play it: ${said}`,
220
+ ...(b?.problem ? [`The last build failed: ${b.problem.split('\n')[0]}`] : []),
221
+ ...running,
222
+ `Targets: ${targets}.`,
223
+ 'Do not ask the human to build or start it by hand: the card has its Play and Build buttons;',
224
+ 'to offer one here call propose_play with its id and a target. The verdict stops the player.',
225
+ '',
226
+ ];
227
+ }
192
228
  /**
193
229
  * What a thread bound to `item` is given to read (AD-47): paths, not their text, but the ones a
194
230
  * session would need a git command or a search for. Empty for a thread of no item.
@@ -220,6 +256,8 @@ export function contextOf(p, board, item) {
220
256
  if (last)
221
257
  lines.push(`- its file as last committed: git show ${last.split(' ')[0]}^:gcf/work/${item}.md (${last})`);
222
258
  }
259
+ if (live)
260
+ lines.push(...playLines(board, live));
223
261
  for (const [what, rel] of [
224
262
  ["its run's log", `.gcf-session/runs/${item}.log`],
225
263
  ["its run's chat", `.gcf-session/runs/${item}.chat.jsonl`],