bullswarm 0.38.1 → 0.38.2

package/AGENTS.md

@@ -61,7 +61,7 @@ before doing anything. Their readers and stored formats are unchanged.
 5. Workflow dispatches honor the same guarantees as single runs, in
    `src/workflow/v2-dispatch.js`: `BULLSWARM_DEPTH` is checked and propagated
    (`assertDepthAllowed` and `childDepthEnv` in `dispatchV2Action`), pools at
-   a spent window are excluded (`preparePools`), and a sign-in failure is
+   a spent window are excluded (`preparePools`, in `dispatch-pools.js`), and a sign-in failure is
    failure kind `auth`: the step's retry skips every pool in the dead
    credential's group (`upstreamGroupOf`), a choice held for that dispatch
    only and never stored. A step's `route`, the run's pin and the step's

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.38.2 — Three large files split into one-concept modules
+
+- internal: the three largest workflow files are split into one-concept
+  modules, with no behaviour change. `src/workflow/dashboard.js` goes from
+  3,613 lines to 2,002 plus 24 `dashboard-*.js` modules (1,837 lines);
+  `step-model.js` from 2,540 to 588 plus 18 `step-model-*.js` modules (2,213
+  lines); `v2-dispatch.js` from 2,039 to 1,191 plus 8 `dispatch-*.js` modules
+  (917 lines). Each old file still exports the names the product reads from
+  it; names only tests read are now imported from the module that holds them.
+
 ## 0.38.1 — Fewer wasted retries, honest no-pool reasons
 
 - no eligible pool: when a pool lacks a tier only because free models are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.38.1",
