agentic-orchestrator 0.1.28 → 0.2.0

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

@@ -10,9 +10,11 @@ import {
   readFeatureCost,
   readFeatureDetail,
   readFeatureLog,
+  readPendingQuestions,
   readInteractivePerformanceMetrics,
   readFeatureQaTestIndex,
   readFeatureReviewBrief,
+  readFeatureTriage,
 } from '@/lib/aop-client.js';
 
 async function writeState(repoRoot: string, featureId: string, frontMatter: string): Promise<void> {
@@ -21,6 +23,47 @@ async function writeState(repoRoot: string, featureId: string, frontMatter: stri
   await fs.writeFile(path.join(featureDir, 'state.md'), `---\n${frontMatter}\n---\n`, 'utf8');
 }
 
+async function writeQuestions(
+  repoRoot: string,
+  featureId: string,
+  items: Array<Record<string, unknown>>,
+): Promise<void> {
+  const featureDir = path.join(repoRoot, '.aop', 'features', featureId);
+  await fs.mkdir(featureDir, { recursive: true });
+  await fs.writeFile(
+    path.join(featureDir, 'questions.json'),
+    JSON.stringify({ version: 1, feature_id: featureId, items }, null, 2),
+    'utf8',
+  );
+}
+
+async function writeWorkerEvents(
+  repoRoot: string,
+  runId: string,
+  entries: Array<Record<string, unknown>>,
+): Promise<void> {
+  const eventsDir = path.join(repoRoot, '.aop', 'runtime', 'worker-events');
+  await fs.mkdir(eventsDir, { recursive: true });
+  await fs.writeFile(
+    path.join(eventsDir, `${runId}.jsonl`),
+    `${entries.map((entry) => JSON.stringify(entry)).join('\n')}\n`,
+    'utf8',
+  );
+}
+
+async function writeLiveOutputSnapshot(
+  repoRoot: string,
+  featureId: string,
+  role: 'planner' | 'builder' | 'qa',
+  metadata: Record<string, unknown>,
+  content = '',
+): Promise<void> {
+  const liveDir = path.join(repoRoot, '.aop', 'features', featureId, 'logs', 'live');
+  await fs.mkdir(liveDir, { recursive: true });
+  await fs.writeFile(path.join(liveDir, `${role}.json`), JSON.stringify(metadata, null, 2), 'utf8');
+  await fs.writeFile(path.join(liveDir, `${role}.txt`), content, 'utf8');
+}
+
 describe('dashboard aop client mapping', () => {
   const tempRoots: string[] = [];
 
@@ -180,6 +223,45 @@ describe('dashboard aop client mapping', () => {
     expect(payload.features[0].activity_state).toBe('idle');
   });
 
+  it('GIVEN blocked feature with retrying recovery WHEN readDashboardStatus THEN maps recovering status and active activity', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    const recentAttemptAt = new Date(Date.now() - 60_000).toISOString();
+    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_recovering'],
+        blocked: [],
+        merged: [],
+        blocked_queue: [],
+      }),
+      'utf8',
+    );
+    await writeState(
+      repoRoot,
+      'feature_recovering',
+      [
+        'feature_id: feature_recovering',
+        'version: 1',
+        'status: blocked',
+        'status_reason: "provider_output_invalid: Planner emitted malformed worker outputs"',
+        'recovery:',
+        '  state: retrying',
+        '  cause: provider_output_invalid',
+        '  role: planner',
+        '  resume_phase: planning',
+        '  attempt: 2',
+        `  last_attempt_at: ${recentAttemptAt}`,
+      ].join('\n'),
+    );
+
+    const payload = await readDashboardStatus(repoRoot);
+    expect(payload.features[0].activity_state).toBe('active');
+    expect(payload.features[0].client_status_label).toBe('Planner Retrying');
+    expect(payload.features[0].attention_reasons).toContain('Recovering');
+  });
+
   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);
@@ -422,6 +504,471 @@ describe('dashboard aop client mapping', () => {
     });
   });
 
