@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/shared/lib/chat/todo/parser.ts

@@ -0,0 +1,262 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Renderer-side parser for one `todo` tool call: reads the human-readable
+ * checklist omp returns as the tool's text output (and the `list` argument as a
+ * fallback) into phase groups for the chat timeline's tool card.
+ *
+ * This is NOT the authoritative list — a tool card shows what that ONE call
+ * did, while the session's live list is the deepest committed snapshot on the
+ * active branch (`./snapshot.ts`, surfaced by the right-panel Todo view). The
+ * two must not be merged: a card that displayed the session-wide list would
+ * attribute every other call's work to this one.
+ *
+ * Two shapes the summary can carry are handled here rather than in the card:
+ *
+ *   - The status vocabulary is omp's own FIVE, not the three the card used to
+ *     know. `blocked` and `abandoned` are real (measured in the author's
+ *     sessions: 21 results mention a dropped task, 2 a blocked one), and a
+ *     parser that only understood three drew both as plain pending.
+ *   - A task whose content is an init-list entry rather than prose is recorded
+ *     that way by omp itself (see `./nested-phase`), so it is labelled by the
+ *     phase it names instead of being rendered as a JSON blob.
+ */
+
+import type { ToolCallData } from '@/shared/types';
+import type { TodoItem, TodoPhase, TodoProgress, TodoStatus } from '@/shared/types/todo';
+import { todoProgress } from '@/shared/lib/chat/todo/snapshot';
+import { parseNestedPhaseEntry, stripTrailingStatusNote } from '@/shared/lib/chat/todo/nested-phase';
+
+export interface TodoDataSummary {
+  groups: TodoPhase[];
+  progress: TodoProgress;
+  opBadge?: string;
+}
+
+/** Status ranking for the dedup pass — a task seen in two groups keeps the most advanced. */
+const STATUS_RANK: Record<TodoStatus, number> = {
+  pending: 0,
+  blocked: 1,
+  in_progress: 2,
+  abandoned: 3,
+  completed: 4,
+};
+
+/**
+ * The status annotation omp's summary appends to a task line, in the order it
+ * can appear. `blocked` carries the reason, which becomes the task's blocker
+ * note — the only place the transcript records WHY a task waits.
+ */
+function statusFromAnnotation(annotation: string | undefined): { status: TodoStatus; blocker?: string } {
+  if (!annotation) return { status: 'pending' };
+  const lower = annotation.toLowerCase();
+  if (lower === 'completed' || lower === 'done') return { status: 'completed' };
+  if (lower === 'in_progress' || lower === 'in progress') return { status: 'in_progress' };
+  if (lower === 'abandoned' || lower === 'dropped') return { status: 'abandoned' };
+  if (lower === 'blocked') return { status: 'blocked' };
+  if (lower.startsWith('blocked')) {
+    const reason = annotation.replace(/^blocked\s*:?\s*/i, '').trim();
+    return { status: 'blocked', ...(reason ? { blocker: reason } : {}) };
+  }
+  return { status: 'pending' };
+}
+
+/** The status + blocker a checklist line's own annotation encodes. */
+function statusFromChecklistText(text: string): { status: TodoStatus; blocker?: string } {
+  const inProgress = text.match(/\(in progress\)|\[in_progress\]/i);
+  if (inProgress) return { status: 'in_progress' };
+  const dropped = text.match(/\((?:dropped|abandoned)\)/i);
+  if (dropped) return { status: 'abandoned' };
+  const blocked = text.match(/\(blocked(?::\s*([^)]*))?\)/i);
+  if (blocked) {
+    const reason = blocked[1]?.trim();
+    return { status: 'blocked', ...(reason ? { blocker: reason } : {}) };
+  }
+  return { status: 'pending' };
+}
+
+/**
+ * One parsed task. `content` is the task text — or, when the content encoded an
+ * init-list entry, the PHASE it named, with that entry's items kept as `notes`
+ * so nothing is lost and no per-item status is invented.
+ */
+function buildTask(rawContent: string, status: TodoStatus, blocker?: string): TodoItem {
+  const clean = stripTrailingStatusNote(rawContent);
+  const nested = parseNestedPhaseEntry(clean);
+  return {
+    content: nested ? nested.phase : clean,
+    status,
+    ...(nested ? { notes: nested.items } : {}),
+    ...(blocker ? { blocker } : {}),
+  };
+}
+
+function cleanPhaseName(raw: string): string {
+  let name = raw.replace(/:$/, '').trim();
+  // Strip "Active phase 1/1" or "Active phase" or "Phase 1:" prefix
+  name = name.replace(/^active\s+phase(?:\s+\d+\/\d+)?(?:\s*[:\-]\s*|\s+)?/i, '');
+  // Strip quotes around phase name: "Coverage" -> Coverage
+  name = name.replace(/^["']|["']$/g, '');
+  // Strip trailing parentheticals like (0/4 done) or (4 tasks) or (Coverage)
+  name = name.replace(/\s*\(\d+(?:\/\d+)?\s*(?:done|remaining|tasks)?\)$/i, '');
+  // If wrapped in parentheses like (Coverage)
+  name = name.replace(/^\((.+)\)$/, '$1');
+  return name.trim() || 'Tasks';
+}
+
+function mergePhaseGroups(rawGroups: TodoPhase[]): TodoPhase[] {
+  const map = new Map<string, TodoPhase>();
+
+  for (const g of rawGroups) {
+    if (!g.tasks.length) continue;
+    const phaseName = cleanPhaseName(g.name);
+    const key = phaseName.toLowerCase();
+
+    const existing = map.get(key);
+    if (!existing) {
+      map.set(key, { name: phaseName, tasks: [...g.tasks] });
+      continue;
+    }
+
+    // Use the larger group as the base list order
+    const baseTasks = g.tasks.length >= existing.tasks.length ? g.tasks : existing.tasks;
+    const otherTasks = baseTasks === g.tasks ? existing.tasks : g.tasks;
+
+    const taskMap = new Map<string, TodoItem>();
+    for (const t of baseTasks) {
+      taskMap.set(t.content.toLowerCase().trim(), { ...t });
+    }
+    for (const t of otherTasks) {
+      const tKey = t.content.toLowerCase().trim();
+      const prev = taskMap.get(tKey);
+      if (!prev) taskMap.set(tKey, { ...t });
+      else if (STATUS_RANK[t.status] > STATUS_RANK[prev.status]) prev.status = t.status;
+    }
+
+    existing.name = phaseName;
+    existing.tasks = Array.from(taskMap.values());
+  }
+
+  const groupsList = Array.from(map.values());
+  const result: TodoPhase[] = [];
+
+  for (let i = 0; i < groupsList.length; i++) {
+    const gA = groupsList[i];
+    const aTexts = gA.tasks.map((t) => t.content.toLowerCase().trim());
+
+    let isSubset = false;
+    for (let j = 0; j < groupsList.length; j++) {
+      if (i === j) continue;
+      const gB = groupsList[j];
+      const bTexts = new Set(gB.tasks.map((t) => t.content.toLowerCase().trim()));
+
+      if (gB.tasks.length >= gA.tasks.length && aTexts.every((txt) => bTexts.has(txt))) {
+        for (const tA of gA.tasks) {
+          const tB = gB.tasks.find((t) => t.content.toLowerCase().trim() === tA.content.toLowerCase().trim());
+          if (tB && STATUS_RANK[tA.status] > STATUS_RANK[tB.status]) tB.status = tA.status;
+        }
+        isSubset = true;
+        break;
+      }
+    }
+
+    if (!isSubset) result.push(gA);
+  }
+
+  return result;
+}
+
+export function parseTodoData(tool: ToolCallData): TodoDataSummary {
+  const input = tool.input;
+  const inputObj = typeof input === 'object' && input !== null ? (input as Record<string, any>) : undefined;
+  const output = tool.output || '';
+
+  let opBadge: string | undefined;
+  let doneRaw: string | undefined;
+  if (inputObj?.op === 'done' && inputObj.task) {
+    doneRaw = String(inputObj.task);
+    opBadge = `Completed: ${parseNestedPhaseEntry(stripTrailingStatusNote(doneRaw))?.phase ?? doneRaw}`;
+  } else if (inputObj?.op === 'init') {
+    opBadge = 'Initialized Todo List';
+  }
+
+  const lines = output.split(/\r?\n/);
+  const rawGroups: TodoPhase[] = [];
+  let currentGroup: TodoPhase = { name: 'Tasks', tasks: [] };
+  let inChecklistSection = false;
+
+  for (const rawLine of lines) {
+    const trimmed = rawLine.trim();
+    if (!trimmed) continue;
+
+    // Detect section start: "Active phase ...", "Coverage:", etc.
+    if (trimmed.endsWith(':') && !trimmed.startsWith('Overall') && !trimmed.startsWith('Remaining')) {
+      const phaseName = cleanPhaseName(trimmed);
+      if (currentGroup.tasks.length > 0) rawGroups.push(currentGroup);
+      currentGroup = { name: phaseName, tasks: [] };
+      inChecklistSection = true;
+      continue;
+    }
+
+    // Detect checklist items: - [X] or [X] or - [ ] or [ ] or * [X]
+    const checkMatch = trimmed.match(/^(?:[-*]\s*)?\[([ xX])\]\s*(.+)$/);
+    if (checkMatch) {
+      const mark = checkMatch[1].toLowerCase();
+      const text = checkMatch[2].trim();
+      const annotated = statusFromChecklistText(text);
+      const status: TodoStatus = mark === 'x' ? 'completed' : annotated.status;
+      currentGroup.tasks.push(buildTask(text, status, annotated.blocker));
+      continue;
+    }
+
+    // Fallback: parse lines like "  - Add Think renderer [in_progress] (Coverage)"
+    const itemMatch = trimmed.match(
+      /^-\s*(.+?)\s*\[(in_progress|pending|completed|abandoned|blocked|done)\](?:\s*\((.+?)\))?$/,
+    );
+    if (itemMatch && !inChecklistSection) {
+      const text = itemMatch[1].trim();
+      const { status, blocker } = statusFromAnnotation(itemMatch[2]);
+      const phase = cleanPhaseName(itemMatch[3]?.trim() || 'Tasks');
+
+      let targetGrp = rawGroups.find((g) => cleanPhaseName(g.name).toLowerCase() === phase.toLowerCase());
+      if (!targetGrp) {
+        targetGrp = { name: phase, tasks: [] };
+        rawGroups.push(targetGrp);
+      }
+      targetGrp.tasks.push(buildTask(text, status, blocker));
+    }
+  }
+
+  if (currentGroup.tasks.length > 0 && !rawGroups.includes(currentGroup)) {
+    rawGroups.push(currentGroup);
+  }
+
+  // If nothing parsed from output, check input.list
+  if (rawGroups.length === 0 && Array.isArray(inputObj?.list)) {
+    for (const p of inputObj.list) {
+      const phaseName = cleanPhaseName(p.phase || 'Tasks');
+      const tasks: TodoItem[] = (p.items || []).map((it: string) => ({ content: it, status: 'pending' as const }));
+      rawGroups.push({ name: phaseName, tasks });
+    }
+  }
+
+  // Merge & deduplicate all phase groups
+  const groups = mergePhaseGroups(rawGroups);
+
+  // If tool was an op: 'done', ensure the task is marked as done
+  if (doneRaw !== undefined) {
+    const doneLabel = parseNestedPhaseEntry(stripTrailingStatusNote(doneRaw))?.phase ?? doneRaw;
+    const doneText = doneLabel.toLowerCase().trim();
+    for (const g of groups) {
+      const target = g.tasks.find((t) => t.content.toLowerCase().trim() === doneText);
+      if (target) target.status = 'completed';
+    }
+  }
+
+  const progress = todoProgress(groups);
+
+  return { groups, progress, opBadge };
+}

package/src/shared/lib/chat/todo/progress.test.ts

@@ -0,0 +1,265 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The todo panel's presentation table and lookups.
+ *
+ * `todoStatusVisual` is a five-way table whose failure mode is silent: a
+ * `blocked` or `abandoned` row drawn with the pending style still looks
+ * plausible, so every status is pinned explicitly — including that `blocked`
+ * is NOT closed while `abandoned` IS. `closedTaskCount`/`todoProgressPercent`
+ * count closed = completed + abandoned (omp's own HUD rule); pinning that stops
+ * a later "completed only" refactor from making a list read as permanently
+ * stuck. `currentTaskLocation` is deliberately two-pass — an in-progress task
+ * anywhere beats an earlier pending one — which is the difference between the
+ * panel highlighting the live task and a stale one.
+ *
+ * `parseNestedPhaseEntry` handles the real transcript shape where a model sends
+ * `items:[{phase,items}]`, so a whole init-list entry lands in a task's content
+ * as JSON. The strictness (the WHOLE string must be the object, string phase,
+ * non-empty string items) is what keeps a prose task that merely mentions JSON
+ * from being drawn as a phase.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  closedTaskCount,
+  currentTaskLocation,
+  taskNote,
+  todoProgressLabel,
+  todoProgressPercent,
+  todoStatusVisual,
+} from '@/shared/lib/chat/todo/progress';
+import { parseNestedPhaseEntry, stripTrailingStatusNote } from '@/shared/lib/chat/todo/nested-phase';
+import type { TodoItem, TodoPhase, TodoProgress, TodoStatus } from '@/shared/types/todo';
+
+const progress = (partial: Partial<TodoProgress>): TodoProgress => ({
+  total: 0,
+  completed: 0,
+  closed: 0,
+  inProgress: 0,
+  pending: 0,
+  blocked: 0,
+  abandoned: 0,
+  ...partial,
+});
+
+const phase = (name: string, tasks: Array<[string, TodoStatus]>): TodoPhase => ({
+  name,
+  tasks: tasks.map(([content, status]) => ({ content, status })),
+});
+
+const task = (status: TodoStatus, extra: Partial<TodoItem> = {}): TodoItem => ({
+  content: 'task',
+  status,
+  ...extra,
+});
+
+describe('todoStatusVisual', () => {
+  test('maps every status to its label, tone and flags', () => {
+    expect(todoStatusVisual('pending')).toEqual({
+      label: 'Pending',
+      tone: 'text-ink/45',
+      active: false,
+      closed: false,
+    });
+    expect(todoStatusVisual('in_progress')).toEqual({
+      label: 'In progress',
+      tone: 'text-ink',
+      active: true,
+      closed: false,
+    });
+    expect(todoStatusVisual('completed')).toEqual({
+      label: 'Completed',
+      tone: 'text-success',
+      active: false,
+      closed: true,
+    });
+    expect(todoStatusVisual('abandoned')).toEqual({
+      label: 'Abandoned',
+      tone: 'text-error/70',
+      active: false,
+      closed: true,
+    });
+  });
+
+  test('a blocked task is warned about but not closed and not active', () => {
+    expect(todoStatusVisual('blocked')).toEqual({
+      label: 'Blocked',
+      tone: 'text-warning',
+      active: false,
+      closed: false,
+    });
+  });
+
+  test('an unknown status degrades to the pending visual', () => {
+    expect(todoStatusVisual('nope' as TodoStatus)).toEqual(todoStatusVisual('pending'));
+  });
+});
+
+describe('todoProgressLabel', () => {
+  test('reports an empty list instead of a 0/0 fraction', () => {
+    expect(todoProgressLabel(progress({}))).toBe('No tasks');
+  });
+
+  test('shows the closed fraction with no suffixes when nothing is live', () => {
+    expect(todoProgressLabel(progress({ total: 4, closed: 4, completed: 4 }))).toBe('4/4 done');
+  });
+
+  test('appends in-progress, blocked and abandoned counts in that order', () => {
+    const label = todoProgressLabel(
+      progress({ total: 11, closed: 4, completed: 3, inProgress: 1, blocked: 2, abandoned: 1 }),
+    );
+    expect(label).toBe('4/11 done · 1 in progress · 2 blocked · 1 abandoned');
+  });
+
+  test('omits zero-count suffixes', () => {
+    expect(todoProgressLabel(progress({ total: 2, closed: 1, inProgress: 1 }))).toBe('1/2 done · 1 in progress');
+  });
+});
+
+describe('todoProgressPercent', () => {
+  test('is 0 for an empty list rather than NaN', () => {
+    expect(todoProgressPercent(progress({}))).toBe(0);
+  });
+
+  test('rounds to the nearest whole percent', () => {
+    expect(todoProgressPercent(progress({ total: 4, closed: 2 }))).toBe(50);
+    expect(todoProgressPercent(progress({ total: 3, closed: 1 }))).toBe(33);
+    expect(todoProgressPercent(progress({ total: 3, closed: 2 }))).toBe(67);
+  });
+
+  test('counts abandoned tasks as closed progress', () => {
+    expect(todoProgressPercent(progress({ total: 2, closed: 1, abandoned: 1 }))).toBe(50);
+  });
+});
+
+describe('currentTaskLocation', () => {
+  test('an in-progress task in a later phase beats an earlier pending one', () => {
+    const phases = [phase('A', [['a', 'pending']]), phase('B', [['b', 'in_progress']])];
+    expect(currentTaskLocation(phases)).toEqual({ phase: 1, task: 0 });
+  });
+
+  test('falls back to the first pending task when nothing is in progress', () => {
+    const phases = [phase('A', [['a', 'completed']]), phase('B', [['b', 'pending'], ['c', 'pending']])];
+    expect(currentTaskLocation(phases)).toEqual({ phase: 1, task: 0 });
+  });
+
+  test('picks the first in-progress task when several are live', () => {
+    const phases = [phase('A', [['a', 'in_progress'], ['b', 'in_progress']])];
+    expect(currentTaskLocation(phases)).toEqual({ phase: 0, task: 0 });
+  });
+
+  test('returns null when every task is settled', () => {
+    expect(currentTaskLocation([phase('A', [['a', 'completed'], ['b', 'abandoned']])])).toBeNull();
+  });
+
+  test('a blocked task is not a pending fallback', () => {
+    expect(currentTaskLocation([phase('A', [['a', 'blocked']])])).toBeNull();
+  });
+
+  test('handles empty phase lists and empty phases', () => {
+    expect(currentTaskLocation([])).toBeNull();
+    expect(currentTaskLocation([phase('A', []), phase('B', [])])).toBeNull();
+  });
+});
+
+describe('closedTaskCount', () => {
+  test('counts completed and abandoned, ignoring the other three states', () => {
+    const p = phase('A', [
+      ['a', 'completed'],
+      ['b', 'abandoned'],
+      ['c', 'pending'],
+      ['d', 'in_progress'],
+      ['e', 'blocked'],
+    ]);
+    expect(closedTaskCount(p)).toBe(2);
+  });
+
+  test('is 0 when nothing is settled', () => {
+    expect(closedTaskCount(phase('A', []))).toBe(0);
+    expect(closedTaskCount(phase('A', [['a', 'pending']]))).toBe(0);
+  });
+});
+
+describe('taskNote', () => {
+  test('prefers a trimmed blocker over the details', () => {
+    expect(taskNote(task('blocked', { blocker: '  waiting on API  ', details: 'ignored' }))).toBe('waiting on API');
+  });
+
+  test('falls back to trimmed details when the blocker is blank', () => {
+    expect(taskNote(task('blocked', { blocker: '   ', details: '  see RFC  ' }))).toBe('see RFC');
+    expect(taskNote(task('pending', { blocker: '', details: 'detail' }))).toBe('detail');
+  });
+
+  test('returns undefined when there is nothing to show', () => {
+    expect(taskNote(task('pending'))).toBeUndefined();
+    expect(taskNote(task('pending', { blocker: '  ', details: '  ' }))).toBeUndefined();
+  });
+});
+
+describe('parseNestedPhaseEntry', () => {
+  test('reads a whole JSON init-list entry out of a task content', () => {
+    expect(parseNestedPhaseEntry('{"phase":"Fondasi","items":["a","b"]}')).toEqual({
+      phase: 'Fondasi',
+      items: ['a', 'b'],
+    });
+  });
+
+  test('tolerates surrounding whitespace and trims the phase name', () => {
+    expect(parseNestedPhaseEntry('  { "phase": "  P  ", "items": ["x"] }  ')).toEqual({ phase: 'P', items: ['x'] });
+  });
+
+  test('ignores extra keys', () => {
+    expect(parseNestedPhaseEntry('{"phase":"P","items":["x"],"extra":1}')).toEqual({ phase: 'P', items: ['x'] });
+  });
+
+  test('rejects prose and non-object JSON', () => {
+    expect(parseNestedPhaseEntry('just a task')).toBeUndefined();
+    expect(parseNestedPhaseEntry('[]')).toBeUndefined();
+    expect(parseNestedPhaseEntry('null')).toBeUndefined();
+    expect(parseNestedPhaseEntry('"a string"')).toBeUndefined();
+    expect(parseNestedPhaseEntry('42')).toBeUndefined();
+    expect(parseNestedPhaseEntry('{not json}')).toBeUndefined();
+  });
+
+  test('rejects a missing/blank phase or a non-array/empty/non-string items list', () => {
+    expect(parseNestedPhaseEntry('{"a":1}')).toBeUndefined();
+    expect(parseNestedPhaseEntry('{"phase":1,"items":["a"]}')).toBeUndefined();
+    expect(parseNestedPhaseEntry('{"phase":"   ","items":["a"]}')).toBeUndefined();
+    expect(parseNestedPhaseEntry('{"phase":"P","items":"x"}')).toBeUndefined();
+    expect(parseNestedPhaseEntry('{"phase":"P","items":[]}')).toBeUndefined();
+    expect(parseNestedPhaseEntry('{"phase":"P","items":["a",1]}')).toBeUndefined();
+  });
+});
+
+describe('stripTrailingStatusNote', () => {
+  test('removes the three trailing status annotations', () => {
+    expect(stripTrailingStatusNote('Write the tests (in progress)')).toBe('Write the tests');
+    expect(stripTrailingStatusNote('Write the tests (dropped)')).toBe('Write the tests');
+    expect(stripTrailingStatusNote('Write the tests (blocked)')).toBe('Write the tests');
+    expect(stripTrailingStatusNote('Write the tests (blocked: waiting on review)')).toBe('Write the tests');
+  });
+
+  test('is case-insensitive and trims the remainder', () => {
+    expect(stripTrailingStatusNote('Do it (IN PROGRESS)   ')).toBe('Do it');
+    expect(stripTrailingStatusNote('Do it (Dropped)')).toBe('Do it');
+  });
+
+  test('leaves text with no trailing note untouched', () => {
+    expect(stripTrailingStatusNote('Write the tests')).toBe('Write the tests');
+    expect(stripTrailingStatusNote('a (in progress) b')).toBe('a (in progress) b');
+    expect(stripTrailingStatusNote('x (blocked: a (b))')).toBe('x (blocked: a (b))');
+  });
+
+  test('recovers a JSON content from behind the annotation', () => {
+    expect(stripTrailingStatusNote('{"phase":"P","items":["a"]} (in progress)')).toBe('{"phase":"P","items":["a"]}');
+  });
+
+  test('handles the empty string', () => {
+    expect(stripTrailingStatusNote('')).toBe('');
+  });
+});

package/src/shared/lib/chat/todo/progress.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Display-side helpers for a todo list: the one-line progress summary, the
+ * per-task visual state, and the "which task is the agent on" lookup the panel
+ * highlights.
+ *
+ * Everything here is presentational — the parse itself lives in `snapshot.ts`.
+ * The status → presentation mapping is a table rather than a chain of `if`s
+ * because there are five statuses and three consumers (icon, label, class
+ * list), and a missing case in any one of them is how a `blocked` task ends up
+ * rendered as a plain pending one.
+ */
+
+import type { TodoItem, TodoPhase, TodoProgress, TodoStatus } from '@/shared/types/todo';
+
+export interface TodoStatusVisual {
+  /** Short label for the row's status pill. */
+  label: string;
+  /** Tailwind text color for the icon and label. */
+  tone: string;
+  /** True when the row is a live (in-progress) task — highlighted, not dimmed. */
+  active: boolean;
+  /** True when the task is out of the way (completed / abandoned). */
+  closed: boolean;
+}
+
+const STATUS_VISUALS: Record<TodoStatus, TodoStatusVisual> = {
+  pending: { label: 'Pending', tone: 'text-ink/45', active: false, closed: false },
+  in_progress: { label: 'In progress', tone: 'text-ink', active: true, closed: false },
+  completed: { label: 'Completed', tone: 'text-success', active: false, closed: true },
+  abandoned: { label: 'Abandoned', tone: 'text-error/70', active: false, closed: true },
+  blocked: { label: 'Blocked', tone: 'text-warning', active: false, closed: false },
+};
+
+export function todoStatusVisual(status: TodoStatus): TodoStatusVisual {
+  return STATUS_VISUALS[status] ?? STATUS_VISUALS.pending;
+}
+
+/**
+ * One-line summary of a snapshot: `4/11 done · 1 in progress · 2 blocked`.
+ *
+ * Counts CLOSED (completed + abandoned) against the total, matching omp's own
+ * HUD counter — an abandoned task is deliberately not coming back, so leaving
+ * it in the denominator is what makes a list read as permanently stuck.
+ */
+export function todoProgressLabel(progress: TodoProgress): string {
+  if (progress.total === 0) return 'No tasks';
+  const parts = [`${progress.closed}/${progress.total} done`];
+  if (progress.inProgress > 0) parts.push(`${progress.inProgress} in progress`);
+  if (progress.blocked > 0) parts.push(`${progress.blocked} blocked`);
+  if (progress.abandoned > 0) parts.push(`${progress.abandoned} abandoned`);
+  return parts.join(' · ');
+}
+
+/** Percentage of the list that is closed, rounded to a whole number. */
+export function todoProgressPercent(progress: TodoProgress): number {
+  if (progress.total === 0) return 0;
+  return Math.round((progress.closed / progress.total) * 100);
+}
+
+/**
+ * The row the panel marks as current: the in-progress task, else the first
+ * pending one. Identified by phase index + task index rather than by content,
+ * because two phases may legitimately hold tasks with identical text (omp
+ * itself keys its own task lookup by content, and that ambiguity is its
+ * problem, not one to inherit here).
+ */
+export function currentTaskLocation(phases: readonly TodoPhase[]): { phase: number; task: number } | null {
+  for (let phase = 0; phase < phases.length; phase++) {
+    const tasks = phases[phase].tasks;
+    for (let task = 0; task < tasks.length; task++) {
+      if (tasks[task].status === 'in_progress') return { phase, task };
+    }
+  }
+  for (let phase = 0; phase < phases.length; phase++) {
+    const tasks = phases[phase].tasks;
+    for (let task = 0; task < tasks.length; task++) {
+      if (tasks[task].status === 'pending') return { phase, task };
+    }
+  }
+  return null;
+}
+
+/** Tasks of one phase that are closed, for the phase header's `n/m` badge. */
+export function closedTaskCount(phase: TodoPhase): number {
+  return phase.tasks.filter((task) => task.status === 'completed' || task.status === 'abandoned').length;
+}
+
+/** Blocker note of a task, trimmed, or undefined when there is nothing to show. */
+export function taskNote(task: TodoItem): string | undefined {
+  const note = task.blocker?.trim() || task.details?.trim();
+  return note ? note : undefined;
+}