agentic-orchestrator 0.1.18 → 0.1.20

package/agentic/orchestrator/prompts/builder.system.md

@@ -1 +1,48 @@
 You are the builder role. Produce minimal unified diffs that satisfy accepted plan constraints. Call gates after meaningful patch batches.
+
+## Output format
+
+Return exactly one JSON object. Do not wrap in markdown code fences.
+
+Allowed forms:
+
+```json
+{ "type": "PATCH", "unified_diff": "<unified diff text>" }
+```
+
+```json
+{ "type": "NOTE", "content": "<message>" }
+```
+
+```json
+{ "type": "REQUEST", "request": { "action": "more_context" } }
+```
+
+```json
+{"outputs": [<one or more of the above>]}
+```
+
+## Unified diff format
+
+Diffs must use standard unified diff format with file headers and hunk markers:
+
+```
+--- a/path/to/file
++++ b/path/to/file
+@@ -N,M +N,M @@ optional context
+ unchanged line
+-removed line
++added line
+ unchanged line
+```
+
+- Use `--- a/` and `+++ b/` path prefixes.
+- Include enough context lines (typically 3) around each change for clean application.
+- Only modify files listed in the accepted plan's `files.modify` or `files.create` lists.
+- New files use `/dev/null` as the `---` source and `b/path` as the `+++` target.
+
+## Constraints
+
+- Only touch files listed in the plan's `allowed_areas` and `files` lists.
+- Do not modify files in `forbidden_areas`.
+- Keep diffs minimal — do not reformat unrelated code.

package/agentic/orchestrator/prompts/planner.system.md

@@ -2,8 +2,54 @@ You are the planner role.
 
 Produce deterministic plan submissions and plan updates that conform to plan schema and policy constraints.
 Avoid speculative edits outside the declared file scope.
+When emitting `PLAN_SUBMISSION` or `REQUEST.action=amend_plan`, `plan_json` must only include keys allowed by `plan.schema.json` (no extra fields such as `phase_notes`).
 
-After each QA wave, perform an explicit reconciliation pass:
+## Required plan_json fields
+
+Every `PLAN_SUBMISSION` must include ALL of the following fields in `plan_json`:
+
+| Field                 | Type             | Notes                                                                                             |
+| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
+| `feature_id`          | string           | Must match the feature being planned                                                              |
+| `plan_version`        | integer ≥ 1      | Use `1` for a new plan; increment by 1 for each revision                                          |
+| `summary`             | string           | Human-readable description of what this feature implements                                        |
+| `allowed_areas`       | string[] (min 1) | Path prefixes or globs that agent patches may touch                                               |
+| `forbidden_areas`     | string[]         | Path prefixes that must not be touched (may be `[]`)                                              |
+| `base_ref`            | string           | Git ref the worktree was created from (e.g. `"main"`)                                             |
+| `files`               | object           | `{ "create": [...], "modify": [...], "delete": [...] }` — all three arrays required, may be empty |
+| `contracts`           | object           | `{ "openapi": "none"\|"modify", "events": "none"\|"modify", "db": "none"\|"migration" }`          |
+| `acceptance_criteria` | string[] (min 1) | Conditions that must all be met before merge                                                      |
+| `gate_profile`        | string           | Gate profile name (e.g. `"fast"` or `"full"`)                                                     |
+
+Optional fields: `gate_targets`, `risk`, `revision_of`, `revision_reason`, `verification_overrides`.
+
+### Minimal example
+
+```json
+{
+  "type": "PLAN_SUBMISSION",
+  "plan_json": {
+    "feature_id": "my_feature",
+    "plan_version": 1,
+    "summary": "Implement X to achieve Y",
+    "allowed_areas": ["apps/control-plane/src/"],
+    "forbidden_areas": [],
+    "base_ref": "main",
+    "files": {
+      "create": ["apps/control-plane/src/new-module.ts"],
+      "modify": ["apps/control-plane/src/existing.ts"],
+      "delete": []
+    },
+    "contracts": { "openapi": "none", "events": "none", "db": "none" },
+    "acceptance_criteria": ["All tests pass at ≥90% coverage", "npm run lint passes"],
+    "gate_profile": "fast"
+  }
+}
+```
+
+## After each QA wave
+
+Perform an explicit reconciliation pass:
 
 - re-read feature context (`feature.get_context`) including spec, accepted plan, QA index summary, and latest gate evidence
 - verify builder/QA outcomes still satisfy the accepted plan and spec intent