+  "version": "0.38.2",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {

package/src/workflow/dashboard-agent-detail.js

@@ -0,0 +1,117 @@
+// The agent detail pane: a selected attempt's route, prompt, activity,
+// outcome and artifacts, with the task and outcome previews it reads.
+import { readFileSync, existsSync } from 'node:fs';
+import { glyphs } from '../lib/glyphs.js';
+import { stepStatusLabel, actionRoleLabel, statusIcon } from './dashboard-status.js';
+import { compactUsage, reasoningText } from './dashboard-value-text.js';
+
+export function agentDetailLines(model, width, spinnerFrame) {
+  const agent = model.selectedAgent;
+  if (!agent) {
+    const lines = ['No agent selected.', '', 'Planned steps in this phase:'];
+    for (const action of model.selectedPhase.actions) {
+      const blocked = (model.selectedPhase.blockedActions ?? []).find((entry) => entry.id === action.id);
+      lines.push(blocked
+        ? `${glyphs().blocked} ${action.id} · ${actionRoleLabel(action)} · never dispatched`
+        : `${statusIcon(action.status, spinnerFrame)} ${action.id} · ${actionRoleLabel(action)} · ${stepStatusLabel(action)}`);
+      if (blocked) {
+        lines.push(`  blocked by ${blocked.blockedBy.length ? blocked.blockedBy.join(', ') : 'a failed dependency'}`);
+      }
+    }
+    if (!model.selectedPhase.actions.length) lines.push('· waiting for the orchestrator to add work');
+    return wrapLines(lines, width);
+  }
+  const { action, attempt, active } = agent;
+  const liveActions = active?.lastActions ?? attempt?.lastActions ?? [];
+  const routing = attempt?.routing;
+  const reasoning = reasoningText(attempt) || reasoningText(active);
+  const lines = [
+    `${statusIcon(agent.status, spinnerFrame)} ${agent.status} · ${agent.model}${reasoning ? ` · ${reasoning}` : ''}`,
+    // V1 stores the tier on the attempt; V2 stores it under routing. Reading
+    // only the V1 shape made every V2 attempt render `effort auto`, right
+    // beside the reasoning level it was resolved against.
+    `${agent.pool} · attempt ${attempt?.attemptNumber ?? active?.attempt ?? 1} · effort ${attempt?.effort ?? routing?.effort ?? active?.effort ?? 'auto'}${reasoning ? ` · reasoning ${reasoning}` : ''}`,
+    '',
+    `Step · ${action.id} · ${actionRoleLabel(action)}`,
+  ];
+  if (routing?.reason) lines.push(`Route: ${routing.reason}`);
+  if (attempt?.startedAt ?? active?.startedAt) lines.push(`Started: ${attempt?.startedAt ?? active.startedAt}`);
+  if (attempt?.finishedAt) lines.push(`Finished: ${attempt.finishedAt}`);
+  if (active?.lastActivityAt) lines.push(`Last activity: ${active.lastActivityAt} · ${active.outputBytesObserved ?? 0} bytes`);
+  if (active?.stall?.status === 'suspected_stalled') {
+    lines.push(`${glyphs().warn} Suspected stalled: ${active.stall.silentForSec}s without evidence; never auto-killed`);
+  }
+  if (attempt?.failureReason) lines.push(`Failure: ${attempt.failureReason}`);
+  const taskFile = attempt?.taskFile ?? active?.taskFile;
+  const prompt = taskPreview(taskFile);
+  lines.push('', `Prompt${prompt.length ? ` · ${prompt.length} lines shown` : ''}`);
+  if (prompt.length) lines.push(...prompt.map((line) => `  ${line}`));
+  else lines.push('  unavailable');
+  const historicalActionIds = new Set(model.events
+    .filter((event) => event.type === 'attempt.agent_action'
+      && event.payload?.actionId === action.id
+      && (attempt?.attemptNumber == null || event.payload?.attemptNumber === attempt.attemptNumber))
+    .map((event) => event.payload?.agentAction?.id)
+    .filter(Boolean));
+  const totalActions = active?.actionCount ?? attempt?.actionCount
+    ?? Math.max(liveActions.length, historicalActionIds.size);
+  const activityLabel = totalActions > liveActions.length
+    ? `Activity · last ${liveActions.length} of ${totalActions}`
+    : 'Activity';
+  lines.push('', compactUsage(attempt?.usage), '', activityLabel);
+  if (!liveActions.length) lines.push('· waiting for semantic action events');
+  const firstVisibleActionNumber = Math.max(1, totalActions - liveActions.length + 1);
+  for (const [index, step] of liveActions.entries()) {
+    lines.push(`#${firstVisibleActionNumber + index} ${statusIcon(step.status, spinnerFrame)} ${step.kind} · ${step.status}`);
+    if (step.summary) lines.push(`  ${step.summary}`);
+  }
+  const output = model.state.outputs?.[action.id];
+  const outcome = outcomePreview(attempt?.outFile ?? active?.outFile ?? output?.outFile, output);
+  if (outcome.length) lines.push('', 'Outcome', ...outcome.map((line) => `  ${line}`));
+  lines.push('', 'Artifacts:');
+  lines.push(`task: ${attempt?.taskFile ?? active?.taskFile ?? '—'}`);
+  lines.push(`output: ${attempt?.outFile ?? active?.outFile ?? '—'}`);
+  return wrapLines(lines, width);
+}
+
+export function taskPreview(path, limit = 6) {
+  if (!path || !existsSync(path)) return [];
+  try {
+    const all = readFileSync(path, 'utf8').split(/\r?\n/).filter((line) => line.trim());
+    const shown = all.slice(0, limit);
+    if (all.length > limit) shown.push(`… ${all.length - limit} more lines`);
+    return shown;
+  } catch {
+    return [];
+  }
+}
+
+export function outcomePreview(path, output, maxChars = 64 * 1024) {
+  let text = '';
+  try {
+    if (path && existsSync(path)) text = readFileSync(path, 'utf8');
+  } catch { /* fall through to the durable state preview */ }
+  if (!text && typeof output?.outputText === 'string') text = output.outputText;
+  if (!text && output?.verify) text = JSON.stringify(output.verify, null, 2);
+  if (!text.trim()) return [];
+  const truncated = text.length > maxChars;
+  const lines = text.slice(0, maxChars).split(/\r?\n/);
+  if (truncated) lines.push('… outcome truncated in TUI; open the artifact for the complete result');
+  return lines;
+}
+
+export function wrapLines(lines, width) {
+  const out = [];
+  for (const line of lines) {
+    if (!line) { out.push(''); continue; }
+    let rest = String(line);
+    while (rest.length > width) {
+      let split = rest.lastIndexOf(' ', width);
+      if (split < Math.floor(width * 0.5)) split = width;
+      out.push(rest.slice(0, split));
+      rest = rest.slice(split).trimStart();
+    }
+    out.push(rest);
+  }
+  return out;
+}

package/src/workflow/dashboard-ansi.js

@@ -0,0 +1,83 @@
+// The ANSI text primitives every dashboard page paints with: the escape
+// introducer, visible length, truncation, dim, the palette tint, bold and
+// inverse, and whether colour meters are on (meterAnsi, blank).
+import { asciiGlyphsPreferred } from '../lib/glyphs.js';
+import { METER_COLORS } from './usage-view.js';
+
+const ESC = '\x1b[';
+
+export function dimText(value, width) {
+  return `\x1b[2m${truncate(value, width)}\x1b[0m`;
+}
+
+// ------------------------------------------------- the palette on the page
+//
+// The pages name a palette role — or the stable hex returned by dash-kit for a
+// pool/model series — and never invent a colour. Every value comes from
+// METER_COLORS in usage-view.js, the one palette the product has; this file
+// adds none. Colour is off wherever the meters are off, so an ascii terminal
+// and a plain-text capture read the same words with no escapes in them.
+
+const SGR_RESET = '\x1b[0m';
+const SGR_BOLD = '\x1b[1m';
+const SGR_NO_BOLD = '\x1b[22m';
+
+const rgbOf = (hex) => {
+  const value = Number.parseInt(String(hex).slice(1), 16);
+  return [(value >> 16) & 255, (value >> 8) & 255, value & 255];
+};
+
+/** `text` in the palette's `role`, or untouched where colour is off. */
+export function tint(text, role) {
+  const body = String(text ?? '');
+  if (!body || !meterAnsi()) return body;
+  const hex = typeof role === 'string' && role.startsWith('#') ? role : METER_COLORS[role];
+  if (typeof hex !== 'string' || !/^#[0-9a-f]{6}$/i.test(hex)) return body;
+  return `\x1b[38;2;${rgbOf(hex).join(';')}m${body}${SGR_RESET}`;
+}
+
+/** A key figure or a key name, bold — ASCII mode keeps bold, dim and inverse. */
+function strong(text) {
+  const body = String(text ?? '');
+  if (!body) return body;
+  return `${SGR_BOLD}${body}${SGR_NO_BOLD}`;
+}
+
+/**
+ * The cursor row, inverse as the tab row: `\x1b[7m … \x1b[27m`. A painted row
+ * resets its own cells, so reverse video is re-armed after each reset and the
+ * whole row stays inverse. SGR only — the row keeps its text and its width —
+ * and kept in ASCII mode, which drops colour but keeps bold, dim and inverse.
+ */
+function inverseText(text) {
+  const body = String(text ?? '');
+  if (!body) return body;
+  return `\x1b[7m${body.replace(/\x1b\[0m/g, '\x1b[0m\x1b[7m')}\x1b[27m`;
+}
+
+export function truncate(value, width) {
+  const text = String(value ?? '');
+  return text.length <= width ? text : `${text.slice(0, Math.max(0, width - 1))}…`;
+}
+
+const ANSI_SGR = /\x1b\[[0-9;?]*[A-Za-z]/g;
+
+/** How many columns a painted line really occupies. */
+export const visibleLength = (value) => String(value ?? '').replace(ANSI_SGR, '').length;
+
+/** Meters are background-coloured cells; an ascii terminal gets the plain bar. */
+export function meterAnsi() {
+  return !asciiGlyphsPreferred();
+}
+
+/** The blank a figure with no measurable source is painted as. */
+export function blank() {
+  return asciiGlyphsPreferred() ? '-' : '—';
+}
+
+export {
+  ESC,
+  strong,
+  inverseText,
+  ANSI_SGR,
+};

package/src/workflow/dashboard-cancel.js

@@ -0,0 +1,37 @@
+// Asking a run to stop: the operator's cancellation request, written for the
+// kernel to honour (requestCancel).
+import { V2_TERMINAL_STATUSES } from './status.js';
+import { existsSync } from 'node:fs';
+import { readJsonForUpdate, writeJsonAtomic } from '../lib/fsjson.js';
+import { join } from 'node:path';
+import { resolveRunId, isLegacyRunState } from './short-id.js';
+import { appendEvent } from './events.js';
+
+export function requestCancel(bullswarmDir, token, { source = 'api', requesterPid = process.pid } = {}) {
+  const resolved = resolveRunId(bullswarmDir, token);
+  if (!resolved) throw new Error(`no run found for "${token}"`);
+  const statePath = join(resolved.runDir, 'state.json');
+  if (!existsSync(statePath)) throw new Error(`run "${token}" has no state.json`);
+  const state = readJsonForUpdate(statePath, 'workflow state');
+  // A legacy run has no kernel to ask, so nothing is written and nothing is
+  // claimed: the caller is told what it is and left alone.
+  if (isLegacyRunState(state)) return { ...resolved, legacy: true, alreadyFinished: true };
+  if (V2_TERMINAL_STATUSES.has(state.lifecycle.status)) return { ...resolved, state, alreadyFinished: true };
+  const requestedAt = new Date().toISOString();
+  state.cancellation = {
+    requested: true,
+    requestedAt,
+    reason: 'operator requested stop',
+    source,
+    requesterPid,
+  };
+  appendEvent(resolved.runDir, state, 'workflow.cancellation_requested', {
+    requestedAt,
+    reason: state.cancellation.reason,
+    source,
+    requesterPid,
+  });
+  // The operator owns this intent file; only the kernel owns state.json.
+  writeJsonAtomic(join(resolved.runDir, 'cancellation.json'), state.cancellation);
+  return { ...resolved, state, alreadyFinished: false };
+}

package/src/workflow/dashboard-clamp.js

@@ -0,0 +1,9 @@
+// The one number helper the dashboard's windows and cursors share (clamp).
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, Number(value) || 0));
+}
+
+export {
+  clamp,
+};

