feat(config)!: replace vuln_classes with agentic_sast

Wire Agentic SAST and reconciliation into the main pipeline, persist their durable state, and add the Miscellaneous finding and exploitation lane. Make scan completion, cancellation, partial outcomes, resume identity, and report recovery use the integrated final workflow contract. Introduce the atomic finalization, ordering, renumbering, compaction, and output services that workflow calls. Keep completed Miscellaneous work and report drafts idempotent across resume, preserve public main's default-on exploit SARIF behavior, and describe stage-fallback candidates without claiming they were exported. BREAKING CHANGE: `vuln_classes` has been removed. Configs containing it now fail validation, and all five core pentest classes run on every scan. Workspaces created by Shannon 2.x cannot be resumed. Finish or discard in-flight scans before upgrading, then start a new workspace name.
2026-09-22 17:50:50 +02:00 · 2026-08-26 19:55:03 -07:00
parent c33132b0ab
commit 98c66e051d
57 changed files with 7628 additions and 1201 deletions
@@ -8,7 +8,13 @@
 */

 import type { RunningAgent } from '../temporal-client.js';
-import { agentClass, PIPELINE, type PipelineState } from './pipeline.js';
+import {
+  agentClass,
+  type OperationalStageState,
+  operationFamilyKey,
+  type PipelineState,
+  pipelineForState,
+} from './pipeline.js';
 import type { RenderInput } from './render.js';

 export type RunState = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
@@ -22,6 +28,8 @@ export interface DerivedAgent {
  readonly durationMs: number | null;
  readonly runningElapsedMs: number | null;
  readonly attempt: number | null;
+  /** The step a running operation row is currently on, merged in from its child activity. */
+  readonly detail?: string;
  readonly error?: string;
 }