package/agentic/orchestrator/prompts/qa.system.md

@@ -1 +1,47 @@
 You are the QA role. Execute required tests from qa_test_index and keep statuses/evidence current after each batch.
+
+## Output format
+
+Return exactly one JSON object. Do not wrap in markdown code fences.
+
+Allowed forms:
+
+```json
+{ "type": "PATCH", "unified_diff": "<unified diff text>" }
+```
+
+```json
+{ "type": "NOTE", "content": "<message>" }
+```
+
+```json
+{ "type": "REQUEST", "request": { "action": "more_context" } }
+```
+
+```json
+{"outputs": [<one or more of the above>]}
+```
+
+## When to use each output type
+
+- **PATCH** — emit a unified diff to apply a targeted fix for a failing test. Use the same unified diff format as the builder role (`--- a/path`, `+++ b/path`, `@@ ... @@` hunk markers).
+- **NOTE** — report test run results, gate evidence, or status updates. Use structured content (e.g. JSON) when logging test outcomes.
+- **REQUEST `more_context`** — request a fresh feature context snapshot when you need updated state, plan, or gate evidence before proceeding.
+
+## Unified diff format
+
+```
+--- a/path/to/file
++++ b/path/to/file
+@@ -N,M +N,M @@ optional context
+ unchanged line
+-removed line
++added line
+ unchanged line
+```
+
+## Constraints
+
+- Only fix test code and implementation details needed to satisfy the accepted plan.
+- Do not modify files in `forbidden_areas`.
+- Keep patches minimal and targeted to the failing assertion or test gap.

package/apps/control-plane/src/providers/cli-worker-provider.ts