package/src/workflow/dashboard-clipboard.js

@@ -0,0 +1,22 @@
+// The local clipboard a copied screen falls back to when a terminal will not
+// take OSC 52 (writeClipboard).
+import { spawnSync } from 'node:child_process';
+
+/**
+ * The local clipboard, for a terminal that will not take OSC 52: pbcopy on
+ * macOS, wl-copy under Wayland. Returns which tool carried it, or why none
+ * did — the message on screen names one or the other, never both.
+ */
+export function writeClipboard(text, { platform = process.platform, env = process.env, run = spawnSync } = {}) {
+  const tools = [];
+  if (platform === 'darwin') tools.push('pbcopy');
+  if (env.WAYLAND_DISPLAY) tools.push('wl-copy');
+  if (env.DISPLAY) tools.push('xclip');
+  for (const tool of tools) {
+    try {
+      const result = run(tool, tool === 'xclip' ? ['-selection', 'clipboard'] : [], { input: text });
+      if (!result?.error && (result?.status === 0 || result?.status == null)) return { ok: true, tool };
+    } catch { /* try the next one */ }
+  }
+  return { ok: false, tool: null, reason: tools.length ? `${tools.join(' and ')} failed` : 'no pbcopy, wl-copy or xclip on this machine' };
+}

package/src/workflow/dashboard-details.js

