AIDLC Cockpit

1// aidlc-cockpit — AIDLC beside the chat.
2//
3// It gates no tool call, rewrites no prompt and approves nothing. What it shows comes from core's
4// scripts (run-files.mjs, sprint.mjs, costs.mjs), found next to this plugin, so it can never disagree
5// with /aidlc:status, /aidlc:sprint or /aidlc:insights. What to show is decided in view.mjs; this file
6// gathers and draws.
7//
8// The one thing it writes is the cost ledger: what each work item cost, by phase, from Claude Code's own
9// session cost (view.mjs → *the cost ledger*). One file per item per session, under the main checkout's
10// git-ignored `.aidlc/logs/costs/`.
11//
12// Cost: no model calls, ever. A board refresh runs at most three short `node` processes, every 30
13// seconds and only while a surface is drawing, so an unattended background sprint run polls nothing.
14import { atom, read, update } from 'claude-code'
15import type { EngineInterface, Register } from 'claude-code'
16
17import type { CockpitBoardRow, CockpitPr, CockpitRun, CockpitSnapshot, CockpitSprint } from '../types'
18import type { Charge, Ledger, LedgerFile } from './view.mjs'
19import {
20  advance,
21  bandModel,
22  boardText,
23  cacheDirOf,
24  commandItem,
25  coreCandidates,
26  coreTooOld,
27  ledgerName,
28  mergeLedger,
29  newestSprintFile,
30  phaseOf,
31  prLine,
32  prState,
33  prTransitions,
34  runFileTarget,
35  runLine,
36  toSlash,
37  transitions,
38} from './view.mjs'
39
40const PANE = 'aidlc-board'
41const COMMAND = 'aidlc-board'
42const POLL_MS = 30_000
43const FLUSH_MS = 120_000
44const MIN_GAP_MS = 5_000
45// Pull requests change on a person's time, not a turn's, and each look is a call to GitHub or Azure.
46const PR_MS = 300_000
47// The oldest core this cockpit reads correctly: pr-state.mjs (0.67), costs.mjs (0.65), run-files --json (0.64).
48const MIN_CORE = '0.67.0'
49
50// Change the shape tag when the snapshot's fields change: a reload keeps $.state, and the tag makes
51// the new code decline what the old code stored instead of misreading it.
52const snapshot = atom({ plugin: 'aidlc-cockpit', key: 'snapshot' } as const, null, { shape: 'snapshot-3' })
53const hidden = atom({ plugin: 'aidlc-cockpit', key: 'hidden' } as const, false)
54
55const clockTime = (ms: number) => {
56  const d = new Date(ms)
57  return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`
58}
59
60// Module variables start over on a reload. For the ledger that means a reload in the middle of a phase
61// charges what was spent before it to nothing; the next flush or phase change picks it up again.
62let core: string | null | undefined // undefined: not looked for yet; null: not found
63let lastRows: CockpitBoardRow[] | null = null
64let busy = false
65let lastAt = 0
66let ledger: Ledger = { item: null, phase: null, baseline: null }
67let costRoot: string | undefined
68let sessionId: string | undefined
69let coreVersion: string | null | undefined
70let prs: CockpitPr[] | null = null
71let prsAt = 0
72
73// Claude Code traces every call a mod makes on `$`, so `$` is only ever passed to functions declared
74// at the top of this file.
75async function findCore($: EngineInterface): Promise<string | null> {
76  let versions: string[] = []
77  try {
78    versions = (await $.fs.list(cacheDirOf($.plugin.root))).filter(e => e.kind === 'dir').map(e => e.name)
79  } catch {
80    // no plugin cache next to us: a checkout or a folder marketplace
81  }
82  for (const dir of coreCandidates($.plugin.root, versions))
83    if (await $.fs.exists(`${dir}/skills/sprint/sprint.mjs`)) return dir
84  return null
85}
86
87async function readCoreVersion($: EngineInterface, dir: string): Promise<string | null> {
88  try {
89    const v = (JSON.parse(await $.fs.read(`${dir}/.claude-plugin/plugin.json`)) as { version?: unknown }).version
90    return typeof v === 'string' ? v : null
91  } catch {
92    return null
93  }
94}
95
96async function nodeJson($: EngineInterface, args: string[], cwd: string): Promise<unknown> {
97  try {
98    const r = await $.process.run(['node', ...args], { cwd, timeoutMs: 30_000 })
99    return r.exitCode === 0 ? JSON.parse(r.stdout) : null
100  } catch {
101    return null
102  }
103}
104
105// The main checkout of a folder. A mono sprint run works in a worktree that is removed when the sprint
106// wraps up; its ledger must not go with it.
107async function mainCheckout($: EngineInterface, cwd: string): Promise<string> {
108  try {
109    const r = await $.process.run(['git', 'rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd, timeoutMs: 10_000 })
110    const dir = toSlash(r.stdout.trim())
111    if (r.exitCode === 0 && /\/\.git$/.test(dir)) return dir.slice(0, -'/.git'.length)
112  } catch {
113    // not a git repository: keep the ledger where the session is
114  }
115  return cwd
116}
117
118// What the session has cost so far, as /cost totals it (subagents included), or null where unknown.
119async function spent($: EngineInterface): Promise<number | null> {
120  try {
121    const usd = (await $.session.usage()).cost?.usd
122    return typeof usd === 'number' && Number.isFinite(usd) ? usd : null
123  } catch {
124    return null
125  }
126}
127
128async function writeCharges($: EngineInterface, charges: readonly Charge[]): Promise<void> {
129  if (!charges.length) return
130  costRoot ??= await mainCheckout($, toSlash(await $.session.cwd()))
131  sessionId ??= await $.session.id()
132  const now = new Date(await $.clock.now()).toISOString()
133  for (const item of new Set(charges.map(c => c.item))) {
134    const path = `${costRoot}/.aidlc/logs/costs/${ledgerName(item, sessionId)}`
135    let existing: LedgerFile | null = null
136    try {
137      existing = JSON.parse(await $.fs.read(path)) as LedgerFile
138    } catch {
139      // the first charge for this item in this session
140    }
141    const file = mergeLedger(existing, { item, session: sessionId.slice(0, 8), now }, charges.filter(c => c.item === item))
142    await $.fs.write(path, `${JSON.stringify(file, null, 2)}\n`)
143  }
144}
145
146// Move the ledger to the item and phase now in force (null: none), charging what was spent since.
147async function track($: EngineInterface, next: { item: string; phase: string } | null): Promise<void> {
148  const usd = await spent($)
149  if (usd == null) return
150  const step = advance(ledger, next, usd)
151  ledger = step.ledger
152  await writeCharges($, step.charges)
153}
154
155// Charge what the current phase has spent so far, and carry on. Bounds what a crash can lose.
156async function flush($: EngineInterface): Promise<void> {
157  if (ledger.item && ledger.phase) await track($, { item: ledger.item, phase: ledger.phase })
158}
159
160async function readPhase($: EngineInterface, path: string): Promise<string | null> {
161  const cwd = toSlash(await $.session.cwd())
162  const p = toSlash(path)
163  try {
164    return phaseOf(await $.fs.read(/^([A-Za-z]:)?\//.test(p) ? p : `${cwd}/${p}`))
165  } catch {
166    return null
167  }
168}
169
170// A run file was written: if its phase moved, the phase that ended is charged.
171async function noteRunFile($: EngineInterface, target: { item: string; path: string }): Promise<void> {
172  const phase = await readPhase($, target.path)
173  if (!phase || (ledger.item === target.item && ledger.phase === phase)) return
174  await track($, { item: target.item, phase })
175}
176
177// `/aidlc:run <ID>` typed by name: charge from its first turn, in the phase its run file is already at.
178async function noteRunCommand($: EngineInterface, item: string): Promise<void> {
179  const phase = (await readPhase($, `.aidlc/runs/${item}.md`)) ?? 'start'
180  await track($, { item, phase })
181}
182
183async function refresh($: EngineInterface, force = false): Promise<void> {
184  const now = await $.clock.now()
185  if (busy || (!force && now - lastAt < MIN_GAP_MS)) return
186  busy = true
187  lastAt = now
188  try {
189    const cwd = toSlash(await $.session.cwd())
190    if (!(await $.fs.exists(`${cwd}/.claude/aidlc.config.json`))) {
191      await update($, snapshot, () => null)
192      return
193    }
194    if (core === undefined) core = await findCore($)
195    if (!core) {
196      await update($, snapshot, () => ({ runs: [], sprint: null, at: now, problem: 'the aidlc plugin was not found next to aidlc-cockpit — install aidlc@aidlc' }))
197      return
198    }
199    // An older core is missing scripts this cockpit reads, which would show as an empty board.
200    if (coreVersion === undefined) coreVersion = await readCoreVersion($, core)
201    if (coreTooOld(coreVersion, MIN_CORE)) {
202      const problem = `this cockpit needs aidlc ${MIN_CORE} or later (found ${coreVersion ?? 'an unknown version'}) — /plugin marketplace update aidlc`
203      await update($, snapshot, () => ({ runs: [], sprint: null, at: now, problem }))
204      return
205    }
206    const runs = ((await nodeJson($, [`${core}/hooks/scripts/lib/run-files.mjs`, cwd, '--json'], cwd)) as CockpitRun[] | null) ?? []
207    let sprint: CockpitSprint | null = null
208    let listing: Awaited<ReturnType<EngineInterface['fs']['list']>> = []
209    try {
210      listing = await $.fs.list(`${cwd}/.aidlc`)
211    } catch {
212      // no .aidlc yet
213    }
214    const file = newestSprintFile(listing)
215    if (file) sprint = (await nodeJson($, [`${core}/skills/sprint/sprint.mjs`, 'board', '--sprint-file', `${cwd}/.aidlc/${file}`, '--json'], cwd)) as CockpitSprint | null
216
217    // What each item has cost: the ledger as core reads it, plus what this session has spent on its
218    // item since the last charge.
219    costRoot ??= await mainCheckout($, cwd)
220    const costs: Record<string, number> = {}
221    if (await $.fs.exists(`${costRoot}/.aidlc/logs/costs`)) {
222      const read = (await nodeJson($, [`${core}/skills/insights/costs.mjs`, costRoot, '--json'], cwd)) as { byItem?: Record<string, { usd: number }> } | null
223      for (const [id, it] of Object.entries(read?.byItem ?? {})) costs[id] = it.usd
224    }
225    if (ledger.item && ledger.baseline != null) {
226      const usd = await spent($)
227      if (usd != null && usd > ledger.baseline) costs[ledger.item] = (costs[ledger.item] ?? 0) + (usd - ledger.baseline)
228    }
229
230    for (const t of transitions(lastRows, sprint?.rows ?? null)) {
231      void $.ui.notify(t.text, { title: 'AIDLC sprint' })
232      $.ui.toast(t.text)
233    }
234    lastRows = sprint?.rows ?? null
235
236    // The pipeline's pull requests: a slower cadence, since each look asks GitHub or Azure.
237    if (force || now - prsAt >= PR_MS) {
238      prsAt = now
239      const fresh = (await nodeJson($, [`${core}/skills/status/pr-state.mjs`, cwd, '--json'], cwd)) as CockpitPr[] | null
240      if (fresh) {
241        for (const t of prTransitions(prs, fresh)) {
242          void $.ui.notify(t.text, { title: 'AIDLC pull request' })
243          $.ui.toast(t.text)
244        }
245        prs = fresh
246      }
247    }
248    const snap: CockpitSnapshot = { runs, sprint, costs, prs: prs ?? [], at: now, problem: null }
249    await update($, snapshot, () => snap)
250  } finally {
251    busy = false
252  }
253}
254
255// The timer's tick: look again only while something is drawing.
256async function poll($: EngineInterface): Promise<void> {
257  if ((await $.session.surfaces()).length) await refresh($)
258}
259
260async function settle($: EngineInterface): Promise<void> {
261  await flush($)
262  await refresh($)
263}
264
265export const register: Register = on => {
266  on('session.start', async ($, e, next) => {
267    // The ledger is kept in every session, a background or `claude -p` sprint run included.
268    $.clock.every(FLUSH_MS, () => void flush($))
269    // The board only where something draws.
270    if (e.isInteractive) {
271      await $.command.register({
272        name: 'aidlc-board',
273        description: 'AIDLC runs and sprint board, with no model turn',
274        immediate: true,
275      })
276      $.clock.after(1, () => void refresh($, true))
277      $.clock.every(POLL_MS, () => void poll($))
278    }
279    return next(e)
280  })
281
282  on('session.end', async ($, e, next) => {
283    try {
284      await flush($)
285    } catch {
286      // a ledger is never worth delaying an exit over
287    }
288    return next(e)
289  })
290
291  // `/aidlc:run <ID>`: the run is charged from its first turn.
292  on('prompt.submit', async ($, e, next) => {
293    const item = commandItem(e.command)
294    if (item) {
295      try {
296        await noteRunCommand($, item)
297      } catch {
298        // never stand between a person and their prompt
299      }
300    }
301    return next(e)
302  }).catch(($, e, next) => next(e))
303
304  // The pipeline writes the run file at every phase change; the call itself always goes ahead untouched.
305  on('tool.call', async ($, e, next) => {
306    const target = runFileTarget(String(e.tool), e as unknown as { command?: unknown; file_path?: unknown })
307    const ran = await next(e)
308    if (target) {
309      try {
310        await noteRunFile($, target)
311      } catch {
312        // the ledger is best-effort; the tool call already happened
313      }
314    }
315    return ran
316  }).catch(($, e, next) => next(e))
317
318  // Run files change during turns: settle the ledger and look again when the main turn ends.
319  on('turn.complete', async ($, e, next) => {
320    const result = await next(e)
321    if (!e.agentId) $.clock.after(250, () => void settle($))
322    return result
323  })
324
325  on('command.run', { command: 'aidlc-board' }, async $ => {
326    await update($, hidden, () => false)
327    await refresh($, true)
328    await $.ui.open({ id: PANE, title: 'AIDLC' })
329    return { text: boardText(await read($, snapshot)) }
330  })
331
332  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
333    if (e.props.hasSurvey || (await read($, hidden))) return next(e)
334    const band = bandModel(await read($, snapshot))
335    if (!band) return next(e)
336    const { Box, Button, Text } = $.ui.resolve(e)
337    return (
338      <Box flexDirection="column">
339        {band.lines.map(line => (
340          <Text color={line.tone === 'warning' ? 'warning' : 'subtle'} wrap="truncate-end">
341            {line.text}
342          </Text>
343        ))}
344        <Box flexDirection="row" gap="sm">
345          <Button key="aidlc-board" label="Board" onPress={() => void $.ui.open({ id: PANE, title: 'AIDLC' })} />
346          <Button key="aidlc-hide" label="Hide" onPress={() => void update($, hidden, () => true)} />
347        </Box>
348      </Box>
349    )
350  })
351
352  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
353    const { Box, Button, Text } = $.ui.resolve(e)
354    const snap = await read($, snapshot)
355    if (!snap) return <Text dimColor>Not an AIDLC workspace: no .claude/aidlc.config.json in this folder.</Text>
356    if (snap.problem) return <Text color="warning">{snap.problem}</Text>
357    const rows = snap.sprint?.rows ?? []
358    return (
359      <Box flexDirection="column" gap="sm">
360        <Box flexDirection="column">
361          <Text weight="bold">{snap.runs.length ? `Runs (${snap.runs.length})` : 'No runs in flight'}</Text>
362          {snap.runs.map(run => {
363            const line = runLine(run, snap.costs?.[run.item])
364            return <Text color={line.tone === 'warning' ? 'warning' : 'text'}>{line.text}</Text>
365          })}
366        </Box>
367        {rows.length > 0 && (
368          <Box flexDirection="column">
369            <Text weight="bold">{`Sprint (${rows.length})`}</Text>
370            {rows.map(row => (
371              <Box flexDirection="row" gap="sm">
372                <Text color={row.needsYou && !row.terminal ? 'warning' : row.terminal ? 'success' : 'text'}>
373                  {`${row.item} · ${row.phase ?? '—'} · ${row.waitingFor ? `${row.status} (${row.waitingFor})` : row.status}`}
374                </Text>
375                {row.session && row.needsYou && !row.terminal && (
376                  <Button
377                    key={`attach-${row.item}`}
378                    label="Copy attach command"
379                    onPress={press => void $.ui.copy({ text: `claude attach ${row.session}`, surface: press.surface })}
380                  />
381                )}
382              </Box>
383            ))}
384          </Box>
385        )}
386        {(snap.prs ?? []).length > 0 && (
387          <Box flexDirection="column">
388            <Text weight="bold">{`Pull requests (${(snap.prs ?? []).length})`}</Text>
389            {(snap.prs ?? []).map(p => {
390              // The command to run next, put in the prompt for the person to send (never sent for them).
391              const command = p.next?.split(' → ').slice(-1)[0]
392              return (
393                <Box flexDirection="row" gap="sm">
394                  <Text color={p.next ? 'warning' : p.error ? 'subtle' : 'text'}>{p.next ? prLine(p) : `${p.item} PR #${p.number}: ${p.error ?? prState(p)}`}</Text>
395                  {command?.startsWith('/') && (
396                    <Button
397                      key={`pr-${p.item}`}
398                      label="Put in prompt"
399                      onPress={() =>
400                        void $.prompt.fill({ text: command, mode: 'replace' }).catch(() => $.ui.toast(`Type ${command} to run it`))
401                      }
402                    />
403                  )}
404                </Box>
405              )
406            })}
407          </Box>
408        )}
409        <Text dimColor>{`Updated ${clockTime(snap.at)} · costs are API-equivalent (/cost) · /${COMMAND} to refresh`}</Text>
410      </Box>
411    )
412  })
413}
414

