@warren-dean/code-kit 0.25.0 → 0.26.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.
@@ -15,6 +15,7 @@ import {
15
15
  RESULT_ID,
16
16
  SETTINGS_ID,
17
17
  approvalsText,
18
+ agentsAlive,
18
19
  agentsAtWork,
19
20
  shownState,
20
21
  attribution,
@@ -23,7 +24,6 @@ import {
23
24
  approvePane,
24
25
  questionAsidePrompt,
25
26
  commandItself,
26
- band,
27
27
  bandLines,
28
28
  finishedStories,
29
29
  ago,
@@ -35,23 +35,40 @@ import {
35
35
  refusalView,
36
36
  resultPane,
37
37
  settingsView,
38
+ usageSection,
38
39
  usageSummary,
39
40
  usageForReport,
40
41
  presenceOf,
41
42
  withUsage,
42
43
  } from './view.mjs';
43
44
  import { holdable } from './hold.mjs';
44
- import { axisStart, barCells, poseOf, rasterCells, sprite, tintOf } from './art.mjs';
45
+ import { axisStart, barCells } from './art.mjs';
45
46
  import {
46
- DEFAULT_UI,
47
47
  SENDBACK_ID,
48
- closeGoesBack,
48
+ codeTab,
49
+ decisionsTab,
50
+ journalTab,
49
51
  laneActions,
50
- lanesFrame,
51
52
  liveLevel,
53
+ mapTab,
52
54
  sendBackPane,
55
+ storyPane,
53
56
  toolLine,
54
57
  } from './panes.mjs';
58
+ import {
59
+ BOARD_UI,
60
+ bandOf,
61
+ board,
62
+ escapeGoesBack,
63
+ lanesAtWork,
64
+ moveSelection,
65
+ needsOf,
66
+ poseFor,
67
+ selectable,
68
+ sheetView,
69
+ viewFrame,
70
+ } from './board.mjs';
71
+ import { charactersOf } from './characters.mjs';
55
72
  import {
56
73
  agentFileModel,
57
74
  answeredPrompt,
@@ -196,16 +213,27 @@ const activityOf = (agentId, now) => {
196
213
  const harness = () => harnessSettings(model.check?.harness);
197
214
  // Panes v2 (spec 11): the Lanes pane's own state, the lead's last tool call, and a send-back waiting
198
215
  // for the person's reason.
199
- let paneUi = { ...DEFAULT_UI };
216
+ let paneUi = { ...BOARD_UI };
200
217
  let leadLast = null; // { tool, at }
201
218
  let sendingBack = null; // { lane, branch, story, reason, error }
202
219
  let storyOpen = null; // the drill-down's story (VIEW-7): { id, lane, data, error }
203
220
  const personAsks = []; // prompts the person asked for (stop an agent), waiting for the lead to be idle
204
- // VIEW-3: the characters' animation, and the surface the Lanes pane was last drawn on.
205
- let frame = 0;
206
- let animation = null; // the timer repainting working characters, while one works
221
+ // The surface the Lanes pane was last drawn on, and its room.
207
222
  let paneSurface = null;
208
223
  let paneColumns = 80;
224
+ let paneRows = 40;
225
+ let paneOpen = false; // whether the Lanes pane is open, as the last look found it
226
+ // UI-11: each lane's one-off move at an event, while it plays: lane → { kind, key, at }; UI-2: the
227
+ // requirements that turned tested, while their segment fills: id → at.
228
+ const moves = new Map();
229
+ const freshTested = new Map();
230
+ const MOVE_MS = 1500;
231
+ // UI-12: the surfaces a surface module failed on, which draw everything still from then on.
232
+ const faulted = {};
233
+ // UI-4: each card's story map (`code-kit map <story> --json`), and each lane's refusals not yet
234
+ // resolved: lane → [{ layer, path }].
235
+ const storyMaps = {};
236
+ const troubles = new Map();
209
237
  let codeMap = null; // MAP-1: `code-kit map <story> --json` for the Code map tab's story
210
238
  let trailData = null; // TRAIL-1: `code-kit trail --json` while the Trail tab shows
211
239
  let journalData = null; // JOURNAL-1: `code-kit journal --json`, for the Journal tab and the decisions
@@ -227,7 +255,9 @@ export function register(on) {
227
255
  await $.command
228
256
  .register({
229
257
  name: 'lanes',
230
- description: "code-kit's lanes: agents, stories, branches and what's ready",
258
+ description:
259
+ "code-kit's pane: the build, what needs you, the lanes, the queue and the log; or a view: trail, map, journal, usage, characters",
260
+ argumentHint: '[trail|map|journal|usage|characters]',
231
261
  immediate: true,
232
262
  })
233
263
  .catch(unavailable('lanes'));
@@ -361,6 +391,7 @@ export function register(on) {
361
391
  : null;
362
392
  // The agents at work; none where the session has none bound (claude -p before it mounts).
363
393
  const atWork = agentsAtWork(await $.agent.list().catch(() => []));
394
+ const before = { state: model.state, status: model.status, queue: model.queue };
364
395
  model = {
365
396
  state: projectState(check, status, nextStep, atWork),
366
397
  requests,
@@ -387,14 +418,61 @@ export function register(on) {
387
418
  elsewhere: owned?.elsewhere ?? [],
388
419
  };
389
420
  if (model.state.kind === 'ok') await act.registerReviewer();
421
+ await act.events(before, await $.clock.now());
390
422
  await act.readMaps();
391
423
  $.ui.invalidate('ui.render');
392
424
  },
425
+ // UI-11: a lane's one-off move at each event (a story arriving, handed back, sent back or
426
+ // merged); UI-2: the requirements that turned tested. Each plays once, then the pane is still.
427
+ events: async (before, now) => {
428
+ if (before.state?.kind !== 'ok' || model.state?.kind !== 'ok') return;
429
+ const was = new Map(before.state.lanes.map((l) => [l.name, l]));
430
+ const done = new Set(
431
+ (model.state.stories ?? []).filter((s) => s.state === 'done').map((s) => s.id),
432
+ );
433
+ for (const l of model.state.lanes) {
434
+ const prev = was.get(l.name);
435
+ if (!prev) continue;
436
+ const then = shownState(prev, before.queue ?? []);
437
+ const nowShown = shownState(l, model.queue ?? []);
438
+ let kind = null;
439
+ if (prev.story?.id && prev.story.id !== l.story?.id && done.has(prev.story.id))
440
+ kind = 'merged';
441
+ else if (l.story?.id && l.story.id !== prev.story?.id && l.state === 'building')
442
+ kind = 'arriving';
443
+ else if (nowShown === 'sent back' && then !== 'sent back') kind = 'sent-back';
444
+ else if (['in review', 'queued'].includes(nowShown) && then === 'building')
445
+ kind = 'handed-back';
446
+ if (!kind) continue;
447
+ moves.set(l.name, {
448
+ kind,
449
+ key: `${kind}:${l.story?.id ?? prev.story?.id}:${now}`,
450
+ at: now,
451
+ });
452
+ // A story merged or moved on leaves no refusal of the lane's standing.
453
+ if (kind === 'merged' || kind === 'arriving') troubles.delete(l.name);
454
+ }
455
+ const tested = (status) =>
456
+ new Set(
457
+ (status?.requirements ?? [])
458
+ .filter((r) => r.state === 'done' && r.tests?.length)
459
+ .map((r) => r.id),
460
+ );
461
+ if (before.status) {
462
+ const old = tested(before.status);
463
+ for (const id of tested(model.status)) if (!old.has(id)) freshTested.set(id, now);
464
+ }
465
+ if (moves.size || freshTested.size)
466
+ $.clock
467
+ .sleep(MOVE_MS + 100)
468
+ .then(() => $.ui.invalidate('ui.render'))
469
+ .catch(() => {});
470
+ },
393
471
  // MAP-1, TRAIL-1: what the Code map and Trail tabs draw, read while they show.
394
472
  readMaps: async () => {
395
473
  if (model.state?.kind !== 'ok') return;
396
- if (paneUi.tab === 'code') {
397
- const id = mapStoryOf(stateNow(), paneUi.selected, paneUi.mapStory);
474
+ if (paneUi.view === 'code') {
475
+ const id = mapStoryOf(stateNow(), selectedLaneName(), paneUi.mapStory);
398
476
  // MAP-5: the whole project reads every code file, so at most every 30 seconds.
399
477
  const now = await $.clock.now();
400
478
  const fresh =
@@ -404,13 +482,24 @@ export function register(on) {
404
482
  if (id === 'project') projectRead = now;
405
483
  }
406
484
  }
407
- if (paneUi.tab === 'map') trailData = (await json('trail')) ?? trailData;
485
+ if (paneUi.view === 'trail') trailData = (await json('trail')) ?? trailData;
486
+ // UI-4: each card's story map, for the layers its changed files are in.
487
+ if (paneOpen)
488
+ for (const l of lanesAtWork(stateNow(), model.queue ?? []).atWork) {
489
+ const id = l.story?.id;
490
+ if (id && l.story.state !== 'done')
491
+ storyMaps[id] = (await json('map', id)) ?? storyMaps[id];
492
+ }
408
493
  // TEAM-6: since you last looked, read once each time its tab opens, which marks it read.
409
494
  if (teamUi.tab === 'activity' && model.check?.team && !teamSince)
410
495
  teamSince = (await json('team', 'since')) ?? { people: {} };
411
496
  // JOURNAL-1, DECIDE-2: the lineage, for the Journal tab and the decisions' cards.
412
497
  const deciding = held.size > 0 || (model.requests?.open ?? []).length > 0;
413
- if (model.check?.docs?.plan && (['journal', 'decisions'].includes(paneUi.tab) || deciding))
498
+ // UI-5: the Log reads it whenever the pane is open.
499
+ if (
500
+ model.check?.docs?.plan &&
501
+ (paneOpen || ['journal', 'decision'].includes(paneUi.view) || deciding)
502
+ )
414
503
  journalData = (await json('journal')) ?? journalData;
415
504
  },
416
505
  // REVW-2: the reviewer, read-only by the hooks' rule for agents outside the lanes. Registered
@@ -558,13 +647,43 @@ export function register(on) {
558
647
  [...agentsAtWork(await $.agent.list().catch(() => []))].sort().join(','),
559
648
  ].join('\n');
560
649
  },
561
- // PANE-1: open the Lanes pane, or close it when it's open.
562
- lanes: async () => {
650
+ // PANE-1: open the Lanes pane, or close it when it's open. UI-6: `/lanes trail`, `map`,
651
+ // `journal`, `usage` and `characters` open that view, over the panels.
652
+ lanes: async (args = '') => {
653
+ const asked = (typeof args === 'string' ? args : '').trim().split(/\s+/)[0].toLowerCase();
654
+ const views = {
655
+ trail: 'trail',
656
+ map: 'code',
657
+ journal: 'journal',
658
+ usage: 'usage',
659
+ characters: 'characters',
660
+ };
661
+ if (asked && !views[asked])
662
+ return {
663
+ text: `/lanes ${asked} isn't a view: try /lanes, or /lanes trail, map, journal, usage or characters.`,
664
+ };
563
665
  // Asked, not remembered: the person may have closed it with Escape.
564
- if ((await $.ui.panes()).some((p) => p.id === PANE_ID)) {
666
+ const isOpen = (await $.ui.panes()).some((p) => p.id === PANE_ID);
667
+ if (isOpen && !asked) {
565
668
  await $.ui.close({ id: PANE_ID });
669
+ paneOpen = false;
670
+ return {};
671
+ }
672
+ if (asked) {
673
+ paneUi = {
674
+ ...paneUi,
675
+ view: views[asked],
676
+ ...(asked === 'map' ? { mapStory: 'project', mapFile: null } : {}),
677
+ };
678
+ storyOpen = null;
679
+ }
680
+ if (isOpen) {
681
+ $.ui.invalidate('ui.render');
682
+ await act.readMaps();
683
+ $.ui.invalidate('ui.render');
566
684
  return {};
567
685
  }
686
+ paneOpen = true;
568
687
  await act.reload();
569
688
  if (model.state.kind === 'none') return { text: NOT_CODE_KIT };
570
689
  const placed = await $.ui.open({
@@ -580,11 +699,16 @@ export function register(on) {
580
699
  // DECIDE-3: the Decisions tab, on the decision the person asked about.
581
700
  decide: async (line) => {
582
701
  const cards = cardsNow(await $.clock.now());
702
+ // UI-3: the card of the very line chosen, else the first of its kind.
703
+ const exact = cards.findIndex(
704
+ (c) => c.source?.kind === line?.kind && c.source?.text === line?.text,
705
+ );
583
706
  const at = Math.max(
584
707
  0,
585
- cards.findIndex((c) => c.line.kind === line?.kind),
708
+ exact >= 0 ? exact : cards.findIndex((c) => c.line.kind === line?.kind),
586
709
  );
587
- paneUi = { ...paneUi, tab: 'decisions', decision: at, story: null };
710
+ paneUi = { ...paneUi, view: 'decision', decision: at };
711
+ storyOpen = null;
588
712
  if (!(await $.ui.panes()).some((p) => p.id === PANE_ID))
589
713
  await $.ui.open({ id: PANE_ID, title: 'Lanes', focus: true, closeOnEscape: true });
590
714
  $.ui.invalidate('ui.render');
@@ -1706,8 +1830,9 @@ export function register(on) {
1706
1830
  beaten = at;
1707
1831
  await $.process.run(['node', cli, 'sessions', 'beat', '--session', session], { cwd });
1708
1832
  },
1709
- // SCHED-1: a lane this session's agent claimed, with no agent of that lane still running here for a
1710
- // minute (stopped with TaskStop, or gone without its finish), is released for its next story.
1833
+ // SCHED-1: a lane this session's agent claimed, with no agent of that lane left here for a minute
1834
+ // (ended, stopped with TaskStop, or gone without its finish), is released for its next story. One
1835
+ // pending, waiting or idle is still alive, and keeps it.
1711
1836
  freeLanes: async () => {
1712
1837
  const at = await $.clock.now();
1713
1838
  // The first look only starts the clock: a session's first minute frees nothing.
@@ -1716,14 +1841,10 @@ export function register(on) {
1716
1841
  lanesFreed = at;
1717
1842
  const claims = ((await json('lanes')) ?? []).filter((c) => c.session === session);
1718
1843
  if (!claims.length) return;
1719
- const running = new Set(
1720
- ((await $.agent.list().catch(() => [])) ?? [])
1721
- .filter((a) => a.status === 'running')
1722
- .map((a) => a.type),
1723
- );
1844
+ const alive = agentsAlive(await $.agent.list().catch(() => []));
1724
1845
  for (const c of claims) {
1725
1846
  const type = model.check?.lanes?.[c.lane]?.agent;
1726
- if (!type || running.has(type) || at - Date.parse(c.since) < LANES_FREE_MS) continue;
1847
+ if (!type || alive.has(type) || at - Date.parse(c.since) < LANES_FREE_MS) continue;
1727
1848
  await $.process.run(['node', cli, 'lanes', 'release', c.lane], { cwd }).catch(() => {});
1728
1849
  await act.record('free', `${c.lane}${c.story ? ` · ${c.story}` : ''}`);
1729
1850
  }
@@ -1779,6 +1900,7 @@ export function register(on) {
1779
1900
  id: agent.id,
1780
1901
  story: a.story,
1781
1902
  minutes: h.stall.restartMinutes,
1903
+ cli,
1782
1904
  }),
1783
1905
  });
1784
1906
  await act.record('restart', `${lane} · ${a.story} (${n}/${h.stall.maxRestarts})`);
@@ -1804,34 +1926,6 @@ export function register(on) {
1804
1926
  }
1805
1927
  if (loop.pending.length) await act.step('tick');
1806
1928
  },
1807
- // VIEW-3: working characters repaint in place while the pane shows them; nothing runs otherwise.
1808
- animate: async () => {
1809
- const open = (await $.ui.panes()).some((p) => p.id === PANE_ID);
1810
- const now = await $.clock.now();
1811
- const art = artNow(now, liveNow(now));
1812
- const working = Object.keys(art.poses).filter((n) => art.poses[n] === 'working');
1813
- if (!open || paneSurface !== 'terminal' || !working.length) {
1814
- animation?.cancel();
1815
- animation = null;
1816
- return;
1817
- }
1818
- if (animation) return;
1819
- animation = $.clock.every(400, async () => {
1820
- frame = (frame + 1) % 2;
1821
- const at = await $.clock.now();
1822
- const still = artNow(at, liveNow(at));
1823
- for (const name of Object.keys(still.poses).filter((n) => still.poses[n] === 'working'))
1824
- await $.ui
1825
- .blit({
1826
- requestId: PANE_ID,
1827
- key: `char-${name}`,
1828
- cells: rasterCells(
1829
- sprite('working', frame, still.tints[name], { lead: name === 'lead' }),
1830
- ),
1831
- })
1832
- .catch(() => {});
1833
- });
1834
- },
1835
1929
  // --- panes v2: the selected lane's acts (VIEW-6) ----------------------------------------
1836
1930
  // A prompt the person asked for: submitted now if the lead is idle, else when it next is.
1837
1931
  askLead: async (prompt, kind, target) => {
@@ -1934,7 +2028,7 @@ export function register(on) {
1934
2028
  openStory: async (lane) => {
1935
2029
  if (!lane.story) return;
1936
2030
  const id = lane.story.id;
1937
- paneUi = { ...paneUi, story: id, file: null };
2031
+ paneUi = { ...paneUi, view: 'story', file: null };
1938
2032
  storyOpen = { id, lane: lane.name, data: null, error: null };
1939
2033
  $.ui.invalidate('ui.render');
1940
2034
  const ran = await $.process.run(['node', cli, 'story', id, '--json'], {
@@ -1952,7 +2046,7 @@ export function register(on) {
1952
2046
  $.ui.invalidate('ui.render');
1953
2047
  },
1954
2048
  closeStory: () => {
1955
- paneUi = { ...paneUi, story: null, file: null };
2049
+ paneUi = { ...paneUi, view: null, file: null };
1956
2050
  storyOpen = null;
1957
2051
  $.ui.invalidate('ui.render');
1958
2052
  },
@@ -1997,11 +2091,11 @@ export function register(on) {
1997
2091
  await act.beat().catch(() => {});
1998
2092
  await act.stalls();
1999
2093
  await act.freeLanes().catch(() => {});
2000
- await act.animate();
2094
+ paneOpen = (await $.ui.panes()).some((p) => p.id === PANE_ID);
2001
2095
  const now = await act.fingerprint();
2002
- const paneOpen = (await $.ui.panes()).some((p) => [PANE_ID, TEAM_ID].includes(p.id));
2096
+ const anyPane = (await $.ui.panes()).some((p) => [PANE_ID, TEAM_ID].includes(p.id));
2003
2097
  quiet += 1;
2004
- if (now === seen && quiet < (paneOpen ? 5 : 30)) return;
2098
+ if (now === seen && quiet < (anyPane ? 5 : 30)) return;
2005
2099
  quiet = 0;
2006
2100
  await act.reload();
2007
2101
  // Taken again: what it covers (the plan) can change with what was read.
@@ -2042,7 +2136,9 @@ export function register(on) {
2042
2136
  const starting = (name) => ({
2043
2137
  text: `code-kit is still starting; try /${name} again in a moment.`,
2044
2138
  });
2045
- on('command.run', { command: 'lanes' }, async ($, e) => (act ? act.lanes() : starting('lanes')));
2139
+ on('command.run', { command: 'lanes' }, async ($, e) =>
2140
+ act ? act.lanes(e.args) : starting('lanes'),
2141
+ );
2046
2142
  on('command.run', { command: 'team' }, async ($, e) =>
2047
2143
  act ? act.team(null, { toggle: true }) : starting('team'),
2048
2144
  );
@@ -2129,7 +2225,7 @@ export function register(on) {
2129
2225
  if (touch && touchLane) {
2130
2226
  touches.push({ ...touch, lane: touchLane, at: calledAt });
2131
2227
  if (touches.length > TOUCHES_KEPT) touches.shift();
2132
- if (paneUi.tab === 'code') $.ui.invalidate('ui.render');
2228
+ if (paneUi.view === 'code') $.ui.invalidate('ui.render');
2133
2229
  }
2134
2230
  try {
2135
2231
  const res = await next(e);
@@ -2151,6 +2247,15 @@ export function register(on) {
2151
2247
  refusals.set(e.tool_use_id, text);
2152
2248
  if (refusals.size > REFUSALS_KEPT) refusals.delete(refusals.keys().next().value);
2153
2249
  }
2250
+ // UI-4: a refusal the lane hasn't resolved turns its story's map chip red, until the same file
2251
+ // is written; a write refused for its layer rules names the layer.
2252
+ const troubleLane = busy ? busy.lane : e.agentId ? null : 'lead';
2253
+ if (troubleLane && touch?.verb === 'edit') {
2254
+ const found = text ? troubleOf(text, touch.path) : [];
2255
+ const kept = (troubles.get(troubleLane) ?? []).filter((t) => t.path !== touch.path);
2256
+ troubles.set(troubleLane, [...kept, ...found]);
2257
+ $.ui.invalidate('ui.render');
2258
+ }
2154
2259
  const ask = text ? holdable(text) : null;
2155
2260
  const settings = model.check?.harness;
2156
2261
  const minutes = settings?.hold?.minutes ?? 2;
@@ -2192,6 +2297,14 @@ export function register(on) {
2192
2297
  }
2193
2298
  }
2194
2299
  }).catch(($, e, next) => next(e)); // whatever fails here, the call goes on as it would
2300
+ // UI-4: what a refused write leaves unresolved: each layer rule it would break, or the write itself.
2301
+ const troubleOf = (text, path) => {
2302
+ const layers = [
2303
+ ...String(text).matchAll(/^\s+(\S+) \(([^()]+)\) (?:imports|may not import)/gm),
2304
+ ];
2305
+ if (layers.length) return layers.map((m) => ({ layer: m[2], path: m[1] }));
2306
+ return refusalCard(text)?.kind === 'write' ? [{ layer: null, path }] : [];
2307
+ };
2195
2308
  // A refused call's text: kept from its tool.call, or the output its row carries (what the model read).
2196
2309
  const refusalOf = (id, output) =>
2197
2310
  refusalCard(refusals.get(id) ?? (typeof output === 'string' ? output : null));
@@ -2458,10 +2571,10 @@ export function register(on) {
2458
2571
  }),
2459
2572
  );
2460
2573
  };
2461
- // VIEW-2, VIEW-3: each lane's pose and tint, and its story's bar on the shared axis.
2574
+ // UI-4, UI-11, UI-12: each lane's pose and the move it's playing, its story's bar on the shared
2575
+ // axis (for swimlanes), the requirements newly tested, and the surfaces drawn still.
2462
2576
  const artNow = (now, live) => {
2463
2577
  const lanesNow = stateNow()?.kind === 'ok' ? stateNow().lanes : [];
2464
- const names = lanesNow.map((l) => l.name);
2465
2578
  const queue = model.queue ?? [];
2466
2579
  const asking = new Set([
2467
2580
  ...[...held.values()].map((c) => c.lane ?? 'lead'),
@@ -2472,23 +2585,34 @@ export function register(on) {
2472
2585
  lanesNow.some((l) => l.story?.id === t.id),
2473
2586
  );
2474
2587
  const start = axisStart(times, now);
2475
- const width = Math.max(10, Math.min(120, paneColumns - 14));
2588
+ // VIEW-2: the time axis, as wide as a card's text has room for.
2589
+ const width = Math.max(10, Math.min(40, paneColumns - 40));
2476
2590
  const poses = {};
2477
- const tints = {};
2478
2591
  const bars = {};
2592
+ const playing = {};
2593
+ for (const [lane, m] of moves) if (now - m.at < MOVE_MS) playing[lane] = m;
2479
2594
  for (const l of lanesNow) {
2480
- poses[l.name] = poseOf(l, {
2595
+ poses[l.name] = poseFor(l, {
2481
2596
  live: live[l.name],
2482
2597
  waiting: asking.has(l.name),
2483
- flagged: stalled.has(l.name),
2484
- shown: shownState(l, queue),
2598
+ stalled: stalled.has(l.name),
2599
+ queue,
2485
2600
  });
2486
- tints[l.name] = tintOf(l.name, names);
2487
2601
  const t = times.find((x) => x.id === l.story?.id);
2488
2602
  if (t) bars[l.name] = barCells(t, { start, now, width });
2489
2603
  }
2490
- return { surface: paneSurface, frame, poses, tints, bars, svgWidth: width * 6 };
2604
+ return {
2605
+ surface: paneSurface,
2606
+ motion: harness().motion,
2607
+ poses,
2608
+ moves: playing,
2609
+ bars,
2610
+ faulted,
2611
+ fresh: [...freshTested].filter(([, at]) => now - at < MOVE_MS).map(([id]) => id),
2612
+ };
2491
2613
  };
2614
+ /** The lane selected in the pane, if a lane is. */
2615
+ const selectedLaneName = () => (paneUi.sel?.kind === 'lane' ? paneUi.sel.id : null);
2492
2616
  const liveNow = (now) => {
2493
2617
  const stall = harness().stall;
2494
2618
  const live = {};
@@ -2585,151 +2709,305 @@ export function register(on) {
2585
2709
  return card ? { ...l, context: contextOf(card) } : l;
2586
2710
  });
2587
2711
  };
2712
+ // UI-3, UI-8: most urgent first, every action numbered in that order, wherever they're shown.
2588
2713
  const linesNowRaw = (now) =>
2589
- bandLines({
2590
- ...model,
2591
- reviewing,
2592
- notice,
2593
- ...usageNow(),
2594
- held: [...held.values()],
2595
- now,
2596
- loop: loopNow(now),
2597
- leadBusy: Boolean(leadTurn),
2598
- live: liveNow(now),
2599
- nextStep: loop.nextStep,
2600
- combined: combinedNow(),
2601
- team: model.team ?? null,
2602
- });
2714
+ needsOf(
2715
+ bandLines({
2716
+ ...model,
2717
+ reviewing,
2718
+ notice,
2719
+ ...usageNow(),
2720
+ held: [...held.values()],
2721
+ now,
2722
+ loop: loopNow(now),
2723
+ leadBusy: Boolean(leadTurn),
2724
+ live: liveNow(now),
2725
+ nextStep: loop.nextStep,
2726
+ combined: combinedNow(),
2727
+ team: model.team ?? null,
2728
+ }),
2729
+ );
2603
2730
 
2604
2731
  on('ui.render', { component: 'Pane', requestId: PANE_ID }, async ($, e) => {
2605
2732
  const now = await $.clock.now();
2606
2733
  paneSurface = e.surface;
2607
2734
  paneColumns = e.props.bodyColumns ?? paneColumns;
2735
+ paneRows = e.props.scroll?.bodyRows ?? paneRows;
2736
+ paneOpen = true;
2737
+ const els = $.ui.resolve(e);
2608
2738
  const { usage, plan } = usageNow();
2609
- const lanesNow = stateNow()?.kind === 'ok' ? stateNow().lanes : [];
2610
- return lanesFrame(
2611
- {
2612
- state: stateNow(),
2739
+ const state = stateNow();
2740
+ const live = liveNow(now);
2741
+ const needs = needsOf(linesNow(now));
2742
+ const loopView = { ...loopNow(now), queue: model.queue ?? [] };
2743
+ const lanesNow = state?.kind === 'ok' ? state.lanes : [];
2744
+ const back = () => {
2745
+ if (paneUi.view === 'story') return act?.closeStory();
2746
+ paneUi = { ...paneUi, view: null };
2747
+ $.ui.invalidate('ui.render');
2748
+ };
2749
+ const looks = charactersOf(lanesNow.map((l) => l.name));
2750
+ const tints = Object.fromEntries(Object.entries(looks).map(([n, c]) => [n, c.tint]));
2751
+ // UI-6: the full views, over the panels; Escape (or Back) returns.
2752
+ if (paneUi.view === 'story' && storyOpen)
2753
+ return viewFrame(
2754
+ `${storyOpen.id}`,
2755
+ storyPane({ ...storyNow(storyOpen, now, usage), columns: paneColumns }, els, {
2756
+ onBack: back,
2757
+ onFile: (file) => {
2758
+ paneUi = { ...paneUi, file };
2759
+ $.ui.invalidate('ui.render');
2760
+ },
2761
+ // JOIN-4: a file in the adapter's own view, through the command it names.
2762
+ onOpenIn: (adapter, path) =>
2763
+ $.command.run({ command: adapter.open.command, args: path }).catch((err) => {
2764
+ notice = `Couldn't open ${path} in ${adapter.name}: ${err?.message ?? err}`;
2765
+ $.ui.invalidate('ui.render');
2766
+ }),
2767
+ onAct: (id) => {
2768
+ const lane = lanesNow.find((l) => l.name === storyOpen?.lane);
2769
+ if (lane) act?.laneAct(id, lane);
2770
+ },
2771
+ }),
2772
+ els,
2773
+ { onBack: back },
2774
+ [{ key: 'esc', label: 'back' }],
2775
+ { head: false },
2776
+ );
2777
+ if (paneUi.view === 'trail')
2778
+ return viewFrame(
2779
+ 'Trail',
2780
+ mapTab(
2781
+ model.status ?? null,
2782
+ paneUi.cell,
2783
+ els,
2784
+ {
2785
+ onCell: (cell) => {
2786
+ paneUi = { ...paneUi, cell };
2787
+ $.ui.invalidate('ui.render');
2788
+ },
2789
+ },
2790
+ trailData,
2791
+ { surface: paneSurface, columns: paneColumns },
2792
+ ),
2793
+ els,
2794
+ { onBack: back },
2795
+ [
2796
+ { key: '←→', label: 'requirement' },
2797
+ { key: 'esc', label: 'back' },
2798
+ ],
2799
+ );
2800
+ if (paneUi.view === 'code')
2801
+ return viewFrame(
2802
+ 'Code map',
2803
+ codeTab(
2804
+ {
2805
+ state,
2806
+ ui: {
2807
+ selected: selectedLaneName(),
2808
+ mapStory: paneUi.mapStory,
2809
+ mapFile: paneUi.mapFile,
2810
+ },
2811
+ codeMap,
2812
+ art: { tints },
2813
+ glow: glowOf(touches, now),
2814
+ surface: paneSurface,
2815
+ columns: paneColumns,
2816
+ },
2817
+ els,
2818
+ {
2819
+ onMapStory: (id) => {
2820
+ paneUi = { ...paneUi, mapStory: id, mapFile: null };
2821
+ $.ui.invalidate('ui.render');
2822
+ act?.readMaps().then(() => $.ui.invalidate('ui.render'));
2823
+ },
2824
+ onMapFile: (path) => {
2825
+ paneUi = { ...paneUi, mapFile: path };
2826
+ $.ui.invalidate('ui.render');
2827
+ },
2828
+ // MAP-3: the file in Context Graph's own view, through the command its adapter names.
2829
+ onOpenFile: (path) => {
2830
+ const command = codeMap?.open?.command;
2831
+ if (!command) return;
2832
+ $.command.run({ command, args: path }).catch((err) => {
2833
+ notice = `Couldn't open ${path}: ${err?.message ?? err}`;
2834
+ $.ui.invalidate('ui.render');
2835
+ });
2836
+ },
2837
+ },
2838
+ ),
2839
+ els,
2840
+ { onBack: back },
2841
+ );
2842
+ if (paneUi.view === 'journal') {
2843
+ const events = journalNow();
2844
+ return viewFrame(
2845
+ 'Journal',
2846
+ events.length
2847
+ ? journalTab(events, els, now)
2848
+ : [
2849
+ els.Text({
2850
+ dimColor: true,
2851
+ children: ['Nothing recorded yet: the journal starts with the brief.'],
2852
+ }),
2853
+ ],
2854
+ els,
2855
+ { onBack: back },
2856
+ );
2857
+ }
2858
+ if (paneUi.view === 'usage') {
2859
+ const body = usageSection(
2613
2860
  usage,
2614
2861
  plan,
2615
- loop: { ...loopNow(now), queue: model.queue ?? [] },
2616
- needs: linesNow(now).filter((l) => !l.mission),
2617
- cards: cardsNow(now),
2618
- journal: journalNow(),
2619
- now,
2620
- live: liveNow(now),
2862
+ (v, st = {}) => els.Text({ ...st, children: [v] }),
2863
+ els.Box,
2864
+ );
2865
+ return viewFrame(
2866
+ 'Usage',
2867
+ body.length
2868
+ ? body
2869
+ : [els.Text({ dimColor: true, children: ['No usage measured yet this session.'] })],
2870
+ els,
2871
+ { onBack: back },
2872
+ );
2873
+ }
2874
+ if (paneUi.view === 'decision') {
2875
+ const cards = cardsNow(now);
2876
+ if (cards.length)
2877
+ return viewFrame(
2878
+ 'Decision',
2879
+ decisionsTab(cards, paneUi, els, {
2880
+ onDecision: (i) => {
2881
+ paneUi = { ...paneUi, decision: i };
2882
+ $.ui.invalidate('ui.render');
2883
+ },
2884
+ onNeed: (id, line) => act?.[id]?.(line),
2885
+ }),
2886
+ els,
2887
+ { onBack: back },
2888
+ [
2889
+ { key: 'j/k', label: 'decision' },
2890
+ { key: 'esc', label: 'back' },
2891
+ ],
2892
+ );
2893
+ paneUi = { ...paneUi, view: null };
2894
+ }
2895
+ if (paneUi.view === 'characters')
2896
+ return viewFrame(
2897
+ 'Characters',
2898
+ sheetView(
2899
+ lanesNow.map((l) => l.name),
2900
+ els,
2901
+ { surface: faulted[paneSurface] ? 'still' : paneSurface, motion: harness().motion },
2902
+ ),
2903
+ els,
2904
+ { onBack: back },
2905
+ );
2906
+ const order = () => {
2907
+ const { atWork, resting } = lanesAtWork(state, model.queue ?? [], {
2908
+ ...(loopView.laneNotes ?? {}),
2909
+ ...artNow(now, live).moves,
2910
+ });
2911
+ return selectable(needs, [...atWork, ...resting]);
2912
+ };
2913
+ return board(
2914
+ {
2915
+ state,
2916
+ status: model.status ?? null,
2917
+ loop: loopView,
2918
+ needs,
2919
+ live,
2621
2920
  held: [...held.values()],
2622
2921
  requests: model.requests?.open ?? [],
2623
- ui: paneUi,
2624
- status: model.status ?? null,
2625
- // VIEW-6: what each lane owns, for the selected lane's detail.
2922
+ leadBusy: Boolean(leadTurn),
2923
+ journal: journalNow(),
2924
+ maps: storyMaps,
2925
+ combined: combinedNow(),
2926
+ usage,
2927
+ // LANES-3: what each lane owns, for the selected lane's detail.
2626
2928
  paths: {
2627
2929
  lead: model.check?.lead?.paths ?? [],
2628
2930
  ...Object.fromEntries(
2629
2931
  Object.entries(model.check?.lanes ?? {}).map(([n, l]) => [n, l.paths ?? []]),
2630
2932
  ),
2631
2933
  },
2632
- art: artNow(now, liveNow(now)),
2633
- combined: combinedNow(),
2634
- codeMap,
2635
- trail: trailData,
2636
- glow: glowOf(touches, now),
2637
- surface: paneSurface,
2638
- columns: paneColumns,
2934
+ trouble: Object.fromEntries(
2935
+ lanesNow.map((l) => {
2936
+ const f = (model.adapters ?? []).some((a) => a.lanes) ? factsOf(l) : null;
2937
+ return [l.name, { refused: troubles.get(l.name) ?? [], owed: f?.cardsOwed ?? [] }];
2938
+ }),
2939
+ ),
2940
+ art: artNow(now, live),
2941
+ now,
2942
+ ui: paneUi,
2639
2943
  placement: e.props.placement,
2640
- story: storyOpen ? storyNow(storyOpen, now, usage) : null,
2944
+ columns: paneColumns,
2945
+ rows: paneRows,
2641
2946
  },
2642
- $.ui.resolve(e),
2947
+ els,
2643
2948
  {
2644
- onTab: (tab) => {
2645
- paneUi = { ...paneUi, tab };
2646
- $.ui.invalidate('ui.render');
2647
- act?.readMaps().then(() => $.ui.invalidate('ui.render'));
2648
- },
2649
- onDecision: (i) => {
2650
- paneUi = { ...paneUi, decision: i };
2651
- $.ui.invalidate('ui.render');
2652
- },
2653
- onMapStory: (id) => {
2654
- paneUi = { ...paneUi, mapStory: id, mapFile: null };
2655
- $.ui.invalidate('ui.render');
2656
- act?.readMaps().then(() => $.ui.invalidate('ui.render'));
2657
- },
2658
- onMapFile: (path) => {
2659
- paneUi = { ...paneUi, mapFile: path };
2660
- $.ui.invalidate('ui.render');
2661
- },
2662
- // MAP-3: the file in Context Graph's own view, through the command its adapter names.
2663
- onOpenFile: (path) => {
2664
- const command = codeMap?.open?.command;
2665
- if (!command) return;
2666
- $.command.run({ command, args: path }).catch((err) => {
2667
- notice = `Couldn't open ${path}: ${err?.message ?? err}`;
2668
- $.ui.invalidate('ui.render');
2669
- });
2670
- },
2671
- onFilter: (state) => {
2672
- paneUi = { ...paneUi, filter: paneUi.filter === state ? null : state };
2949
+ onNeed: (id, line) => act?.[id]?.(line),
2950
+ onDecide: (i, line) => act?.decide(line),
2951
+ onSelect: (sel) => {
2952
+ paneUi = { ...paneUi, sel, ...(sel.kind === 'need' ? { need: Number(sel.id) } : {}) };
2673
2953
  $.ui.invalidate('ui.render');
2674
2954
  },
2675
2955
  onMove: (step) => {
2676
- if (!lanesNow.length) return;
2677
- const at = lanesNow.findIndex((l) => l.name === paneUi.selected);
2678
- const to =
2679
- at < 0
2680
- ? step > 0
2681
- ? 0
2682
- : lanesNow.length - 1
2683
- : (at + step + lanesNow.length) % lanesNow.length;
2684
- paneUi = { ...paneUi, selected: lanesNow[to].name };
2956
+ const sel = moveSelection(order(), paneUi.sel, step);
2957
+ if (!sel) return;
2958
+ paneUi = { ...paneUi, sel, ...(sel.kind === 'need' ? { need: Number(sel.id) } : {}) };
2685
2959
  $.ui.invalidate('ui.render');
2686
- // VIEW-6: Enter opens the selected lane's story: the focus waits on its Open button.
2687
- if (
2688
- lanesNow[to].story ||
2689
- (model.state?.stories ?? []).some((s) => s.lane === lanesNow[to].name)
2690
- )
2691
- $.ui.focus({ requestId: PANE_ID, key: 'open-story' }).catch(() => {});
2960
+ // UI-8: Enter opens what's selected: the focus waits on its button.
2961
+ $.ui
2962
+ .focus({ requestId: PANE_ID, key: sel.kind === 'need' ? 'need-why' : 'open-story' })
2963
+ .catch(() => {});
2692
2964
  },
2693
2965
  onOpen: (lane) => act?.openStory(lane),
2694
- // TRACE-2: a cell selected by its keys or the requirement list.
2695
- onCell: (cell) => {
2696
- paneUi = { ...paneUi, cell };
2966
+ onView: (view, at = null) => {
2967
+ const reqs = at?.story?.requirements ?? [];
2968
+ paneUi = {
2969
+ ...paneUi,
2970
+ view,
2971
+ ...(view === 'trail' && reqs.length ? { cell: reqs[0] } : {}),
2972
+ ...(view === 'code' && at?.story ? { mapStory: at.story.id, mapFile: null } : {}),
2973
+ };
2697
2974
  $.ui.invalidate('ui.render');
2975
+ act?.readMaps().then(() => $.ui.invalidate('ui.render'));
2698
2976
  },
2699
- story: {
2700
- onBack: () => act?.closeStory(),
2701
- onFile: (file) => {
2702
- paneUi = { ...paneUi, file };
2703
- $.ui.invalidate('ui.render');
2704
- },
2705
- // JOIN-4: a file in the adapter's own view, through the command it names.
2706
- onOpenIn: (adapter, path) =>
2707
- $.command.run({ command: adapter.open.command, args: path }).catch((err) => {
2708
- notice = `Couldn't open ${path} in ${adapter.name}: ${err?.message ?? err}`;
2709
- $.ui.invalidate('ui.render');
2710
- }),
2711
- onAct: (id) => {
2712
- const lane = lanesNow.find((l) => l.name === storyOpen?.lane);
2713
- if (lane) act?.laneAct(id, lane);
2714
- },
2715
- },
2716
- onNeed: (id, line) => act?.[id]?.(line),
2717
2977
  onLane: (id, lane) => act?.laneAct(id, lane),
2718
2978
  onSearch: (search) => {
2719
- paneUi = { ...paneUi, search };
2979
+ paneUi = { ...paneUi, search, filtering: Boolean(search) || paneUi.filtering };
2980
+ $.ui.invalidate('ui.render');
2981
+ },
2982
+ onFocusSearch: () => {
2983
+ paneUi = { ...paneUi, filtering: true };
2720
2984
  $.ui.invalidate('ui.render');
2985
+ $.ui.focus({ requestId: PANE_ID, key: 'filter' }).catch(() => {});
2721
2986
  },
2722
- onFocusSearch: () => $.ui.focus({ requestId: PANE_ID, key: 'filter' }).catch(() => {}),
2723
2987
  },
2724
2988
  );
2725
2989
  });
2726
2990
 
2727
- // VIEW-6: Escape on a story goes back to the lanes; on the lanes, it closes the pane.
2991
+ // UI-6: Escape on a full view goes back to the panels; on the panels, it closes the pane.
2728
2992
  on('ui.close', async ($, e, next) => {
2729
- if (closeGoesBack(e, PANE_ID, paneUi)) {
2730
- act?.closeStory();
2993
+ if (escapeGoesBack(e, PANE_ID, paneUi)) {
2994
+ if (paneUi.view === 'story') act?.closeStory();
2995
+ else {
2996
+ paneUi = { ...paneUi, view: null };
2997
+ $.ui.invalidate('ui.render');
2998
+ }
2731
2999
  return;
2732
3000
  }
3001
+ if (e.id === PANE_ID) paneOpen = false;
3002
+ return next(e);
3003
+ });
3004
+
3005
+ // UI-12: a surface module that fails draws everything still on that surface from then on.
3006
+ on('ui.fault', async ($, e, next) => {
3007
+ if (String(e.module ?? '').includes('surface/')) {
3008
+ faulted[e.surface] = true;
3009
+ $.ui.invalidate('ui.render');
3010
+ }
2733
3011
  return next(e);
2734
3012
  });
2735
3013
 
@@ -2744,12 +3022,25 @@ export function register(on) {
2744
3022
  }),
2745
3023
  );
2746
3024
 
2747
- // BAND-2: absent when nothing waits. Its lines go above whatever else the band holds (another
2748
- // plugin's lines, such as Context Graph's, or Claude Code's own), which it keeps.
3025
+ // UI-9: the band speaks only when it's needed: what needs the person, else one line while the
3026
+ // build moves, else nothing. Its lines go above whatever else the band holds (another plugin's, such
3027
+ // as Context Graph's, or Claude Code's own), which it keeps.
2749
3028
  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
2750
- const lines = linesNow(await $.clock.now());
2751
- if (!lines.length || !act) return next(e);
2752
- const ours = band(lines, $.ui.resolve(e), (id, line) => act[id](line));
3029
+ if (!act) return next(e);
3030
+ const now = await $.clock.now();
3031
+ const ours = bandOf(
3032
+ {
3033
+ state: stateNow(),
3034
+ status: model.status ?? null,
3035
+ loop: { ...loopNow(now), queue: model.queue ?? [] },
3036
+ needs: needsOf(linesNow(now)),
3037
+ leadBusy: Boolean(leadTurn),
3038
+ columns: e.props.bodyColumns,
3039
+ },
3040
+ $.ui.resolve(e),
3041
+ (id, line) => act[id](line),
3042
+ );
3043
+ if (!ours) return next(e);
2753
3044
  const below = await next(e);
2754
3045
  return below ? $.ui.resolve(e).Box({ flexDirection: 'column', children: [ours, below] }) : ours;
2755
3046
  });