+  it('GIVEN_worker_events_with_historical_provider_baseline_WHEN_readFeatureDetail_THEN_returns_role_performance_cards', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    tempRoots.push(repoRoot);
+    const featureId = 'feature_role_perf';
+    await writeState(
+      repoRoot,
+      featureId,
+      [
+        `feature_id: ${featureId}`,
+        'version: 1',
+        'status: building',
+        'branch: feature/feature_role_perf',
+        'worktree_path: /tmp/worktrees/feature_role_perf',
+        'role_status:',
+        '  planner: ready',
+        '  builder: done',
+        '  qa: ready',
+      ].join('\n'),
+    );
+
+    await writeWorkerEvents(repoRoot, 'run-current', [
+      {
+        ts: '2026-03-16T10:00:00.000Z',
+        role: 'builder',
+        output_types: ['patch'],
+        patch_count: 5,
+        plan_submission_count: 0,
+        request_count: 20,
+        note_count: 1,
+        valid: true,
+        error_code: null,
+        provider: 'claude',
+        model: 'sonnet-4-6',
+        elapsed_ms: 300000,
+        feature_id: featureId,
+      },
+      {
+        ts: '2026-03-16T10:05:00.000Z',
+        role: 'builder',
+        output_types: ['patch'],
+        patch_count: 3,
+        plan_submission_count: 0,
+        request_count: 12,
+        note_count: 0,
+        valid: true,
+        error_code: null,
+        provider: 'claude',
+        model: 'sonnet-4-6',
+        elapsed_ms: 180000,
+        feature_id: featureId,
+      },
+      {
+        ts: '2026-03-16T09:00:00.000Z',
+        role: 'builder',
+        output_types: ['patch'],
+        patch_count: 4,
+        plan_submission_count: 0,
+        request_count: 10,
+        note_count: 0,
+        valid: true,
+        error_code: null,
+        provider: 'claude',
+        model: 'sonnet-4-6',
+        elapsed_ms: 240000,
+        feature_id: 'feature_prev_one',
+      },
+      {
+        ts: '2026-03-15T09:00:00.000Z',
+        role: 'builder',
+        output_types: ['patch'],
+        patch_count: 5,
+        plan_submission_count: 0,
+        request_count: 14,
+        note_count: 0,
+        valid: true,
+        error_code: null,
+        provider: 'claude',
+        model: 'sonnet-4-6',
+        elapsed_ms: 210000,
+        feature_id: 'feature_prev_two',
+      },
+    ]);
+
+    const detail = await readFeatureDetail(featureId, repoRoot);
+
+    expect(detail?.role_performance).toEqual([
+      expect.objectContaining({
+        role: 'builder',
+        role_status: 'done',
+        provider: 'claude',
+        model: 'sonnet-4-6',
+        sample_size: 2,
+        summary: 'Running slower and making more requests than average.',
+        metrics: {
+          elapsed_ms: expect.objectContaining({ actual: 480000, average: 225000, ratio: 2.13 }),
+          request_count: expect.objectContaining({ actual: 32, average: 12, ratio: 2.67 }),
+          patch_count: expect.objectContaining({ actual: 8, average: 4.5, ratio: 1.78 }),
+          plan_submission_count: expect.objectContaining({
+            actual: 0,
+            average: 0,
+            ratio: null,
+          }),
+        },
+      }),
+    ]);
+  });
+
+  it('GIVEN_active_feature_file_sets_WHEN_readFeatureDetail_THEN_returns_collision_radar_snapshot', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    tempRoots.push(repoRoot);
+    const featureId = 'feature_collision';
+    await fs.mkdir(path.join(repoRoot, '.aop', 'features'), { recursive: true });
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'index.json'),
+      JSON.stringify({
+        active: [featureId, 'feat_auth_tokens', 'feat_route_cleanup'],
+        blocked: [],
+        merged: ['feat_merged'],
+        blocked_queue: [],
+      }),
+      'utf8',
+    );
+    await writeState(
+      repoRoot,
+      featureId,
+      [
+        `feature_id: ${featureId}`,
+        'version: 1',
+        'status: building',
+        'branch: feature/feature_collision',
+        'worktree_path: /tmp/worktrees/feature_collision',
+      ].join('\n'),
+    );
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', featureId, 'plan.json'),
+      JSON.stringify({
+        files: {
+          modify: ['src/auth/login.ts', 'src/api/auth/routes.ts'],
+        },
+      }),
+      'utf8',
+    );
+
+    await writeState(
+      repoRoot,
+      'feat_auth_tokens',
+      ['feature_id: feat_auth_tokens', 'version: 1', 'status: building'].join('\n'),
+    );
+    await fs.mkdir(path.join(repoRoot, '.aop', 'features', 'feat_auth_tokens', 'evidence'), {
+      recursive: true,
+    });
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'feat_auth_tokens', 'evidence', 'diff.patch'),
+      [
+        'diff --git a/src/auth/login.ts b/src/auth/login.ts',
+        'index 1111111..2222222 100644',
+        '--- a/src/auth/login.ts',
+        '+++ b/src/auth/login.ts',
+        '@@ -1 +1 @@',
+        '-export const login = false;',
+        '+export const login = true;',
+      ].join('\n'),
+      'utf8',
+    );
+
+    await writeState(
+      repoRoot,
+      'feat_route_cleanup',
+      ['feature_id: feat_route_cleanup', 'version: 1', 'status: building'].join('\n'),
+    );
+    await fs.mkdir(path.join(repoRoot, '.aop', 'features', 'feat_route_cleanup', 'evidence'), {
+      recursive: true,
+    });
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'feat_route_cleanup', 'evidence', 'diff.patch'),
+      [
+        'diff --git a/src/api/cleanup.ts b/src/api/cleanup.ts',
+        'index 1111111..2222222 100644',
+        '--- a/src/api/cleanup.ts',
+        '+++ b/src/api/cleanup.ts',
+        '@@ -1 +1 @@',
+        '-export const cleanup = false;',
+        '+export const cleanup = true;',
+      ].join('\n'),
+      'utf8',
+    );
+
+    await writeState(
+      repoRoot,
+      'feat_merged',
+      ['feature_id: feat_merged', 'version: 1', 'status: merged'].join('\n'),
+    );
+    await fs.mkdir(path.join(repoRoot, '.aop', 'features', 'feat_merged', 'evidence'), {
+      recursive: true,
+    });
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'feat_merged', 'evidence', 'diff.patch'),
+      [
+        'diff --git a/src/auth/login.ts b/src/auth/login.ts',
+        'index 1111111..2222222 100644',
+        '--- a/src/auth/login.ts',
+        '+++ b/src/auth/login.ts',
+        '@@ -1 +1 @@',
+        '-const oldMerged = true;',
+        '+const merged = true;',
+      ].join('\n'),
+      'utf8',
+    );
+
+    const detail = await readFeatureDetail(featureId, repoRoot);
+
+    expect(detail?.collision_radar).toEqual({
+      this_feature_files: ['src/api/auth/routes.ts', 'src/auth/login.ts'],
+      entries: [
+        {
+          path: 'src/auth/login.ts',
+          depth: 2,
+          competing_features: ['feat_auth_tokens'],
+          risk: 'high',
+        },
+        {
+          path: 'src/api/auth/routes.ts',
+          depth: 3,
+          competing_features: ['feat_route_cleanup'],
+          risk: 'low',
+        },
+      ],
+      high_count: 1,
+      medium_count: 0,
+      low_count: 1,
+    });
+  });
+
+  it('GIVEN_focus_track_b_artifacts_WHEN_readFeatureDetail_THEN_returns_usage_genealogy_gate_history_and_merge_queue', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    tempRoots.push(repoRoot);
+    const featureId = 'feature_focus_track_b';
+    const featureRoot = path.join(repoRoot, '.aop', 'features', featureId);
+    await fs.mkdir(path.join(featureRoot, 'evidence'), { recursive: true });
+    await fs.mkdir(path.join(repoRoot, '.aop', 'features'), { recursive: true });
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'index.json'),
+      JSON.stringify({
+        active: ['feature_ahead', featureId],
+        blocked: [],
+        merged: [],
+        blocked_queue: [],
+        dep_blocked: [{ feature_id: featureId, depends_on_unresolved: ['feature_ahead'] }],
+      }),
+      'utf8',
+    );
+    await fs.mkdir(path.join(repoRoot, 'config', 'agentic', 'orchestrator'), { recursive: true });
+    await fs.writeFile(
+      path.join(repoRoot, 'config', 'agentic', 'orchestrator', 'policy.yaml'),
+      [
+        'budget:',
+        '  per_feature_limit_tokens: 200000',
+        '  token_cost_conversion:',
+        '    usd_per_1k_tokens: 0.01',
+      ].join('\n'),
+      'utf8',
+    );
+    await writeState(
+      repoRoot,
+      featureId,
+      [
+        `feature_id: ${featureId}`,
+        'version: 1',
+        'status: ready_to_merge',
+        'plan_version: 2',
+        'revision_of: 1',
+        'revision_reason: Prior gate failed',
+        'gate_retry_count: 2',
+        'phase_entered_at: 2026-03-16T19:00:00.000Z',
+        'pr:',
+        '  pending_review_threads: 1',
+        '  ci_status: pending',
+      ].join('\n'),
+    );
+    await writeState(
+      repoRoot,
+      'feature_ahead',
+      [
+        'feature_id: feature_ahead',
+        'version: 1',
+        'status: ready_to_merge',
+        'phase_entered_at: 2026-03-16T18:00:00.000Z',
+      ].join('\n'),
+    );
+    await fs.writeFile(
+      path.join(featureRoot, 'plan.json'),
+      JSON.stringify({ plan_version: 2, revision_of: 1 }),
+      'utf8',
+    );
+    await fs.writeFile(
+      path.join(featureRoot, 'cost.json'),
+      JSON.stringify({
+        tokens_used: 42000,
+        estimated_cost_usd: 0.42,
+        recorded_at: '2026-03-16T19:40:00.000Z',
+      }),
+      'utf8',
+    );
+    await fs.writeFile(
+      path.join(featureRoot, 'evidence', 'gate-fast-20260316T194000.json'),
+      JSON.stringify({
+        mode: 'fast',
+        overall: 'fail',
+        finished_at: '2026-03-16T19:40:00.000Z',
+        step_results: [
+          {
+            name: 'npm run test',
+            status: 'fail',
+            exit_code: 1,
+            output_tail: ['coverage threshold missed'],
+            started_at: '2026-03-16T19:39:00.000Z',
+            finished_at: '2026-03-16T19:40:00.000Z',
+          },
+        ],
+      }),
+      'utf8',
+    );
+    await fs.writeFile(
+      path.join(featureRoot, 'evidence', 'gate-fast-20260316T194500.json'),
+      JSON.stringify({
+        mode: 'fast',
+        overall: 'pass',
+        finished_at: '2026-03-16T19:45:00.000Z',
+        step_results: [
+          {
+            name: 'npm run test',
+            status: 'pass',
+            exit_code: 0,
+            output_tail: [],
+            started_at: '2026-03-16T19:44:00.000Z',
+            finished_at: '2026-03-16T19:45:00.000Z',
+          },
+        ],
+      }),
+      'utf8',
+    );
+    await writeWorkerEvents(repoRoot, 'run-focus', [
+      {
+        ts: '2026-03-16T19:05:00.000Z',
+        role: 'builder',
+        output_types: ['patch'],
+        patch_count: 2,
+        plan_submission_count: 0,
+        request_count: 6,
+        note_count: 0,
+        valid: true,
+        error_code: null,
+        provider: 'claude',
+        model: 'sonnet-4-6',
+        elapsed_ms: 120000,
+        feature_id: featureId,
+      },
+      {
+        ts: '2026-03-16T19:15:00.000Z',
+        role: 'builder',
+        output_types: ['patch'],
+        patch_count: 2,
+        plan_submission_count: 0,
+        request_count: 7,
+        note_count: 0,
+        valid: true,
+        error_code: null,
+        provider: 'claude',
+        model: 'sonnet-4-6',
+        elapsed_ms: 150000,
+        feature_id: featureId,
+      },
+      {
+        ts: '2026-03-15T19:15:00.000Z',
+        role: 'builder',
+        output_types: ['patch'],
+        patch_count: 1,
+        plan_submission_count: 0,
+        request_count: 4,
+        note_count: 0,
+        valid: true,
+        error_code: null,
+        provider: 'claude',
+        model: 'sonnet-4-6',
+        elapsed_ms: 90000,
+        feature_id: 'feature_old',
+      },
+    ]);
+
+    const detail = await readFeatureDetail(featureId, repoRoot);
+
+    expect(detail?.usage_burn).toMatchObject({
+      current_tokens_used: 42000,
+      budget_limit_tokens: 200000,
+      confidence: 'medium',
+    });
+    expect(detail?.genealogy?.nodes).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ id: featureId, kind: 'feature' }),
+        expect.objectContaining({ label: 'Plan v2', kind: 'plan_revision' }),
+      ]),
+    );
+    expect(detail?.gate_history?.[0]).toMatchObject({
+      mode: 'fast',
+      steps: [expect.objectContaining({ name: 'npm run test' })],
+    });
+    expect(detail?.merge_queue?.current_feature).toMatchObject({
+      feature_id: featureId,
+      blocked_by: ['feature_ahead'],
+    });
+    expect(detail?.worker_summary?.entries).toHaveLength(2);
+  });
+
+  it('GIVEN_live_agent_output_WHEN_reading_feature_detail_THEN_includes_live_snapshot_metadata_without_console_content', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    tempRoots.push(repoRoot);
+    const featureId = 'feature_live_runtime';
+
+    await fs.mkdir(path.join(repoRoot, '.aop', 'features'), { recursive: true });
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'index.json'),
+      JSON.stringify({ active: [featureId], blocked: [], merged: [], blocked_queue: [] }),
+      'utf8',
+    );
+    await writeState(
+      repoRoot,
+      featureId,
+      [
+        `feature_id: ${featureId}`,
+        'version: 1',
+        'status: qa',
+        'phase_entered_at: 2026-03-17T18:00:00.000Z',
+      ].join('\n'),
+    );
+    await writeLiveOutputSnapshot(
+      repoRoot,
+      featureId,
+      'qa',
+      {
+        session_id: 'qa-session-1',
+        provider: 'openai',
+        model: 'gpt-5.4',
+        execution_mode: 'interactive',
+        status: 'running',
+        started_at: '2026-03-17T18:05:00.000Z',
+      },
+      'live runtime output',
+    );
+
+    const detail = await readFeatureDetail(featureId, repoRoot);
+
+    expect(detail?.live_output_snapshots).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          role: 'qa',
+          session_id: 'qa-session-1',
+          status: 'running',
+          provider: 'openai',
+          model: 'gpt-5.4',
+        }),
+      ]),
+    );
+    expect(detail?.live_output_snapshots?.[0]).not.toHaveProperty('content');
+  });
+
   it('GIVEN_checkpoint_state_and_diff_artifacts_WHEN_read_checkpoint_helpers_THEN_returns_snapshot_and_comparison', async () => {
     const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
     tempRoots.push(repoRoot);
@@ -592,4 +1139,405 @@ describe('dashboard aop client mapping', () => {
     expect(metrics.execution_modes.context_request_reduction_ratio).toBeCloseTo(0.75, 2);
     expect(metrics.latest?.checkpoint_id).toBe('checkpoint-003');
   });
+
+  it('GIVEN_policy_and_cost_artifacts_WHEN_readDashboardStatus_THEN_derives_token_budget_and_attention_fields', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    tempRoots.push(repoRoot);
+    await fs.mkdir(path.join(repoRoot, '.aop', 'features', 'feature_tokens'), { recursive: true });
+    await fs.mkdir(path.join(repoRoot, 'config', 'agentic', 'orchestrator'), { recursive: true });
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'index.json'),
+      JSON.stringify({ active: ['feature_tokens'], blocked: [], merged: [], blocked_queue: [] }),
+      'utf8',
+    );
+    await fs.writeFile(
+      path.join(repoRoot, 'config', 'agentic', 'orchestrator', 'policy.yaml'),
+      [
+        'budget:',
+        '  per_feature_limit_tokens: 1000',
+        '  alert_threshold: 0.8',
+        '  token_cost_conversion:',
+        '    usd_per_1k_tokens: 0.35',
+      ].join('\n'),
+      'utf8',
+    );
+    await writeState(
+      repoRoot,
+      'feature_tokens',
+      [
+        'feature_id: feature_tokens',
+        'version: 1',
+        'status: building',
+        `last_updated: ${new Date().toISOString()}`,
+        'status_reason: waiting_input:user_confirmation',
+      ].join('\n'),
+    );
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'feature_tokens', 'cost.json'),
+      JSON.stringify({
+        tokens_used: 920,
+        estimated_cost_usd: 0.32,
+        recorded_at: '2026-03-05T00:00:00Z',
+      }),
+      'utf8',
+    );
+
+    const payload = await readDashboardStatus(repoRoot);
+    expect(payload.metrics?.total_tokens_today).toBe(920);
+    expect(payload.metrics?.total_cost_today_usd).toBeCloseTo(0.32, 2);
+    expect(payload.features[0]).toMatchObject({
+      feature_id: 'feature_tokens',
+      waiting_input_count: 1,
+      usage_tokens: 920,
+      budget_state: 'critical',
+      client_status_label: 'Needs Input',
+    });
+    expect(payload.features[0].attention_reasons).toContain('Needs Me');
+  });
+
+  it('GIVEN_feature_triage_request_WHEN_readFeatureTriage_THEN_returns_reduced_root_payload', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-dash-client-'));
+    tempRoots.push(repoRoot);
+    await fs.mkdir(path.join(repoRoot, '.aop', 'features', 'feature_triage'), { recursive: true });
+    await fs.mkdir(path.join(repoRoot, 'config', 'agentic', 'orchestrator'), { recursive: true });
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'index.json'),
+      JSON.stringify({
+        active: ['feature_triage'],
+        blocked: [],
+        merged: [],
+        blocked_queue: [],
+        dep_blocked: [{ feature_id: 'feature_triage', depends_on_unresolved: ['dep_a'] }],
+      }),
+      'utf8',
+    );
+    await fs.writeFile(
+      path.join(repoRoot, 'config', 'agentic', 'orchestrator', 'policy.yaml'),
+      ['budget:', '  per_feature_limit_tokens: 2000'].join('\n'),
+      'utf8',
+    );
+    await writeState(
+      repoRoot,
+      'feature_triage',
+      [
+        'feature_id: feature_triage',
+        'version: 1',
+        'status: qa',
+        'status_reason: gate failure on full profile',
+        'pr:',
+        '  ci_status: pending',
+      ].join('\n'),
+    );
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'feature_triage', 'cost.json'),
+      JSON.stringify({ tokens_used: 400, estimated_cost_usd: 0.14 }, null, 2),
+      'utf8',
+    );
+
+    const triage = await readFeatureTriage('feature_triage', repoRoot);
+    expect(triage).not.toBeNull();
+    expect(triage?.dependency_summary).toEqual(['dep_a']);
+    expect(triage?.usage?.budget_limit_tokens).toBe(2000);
+    expect(triage?.review_snapshot?.ci_status).toBe('pending');
+    expect(triage?.blocker_summary).toContain('dep_a');
+  });
+
+  it('GIVEN_ready_and_stale_open_questions_WHEN_reading_pending_questions_THEN_only_persisted_awaiting_input_questions_are_actionable', 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_ready', 'feature_stale'],
+        blocked: [],
+        merged: [],
+        blocked_queue: [],
+      }),
+      'utf8',
+    );
+
+    await writeState(
+      repoRoot,
+      'feature_ready',
+      [
+        'feature_id: feature_ready',
+        'version: 1',
+        'status: awaiting_input',
+        'human_input:',
+        '  open_question_id: q_ready',
+        '  open_question_count: 1',
+        '  awaiting_since: 2026-03-17T12:00:00.000Z',
+        '  requested_by_role: builder',
+        '  resume_status: building',
+      ].join('\n'),
+    );
+    await writeQuestions(repoRoot, 'feature_ready', [
+      {
+        question_id: 'q_ready',
+        status: 'open',
+        blocking: true,
+        question_type: 'clarification',
+        role: 'builder',
+        phase: 'building',
+        request_action: 'ask_user_input',
+        prompt: 'Ready question',
+        created_at: '2026-03-17T12:00:00.000Z',
+      },
+    ]);
+
+    await writeState(
+      repoRoot,
+      'feature_stale',
+      [
+        'feature_id: feature_stale',
+        'version: 1',
+        'status: building',
+        'human_input:',
+        '  open_question_id: q_stale',
+        '  open_question_count: 1',
+        '  awaiting_since: 2026-03-17T12:05:00.000Z',
+        '  requested_by_role: qa',
+        '  resume_status: building',
+      ].join('\n'),
+    );
+    await writeQuestions(repoRoot, 'feature_stale', [
+      {
+        question_id: 'q_stale',
+        status: 'open',
+        blocking: true,
+        question_type: 'clarification',
+        role: 'qa',
+        phase: 'qa',
+        request_action: 'ask_user_input',
+        prompt: 'Stale question',
+        created_at: '2026-03-17T12:05:00.000Z',
+      },
+    ]);
+
+    const pending = await readPendingQuestions(repoRoot);
+    const payload = await readDashboardStatus(repoRoot);
+
+    expect(pending).toHaveLength(1);
+    expect(pending[0]).toMatchObject({
+      feature_id: 'feature_ready',
+      question_id: 'q_ready',
+    });
+    expect(payload.pending_questions).toMatchObject({
+      count: 1,
+      items: [expect.objectContaining({ feature_id: 'feature_ready', question_id: 'q_ready' })],
+    });
+  });
+
+  it('GIVEN_open_question_without_awaiting_input_state_WHEN_reading_triage_and_detail_THEN_question_is_not_exposed_as_actionable', 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_triage_question'],
+        blocked: [],
+        merged: [],
+        blocked_queue: [],
+      }),
+      'utf8',
+    );
+
+    await writeState(
+      repoRoot,
+      'feature_triage_question',
+      [
+        'feature_id: feature_triage_question',
+        'version: 1',
+        'status: building',
+        'human_input:',
+        '  open_question_id: q_hidden',
+        '  open_question_count: 1',
+        '  awaiting_since: 2026-03-17T12:10:00.000Z',
+        '  requested_by_role: builder',
+        '  resume_status: building',
+      ].join('\n'),
+    );
+    await writeQuestions(repoRoot, 'feature_triage_question', [
+      {
+        question_id: 'q_hidden',
+        status: 'open',
+        blocking: true,
+        question_type: 'clarification',
+        role: 'builder',
+        phase: 'building',
+        request_action: 'ask_user_input',
+        prompt: 'Should stay hidden',
+        created_at: '2026-03-17T12:10:00.000Z',
+      },
+    ]);
+
+    const triage = await readFeatureTriage('feature_triage_question', repoRoot);
+    const detail = await readFeatureDetail('feature_triage_question', repoRoot);
+
+    expect(triage?.open_questions).toEqual([]);
+    expect(detail?.questions?.filter((question) => question.status === 'open')).toEqual([]);
+  });
+
+  it('GIVEN_stale_waiting_input_activity_after_question_answer_WHEN_reading_dashboard_status_THEN_needs_input_is_cleared', 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_resumed'],
+        blocked: [],
+        merged: [],
+        blocked_queue: [],
+      }),
+      'utf8',
+    );
+
+    await writeState(
+      repoRoot,
+      'feature_resumed',
+      [
+        'feature_id: feature_resumed',
+        'version: 1',
+        'status: building',
+        'status_reason: question_answered:q_resumed',
+        'activity_state: waiting_input',
+        'activity_last_event_at: 2026-03-18T12:00:00.000Z',
+        'activity_detected_via: jsonl',
+        'human_input:',
+        '  open_question_id: null',
+        '  open_question_count: 0',
+        '  awaiting_since: null',
+        '  requested_by_role: null',
+        '  resume_status: null',
+      ].join('\n'),
+    );
+
+    const payload = await readDashboardStatus(repoRoot);
+
+    expect(payload.features[0]).toMatchObject({
+      feature_id: 'feature_resumed',
+      status: 'building',
+      activity_state: 'idle',
+      waiting_input_count: 0,
+    });
+    expect(payload.features[0].client_status_label).not.toBe('Needs Input');
+    expect(payload.features[0].attention_reasons).not.toContain('Needs Me');
+  });
+
+  it('GIVEN_intake_question_and_review_WHEN_reading_dashboard_views_THEN_exposes_intake_metadata_and_ready_state', 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_intake'],
+        blocked: [],
+        merged: [],
+        blocked_queue: [],
+      }),
+      'utf8',
+    );
+
+    await writeState(
+      repoRoot,
+      'feature_intake',
+      [
+        'feature_id: feature_intake',
+        'version: 1',
+        'status: awaiting_input',
+        'human_input:',
+        '  open_question_id: q_intake',
+        '  open_question_count: 1',
+        '  awaiting_since: 2026-03-17T12:00:00.000Z',
+        '  requested_by_role: planner',
+        '  resume_status: intake',
+        'intake:',
+        '  status: awaiting_input',
+        '  bootstrap_manifest_version: 2',
+        '  verified_manifest_version: 1',
+        '  open_ambiguity_count: 3',
+        '  last_verified_at: 2026-03-17T11:55:00.000Z',
+        '  promotion_basis: human_review_confirmed',
+      ].join('\n'),
+    );
+    await writeQuestions(repoRoot, 'feature_intake', [
+      {
+        question_id: 'q_intake',
+        status: 'open',
+        blocking: true,
+        question_type: 'clarification',
+        role: 'planner',
+        phase: 'intake',
+        request_action: 'ask_user_input',
+        prompt: 'Resolve the remaining intake ambiguity',
+        details: {
+          ambiguity_id: 'AMB-003',
+          obligation_ids: ['OBL-001', 'OBL-004'],
+        },
+        created_at: '2026-03-17T12:00:00.000Z',
+        resume_status: 'intake',
+      },
+    ]);
+    await fs.writeFile(
+      path.join(repoRoot, '.aop', 'features', 'feature_intake', 'intake.review.json'),
+      JSON.stringify(
+        {
+          feature_id: 'feature_intake',
+          version: 2,
+          status: 'proposed',
+          questions_open: 1,
+          questions_resolved: 2,
+          ambiguities: [{ ambiguity_id: 'AMB-003' }],
+        },
+        null,
+        2,
+      ),
+      'utf8',
+    );
+
+    const pending = await readPendingQuestions(repoRoot);
+    const triage = await readFeatureTriage('feature_intake', repoRoot);
+    const detail = await readFeatureDetail('feature_intake', repoRoot);
+
+    expect(pending).toHaveLength(1);
+    expect(pending[0]).toMatchObject({
+      feature_id: 'feature_intake',
+      question_id: 'q_intake',
+      ambiguity_id: 'AMB-003',
+      obligation_ids: ['OBL-001', 'OBL-004'],
+      intake_context: expect.objectContaining({
+        status: 'awaiting_input',
+        bootstrap_manifest_version: 2,
+        verified_manifest_version: 1,
+        open_ambiguity_count: 3,
+      }),
+    });
+    expect(triage?.intake).toMatchObject({
+      summary: {
+        status: 'awaiting_input',
+        bootstrap_manifest_version: 2,
+        verified_manifest_version: 1,
+      },
+      review: {
+        status: 'proposed',
+        questions_open: 1,
+        questions_resolved: 2,
+        ambiguity_count: 1,
+      },
+    });
+    expect(detail?.intake).toMatchObject({
+      summary: {
+        status: 'awaiting_input',
+        promotion_basis: 'human_review_confirmed',
+      },
+      review: {
+        status: 'proposed',
+        questions_open: 1,
+      },
+    });
+  });
 });