1// The aidlc-cockpit mod's logic: plain data in, plain data out. The mod (register.tsx) gathers the
2// data through Claude Code and draws; everything that decides WHAT to show lives here, so node can
3// test it (view.test.mjs) on every OS in CI, where no Claude Code runs.
4//
5// The data itself is never computed here. Runs come from core's `run-files.mjs --json` and the sprint
6// board from core's `sprint.mjs board --json`, so the cockpit cannot disagree with /aidlc:status or
7// /aidlc:sprint about what a run is doing.
8
9const MAX_RUN_LINES = 3;
10const MAX_NEED_LINES = 2;
11const MAX_PR_LINES = 2;
12
13export const toSlash = (p) => String(p).replace(/\\/g, "/").replace(/\/+$/, "");
14const parent = (p) => {
15  const parts = toSlash(p).split("/");
16  parts.pop();
17  return parts.join("/");
18};
19
20function compareVersions(a, b) {
21  const pa = String(a).split(".").map((n) => parseInt(n, 10));
22  const pb = String(b).split(".").map((n) => parseInt(n, 10));
23  for (let i = 0; i < 3; i++) {
24    const d = (Number.isNaN(pa[i]) ? -1 : pa[i] ?? 0) - (Number.isNaN(pb[i]) ? -1 : pb[i] ?? 0);
25    if (d) return d;
26  }
27  return 0;
28}
29
30// Where the aidlc core plugin can be, given this plugin's root, best guess first:
31//   <root>/../aidlc-core              a checkout, a --plugin-dir, or a folder marketplace
32//   <root>/../../aidlc/<version>      Claude Code's plugin cache (cache/<marketplace>/<plugin>/<version>),
33//                                     newest version first
34// `cacheVersions` is the listing of <root>/../../aidlc (directory names), or [] when it does not exist.
35export function coreCandidates(root, cacheVersions = []) {
36  const r = toSlash(root);
37  const out = [`${parent(r)}/aidlc-core`];
38  const cache = `${parent(parent(r))}/aidlc`;
39  for (const v of [...cacheVersions].sort((a, b) => compareVersions(b, a))) out.push(`${cache}/${v}`);
40  return out;
41}
42export const cacheDirOf = (root) => `${parent(parent(toSlash(root)))}/aidlc`;
43
44// The newest sprint file in a listing of .aidlc/ (`{ name, kind, mtimeMs }` entries), or null.
45export function newestSprintFile(entries) {
46  const files = (entries ?? []).filter((e) => e.kind === "file" && /^sprint-.+\.json$/.test(e.name));
47  files.sort((a, b) => (b.mtimeMs ?? 0) - (a.mtimeMs ?? 0));
48  return files[0]?.name ?? null;
49}
50
51export function prLabel(pr) {
52  if (!pr || pr === "null") return null;
53  const n = /\/(?:pull|pullrequest|merge_requests)\/(\d+)/.exec(pr);
54  if (n) return `PR #${n[1]}`;
55  const local = /^local-merge:([0-9a-f]{7})/.exec(pr);
56  return local ? `merged ${local[1]}` : "PR";
57}
58
59const WAITING_PHASES = new Set(["blocked", "review-pending"]);
60const fixLabel = (n) => (n && n !== "0" && n !== "null" ? `fix-cycle ${n}` : null);
61const repoLabel = (r) => (r && r !== "null" && r !== "control-plane" ? r : null);
62
63export const money = (usd) => (usd == null || !(usd > 0) ? null : usd >= 10 ? `$${usd.toFixed(0)}` : usd < 0.01 ? "<$0.01" : `$${usd.toFixed(2)}`);
64
65// One run, as one line. `usd` is what it has cost so far, when the ledger measured it.
66export function runLine(run, usd) {
67  const waiting = WAITING_PHASES.has(run.phase);
68  const bits = [run.item, repoLabel(run.repo), run.phase, fixLabel(run.fixCycles), prLabel(run.pr), money(usd)].filter(Boolean);
69  const hint = run.phase === "blocked" ? ` → /aidlc:run ${run.item}` : run.phase === "review-pending" ? " → waiting for your review" : "";
70  return { text: bits.join(" · ") + hint, tone: waiting ? "warning" : "subtle" };
71}
72
73// One PR that needs something, as one line.
74export const prLine = (p) => `${p.item} PR #${p.number}: ${p.next}`;
75
76// The line above the prompt, or null when there is nothing worth the room. A sprint, when one is
77// running, takes the band: it is the one place several runs can each be waiting on the person. Pull
78// requests that need something (review comments, a red check, a merge to clean up) follow either.
79export function bandModel(snapshot) {
80  if (!snapshot) return null;
81  if (snapshot.problem) return { lines: [{ text: `AIDLC cockpit: ${snapshot.problem}`, tone: "subtle" }], needsYou: 0 };
82  const lines = [];
83  let needsYou = 0;
84  const rows = snapshot.sprint?.rows ?? [];
85  if (rows.length && !snapshot.sprint.allTerminal) {
86    const need = rows.filter((r) => r.needsYou && !r.terminal);
87    const inFlight = rows.filter((r) => !r.terminal).length;
88    lines.push({
89      text: `AIDLC sprint · ${rows.length} run${rows.length === 1 ? "" : "s"} · ${inFlight} in flight${need.length ? ` · ${need.length} need${need.length === 1 ? "s" : ""} you` : ""}`,
90      tone: need.length ? "warning" : "subtle",
91    });
92    for (const r of need.slice(0, MAX_NEED_LINES))
93      lines.push({ text: `  ${r.item}: ${r.waitingFor ?? r.status}${r.session ? ` → claude attach ${r.session}` : ""}`, tone: "warning" });
94    if (need.length > MAX_NEED_LINES) lines.push({ text: `  +${need.length - MAX_NEED_LINES} more — /aidlc-board`, tone: "subtle" });
95    needsYou += need.length;
96  } else {
97    const runs = snapshot.runs ?? [];
98    // Runs waiting on the person first: they are the reason to look.
99    const ordered = [...runs].sort((a, b) => Number(WAITING_PHASES.has(b.phase)) - Number(WAITING_PHASES.has(a.phase)));
100    for (const r of ordered.slice(0, MAX_RUN_LINES)) lines.push(runLine(r, snapshot.costs?.[r.item]));
101    if (runs.length > MAX_RUN_LINES) lines.push({ text: `+${runs.length - MAX_RUN_LINES} more — /aidlc-board`, tone: "subtle" });
102    needsYou += runs.filter((r) => WAITING_PHASES.has(r.phase)).length;
103  }
104  const prs = (snapshot.prs ?? []).filter((p) => p.next);
105  for (const p of prs.slice(0, MAX_PR_LINES)) lines.push({ text: prLine(p), tone: "warning" });
106  if (prs.length > MAX_PR_LINES) lines.push({ text: `+${prs.length - MAX_PR_LINES} more PRs — /aidlc-board`, tone: "subtle" });
107  needsYou += prs.length;
108  if (!lines.length) return null;
109  // One label for the band; the sprint header carries its own, sprint detail lines keep their indent.
110  return {
111    lines: lines.map((l, i) => (i === 0 ? (l.text.startsWith("AIDLC") ? l : { ...l, text: `AIDLC  ${l.text}` }) : l.text.startsWith("  ") ? l : { ...l, text: `       ${l.text}` })),
112    needsYou,
113  };
114}
115
116// The board as plain text: the /aidlc-board reply, for surfaces that draw no pane.
117export function boardText(snapshot) {
118  if (!snapshot) return "Not an AIDLC workspace (no .claude/aidlc.config.json here).";
119  if (snapshot.problem) return `AIDLC cockpit: ${snapshot.problem}`;
120  const out = [];
121  const runs = snapshot.runs ?? [];
122  out.push(runs.length ? `Runs (${runs.length}):` : "No AIDLC runs in flight.");
123  for (const r of runs) out.push(`  ${runLine(r, snapshot.costs?.[r.item]).text}`);
124  const rows = snapshot.sprint?.rows ?? [];
125  if (rows.length) {
126    out.push("", `Sprint (${rows.length}):`);
127    for (const r of rows) out.push(`  ${r.item} · ${r.phase ?? "—"} · ${r.waitingFor ? `${r.status} (${r.waitingFor})` : r.status}${r.needsYou ? ` → ${r.needsYou}` : ""}`);
128  }
129  const prs = snapshot.prs ?? [];
130  if (prs.length) {
131    out.push("", `Pull requests (${prs.length}):`);
132    for (const p of prs) out.push(`  ${p.item} PR #${p.number}: ${p.error ?? prState(p)}${p.next ? ` → ${p.next.split(" → ").slice(-1)[0]}` : ""}`);
133  }
134  return out.join("\n");
135}
136
137// A PR's state in words: "open · changes requested · 2 unresolved · checks failing".
138export function prState(p) {
139  const bits = [p.state + (p.draft ? " (draft)" : "")];
140  if (p.review && p.review !== "none") bits.push(p.review.replace(/_/g, " "));
141  if (p.unresolved) bits.push(`${p.unresolved} unresolved`);
142  if (p.checks && p.checks !== "none") bits.push(`checks ${p.checks}`);
143  return bits.join(" · ");
144}
145
146// A PR newly needing something is worth a notification; one that needed the same thing last time is
147// not. The first look of a session notifies nothing.
148export function prTransitions(prev, now) {
149  if (!prev || !now) return [];
150  const before = new Map(prev.map((p) => [p.pr, p.next ?? null]));
151  return now.filter((p) => p.next && before.has(p.pr) && before.get(p.pr) !== p.next).map((p) => ({ item: p.item, kind: "pr", text: prLine(p) }));
152}
153
154// Is the core plugin new enough for this cockpit? Compares a.b.c numerically.
155export function coreTooOld(version, min) {
156  const a = String(version ?? "0").split(".").map(Number);
157  const b = String(min).split(".").map(Number);
158  for (let i = 0; i < 3; i++) if ((a[i] || 0) !== (b[i] || 0)) return (a[i] || 0) < (b[i] || 0);
159  return false;
160}
161
162// What changed between two sprint boards that is worth interrupting someone for: a run starting to
163// wait on them, and a run finishing. The first board of a session notifies nothing; the person can
164// see it, and a notification for every row already on it would be noise.
165export function transitions(prevRows, rows) {
166  if (!prevRows || !rows) return [];
167  const before = new Map(prevRows.map((r) => [r.item, r]));
168  const out = [];
169  for (const r of rows) {
170    const was = before.get(r.item);
171    if (!was) continue;
172    const waitsNow = r.status === "NEEDS YOU" && !r.terminal;
173    const waitedBefore = was.status === "NEEDS YOU" && !was.terminal;
174    if (waitsNow && (!waitedBefore || was.waitingFor !== r.waitingFor))
175      out.push({ item: r.item, kind: "needs-you", text: `${r.item} needs you: ${r.waitingFor ?? "an answer"}` });
176    else if (r.terminal && !was.terminal) out.push({ item: r.item, kind: "over", text: `${r.item}: ${r.status}` });
177  }
178  return out;
179}
180
181// ---- the cost ledger --------------------------------------------------------------------------
182//
183// What a work item costs is charged by phase. Claude Code reports the session's running cost
184// (`$.session.usage().cost.usd`, what /cost shows, subagents included). The mod notes the figure when
185// a run moves to a new phase, and charges the difference to the phase that just ended. The run file is
186// how it knows: the pipeline writes `.aidlc/runs/<ID>.md` at every phase change, whichever door the run
187// came in by (/aidlc:run, /aidlc:next, /aidlc:do, a sprint). The ledger's format is defined by its
188// reader, core's skills/insights/costs.mjs.
189
190// Phases after which nothing more is charged until the run writes its file again (a resume).
191const NOT_WORKING = new Set(["done", "abandoned", "blocked", "review-pending"]);
192
193const RUN_FILE = /(?:^|[\\/"'\s=])((?:[^\s"'`<>|;&]*[\\/])?\.aidlc[\\/]runs[\\/]([A-Za-z0-9][\w.-]*)\.md)\b/;
194
195// The run file a tool call writes, if any: `{ item, path }`. Edit and Write name it; a shell command
196// that writes it (a heredoc, `sed -i`) names it in its text. Archived run files are not live runs.
197export function runFileTarget(tool, input) {
198  const t = String(tool);
199  const text = t === "Bash" || t === "PowerShell" ? String(input?.command ?? "") : ["Edit", "Write", "MultiEdit"].includes(t) ? String(input?.file_path ?? "") : "";
200  const m = RUN_FILE.exec(text);
201  if (!m || /[\\/]archive[\\/]/.test(m[1])) return null;
202  return { item: m[2], path: m[1] };
203}
204
205// The `phase:` of a run file's frontmatter, or null.
206export function phaseOf(text) {
207  const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(String(text));
208  const m = fm && /^phase:\s*([\w-]+)/m.exec(fm[1]);
209  return m ? m[1] : null;
210}
211
212// `/aidlc:run PROJ-1 --sprint` → "PROJ-1": a run typed by name is charged from its first turn, before
213// its run file exists. Other doors are picked up at the first run-file write.
214export function commandItem(command) {
215  if (!command || command.name !== "aidlc:run") return null;
216  const id = String(command.args ?? "").split(/\s+/).find((a) => /^[A-Za-z][A-Za-z0-9]*-\d+$/.test(a));
217  return id ?? null;
218}
219
220// One step of the bookkeeping. `ledger` is `{ item, phase, baseline }` (baseline: the session cost when
221// the current phase began); `next` is the `{ item, phase }` now in force, or null for "nothing"; `usd`
222// is the session cost now. Returns the new ledger and what to charge. Passing the current item and
223// phase again charges what has been spent so far and carries on: that is a flush.
224export function advance(ledger, next, usd) {
225  const charges = [];
226  if (ledger.item && ledger.baseline != null && usd > ledger.baseline)
227    charges.push({ item: ledger.item, phase: ledger.phase ?? "start", usd: usd - ledger.baseline });
228  // A cost that went down (a new ledger behind the session) restarts from here, charging nothing.
229  const working = next && next.item && !NOT_WORKING.has(next.phase);
230  return { ledger: working ? { item: next.item, phase: next.phase, baseline: usd } : { item: null, phase: null, baseline: usd }, charges };
231}
232
233// The ledger file's name for an item and a session. Item ids are already path-safe; anything else is
234// replaced so a strange id cannot leave the folder.
235export const ledgerName = (item, session) => `${String(item).replace(/[^\w.-]/g, "_")}--${String(session).replace(/[^\w-]/g, "").slice(0, 8)}.json`;
236
237// The ledger file after adding `charges` (all for one item): phases summed, `started` kept.
238export function mergeLedger(existing, { item, session, now }, charges) {
239  const phases = { ...(existing?.phases ?? {}) };
240  for (const c of charges) phases[c.phase] = Math.round(((phases[c.phase] ?? 0) + c.usd) * 1e6) / 1e6;
241  return { item, session, started: existing?.started ?? now, updated: now, phases };
242}
243

1// What aidlc-cockpit keeps in the session's state. The values come from core's own scripts:
2// `run-files.mjs --json` (runs) and `sprint.mjs board --json` (the sprint board).
3
4export type CockpitRun = {
5  item: string;
6  phase: string;
7  repo?: string;
8  branch?: string;
9  fixCycles?: string;
10  pr?: string;
11};
12
13export type CockpitBoardRow = {
14  item: string;
15  repo: string | null;
16  phase: string | null;
17  fixCycles: string | null;
18  branch: string | null;
19  pr: string | null;
20  session: string | null;
21  status: string;
22  terminal: boolean;
23  waitingFor?: string;
24  needsYou?: string;
25};
26
27export type CockpitSprint = { rows: CockpitBoardRow[]; allTerminal: boolean };
28
29/** One pull request the pipeline opened, as core's `pr-state.mjs --json` reports it. */
30export type CockpitPr = {
31  item: string;
32  pr: string;
33  number: number;
34  host: 'github' | 'azure-repos';
35  state?: 'open' | 'merged' | 'closed' | 'unknown';
36  draft?: boolean;
37  review?: string;
38  unresolved?: number;
39  checks?: 'passing' | 'failing' | 'pending' | 'none';
40  error?: string;
41  next: string | null;
42};
43
44export type CockpitSnapshot = {
45  runs: CockpitRun[];
46  sprint: CockpitSprint | null;
47  /** What each item has cost so far (ledger + this session's uncharged spend), when measured. */
48  costs?: Record<string, number>;
49  /** The pipeline's open pull requests, looked at every few minutes. */
50  prs?: CockpitPr[];
51  at: number;
52  problem: string | null;
53};
54
55declare module 'claude-code' {
56  interface PluginState {
57    'aidlc-cockpit': {
58      snapshot: Shaped<CockpitSnapshot | null>;
59      hidden: boolean;
60    };
61  }
62}
63