@@ -0,0 +1,60 @@
+// The static details pane for one run: the legacy line, or a v2 run's stages,
+// planner, requirements and recent events (renderDetails).
+import { isLegacyRunState, legacyRunLine } from './short-id.js';
+import { presentationStageStatus, projectV2DependencyStages } from './v2-presentation.js';
+import { isProgramWorkflow } from './execution-policy.js';
+import { ESC } from './dashboard-ansi.js';
+import { keyHint } from './dashboard-keys.js';
+import { stepStatusLabel, statusIcon } from './dashboard-status.js';
+
+export function renderDetails(row, { interactive = true } = {}) {
+  const state = row?.state ?? {};
+  // A legacy run has no readable graph left, so the pane says exactly what the
+  // CLI says and stops there.
+  if (row?.legacy || isLegacyRunState(state)) {
+    return [
+      `${ESC}2J${ESC}H`,
+      legacyRunLine({ shortId: row?.shortId, runId: row?.runId, runDir: row?.runDir }),
+      ...(interactive ? ['', ` ${keyHint('out')} · r refresh · ${keyHint('detach')}`] : []),
+    ].join('\n');
+  }
+  return renderV2Details(row, { interactive });
+}
+
+function renderV2Details(row, { interactive = true } = {}) {
+  const state = row.state;
+  const lines = [
+    `${ESC}2J${ESC}H`,
+    ` bullswarm · ${row.shortId ?? state.shortId ?? state.runId}`,
+    '',
+    ` status: ${state.lifecycle.status}`,
+    ...(isProgramWorkflow(state) ? [` mode:   program in ${state.config.settings.workspaceMode ?? 'shared'} workspace; requirement evidence reported separately`] : []),
+    ` goal:   ${state.intent.goal}`,
+    ` dir:    ${row.runDir ?? '—'}`,
+    '',
+    ' presentation stages:',
+  ];
+  for (const stage of isProgramWorkflow(state) ? projectV2DependencyStages(state) : state.presentation.stages) {
+    const progress = presentationStageStatus(stage, state.actions);
+    const status = stage.completedAt ? (progress.successful ? 'completed' : 'completed with gaps') : stage.startedAt ? 'running' : 'not started';
+    lines.push(`   ${statusIcon(status)} ${stage.label} · ${progress.completed}/${progress.total} · ${status}`);
+    for (const id of stage.actionIds) {
+      const action = state.actions.find((entry) => entry.id === id);
+      lines.push(`     ${statusIcon(action?.status)} ${id} · ${stepStatusLabel(action)}`);
+    }
+  }
+  if (!state.presentation.stages.length) lines.push('   planning has not created the first program yet');
+  lines.push('', ' workflow planner:');
+  lines.push(`   ${statusIcon(state.planner.status)} ${state.planner.status} · ${state.planner.turns} checkpoint${state.planner.turns === 1 ? '' : 's'}`);
+  lines.push(`   latest: ${state.planner.lastDecision?.summary ?? 'not available'}`);
+  lines.push('', ' requirements:');
+  for (const requirement of Object.values(state.ledger.requirements)) {
+    lines.push(`   ${statusIcon(requirement.status)} ${requirement.id} · ${requirement.status}`);
+  }
+  lines.push('', ' recent events:');
+  for (const event of (row.events ?? []).slice(-12)) lines.push(`   #${event.sequence} ${event.type}`);
+  if (!(row.events ?? []).length) lines.push('   none');
+  if (row.kernelStderrTail?.length) lines.push('', ' kernel log: available');
+  if (interactive) lines.push('', ` ${keyHint('out')} · c stop · r refresh · ${keyHint('detach')}`);
+  return lines.join('\n');
+}