@@ -33,8 +33,16 @@ interface CommandTemplateValues {
 const CLAUDE_MIN_EFFECTIVE_TIMEOUT_MS = 300_000;
 const HISTORICAL_DEFAULT_TIMEOUT_MS = 120_000;
 
-function buildStructuredWorkerPrompt(payload: Record<string, unknown>): string {
-  return [
+function buildStructuredWorkerPrompt(
+  payload: Record<string, unknown>,
+  systemPrompt: string | null,
+): string {
+  const lines: string[] = [];
+  if (systemPrompt) {
+    lines.push(systemPrompt);
+    lines.push('---');
+  }
+  lines.push(
     'Return exactly one JSON object and nothing else.',
     'Allowed output object forms:',
     '{"type":"PLAN_SUBMISSION|PATCH|NOTE|REQUEST", ...}',
@@ -42,7 +50,8 @@ function buildStructuredWorkerPrompt(payload: Record<string, unknown>): string {
     'Do not wrap JSON in markdown code fences.',
     'Worker input payload:',
     JSON.stringify(payload),
-  ].join('\n');
+  );
+  return lines.join('\n');
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -196,6 +205,7 @@ export class CliWorkerProvider implements WorkerProvider {
   private readonly attachTemplate: ProviderCommandTemplate | undefined;
   private readonly sendTemplate: ProviderCommandTemplate | undefined;
   private readonly sessionsByRoleFeature = new Map<string, string>();
+  private readonly systemPromptsBySession = new Map<string, string | null>();
 
   constructor(selection: ProviderSelection, options: CliWorkerProviderOptions) {
     this.selection = selection;
@@ -231,6 +241,7 @@ export class CliWorkerProvider implements WorkerProvider {
   ): Promise<WorkerSession> {
     const sessionId = `${role}-${featureId}-${crypto.randomUUID()}`;
     this.sessionsByRoleFeature.set(this.sessionKey(role, featureId), sessionId);
+    this.systemPromptsBySession.set(sessionId, systemPrompt);
     return Promise.resolve({
       session_id: sessionId,
       role,
@@ -257,6 +268,7 @@ export class CliWorkerProvider implements WorkerProvider {
         this.sessionsByRoleFeature.delete(key);
       }
     }
+    this.systemPromptsBySession.delete(sessionId);
     return Promise.resolve({ closed: true });
   }
 
@@ -296,7 +308,8 @@ export class CliWorkerProvider implements WorkerProvider {
       runtime_selection: input.runtime_selection ?? null,
       session_id: sessionId,
     };
-    const prompt = buildStructuredWorkerPrompt(promptPayload);
+    const systemPrompt = this.systemPromptsBySession.get(sessionId) ?? null;
+    const prompt = buildStructuredWorkerPrompt(promptPayload, systemPrompt);
 
     const args = applyTemplateArgs(this.runTemplate.args, {
       sessionId,

package/apps/control-plane/src/supervisor/worker-decision-loop.ts

@@ -7,6 +7,23 @@ import type { RuntimeRole, SupervisorToolCaller } from './types.js';
 import type { ActivityMonitorService } from '../application/services/activity-monitor-service.js';
 
 type AnyRecord = Record<string, unknown>;
+const PLAN_TOP_LEVEL_KEYS = new Set([
+  'feature_id',
+  'plan_version',
+  'summary',
+  'allowed_areas',
+  'forbidden_areas',
+  'base_ref',
+  'files',
+  'contracts',
+  'acceptance_criteria',
+  'gate_profile',
+  'gate_targets',
+  'risk',
+  'revision_of',
+  'revision_reason',
+  'verification_overrides',
+]);
 
 export interface WorkerDecisionInput {
   role: RuntimeRole;
@@ -65,6 +82,17 @@ function readPlanVersion(value: unknown): number | null {
   return Math.floor(value);
 }
 
+function sanitizePlannerPlan(plan: AnyRecord): AnyRecord {
+  const sanitized: AnyRecord = {};
+  for (const [key, value] of Object.entries(plan)) {
+    if (!PLAN_TOP_LEVEL_KEYS.has(key)) {
+      continue;
+    }
+    sanitized[key] = value;
+  }
+  return sanitized;
+}
+
 function asOutputs(result: Record<string, unknown>): AnyRecord[] {
   const outputs = result.outputs;
   if (Array.isArray(outputs)) {
@@ -223,7 +251,7 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
       return;
     }
 
-    const planJson = asRecord(output.plan_json ?? output.plan);
+    const planJson = sanitizePlannerPlan(asRecord(output.plan_json ?? output.plan));
     if (Object.keys(planJson).length === 0) {
       return;
     }
@@ -350,7 +378,7 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
     }
 
     if (action === 'amend_plan' && input.role === 'planner') {
-      const planJson = asRecord(request.plan_json);
+      const planJson = sanitizePlannerPlan(asRecord(request.plan_json));
       if (Object.keys(planJson).length === 0) {
         return;
       }

package/apps/control-plane/test/dashboard-api.integration.spec.ts

@@ -11,6 +11,12 @@ const readDashboardStatusMock = vi.hoisted(() =>
   })),
 );
 const readFeatureStateMock = vi.hoisted(() => vi.fn(async () => null));
+const readFeatureLogMock = vi.hoisted(() =>
+  vi.fn(async () => ({
+    entries: [{ timestamp: '2026-03-05T00:00:00Z', message: 'log message', type: 'log' }],
+    total: 1,
+  })),
+);
 const getAopRootMock = vi.hoisted(() => vi.fn(() => process.cwd()));
 const approveFeatureReviewMock = vi.hoisted(() =>
   vi.fn(async () => ({ ok: true, data: { merged: true } })),
@@ -21,12 +27,19 @@ const denyFeatureReviewMock = vi.hoisted(() =>
 const requestFeatureChangesMock = vi.hoisted(() =>
   vi.fn(async () => ({ ok: true, data: { delivered: true } })),
 );
+const sendFeatureMessageMock = vi.hoisted(() =>
+  vi.fn(async () => ({ ok: true, data: { delivered: true } })),
+);
+const retryFeatureMock = vi.hoisted(() =>
+  vi.fn(async () => ({ ok: true, data: { retry_mode: 'full' } })),
+);
 const execFileMock = vi.hoisted(() => vi.fn());
 
 vi.mock('../../../packages/web-dashboard/src/lib/aop-client.js', () => ({
   resolveProjectRoot: resolveProjectRootMock,
   readDashboardStatus: readDashboardStatusMock,
   readFeatureState: readFeatureStateMock,
+  readFeatureLog: readFeatureLogMock,
   getAopRoot: getAopRootMock,
 }));
 
@@ -34,6 +47,8 @@ vi.mock('../../../packages/web-dashboard/src/lib/orchestrator-tools.js', () => (
   approveFeatureReview: approveFeatureReviewMock,
   denyFeatureReview: denyFeatureReviewMock,
   requestFeatureChanges: requestFeatureChangesMock,
+  sendFeatureMessage: sendFeatureMessageMock,
+  retryFeature: retryFeatureMock,
 }));
 
 vi.mock('node:child_process', () => ({
@@ -52,6 +67,7 @@ vi.mock('node:child_process', () => ({
 
 import { POST as actionsPost } from '../../../packages/web-dashboard/src/app/api/actions/route.js';
 import { POST as checkoutPost } from '../../../packages/web-dashboard/src/app/api/features/[id]/checkout/route.js';
+import { GET as logGet } from '../../../packages/web-dashboard/src/app/api/features/[id]/log/route.js';
 import { GET as statusGet } from '../../../packages/web-dashboard/src/app/api/status/route.js';
 import { GET as projectsGet } from '../../../packages/web-dashboard/src/app/api/projects/route.js';
 
@@ -67,10 +83,13 @@ describe('dashboard api integration', () => {
     resolveProjectRootMock.mockReset();
     readDashboardStatusMock.mockReset();
     readFeatureStateMock.mockReset();
+    readFeatureLogMock.mockReset();
     getAopRootMock.mockReset();
     approveFeatureReviewMock.mockReset();
     denyFeatureReviewMock.mockReset();
     requestFeatureChangesMock.mockReset();
+    sendFeatureMessageMock.mockReset();
+    retryFeatureMock.mockReset();
     execFileMock.mockReset();
 
     resolveProjectRootMock.mockResolvedValue(repoRoot);
@@ -89,6 +108,10 @@ describe('dashboard api integration', () => {
         },
       ],
     });
+    readFeatureLogMock.mockResolvedValue({
+      entries: [{ timestamp: '2026-03-05T00:00:00Z', message: 'log message', type: 'log' }],
+      total: 1,
+    });
   });
 
   afterEach(async () => {
@@ -154,6 +177,58 @@ describe('dashboard api integration', () => {
     expect(body.error.code).toBe('reason_required');
   });
 
+  it('GIVEN_feature_send_message_without_message_WHEN_posted_THEN_returns_400', async () => {
+    const response = await actionsPost(
+      new Request('http://localhost/api/actions', {
+        method: 'POST',
+        body: JSON.stringify({
+          action: 'feature.send_message',
+          feature_id: 'feature_checkout',
+        }),
+      }),
+    );
+
+    const body = (await response.json()) as { ok: boolean; error: { code: string } };
+    expect(response.status).toBe(400);
+    expect(body.ok).toBe(false);
+    expect(body.error.code).toBe('message_required');
+  });
+
+  it('GIVEN_feature_send_message_WHEN_posted_THEN_routes_to_tool', async () => {
+    const response = await actionsPost(
+      new Request('http://localhost/api/actions?project=alpha', {
+        method: 'POST',
+        body: JSON.stringify({
+          action: 'feature.send_message',
+          feature_id: 'feature_checkout',
+          message: 'Need clarification',
+        }),
+      }),
+    );
+
+    expect(response.status).toBe(200);
+    expect(sendFeatureMessageMock).toHaveBeenCalledWith(
+      'feature_checkout',
+      'Need clarification',
+      repoRoot,
+    );
+  });
+
+  it('GIVEN_feature_retry_WHEN_posted_THEN_routes_to_retry_tool', async () => {
+    const response = await actionsPost(
+      new Request('http://localhost/api/actions', {
+        method: 'POST',
+        body: JSON.stringify({
+          action: 'feature.retry',
+          feature_id: 'feature_checkout',
+        }),
+      }),
+    );
+
+    expect(response.status).toBe(200);
+    expect(retryFeatureMock).toHaveBeenCalledWith('feature_checkout', repoRoot);
+  });
+
   it('GIVEN_checkout_then_restore_WHEN_feature_branch_exists_THEN_persists_and_restores_checkout_record', async () => {
     readFeatureStateMock.mockResolvedValue({
       id: 'feature_checkout',
@@ -276,4 +351,23 @@ describe('dashboard api integration', () => {
     expect(body.data.projects.map((project) => project.name)).toEqual(['alpha', 'beta']);
     expect(body.data.projects.map((project) => project.path)).toEqual([projectAlpha, projectBeta]);
   });
+
+  it('GIVEN_feature_history_route_WHEN_requested_THEN_returns_log_entries', async () => {
+    const response = await logGet(
+      new Request('http://localhost/api/features/feature_checkout/log?project=alpha'),
+      {
+        params: Promise.resolve({ id: 'feature_checkout' }),
+      },
+    );
+    const body = (await response.json()) as {
+      ok: boolean;
+      data: { entries: Array<{ message: string }>; total: number };
+    };
+
+    expect(response.status).toBe(200);
+    expect(body.ok).toBe(true);
+    expect(body.data.total).toBe(1);
+    expect(body.data.entries[0].message).toBe('log message');
+    expect(readFeatureLogMock).toHaveBeenCalledWith('feature_checkout', repoRoot);
+  });
 });

package/apps/control-plane/test/dashboard-client.spec.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
-import { readDashboardStatus } from '@/lib/aop-client.js';
+import { readDashboardStatus, readFeatureLog } from '@/lib/aop-client.js';
 
 async function writeState(repoRoot: string, featureId: string, frontMatter: string): Promise<void> {
   const featureDir = path.join(repoRoot, '.aop', 'features', featureId);
@@ -91,6 +91,33 @@ describe('dashboard aop client mapping', () => {
     });
   });
 
+  it('GIVEN_state_with_gate_map_WHEN_readDashboardStatus_THEN_gate_statuses_are_parsed', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    tempRoots.push(repoRoot);
+    await fs.mkdir(path.join(repoRoot, '.aop', 'features'), { recursive: true });
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'index.json'),
+      JSON.stringify({ active: ['feature_gate'], blocked: [], merged: [], blocked_queue: [] }),
+      'utf8',
+    );
+    await writeState(
+      repoRoot,
+      'feature_gate',
+      [
+        'feature_id: feature_gate',
+        'version: 1',
+        'status: qa',
+        'gates:',
+        '  fast: pass',
+        '  full: fail',
+        '  merge: na',
+      ].join('\n'),
+    );
+
+    const payload = await readDashboardStatus(repoRoot);
+    expect(payload.features[0].gates).toEqual({ fast: 'pass', full: 'fail', merge: 'na' });
+  });
+
   it('GIVEN_blocked_queue_feature_without_state_WHEN_readDashboardStatus_THEN_phase_is_blocked', async () => {
     const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
     tempRoots.push(repoRoot);
@@ -119,4 +146,31 @@ describe('dashboard aop client mapping', () => {
       phase: 'blocked',
     });
   });
+
+  it('GIVEN_state_body_and_evidence_WHEN_readFeatureLog_THEN_returns_sorted_entries', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    tempRoots.push(repoRoot);
+    const featureRoot = path.join(repoRoot, '.aop', 'features', 'feature_hist');
+    const evidenceRoot = path.join(featureRoot, 'evidence');
+    await fs.mkdir(evidenceRoot, { recursive: true });
+    await fs.writeFile(
+      path.join(featureRoot, 'state.md'),
+      [
+        '---',
+        'feature_id: feature_hist',
+        'status: qa',
+        '---',
+        '[2026-03-05T00:00:00Z] status changed to qa',
+        '[2026-03-04T20:00:00Z] gates fast pass',
+      ].join('\n'),
+      'utf8',
+    );
+    await fs.writeFile(path.join(evidenceRoot, 'qa-summary.txt'), 'ok', 'utf8');
+
+    const log = await readFeatureLog('feature_hist', repoRoot);
+    expect(log.total).toBeGreaterThanOrEqual(3);
+    expect(log.entries[0].timestamp >= log.entries[1].timestamp).toBe(true);
+    expect(log.entries.some((entry) => entry.type === 'evidence')).toBe(true);
+    expect(log.entries.some((entry) => entry.type === 'state_change')).toBe(true);
+  });
 });

package/apps/control-plane/test/dashboard-ui-utils.spec.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'vitest';
+import {
+  applyQuickFilter,
+  computeSummaryCounts,
+  createDefaultFilters,
+  filterFeatures,
+  formatElapsedTime,
+  formatRelativeTime,
+  parseUnifiedDiff,
+  truncateText,
+} from '../../../packages/web-dashboard/src/lib/dashboard-utils.js';
+import type {
+  DashboardStatusPayload,
+  FeatureSummary,
+} from '../../../packages/web-dashboard/src/lib/types.js';
+
+function feature(overrides: Partial<FeatureSummary>): FeatureSummary {
+  return {
+    id: overrides.feature_id ?? 'feature_a',
+    feature_id: overrides.feature_id ?? 'feature_a',
+    status: overrides.status ?? 'planning',
+    phase: overrides.phase ?? 'planning',
+    branch: overrides.branch ?? null,
+    worktree_path: overrides.worktree_path ?? null,
+    activity_state: overrides.activity_state ?? 'idle',
+    pr: overrides.pr ?? null,
+    gates: overrides.gates,
+    ...overrides,
+  };
+}
+
+describe('dashboard utilities', () => {
+  it('applies quick filters deterministically', () => {
+    const active = applyQuickFilter('active');
+    expect(active.phases).toEqual(['planning', 'building', 'qa', 'ready_to_merge']);
+
+    const awaitingInput = applyQuickFilter('awaiting_input');
+    expect(awaitingInput.activities).toEqual(['waiting_input']);
+
+    const ciFailing = applyQuickFilter('ci_failing');
+    expect(ciFailing.ciFailuresOnly).toBe(true);
+  });
+
+  it('filters feature collections by search, phase, activity, gates, and ci', () => {
+    const features = [
+      feature({
+        feature_id: 'alpha',
+        phase: 'blocked',
+        activity_state: 'waiting_input',
+        gates: { fast: 'fail' },
+        pr: { ci_status: 'failure' },
+      }),
+      feature({
+        feature_id: 'beta',
+        phase: 'qa',
+        activity_state: 'active',
+        gates: { fast: 'pass' },
+        pr: { ci_status: 'success' },
+      }),
+    ];
+
+    const filters = {
+      ...createDefaultFilters(),
+      searchText: 'alp',
+      phases: ['blocked'] as FeatureSummary['phase'][],
+      activities: ['waiting_input'] as NonNullable<FeatureSummary['activity_state']>[],
+      gateFailuresOnly: true,
+      ciFailuresOnly: true,
+    };
+
+    const filtered = filterFeatures(features, filters);
+    expect(filtered).toHaveLength(1);
+    expect(filtered[0].feature_id).toBe('alpha');
+  });
+
+  it('computes summary counters from status payload', () => {
+    const payload: DashboardStatusPayload = {
+      index: {
+        active: ['alpha', 'beta'],
+        blocked: ['alpha'],
+        merged: [],
+        blocked_queue: [],
+      },
+      features: [
+        feature({
+          feature_id: 'alpha',
+          phase: 'blocked',
+          activity_state: 'waiting_input',
+          pr: { ci_status: 'failure' },
+        }),
+        feature({
+          feature_id: 'beta',
+          phase: 'ready_to_merge',
+          activity_state: 'active',
+          pr: { ci_status: 'success' },
+        }),
+      ],
+    };
+
+    const counts = computeSummaryCounts(payload);
+    expect(counts).toEqual({
+      active: 2,
+      blocked: 1,
+      awaitingInput: 1,
+      readyToMerge: 1,
+      ciFailing: 1,
+    });
+  });
+
+  it('parses unified diff into file and hunk metadata with line numbers', () => {
+    const parsed = parseUnifiedDiff(
+      [
+        'diff --git a/file.ts b/file.ts',
+        'index abc..def 100644',
+        '--- a/file.ts',
+        '+++ b/file.ts',
+        '@@ -1,2 +1,2 @@',
+        '-const oldValue = 1;',
+        '+const newValue = 2;',
+        ' export const done = true;',
+      ].join('\n'),
+    );
+
+    expect(parsed).toHaveLength(1);
+    expect(parsed[0].filePath).toBe('file.ts');
+    const allLines = parsed[0].hunks.flatMap((hunk) => hunk.lines);
+    const firstDelete = allLines.find((line) => line.type === 'del');
+    const firstAdd = allLines.find((line) => line.type === 'add');
+    expect(firstDelete).toMatchObject({ type: 'del', oldLineNumber: 1 });
+    expect(firstAdd).toMatchObject({ type: 'add', newLineNumber: 1 });
+  });
+
+  it('formats relative and elapsed time and truncates text', () => {
+    const now = Date.parse('2026-03-05T00:01:00Z');
+    expect(formatRelativeTime('2026-03-05T00:00:00Z', now)).toBe('1 minute ago');
+    expect(formatElapsedTime('2026-03-04T22:31:00Z', now)).toBe('1h 30m');
+    expect(truncateText('feature_abcdefghijklmnopqrstuvwxyz', 24)).toBe('feature_abcdefghijklm...');
+  });
+});