@@ -48,12 +56,12 @@ function isAgentActive(name: string, state: PipelineState | null, running: Set<s
 }

 /**
- * Resolve one agent's state. "Ran" is signalled by a metrics entry, not by
- * completedAgents — the workflow lists conditionally-skipped agents (e.g. exploit
- * agents when there is nothing to exploit) as completed but records no metrics for
- * them. `resolved` is true once we've moved past this agent's phase (the scan is
- * terminal, or a later phase is already active), at which point a metric-less,
- * non-running agent is skipped rather than still pending.
+ * Resolve one agent's state. "Ran" is signalled by a metrics entry: a
+ * conditionally-skipped agent (e.g. an exploit agent when there is nothing to
+ * exploit) records no metrics, and the workflow tracks it in skippedAgents rather
+ * than completedAgents. `resolved` is true once we've moved past this agent's phase
+ * (the scan is terminal, or a later phase is already active), at which point a
+ * metric-less, non-running agent is skipped rather than still pending.
 */
 function agentState(name: string, state: PipelineState | null, running: Set<string>, resolved: boolean): RunState {
  if (running.has(name)) return 'running';
@@ -99,16 +107,17 @@ export function phaseGlyphState(states: readonly RunState[]): RunState {
 * class had anything to exploit), not still pending.
 */
 export function deriveAgentStates(input: RenderInput): Map<string, RunState> {
-  const runningSet = new Set(input.running.map((r) => r.agent));
+  const pipeline = pipelineForState(input.state);
+  const runningSet = new Set(input.running.filter((runner) => runner.kind === 'agent').map((runner) => runner.agent));
  const terminal = isTerminal(input.temporalStatus);

  let frontier = -1;
-  PIPELINE.forEach((phase, idx) => {
+  pipeline.forEach((phase, idx) => {
    if (phase.agents.some((a) => isAgentActive(a.name, input.state, runningSet))) frontier = idx;
  });

  const states = new Map<string, RunState>();
-  for (const [phaseIdx, phase] of PIPELINE.entries()) {
+  for (const [phaseIdx, phase] of pipeline.entries()) {
    const resolved = terminal || phaseIdx < frontier;
    for (const agent of phase.agents) {
      states.set(agent.name, agentState(agent.name, input.state, runningSet, resolved));
@@ -117,6 +126,52 @@ export function deriveAgentStates(input: RenderInput): Map<string, RunState> {
  return states;
 }

+/** Which operation families have a running parent stage, and the step to show on it. */
+interface OperationFamilyView {
+  /** Families whose parent stage row already represents their child activities. */
+  readonly runningFamilies: ReadonlySet<string>;
+  /** Family to current step, present only where the child activities agree on one. */
+  readonly stepByFamily: ReadonlyMap<string, string>;
+}
+
+/**
+ * Resolve the parent stage rows that own their family's child activities. A family only
+ * resolves to a step when its running children agree: several classes reconcile at once and
+ * their pending activities carry no class, so a family caught mid-stride shows its parent
+ * rows without a step rather than attributing one to the wrong class.
+ */
+function operationFamilyView(
+  running: readonly RunningAgent[],
+  persistedOperations: readonly OperationalStageState[],
+): OperationFamilyView {
+  const runningFamilies = new Set(
+    persistedOperations
+      .filter((operation) => operation.status === 'running')
+      .map((operation) => operationFamilyKey(operation.key)),
+  );
+
+  const labelsByFamily = new Map<string, Set<string>>();
+  for (const runner of running) {
+    if (runner.kind !== 'operation' || runner.parentKey === undefined) continue;
+    if (!runningFamilies.has(runner.parentKey)) continue;
+    const labels = labelsByFamily.get(runner.parentKey) ?? new Set<string>();
+    labels.add(runner.label);
+    labelsByFamily.set(runner.parentKey, labels);
+  }
+
+  const stepByFamily = new Map<string, string>();
+  for (const [family, labels] of labelsByFamily) {
+    const [onlyLabel] = labels;
+    if (labels.size === 1 && onlyLabel !== undefined) stepByFamily.set(family, lowercaseFirst(onlyLabel));
+  }
+  return { runningFamilies, stepByFamily };
+}
+
+/** Progress labels are written to start a row; as a detail they continue a sentence. */
+function lowercaseFirst(label: string): string {
+  return label.charAt(0).toLowerCase() + label.slice(1);
+}
+
 /**
 * Full structured view of the pipeline: every agent's state plus the raw
 * metrics/timing needed to present it, and each phase's collapsed state.
@@ -124,8 +179,9 @@ export function deriveAgentStates(input: RenderInput): Map<string, RunState> {
 export function derivePipeline(input: RenderInput, now: number): DerivedPhase[] {
  const states = deriveAgentStates(input);
  const byAgent = new Map(input.running.map((r) => [r.agent, r]));
+  const pipeline = pipelineForState(input.state);

-  return PIPELINE.map((phase) => {
+  const agentPhases = pipeline.map((phase) => {
    const agents = phase.agents.map((a): DerivedAgent => {
      const state = states.get(a.name) ?? 'pending';
      const metrics = input.state?.agentMetrics[a.name];
@@ -150,6 +206,57 @@ export function derivePipeline(input: RenderInput, now: number): DerivedPhase[]
      agents,
    };
  });
+
+  // Operational rows merge two sources: stages the worker has persisted (durable truth,
+  // including terminal outcomes) and pending activities whose stage record has not landed
+  // yet. Persisted keys win, so a stage is never listed twice while the two views overlap.
+  const persistedOperations = Object.values(input.state?.operationalStages ?? {});
+  const persistedKeys = new Set(persistedOperations.map((operation) => operation.key));
+  const { runningFamilies, stepByFamily } = operationFamilyView(input.running, persistedOperations);
+  const unpersistedRunning = input.running
+    .filter((runner) => runner.kind === 'operation' && !persistedKeys.has(runner.agent))
+    // A child activity whose family already has a running parent stage is that stage's current
+    // step, not separate work: the parent row below represents it, with the step as its detail
+    // where the family's children agree on one. Without such a parent it keeps its own row.
+    .filter((runner) => runner.parentKey === undefined || !runningFamilies.has(runner.parentKey))
+    .map((runner) => ({
+      key: runner.agent,
+      label: runner.label,
+      status: 'running' as const,
+      ...(runner.startedAt !== undefined && { startedAt: runner.startedAt }),
+      ...(runner.lastFailure !== undefined && { error: runner.lastFailure }),
+    }));
+  const operationalAgents: DerivedAgent[] = [...persistedOperations, ...unpersistedRunning].map((operation) => {
+    const runner = byAgent.get(operation.key);
+    const operationState = operation.status as RunState;
+    const persistedDurationMs = 'durationMs' in operation ? (operation.durationMs ?? null) : null;
+    const detail = operationState === 'running' ? stepByFamily.get(operationFamilyKey(operation.key)) : undefined;
+    return {
+      name: operation.key,
+      label: operation.label,
+      state: operationState,
+      durationMs: operationState === 'completed' ? persistedDurationMs : null,
+      runningElapsedMs:
+        operationState === 'running' && operation.startedAt !== undefined ? now - operation.startedAt : null,
+      attempt: operationState === 'running' ? (runner?.attempt ?? null) : null,
+      ...(detail !== undefined && { detail }),
+      ...(operation.error !== undefined && { error: operation.error }),
+    };
+  });
+
+  // The synthetic phase appears only when there is operational work to show, so a scan
+  // with no recorded operational stages keeps the plain agent tree.
+  if (operationalAgents.length === 0) return agentPhases;
+  return [
+    ...agentPhases,
+    {
+      key: 'operational-work',
+      label: 'Background work',
+      parallel: true,
+      state: phaseGlyphState(operationalAgents.map((operation) => operation.state)),
+      agents: operationalAgents,
+    },
+  ];
 }

 export { agentError };
@@ -8,6 +8,7 @@
 *   - apps/worker/src/temporal/activities.ts (the run*Agent activity names → `activityType`)
 *   - apps/worker/src/temporal/shared.ts     (PipelineState / PipelineSummary)
 *   - apps/worker/src/types/metrics.ts       (AgentMetrics)
+ *   - apps/worker/src/types/run-state.ts     (PartialReasonView)
 */

 export interface AgentSpec {
@@ -26,6 +27,18 @@ export interface PhaseSpec {
  readonly agents: readonly AgentSpec[];
 }

+export interface ActivityProgressSpec {
+  readonly key: string;
+  readonly label: string;
+  readonly kind: 'agent' | 'operation';
+  /**
+   * Operation rows whose work is already represented by a persisted parent stage. The parent
+   * owns the row; this activity supplies the step shown as its detail. Parent stage keys are
+   * the family key itself or the family key followed by ':' and a class or stage suffix.
+   */
+  readonly parentKey?: string;
+}
+
 /** The pipeline phases in execution order, each with its agents. */
 export const PIPELINE: readonly PhaseSpec[] = [
  {
@@ -80,9 +93,175 @@ export const PIPELINE: readonly PhaseSpec[] = [
  },
 ];

-/** Temporal activity type name → canonical agent name, for mapping pendingActivities. */
+const OTHER_EXPLOIT_AGENT: AgentSpec = {
+  name: 'other-exploit',
+  label: 'other',
+  activityType: 'runOtherExploitAgent',
+};
+
+/**
+ * Shape the static PIPELINE to one scan's durable truth. expectedAgents, persisted by the
+ * worker at scan start, names every exploit agent the scan can ever run: exploit rows it
+ * excludes are dropped, 'other-exploit' is appended only once the other pipeline has
+ * admitted findings, and a phase left with no agents disappears entirely. Without state
+ * (the scan has not initialized durable state yet) the full static pipeline is the best
+ * available guess.
+ */
+export function pipelineForState(state: PipelineState | null): readonly PhaseSpec[] {
+  if (state?.expectedAgents === undefined) return PIPELINE;
+  const expected = new Set(state.expectedAgents);
+  return PIPELINE.map((phase) => {
+    if (phase.key !== 'exploitation') return phase;
+    const agents = phase.agents.filter((agent) => expected.has(agent.name));
+    if (expected.has(OTHER_EXPLOIT_AGENT.name)) agents.push(OTHER_EXPLOIT_AGENT);
+    return { ...phase, agents };
+  }).filter((phase) => phase.agents.length > 0);
+}
+
+const AGENT_ACTIVITY_PROGRESS: Readonly<Record<string, ActivityProgressSpec>> = Object.fromEntries(
+  [...PIPELINE.flatMap((phase) => phase.agents), OTHER_EXPLOIT_AGENT].map((agent) => [
+    agent.activityType,
+    { key: agent.name, label: agent.label, kind: 'agent' },
+  ]),
+);
+
+/** Families whose per-class or per-stage work is already carried by one persisted stage row. */
+const RECONCILIATION_PARENT_KEY = 'reconciliation';
+const AGENTIC_SAST_PARENT_KEY = 'agentic-sast';
+
+// Every production activity that is not an agent run must have a row here. describeScan
+// throws on an unmapped activity type, so adding a worker activity without updating this
+// table breaks `shannon status` loudly instead of hiding the new work. The authoritative
+// name lists live in apps/worker/src/temporal/worker.ts,
+// apps/worker/src/temporal/reconcile-activity-types.ts, and
+// apps/worker/src/ai/sast/capella/temporal/activity-types.ts.
+const OPERATION_ACTIVITY_PROGRESS: Readonly<Record<string, ActivityProgressSpec>> = {
+  runPreflightValidation: { key: 'preflight', label: 'Preflight validation', kind: 'operation' },
+  syncPlaywrightStealthConfig: { key: 'preflight', label: 'Browser setup', kind: 'operation' },
+  initDeliverableGit: { key: 'scan-initialization', label: 'Initialize deliverables', kind: 'operation' },
+  syncCodePathDenyRules: { key: 'scan-initialization', label: 'Apply source rules', kind: 'operation' },
+  initializeDurableScanState: { key: 'durable-state', label: 'Saving scan state', kind: 'operation' },
+  persistOtherOutcome: { key: 'other-pipeline', label: 'Including other findings', kind: 'operation' },
+  initializeReportProgress: { key: 'report:initialize', label: 'Initialize report state', kind: 'operation' },
+  renumberClassFindings: { key: 'report:renumber', label: 'Renumber findings', kind: 'operation' },
+  assembleReportActivity: { key: 'report:assemble', label: 'Assemble report inputs', kind: 'operation' },
+  compactReportFindings: { key: 'report:compact', label: 'Compact report findings', kind: 'operation' },
+  persistCanonicalReportProgress: { key: 'report:checkpoint', label: 'Saving report progress', kind: 'operation' },
+  finalizeReportOutputs: { key: 'report:finalize', label: 'Finalize report outputs', kind: 'operation' },
+  persistFinalizedReportProgress: { key: 'report:terminal', label: 'Saving final report state', kind: 'operation' },
+  surfaceReportOutputs: { key: 'report:surface', label: 'Surface customer report', kind: 'operation' },
+  checkExploitationQueue: { key: 'queue-check', label: 'Check exploitation queue', kind: 'operation' },
+  loadResumeState: { key: 'resume-validation', label: 'Validate resume state', kind: 'operation' },
+  restoreGitCheckpoint: { key: 'resume-restore', label: 'Restore checkpoint', kind: 'operation' },
+  registerResumeAttempt: { key: 'resume-registration', label: 'Register resume', kind: 'operation' },
+  recordResumeAttempt: { key: 'resume-registration', label: 'Record resume', kind: 'operation' },
+  logPhaseTransition: { key: 'audit-log', label: 'Update audit log', kind: 'operation' },
+  logWorkflowComplete: { key: 'audit-log', label: 'Finalize audit log', kind: 'operation' },
+  saveCheckpoint: { key: 'checkpoint', label: 'Save checkpoint', kind: 'operation' },
+  seedEmptyProducerQueue: { key: 'other-pipeline', label: 'Preparing other findings', kind: 'operation' },
+  prepareClassReconciliation: {
+    key: 'reconciliation',
+    label: 'Preparing findings',
+    kind: 'operation',
+    parentKey: RECONCILIATION_PARENT_KEY,
+  },
+  enrichClassSastObservations: {
+    key: 'reconciliation',
+    label: 'Adding code context',
+    kind: 'operation',
+    parentKey: RECONCILIATION_PARENT_KEY,
+  },
+  formClassExploitTasks: {
+    key: 'reconciliation',
+    label: 'Grouping into test cases',
+    kind: 'operation',
+    parentKey: RECONCILIATION_PARENT_KEY,
+  },
+  materializeClassExploitTasks: {
+    key: 'reconciliation',
+    label: 'Writing test cases',
+    kind: 'operation',
+    parentKey: RECONCILIATION_PARENT_KEY,
+  },
+  publishClassReconciliationOss: {
+    key: 'reconciliation',
+    label: 'Saving results',
+    kind: 'operation',
+    parentKey: RECONCILIATION_PARENT_KEY,
+  },
+  capellaArchitecture: {
+    key: 'agentic-sast:architecture',
+    label: 'Mapping architecture',
+    kind: 'operation',
+    parentKey: AGENTIC_SAST_PARENT_KEY,
+  },
+  capellaThreatModel: {
+    key: 'agentic-sast:threat-model',
+    label: 'Modelling threats',
+    kind: 'operation',
+    parentKey: AGENTIC_SAST_PARENT_KEY,
+  },
+  capellaPlan: {
+    key: 'agentic-sast:plan',
+    label: 'Planning the review',
+    kind: 'operation',
+    parentKey: AGENTIC_SAST_PARENT_KEY,
+  },
+  capellaResearch: {
+    key: 'agentic-sast:research',
+    label: 'Researching code',
+    kind: 'operation',
+    parentKey: AGENTIC_SAST_PARENT_KEY,
+  },
+  capellaDedupe: {
+    key: 'agentic-sast:dedupe',
+    label: 'Merging duplicates',
+    kind: 'operation',
+    parentKey: AGENTIC_SAST_PARENT_KEY,
+  },
+  capellaReview: {
+    key: 'agentic-sast:review',
+    label: 'Reviewing findings',
+    kind: 'operation',
+    parentKey: AGENTIC_SAST_PARENT_KEY,
+  },
+  capellaCritic: {
+    key: 'agentic-sast:critic',
+    label: 'Critiquing findings',
+    kind: 'operation',
+    parentKey: AGENTIC_SAST_PARENT_KEY,
+  },
+  capellaConfirm: {
+    key: 'agentic-sast:confirm',
+    label: 'Confirming findings',
+    kind: 'operation',
+    parentKey: AGENTIC_SAST_PARENT_KEY,
+  },
+  capellaCalibrate: {
+    key: 'agentic-sast:calibrate',
+    label: 'Calibrating risk',
+    kind: 'operation',
+    parentKey: AGENTIC_SAST_PARENT_KEY,
+  },
+  capellaExport: {
+    key: 'agentic-sast:export',
+    label: 'Exporting findings',
+    kind: 'operation',
+    parentKey: AGENTIC_SAST_PARENT_KEY,
+  },
+};
+
+/** Complete production activity mirror. Unknown names are errors, never hidden progress. */
+export const ACTIVITY_TO_PROGRESS: Readonly<Record<string, ActivityProgressSpec>> = Object.freeze({
+  ...AGENT_ACTIVITY_PROGRESS,
+  ...OPERATION_ACTIVITY_PROGRESS,
+});
+
+/** Agent-only projection of ACTIVITY_TO_PROGRESS: activity type name to canonical agent name. */
 export const ACTIVITY_TO_AGENT: Readonly<Record<string, string>> = Object.fromEntries(
-  PIPELINE.flatMap((phase) => phase.agents.map((agent) => [agent.activityType, agent.name])),
+  Object.entries(ACTIVITY_TO_PROGRESS)
+    .filter(([, progress]) => progress.kind === 'agent')
+    .map(([activityType, progress]) => [activityType, progress.key]),
 );

 /** The vuln/exploit class of an agent (e.g. "authz-vuln" → "authz"), for failedPipelines matching. */
@@ -100,11 +279,36 @@ export interface AgentMetrics {
  readonly skipped?: boolean;
 }

+export interface OperationalStageState {
+  readonly key: string;
+  readonly label: string;
+  readonly status: 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+  readonly startedAt?: number;
+  readonly durationMs?: number;
+  readonly error?: string;
+}
+
+/** Family key a persisted operational stage belongs to, e.g. `reconciliation:xss` to `reconciliation`. */
+export function operationFamilyKey(stageKey: string): string {
+  const separator = stageKey.indexOf(':');
+  return separator === -1 ? stageKey : stageKey.slice(0, separator);
+}
+
 export interface PipelineSummary {
  readonly totalCostUsd: number;
  readonly totalDurationMs: number; // Wall-clock (end - start)
  readonly totalTurns: number;
  readonly agentCount: number;
+  /** False when operational (Capella/reconciliation) spend is known to be incomplete. */
+  readonly usageAccountingComplete?: boolean;
+}
+
+/** One durable degradation reason with its derived safe message (mirror of PartialReasonView). */
+export interface PartialReasonView {
+  readonly code: string;
+  readonly vulnerabilityClass?: string;
+  readonly stage?: string;
+  readonly message: string;
 }

 export type PipelineStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'partial';
@@ -114,10 +318,27 @@ export interface PipelineState {
  readonly currentPhase: string | null;
  readonly currentAgent: string | null;
  readonly completedAgents: string[];
+  readonly expectedAgents?: string[];
+  readonly participatingClasses?: string[];
  readonly failedPipelines: { vulnType: string; error: string }[];
+  readonly failedReconciliations?: { vulnerabilityClass: string; error: string }[];
  readonly failedAgent: string | null;
  readonly error: string | null;
  readonly startTime: number;
  readonly agentMetrics: Record<string, AgentMetrics>;
+  readonly operationalMetrics?: Record<string, AgentMetrics>;
+  readonly operationalStages?: Record<string, OperationalStageState>;
+  /** `error` is the worker's sanitized failure sentence, safe to print verbatim. */
+  readonly agenticSast?: {
+    readonly status: string;
+    readonly durationMs?: number;
+    /** Reader-facing name of the failed stage, already projected by the worker. */
+    readonly failedStageLabel?: string;
+    readonly error?: string;
+    readonly errorCode?: string;
+  };
+  readonly nonFatalFailures?: { readonly phase: string; readonly error: string }[];
+  /** Ordered durable degradation reasons with safe messages; empty or absent for full success. */
+  readonly partialReasons?: readonly PartialReasonView[];
  readonly summary: PipelineSummary | null;
 }
@@ -10,9 +10,8 @@
 import { BOLD, DIM, GOLD, paint, RED, YELLOW } from '../colors.js';
 import { commandPrefix } from '../mode.js';
 import type { RunningAgent } from '../temporal-client.js';
-import { agentError, deriveAgentStates, isTerminal, phaseGlyphState, type RunState, scanElapsedMs } from './derive.js';
-import { inlineFailureReason } from './failure.js';
-import { PIPELINE, type PipelineState } from './pipeline.js';
+import { derivePipeline, isTerminal, type RunState, scanElapsedMs } from './derive.js';
+import type { PipelineState } from './pipeline.js';

 export interface RenderInput {
  readonly workspace: string;
@@ -95,6 +94,12 @@ const STATE_COLOR: Record<RunState, string> = {
  skipped: COLORS.dim,
 };

+/** Column width for an agent or background-work label inside a phase. */
+const AGENT_LABEL_WIDTH = 18;
+
+/** Inline budget for a failure sentence, wide enough to carry a whole first sentence. */
+const FAILURE_DETAIL_WIDTH = 120;
+
 /** Braille spinner frames for running agents — the clack loader style. */
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'] as const;

@@ -112,13 +117,14 @@ function statusBadge(input: RenderInput, opts: RenderOptions): string {
  const workflowStatus = input.state?.status;
  if (!isTerminal(input.temporalStatus)) return paint('running', COLORS.gold, opts.color);
  if (workflowStatus === 'partial') return paint('partial', COLORS.yellow, opts.color);
+  if (workflowStatus === 'cancelled') return paint('cancelled', COLORS.yellow, opts.color);
  if (input.temporalStatus === 'COMPLETED') return paint('completed', COLORS.gold, opts.color);
  if (input.temporalStatus === 'TERMINATED') return paint('stopped', COLORS.yellow, opts.color);
  if (input.temporalStatus === 'CANCELLED' || input.temporalStatus === 'CANCELED') {
    return paint('cancelled', COLORS.yellow, opts.color);
  }
  if (input.temporalStatus === 'TIMED_OUT') return paint('timed out', COLORS.red, opts.color);
-  return paint('FAILED', COLORS.red, opts.color);
+  return paint('failed', COLORS.red, opts.color);
 }

 // === Line builders ===
@@ -129,6 +135,7 @@ function agentMeta(
  runner: RunningAgent | undefined,
  error: string | undefined,
  opts: RenderOptions,
+  step?: string,
 ): string {
  if (state === 'completed') {
    const duration = metrics?.durationMs != null ? formatDuration(metrics.durationMs) : 'done';
@@ -136,12 +143,13 @@ function agentMeta(
  }
  if (state === 'running') {
    const parts = ['running'];
+    if (step !== undefined) parts.push(step);
    if (runner?.startedAt !== undefined) parts.push(formatDuration(opts.now - runner.startedAt));
    if (runner && runner.attempt > 1) parts.push(`retry ${runner.attempt}`);
    return paint(parts.join(' · '), COLORS.gold, opts.color);
  }
  if (state === 'failed') {
-    const detail = error ? ` · ${truncate(error, 46)}` : '';
+    const detail = error ? ` · ${truncate(error, FAILURE_DETAIL_WIDTH)}` : '';
    return paint(`failed${detail}`, COLORS.red, opts.color);
  }
  if (state === 'skipped') return paint('skipped', COLORS.dim, opts.color);
@@ -163,18 +171,20 @@ function phaseMeta(states: readonly RunState[], inPlay: number, parallel: boolea
 /** Render the full progress frame as one string (no trailing newline). */
 export function renderScan(input: RenderInput, opts: RenderOptions): string {
  const byAgent = new Map(input.running.map((r) => [r.agent, r]));
-  const stateMap = deriveAgentStates(input);
+  const phases = derivePipeline(input, opts.now);
  const lines: string[] = ['', ...headerLines(input, opts), ''];

-  const metaFor = (name: string, state: RunState): string =>
-    agentMeta(state, input.state?.agentMetrics[name], byAgent.get(name), agentError(name, input.state, byAgent), opts);
  // Only agents that have actually entered play are shown; pending/skipped ones stay hidden.
  const inPlay = (s: RunState): boolean => s === 'running' || s === 'completed' || s === 'failed';

-  for (const phase of PIPELINE) {
-    const states = phase.agents.map((a) => stateMap.get(a.name) ?? 'pending');
+  for (const phase of phases) {
+    const states = phase.agents.map((agent) => agent.state);
    const playing = states.filter(inPlay).length;
-    const phaseRunState: RunState = phaseGlyphState(states);
+    const phaseRunState = phase.state;
+    const metaFor = (agent: (typeof phase.agents)[number]): string => {
+      const metrics = agent.durationMs === null ? undefined : { durationMs: agent.durationMs };
+      return agentMeta(agent.state, metrics, byAgent.get(agent.name), agent.error, opts, agent.detail);
+    };

    // A single-agent phase carries that agent's own duration/cost on the phase line once it
    // starts; a parallel phase gets a "k/N done" summary over the agents in play.
@@ -182,7 +192,7 @@ export function renderScan(input: RenderInput, opts: RenderOptions): string {
    const firstState = states[0];
    const phaseMetaStr =
      !phase.parallel && first && firstState && inPlay(firstState)
-        ? metaFor(first.name, firstState)
+        ? metaFor(first)
        : phaseMeta(states, playing, phase.parallel, opts);
    lines.push(`  ${glyph(phaseRunState, opts)}  ${phase.label.padEnd(26)}${phaseMetaStr}`);

@@ -191,7 +201,9 @@ export function renderScan(input: RenderInput, opts: RenderOptions): string {
      const agent = phase.agents[i];
      const state = states[i];
      if (!agent || !state || !inPlay(state)) continue;
-      lines.push(`       ${glyph(state, opts)} ${agent.label.padEnd(18)}${metaFor(agent.name, state)}`);
+      // Two trailing spaces before padding, so a label wider than the column still separates
+      // from its meta text; a label inside the column pads to the same width as before.
+      lines.push(`       ${glyph(state, opts)} ${`${agent.label}  `.padEnd(AGENT_LABEL_WIDTH)}${metaFor(agent)}`);
    }
  }

@@ -223,15 +235,44 @@ function footerLines(input: RenderInput, opts: RenderOptions): string[] {

  if (isTerminal(input.temporalStatus) && input.state?.summary) {
    const wall = formatDuration(input.state.summary.totalDurationMs);
-    return ['', `  Time Taken   ${wall}`];
+    const lines = ['', `  Time Taken   ${wall}`];
+
+    // A partial scan names each durable degradation reason through its safe message,
+    // so the operator never has to guess why the badge is not "completed".
+    const reasons = input.state.partialReasons ?? [];
+    if (reasons.length > 0) {
+      lines.push('', `  ${paint('Why this scan is partial:', COLORS.yellow, opts.color)}`);
+      for (const reason of reasons) {
+        lines.push(paint(`    - ${reason.message}`, COLORS.dim, opts.color));
+      }
+      // The safe message names what degraded; these three name the agentic-SAST failure
+      // behind it, under the same labels the scan log and worker output use.
+      const agenticSast = input.state.agenticSast;
+      if (agenticSast?.status === 'failed') {
+        if (agenticSast.failedStageLabel !== undefined) {
+          lines.push(paint(`    Agentic SAST stopped at: ${agenticSast.failedStageLabel}`, COLORS.dim, opts.color));
+        }
+        if (agenticSast.error !== undefined) {
+          lines.push(paint(`    What happened: ${agenticSast.error}`, COLORS.dim, opts.color));
+        }
+        if (agenticSast.errorCode !== undefined) {
+          lines.push(paint(`    Reference code (for a bug report): ${agenticSast.errorCode}`, COLORS.dim, opts.color));
+        }
+      }
+    }
+    if (input.state.summary.usageAccountingComplete === false) {
+      lines.push(
+        paint('  Cost is incomplete — some background work is not included in this total.', COLORS.dim, opts.color),
+      );
+    }
+    return lines;
  }

  const logsValue = `${prefix} logs ${input.workspace}`;
  const temporalValue = temporalDashboardUrl(input.workflowId);

  if (isTerminal(input.temporalStatus)) {
-    const rawReason = input.failureMessage ?? input.state?.error;
-    const reason = rawReason ? inlineFailureReason(rawReason) : 'no result recorded';
+    const reason = input.failureMessage ?? input.state?.error ?? 'no result recorded';
    return [
      footerDivider(opts),
      paint(
@@ -8,6 +8,7 @@

 import type { DerivedPhase } from './derive.js';
 import { derivePipeline, isTerminal, scanElapsedMs } from './derive.js';
+import type { PartialReasonView } from './pipeline.js';
 import type { RenderInput } from './render.js';

 /** Coarse scan status token, mirroring the human status badge in machine-friendly form. */
@@ -27,6 +28,12 @@ export interface StatusJson {
  readonly endedAt?: string;
  /** Failure text when a failed scan left no readable state. */
  readonly failureMessage?: string;
+  /** Ordered durable degradation reasons with safe messages; present only when non-empty. */
+  readonly partialReasons?: readonly PartialReasonView[];
+  /** Agentic SAST outcome, with the worker's sanitized failure sentence and bounded code. */
+  readonly agenticSast?: { readonly status: string; readonly error?: string; readonly errorCode?: string };
+  /** False when operational (Capella/reconciliation) spend is known to be incomplete. */
+  readonly usageAccountingComplete?: boolean;
  readonly phases: readonly DerivedPhase[];
 }

@@ -34,6 +41,7 @@ export interface StatusJson {
 function deriveStatus(input: RenderInput): ScanStatus {
  if (!isTerminal(input.temporalStatus)) return 'running';
  if (input.state?.status === 'partial') return 'partial';
+  if (input.state?.status === 'cancelled') return 'cancelled';

  switch (input.temporalStatus) {
    case 'COMPLETED':
@@ -53,6 +61,9 @@ function deriveStatus(input: RenderInput): ScanStatus {
 /** Build the JSON snapshot for a scan at instant `now`. */
 export function toStatusJson(input: RenderInput, now: number): StatusJson {
  const elapsedMs = scanElapsedMs(input, now);
+  const partialReasons = input.state?.partialReasons ?? [];
+  const agenticSast = input.state?.agenticSast;
+  const usageAccountingComplete = input.state?.summary?.usageAccountingComplete;

  return {
    workspace: input.workspace,
@@ -63,6 +74,17 @@ export function toStatusJson(input: RenderInput, now: number): StatusJson {
    ...(input.startedAt !== undefined && { startedAt: new Date(input.startedAt).toISOString() }),
    ...(input.endedAt !== undefined && { endedAt: new Date(input.endedAt).toISOString() }),
    ...(input.failureMessage !== undefined && { failureMessage: input.failureMessage }),
+    ...(partialReasons.length > 0 && { partialReasons }),
+    // Present only when agentic SAST actually ran; a disabled scan omits the key entirely.
+    ...(agenticSast !== undefined &&
+      agenticSast.status !== 'disabled' && {
+        agenticSast: {
+          status: agenticSast.status,
+          ...(agenticSast.error !== undefined && { error: agenticSast.error }),
+          ...(agenticSast.errorCode !== undefined && { errorCode: agenticSast.errorCode }),
+        },
+      }),
+    ...(usageAccountingComplete !== undefined && { usageAccountingComplete }),
    phases: derivePipeline(input, now),
  };
 }