package/src/workflow/dashboard-frame.js

@@ -0,0 +1,134 @@
+// The frame and window builder: lines that remember where each clickable part
+// was painted, a view module's regions shifted into place, and the window a
+// body is drawn through.
+import { columns } from './dash-kit.js';
+import { visibleLength } from './dashboard-ansi.js';
+import { clamp } from './dashboard-clamp.js';
+
+/**
+ * A `columns()` band painted into the body at `indent`, each column clickable
+ * over its own rows. `cells` carry an optional `action`; a cell columns()
+ * dropped for want of room simply has no region.
+ */
+function pushColumns(body, cells, { width, gap = 2, indent = 1 } = {}) {
+  const lines = columns(cells, { width, gap });
+  const base = body.lines.length;
+  for (const line of lines) body.push(`${' '.repeat(indent)}${line}`);
+  for (const [index, column] of (lines.meta?.columns ?? []).entries()) {
+    const action = cells[index]?.action;
+    if (!action) continue;
+    // A cell may name the rows it reacts to — a tile is one click on its
+    // number, not three on a number, a label and a caption.
+    const only = cells[index]?.actionRows ?? null;
+    for (let row = 0; row < column.rows; row += 1) {
+      if (only && !only.includes(row)) continue;
+      const painted = visibleLength(body.lines[base + row] ?? '');
+      const x1 = column.x + indent;
+      const x2 = Math.min(painted, x1 + Math.max(1, column.width) - 1);
+      if (x2 >= x1) body.regions.push({ x1, x2, y: base + row + 1, action });
+    }
+  }
+  return lines;
+}
+
+/** A line builder that remembers where each clickable part was painted. */
+function frameBuilder() {
+  const builder = {
+    lines: [],
+    regions: [],
+    push(text = '') { builder.lines.push(text); return builder; },
+    /** A row that reacts to a click anywhere on it. */
+    row(text = '', action = null) {
+      builder.lines.push(text);
+      if (action) {
+        builder.regions.push({ x1: 1, x2: Math.max(1, visibleLength(text)), y: builder.lines.length, action });
+      }
+      return builder;
+    },
+    /** One line from parts: `{ text, action }` makes that text clickable. */
+    parts(parts) {
+      let column = 1;
+      let text = '';
+      for (const part of parts) {
+        const span = visibleLength(part.text);
+        if (part.action) {
+          builder.regions.push({ x1: column, x2: Math.max(column, column + span - 1), y: builder.lines.length + 1, action: part.action });
+        }
+        column += span;
+        text += part.text;
+      }
+      builder.lines.push(text);
+      return builder;
+    },
+    /** A dash-kit `{ text, regions }` row, its regions shifted by `indent`. */
+    kit({ text = '', regions = [] } = {}, indent = 0) {
+      builder.lines.push(`${' '.repeat(indent)}${text}`);
+      for (const region of regions) {
+        builder.regions.push({
+          x1: region.x + indent,
+          x2: region.x + indent + Math.max(1, region.width) - 1,
+          y: builder.lines.length,
+          action: region.action,
+        });
+      }
+      return builder;
+    },
+  };
+  return builder;
+}
+
+/**
+ * A view module's lines and its regions, appended to a builder.
+ *
+ * budget-view, fleet-view, stats-view and history-view each return regions as
+ * `{ x, y, width, action }`, where `y` is the 1-based row of the view's own
+ * lines the region was painted on.  The shell only has to shift that row by
+ * where the view landed in the body, so a click always reaches the row it was
+ * drawn on instead of the shell searching the text for it.  A region without
+ * a usable row is dropped rather than made to fire the wrong action.
+ */
+function pushView(builder, view) {
+  const lines = Array.isArray(view) ? view : (view?.lines ?? []);
+  const regions = Array.isArray(view) ? [] : (view?.regions ?? []);
+  const base = builder.lines.length;
+  for (const line of lines) builder.lines.push(line);
+  for (const region of regions) {
+    if (!region?.action || !(region.width > 0)) continue;
+    const row = Number(region.y);
+    if (!Number.isInteger(row) || row < 1 || row > lines.length) continue;
+    builder.regions.push({
+      x1: region.x, x2: region.x + region.width - 1, y: base + row, action: region.action,
+    });
+  }
+  return builder;
+}
+
+/** The window a body is drawn through, and its `first–last/total` label. */
+function windowOf(body, { height, scroll = 0 } = {}) {
+  const total = body.lines.length;
+  const capacity = Math.max(1, Number(height) || 1);
+  const offset = clamp(scroll, 0, Math.max(0, total - capacity));
+  const end = Math.min(total, offset + capacity);
+  const scrolled = offset > 0 || total > end;
+  return { offset, end, total, position: scrolled ? ` · ${offset + 1}–${end}/${total}` : '' };
+}
+
+/** Copies a windowed body into the frame, moving its hit regions down with it. */
+function drawWindow(frame, body, window) {
+  const base = frame.lines.length;
+  for (let index = window.offset; index < window.end; index += 1) frame.lines.push(body.lines[index]);
+  for (const region of body.regions) {
+    if (region.y > window.offset && region.y <= window.end) {
+      frame.regions.push({ ...region, y: base + (region.y - window.offset) });
+    }
+  }
+  return frame;
+}
+
+export {
+  pushColumns,
+  frameBuilder,
+  pushView,
+  windowOf,
+  drawWindow,
+};

package/src/workflow/dashboard-integration.js

@@ -0,0 +1,80 @@
+// The agent integration block: each agent's skill, awareness and mod state,
+// what an install changed, and the commands that operate the product.
+import { glyphs } from '../lib/glyphs.js';
+import { rule } from './dash-kit.js';
+import { dimText, truncate, visibleLength } from './dashboard-ansi.js';
+
+/** The one-line commands that operate the product, as Runs lists them. */
+const DASHBOARD_COMMANDS = Object.freeze([
+  'bullswarm run',
+  'bullswarm workflow goal "<goal>"',
+  'bullswarm workflow watch <id> --next',
+  'bullswarm workflow reindex',
+  'bullswarm setup',
+  'bullswarm doctor',
+]);
+
+/** `skill ✓ · awareness ✓`, plus the mod link and hooks flag for Claude. */
+function integrationAgentLine(entry) {
+  const ok = glyphs().ok;
+  const mark = (installed) => (installed ? ok : '—');
+  const parts = [
+    `skill ${mark(entry.skill?.status === 'installed')}`,
+    `awareness ${mark(entry.awareness === true)}`,
+  ];
+  if (entry.mod !== undefined) {
+    parts.push(`mod ${mark(entry.mod?.status === 'installed')}`, `hooks ${mark(entry.hooksFlag === true)}`);
+  }
+  return `${String(entry.agent ?? '?').padEnd(8)} ${parts.join(' · ')}`;
+}
+
+/** What `installIntegration` changed, agent by agent. */
+function installResultLines(result) {
+  const lines = [' install results'];
+  for (const change of result?.changes ?? []) {
+    const parts = [
+      `skill ${change.skill?.changed ? 'installed' : 'already installed'}`,
+      `awareness ${change.awareness?.reason ?? 'unchanged'}`,
+    ];
+    if (change.mod) parts.push(`mod ${change.mod.changed ? 'linked' : 'already linked'}`);
+    if (change.hooksFlag) parts.push(`hooks flag ${change.hooksFlag.reason ?? 'unchanged'}`);
+    lines.push(`   ${change.agent} · ${parts.join(' · ')}`);
+  }
+  if (lines.length === 1) lines.push('   nothing to change');
+  return lines;
+}
+
+function integrationLines(model, opts, body) {
+  const { width } = opts;
+  body.push('');
+  body.push(rule('agents', null, width));
+  const installed = model.integration?.ok === true;
+  const button = installed ? `[installed ${glyphs().ok}]` : '[install]';
+  const prefix = ' agent integration  ';
+  const suffix = installed ? ' · every agent already has it' : ' · i installs the skill and the awareness block for every agent';
+  const fits = visibleLength(prefix) + visibleLength(button) + visibleLength(suffix) <= width;
+  body.parts([
+    { text: prefix },
+    { text: button, action: installed ? null : { kind: 'install' } },
+    { text: fits ? dimText(suffix, Math.max(0, width - visibleLength(prefix) - visibleLength(button))) : '' },
+  ]);
+  if (!model.integration) {
+    body.push(dimText('   reading the agent integration…', width));
+  } else {
+    for (const entry of model.integration.agents ?? []) {
+      body.push(dimText(`   ${integrationAgentLine(entry)}`, width));
+    }
+    if (model.installResult) {
+      for (const line of installResultLines(model.installResult)) body.push(dimText(truncate(line, width), width));
+    }
+  }
+
+  body.push('');
+  body.push(rule('run it', null, width));
+  for (const command of DASHBOARD_COMMANDS) body.push(dimText(`   ${command}`, width));
+  return ' bullswarm · runs';
+}
+
+export {
+  integrationLines,
+};

package/src/workflow/dashboard-keys.js

@@ -0,0 +1,49 @@
+// The dashboard's keys: every binding with the words its hint uses
+// (DASHBOARD_KEYS), and the hint and key-press tests built on it.
+
+// Keep navigation wording and bindings in one place. Rendering and input use
+// the same vocabulary so a hint never describes a different action.
+const keyRow = (keys, label, bindings) => Object.freeze({ keys, label, bindings: Object.freeze(bindings) });
+
+// 0.33.0 rebinds three keys the 0.32 viewer used: `r` was refresh (the 1 s
+// timer already refreshes, so nothing is lost), `b` was move out (Esc and the
+// left arrow still are), and `Tab` was the next workflow (Shift+Tab still
+// cycles workflows, and Tab now walks a page's sub-tabs). The changelog
+// records the change; the Help page names every key below.
+export const DASHBOARD_KEYS = Object.freeze({
+  home: keyRow('h', 'Home', ['h']),
+  runs: keyRow('r', 'Runs', ['r']),
+  budget: keyRow('b', 'Budget', ['b']),
+  stats: keyRow('s', 'Stats', ['s']),
+  history: keyRow('y', 'History', ['y']),
+  fleet: keyRow('f', 'Fleet', ['f']),
+  help: keyRow('?', 'Help', ['?']),
+  openRun: keyRow('1\u20139', 'open that run', []),
+  nextTab: keyRow('Tab', 'next sub-tab', ['\t']),
+  cycleWorkflow: keyRow('Shift+Tab', 'cycle workflows', ['\x1b[Z']),
+  period: keyRow('p', 'cycle the period', ['p']),
+  up: keyRow('\u2191/k', 'move up', ['\x1b[A', 'k']),
+  down: keyRow('\u2193/j', 'move down', ['\x1b[B', 'j']),
+  in: keyRow('Enter/\u2192/l', 'open', ['\r', '\n', '\x1b[C', 'l']),
+  out: keyRow('Esc/\u2190', 'move out', ['\x1b', '\x1b[D']),
+  pageUp: keyRow('PgUp', 'scroll up a screen', ['\x1b[5~']),
+  pageDown: keyRow('PgDn', 'scroll down a screen', ['\x1b[6~']),
+  top: keyRow('Home', 'top', ['\x1b[H', '\x1b[1~', '\x1bOH']),
+  end: keyRow('End', 'bottom', ['\x1b[F', '\x1b[4~', '\x1bOF']),
+  copy: keyRow('ctrl+s', 'copy the screen', ['\x13']),
+  detach: keyRow('q', 'quit', ['q', '\x03']),
+});
+
+function keyHint(name) {
+  const action = DASHBOARD_KEYS[name];
+  return `${action.keys.split('/')[0]} ${action.label}`;
+}
+
+function keyPressed(name, key) {
+  return DASHBOARD_KEYS[name].bindings?.includes(key) ?? false;
+}
+
+export {
+  keyHint,
+  keyPressed,
+};