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.

apps/cli/src/commands/start.ts

@@ -18,6 +18,7 @@ import { commandPrefix, isLocal } from '../mode.js';
 import { resolveModelSpec } from '../model-spec.js';
 import {
   expandHome,
+  FINAL_REPORT_MD_FILENAME,
   FINAL_REPORT_PDF_FILENAME,
   INTERNAL_DIR,
   resolveConfig,
@@ -43,81 +44,216 @@ export interface StartArgs {
   version: string;
 }
 
+const LAUNCH_STATE_SCHEMA_VERSION = 1 as const;
+const LAUNCH_STATE_FILENAME = 'launch.json';
+const FIXED_CLASSES = ['injection', 'xss', 'auth', 'authz', 'ssrf'] as const;
+
 /**
- * Upgrade a pre-restructure workspace (flat layout, no INTERNAL_DIR) before it is mounted,
- * so resume finds the old deliverables and their git checkpoints instead of re-running every
- * agent. For a legacy run every top-level entry is internal, so move them all into INTERNAL_DIR
- * (a same-filesystem rename carries the deliverables .git along).
+ * CLI-owned launch record at INTERNAL_DIR/launch.json, written once when a workspace is
+ * created and never rewritten. It pins the customer output destination so a resume with a
+ * different -o cannot silently redirect the final report. The worker does not read it.
  */
-function migrateLegacyWorkspaceLayout(workspacePath: string): void {
-  const legacySessionJson = path.join(workspacePath, 'session.json');
-  const internalPath = path.join(workspacePath, INTERNAL_DIR);
-  if (!fs.existsSync(legacySessionJson) || fs.existsSync(internalPath)) {
-    return;
+interface LaunchState {
+  readonly schema_version: typeof LAUNCH_STATE_SCHEMA_VERSION;
+  readonly customer_output_path?: string;
+}
+
+export interface WorkspaceLaunchDecision {
+  readonly isResume: boolean;
+  readonly outputDir?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function arraysEqual(left: readonly unknown[], right: readonly unknown[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+/**
+ * Hand-rolled twin of the worker's durable-state validator in
+ * apps/worker/src/types/run-state.ts, which owns the session.json.durableScanState shape.
+ * Each array check accepts two variants because the worker appends 'other' and
+ * 'other-exploit' only after the other pipeline admits findings. If the worker's shape
+ * changes and this twin lags, resume fails fast as incompatible instead of launching a
+ * worker against state it would misread.
+ */
+function isCurrentDurableState(value: unknown): boolean {
+  if (!isRecord(value) || value.schema_version !== 1 || typeof value.exploit !== 'boolean') return false;
+  if (!Array.isArray(value.participating_classes) || !Array.isArray(value.expected_agents)) return false;
+
+  const participating = value.participating_classes;
+  const validParticipation =
+    arraysEqual(participating, FIXED_CLASSES) || arraysEqual(participating, [...FIXED_CLASSES, 'other']);
+  if (!validParticipation) return false;
+
+  const baselineAgents = ['pre-recon', 'recon', ...FIXED_CLASSES.map((name) => `${name}-vuln`)];
+  if (value.exploit) baselineAgents.push(...FIXED_CLASSES.map((name) => `${name}-exploit`));
+  baselineAgents.push('report');
+  const expected = value.expected_agents;
+  return arraysEqual(expected, baselineAgents) || arraysEqual(expected, [...baselineAgents, 'other-exploit']);
+}
+
+/** One refusal for damaged CLI-owned or worker-owned workspace records, whichever reads first. */
+const DAMAGED_RECORDS_MESSAGE =
+  "This workspace's internal records are damaged and it cannot be resumed. Its report files are untouched. Start a new scan with a different -w name.";
+
+const NEWER_RELEASE_MESSAGE =
+  'This workspace was created by a newer version of Shannon. Upgrade Shannon, or start a new scan with a different -w name.';
+
+function readJsonFile(filePath: string): unknown {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    fail(DAMAGED_RECORDS_MESSAGE);
+  }
+}
+
+function readLaunchState(filePath: string): LaunchState {
+  if (!fs.existsSync(filePath)) {
+    fail(
+      'This workspace was created by an earlier version of Shannon and cannot be resumed. Its files and report are untouched. Start a new scan with a different -w name.',
+    );
+  }
+  const value = readJsonFile(filePath);
+  if (!isRecord(value)) fail(NEWER_RELEASE_MESSAGE);
+  // Unknown keys mean a newer release wrote this workspace; refuse rather than half-read it.
+  const keys = Object.keys(value).sort();
+  const keysAreValid = keys.every((key) => key === 'customer_output_path' || key === 'schema_version');
+  const customerPath = value.customer_output_path;
+  const pathIsValid =
+    customerPath === undefined ||
+    (typeof customerPath === 'string' && path.isAbsolute(customerPath) && path.resolve(customerPath) === customerPath);
+  if (value.schema_version !== LAUNCH_STATE_SCHEMA_VERSION || !keysAreValid || !pathIsValid) {
+    fail(NEWER_RELEASE_MESSAGE);
+  }
+  return {
+    schema_version: LAUNCH_STATE_SCHEMA_VERSION,
+    ...(typeof customerPath === 'string' && { customer_output_path: customerPath }),
+  };
+}
+
+/**
+ * Decide fresh-versus-resume from on-disk state alone, before start() mutates anything.
+ * A fresh launch requires the workspace directory to be absent or empty; a resume requires
+ * current-release session state, a matching target URL, and a customer output path that
+ * agrees with the recorded one. Every other combination fails the launch, so a typo in
+ * -w or -o stops here instead of spawning a worker into the wrong workspace.
+ */
+export function classifyWorkspaceLaunch(
+  workspacePath: string,
+  expectedUrl: string,
+  requestedOutputDir: string | undefined,
+): WorkspaceLaunchDecision {
+  const sessionPath = resolveRunFile(workspacePath, 'session.json');
+  const sessionExists = fs.existsSync(sessionPath);
+  if (!sessionExists) {
+    if (fs.existsSync(workspacePath) && fs.readdirSync(workspacePath).length > 0) {
+      fail(
+        'This directory is not a Shannon workspace, or its scan state is missing. Start a new scan with a different -w name.',
+      );
+    }
+    return { isResume: false, ...(requestedOutputDir !== undefined && { outputDir: requestedOutputDir }) };
   }
 
-  fs.mkdirSync(internalPath, { recursive: true });
-  for (const entry of fs.readdirSync(workspacePath)) {
-    if (entry === INTERNAL_DIR) {
-      continue;
+  const launchPath = path.join(workspacePath, INTERNAL_DIR, LAUNCH_STATE_FILENAME);
+  const launch = readLaunchState(launchPath);
+  const session = readJsonFile(sessionPath);
+  if (!isRecord(session) || !isRecord(session.session) || session.session.webUrl !== expectedUrl) {
+    fail(
+      'This workspace was created for a different target URL, so it cannot be resumed against this one. Check -u, or start a new scan with a different -w name.',
+    );
+  }
+  if (!isCurrentDurableState(session.durableScanState)) {
+    fail(
+      "This workspace's scan state cannot be read by this version. Its files are untouched. Start a new scan with a different -w name.",
+    );
+  }
+
+  const storedOutputDir = launch.customer_output_path;
+  if (requestedOutputDir !== undefined && requestedOutputDir !== storedOutputDir) {
+    fail(
+      'This workspace already copies its report to a different location than the -o path you passed. Re-run without -o to keep the original location, or start a new scan with a different -w name.',
+    );
+  }
+  return { isResume: true, ...(storedOutputDir !== undefined && { outputDir: storedOutputDir }) };
+}
+
+/**
+ * Crash-safe single write: exclusive temp file (pid plus random suffix keeps concurrent
+ * starts apart), fsync, rename into place, then directory fsync so the entry survives a
+ * host crash. Callers invoke this only for a fresh workspace; an existing launch.json is
+ * the resume contract and must never be replaced.
+ */
+export function writeLaunchStateAtomically(internalPath: string, outputDir: string | undefined): void {
+  const finalPath = path.join(internalPath, LAUNCH_STATE_FILENAME);
+  const temporaryPath = path.join(internalPath, `${LAUNCH_STATE_FILENAME}.tmp-${process.pid}-${randomSuffix()}`);
+  const launchState: LaunchState = {
+    schema_version: LAUNCH_STATE_SCHEMA_VERSION,
+    ...(outputDir !== undefined && { customer_output_path: outputDir }),
+  };
+  const descriptor = fs.openSync(temporaryPath, 'wx', 0o600);
+  try {
+    fs.writeFileSync(descriptor, `${JSON.stringify(launchState, null, 2)}\n`, 'utf8');
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  try {
+    fs.renameSync(temporaryPath, finalPath);
+    const directory = fs.openSync(internalPath, 'r');
+    try {
+      fs.fsyncSync(directory);
+    } finally {
+      fs.closeSync(directory);
     }
-    fs.renameSync(path.join(workspacePath, entry), path.join(internalPath, entry));
+  } catch (error) {
+    fs.rmSync(temporaryPath, { force: true });
+    throw error;
   }
-  console.log(`Migrated workspace to ${INTERNAL_DIR}/ layout: ${workspacePath}`);
 }
 
 export async function start(args: StartArgs): Promise<void> {
-  // 1. Initialize state directories and load env
+  // 1. Resolve non-mutating inputs and classify the workspace before changing it.
   initHome();
   loadEnv();
-
-  // 2. Validate credentials
   const creds = validateCredentials();
   if (!creds.valid) {
     fail(creds.error ?? 'Invalid credentials');
   }
-
-  // 3. Resolve paths
   const repo = resolveRepo(args.repo);
   const config = args.config ? resolveConfig(args.config) : undefined;
+  const workspacesDir = getWorkspacesDir();
+  const workspace =
+    args.workspace ?? `${new URL(args.url).hostname.replace(/[^a-zA-Z0-9-]/g, '-')}_shannon-${Date.now()}`;
+  const workspacePath = path.join(workspacesDir, workspace);
+  const requestedOutputDir = args.output ? path.resolve(expandHome(args.output)) : undefined;
+  const launchDecision = classifyWorkspaceLaunch(workspacePath, args.url, requestedOutputDir);
 
-  // Inputs are valid — show the splash before the Docker/Temporal setup work.
-  // Skip it off a real terminal (e.g. CI) so piped/logged output stays clean.
+  // 2. Inputs are valid; initialize shared infrastructure.
   if (stdoutIsTerminal()) {
     displaySplash(isLocal() ? undefined : args.version);
   }
-
-  // 4. Ensure workspaces dir is writable by container user (UID 1001)
-  const workspacesDir = getWorkspacesDir();
   fs.mkdirSync(workspacesDir, { recursive: true });
   fs.chmodSync(workspacesDir, 0o777);
-
-  // 5. Ensure Docker and the worker image are available (pull/build prints its own progress).
   ensureDocker();
   ensureImage(args.version);
-
-  // One spinner spans the whole launch: bringing up Temporal and registering the worker.
   const spinner = p.spinner();
   spinner.start('Starting scan');
   await ensureInfra(spinner);
 
-  // 6. Generate unique task queue and container name
+  // 3. Generate the invocation identity.
   const suffix = randomSuffix();
   const taskQueue = `shannon-${suffix}`;
   const containerName = `shannon-worker-${suffix}`;
 
-  // 7. Generate workspace name if not provided
-  const workspace =
-    args.workspace ?? `${new URL(args.url).hostname.replace(/[^a-zA-Z0-9-]/g, '-')}_shannon-${Date.now()}`;
-
-  // 8. Create writable overlay directories (mounted over :ro repo paths inside container)
+  // 4. Create writable overlay directories after resume validation has succeeded.
   // The run dir and its INTERNAL_DIR must be 0o777 so the container user can create audit
   // subdirs and the overlay backing dirs.
-  const workspacePath = path.join(workspacesDir, workspace);
   const internalPath = path.join(workspacePath, INTERNAL_DIR);
   fs.mkdirSync(workspacePath, { recursive: true });
   fs.chmodSync(workspacePath, 0o777);
-  migrateLegacyWorkspaceLayout(workspacePath);
   fs.mkdirSync(internalPath, { recursive: true });
   fs.chmodSync(internalPath, 0o777);
   for (const dir of ['deliverables', 'scratchpad', '.playwright-cli', '.playwright']) {
@@ -125,24 +261,37 @@ export async function start(args: StartArgs): Promise<void> {
     fs.mkdirSync(dirPath, { recursive: true });
     fs.chmodSync(dirPath, 0o777);
   }
+  if (!launchDecision.isResume) {
+    writeLaunchStateAtomically(internalPath, launchDecision.outputDir);
+  }
 
-  // 9. Pre-create overlay mount points (:ro mounts can't auto-create them)
+  // 5. Pre-create overlay mount points (:ro mounts cannot create them).
   const shannonDir = path.join(repo.hostPath, '.shannon');
   for (const dir of ['deliverables', 'scratchpad', '.playwright-cli']) {
     fs.mkdirSync(path.join(shannonDir, dir), { recursive: true });
   }
   fs.mkdirSync(path.join(repo.hostPath, '.playwright'), { recursive: true });
 
-  // 10. Resolve output directory
-  const outputDir = args.output ? path.resolve(expandHome(args.output)) : undefined;
+  // 6. Create the validated customer-copy destination, if configured.
+  const outputDir = launchDecision.outputDir;
   if (outputDir) {
     fs.mkdirSync(outputDir, { recursive: true });
   }
 
-  // 11. Resolve prompts directory (local mode only)
+  // 7. Resolve prompts and capture the pre-launch resume counter.
   const promptsDir = isLocal() ? path.resolve('apps/worker/prompts') : undefined;
+  const sessionJson = resolveRunFile(workspacePath, 'session.json');
+  const isResume = launchDecision.isResume;
+  let initialResumeCount = 0;
+  if (isResume) {
+    // Docker and Temporal startup sit between this read and the classification that validated the
+    // same file, so a file that changed in between is a workspace-state failure, not a CLI bug.
+    const session = readJsonFile(sessionJson);
+    const attempts = isRecord(session) && isRecord(session.session) ? session.session.resumeAttempts : undefined;
+    initialResumeCount = Array.isArray(attempts) ? attempts.length : 0;
+  }
 
-  // 12. Spawn worker container
+  // 8. Spawn the worker container.
   const proc = spawnWorker({
     version: args.version,
     url: args.url,
@@ -171,24 +320,16 @@ export async function start(args: StartArgs): Promise<void> {
     process.exit(1);
   }
 
-  // Detect whether this is a fresh workspace or a resume by checking session.json existence
-  const sessionJson = resolveRunFile(path.join(workspacesDir, workspace), 'session.json');
-  const isResume = fs.existsSync(sessionJson);
-  let initialResumeCount = 0;
-  if (isResume) {
-    try {
-      const session = JSON.parse(fs.readFileSync(sessionJson, 'utf-8'));
-      initialResumeCount = session.session?.resumeAttempts?.length ?? 0;
-    } catch {
-      // Corrupted file — worker will handle validation
-    }
-  }
-
   let started = false;
 
+  // Set when the startup poll times out but session.json already holds durable state this
+  // release understands: the workflow is executing, so the exit handler must not stop its
+  // worker. An operator abort is a different intent and still stops it.
+  let scanRunningUnconfirmed = false;
+
   // Stop the worker only if the scan hasn't registered yet (e.g. Ctrl-C mid-startup).
   let cleaned = false;
-  const cleanup = (): void => {
+  const stopWorker = (): void => {
     if (cleaned || started) return;
     cleaned = true;
     spinner.stop('Stopping scan');
@@ -202,14 +343,17 @@ export async function start(args: StartArgs): Promise<void> {
     }
   };
   process.on('SIGINT', () => {
-    cleanup();
+    stopWorker();
     process.exit(0);
   });
   process.on('SIGTERM', () => {
-    cleanup();
+    stopWorker();
     process.exit(0);
   });
-  process.on('exit', cleanup);
+  process.on('exit', () => {
+    if (scanRunningUnconfirmed) return;
+    stopWorker();
+  });
 
   // Poll for the workflow to register in session.json; the spinner resolves once it does.
   spinner.message('Waiting for the scan to start');
@@ -236,10 +380,52 @@ export async function start(args: StartArgs): Promise<void> {
     await sleep(2000);
   }
 
+  if (classifyStartupTimeout(sessionJson) === 'scan-running') {
+    scanRunningUnconfirmed = true;
+    spinner.error('The scan started, but this CLI could not confirm it');
+    printUnconfirmedScanHint(workspace, taskQueue, containerName);
+    process.exit(1);
+  }
+
   spinner.error('Timed out waiting for the scan to start');
   process.exit(1);
 }
 
+/**
+ * Read the startup timeout: 'scan-running' when session.json already holds durable state this
+ * release understands, which only the worker writes and only after Temporal began executing the
+ * workflow; 'unregistered' when nothing proves the scan started. The distinction decides whether
+ * timing out may stop the worker container.
+ */
+export function classifyStartupTimeout(sessionJsonPath: string): 'unregistered' | 'scan-running' {
+  let session: unknown;
+  try {
+    session = JSON.parse(fs.readFileSync(sessionJsonPath, 'utf-8'));
+  } catch {
+    return 'unregistered';
+  }
+  if (!isRecord(session) || !isCurrentDurableState(session.durableScanState)) {
+    return 'unregistered';
+  }
+  return 'scan-running';
+}
+
+/** Point the operator at a scan that is running but whose startup this CLI could not confirm. */
+function printUnconfirmedScanHint(workspace: string, taskQueue: string, containerName: string): void {
+  console.log('');
+  console.log('  The scan is running and was left alone; only its startup confirmation is missing.');
+  console.log('');
+  console.log(`  Workspace:  ${workspace}`);
+  console.log(`  Task queue: ${taskQueue}`);
+  console.log(`  Container:  ${containerName}`);
+  console.log('');
+  console.log('  Inspect it:');
+  console.log(`    Live logs:   ${commandPrefix()} logs ${workspace}`);
+  console.log(`    Worker logs: docker logs ${containerName}`);
+  console.log('    Dashboard:   http://localhost:8233');
+  console.log('');
+}
+
 /**
  * Follow a just-started scan (for `--follow`, aimed at CI): stream its log while Temporal drives
  * completion, then exit on the workflow outcome — 0 if the assessment ran, 1 if the scan failed.
@@ -329,7 +515,7 @@ function printInfo(args: StartArgs, workspace: string, repoPath: string, workspa
     return;
   }
 
-  const reportPath = path.join(workspacesDir, workspace, FINAL_REPORT_PDF_FILENAME);
+  const reportDir = path.join(workspacesDir, workspace);
 
   // When following, the scan log streams inline next, so the "run these to watch it" hints
   // would only contradict that.
@@ -343,6 +529,8 @@ function printInfo(args: StartArgs, workspace: string, repoPath: string, workspa
 
   console.log('');
   console.log('  Report (when the scan finishes):');
-  console.log(`    ${reportPath}`);
+  console.log(`    ${reportDir}${path.sep}`);
+  console.log(`      ${FINAL_REPORT_PDF_FILENAME}`);
+  console.log(`      ${FINAL_REPORT_MD_FILENAME}`);
   console.log('');
 }

apps/cli/src/commands/status.ts

@@ -15,7 +15,13 @@ import { type RenderInput, renderScan } from '../scan/render.js';
 import { toStatusJson } from '../scan/status-json.js';
 import { resolveWorkflowId } from '../session.js';
 import { displaySplash } from '../splash.js';
-import { describeScan, getTerminalOutcome, queryProgress, type ScanDescription } from '../temporal-client.js';
+import {
+  ActivityMirrorError,
+  describeScan,
+  getTerminalOutcome,
+  queryProgress,
+  type ScanDescription,
+} from '../temporal-client.js';
 import { stdoutIsTerminal, supportsColor } from '../tty.js';
 import { getVersion } from '../version.js';
 
@@ -30,6 +36,24 @@ function isTerminalStatus(status: string): boolean {
   return status !== 'RUNNING' && status !== 'UNSPECIFIED';
 }
 
+/**
+ * Read one scan description, telling the two failure modes apart. A stale activity mirror
+ * carries its own message and needs a CLI update; anything else is a read that did not reach
+ * a usable answer, which is most often Temporal being down.
+ */
+async function readScanDescription(workflowId: string): Promise<ScanDescription | null> {
+  try {
+    return await describeScan(workflowId);
+  } catch (error) {
+    if (error instanceof ActivityMirrorError) fail(error.message);
+    fail(
+      "Could not read this scan's progress.",
+      'If Temporal is not running, start a scan to bring it up. If it is running, this build of the CLI',
+      'does not recognise part of the scan and needs updating.',
+    );
+  }
+}
+
 // Match SGR color escapes (ESC[…m) so a line's on-screen width excludes them. Built from the ESC
 // char code so the source carries no literal control character.
 const ANSI_PATTERN = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
@@ -128,7 +152,7 @@ async function watch(workspace: string, workflowId: string): Promise<never> {
   }, RENDER_MS);
 
   for (;;) {
-    const desc = await describeScan(workflowId);
+    const desc = await readScanDescription(workflowId);
     if (!desc) {
       clearInterval(ticker);
       fail(`Scan "${workspace}" is no longer in Temporal.`);
@@ -158,12 +182,7 @@ export async function status(workspace: string, opts: { readonly json: boolean }
   // follows the current resume, not the superseded original. Fresh scans: the name is the id.
   const workflowId = resolveWorkflowId(workspace) ?? workspace;
 
-  let desc: ScanDescription | null;
-  try {
-    desc = await describeScan(workflowId);
-  } catch {
-    fail('Could not reach Temporal at 127.0.0.1:7233.', 'Start Temporal (it comes up with a scan) and try again.');
-  }
+  const desc = await readScanDescription(workflowId);
 
   if (!desc) {
     fail(

apps/cli/src/docker.ts

@@ -345,7 +345,7 @@ export function spawnWorker(opts: WorkerOptions): ChildProcess {
     args.push('-v', `${opts.config.hostPath}:${opts.config.containerPath}:ro`);
   }
 
-  // Output directory for deliverables copy
+  // Customer-copy destination. The workflow surfaces only final report artifacts here.
   if (opts.outputDir) {
     args.push('-v', `${opts.outputDir}:/app/output`);
   }

apps/cli/src/paths.ts

@@ -42,6 +42,12 @@ export const INTERNAL_DIR = '.shannon';
  */
 export const FINAL_REPORT_PDF_FILENAME = 'Security-Assessment-Report.pdf';
 
+/**
+ * Customer-facing Markdown report name at the run root.
+ * Must match FINAL_REPORT_MD_FILENAME in the worker package.
+ */
+export const FINAL_REPORT_MD_FILENAME = 'Security-Assessment-Report.md';
+
 /**
  * Resolve a run-directory file (e.g. session.json, workflow.log), preferring the
  * current INTERNAL_DIR location and falling back to the legacy run-root location

apps/cli/src/scan/derive.ts

@@ -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 };

apps/cli/src/scan/pipeline.ts

@@ -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;
 }

apps/cli/src/scan/render.ts

@@ -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(

apps/cli/src/scan/status-json.ts

@@ -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),
   };
 }

apps/cli/src/temporal-client.ts

@@ -9,7 +9,7 @@
 
 import { setTimeout as sleep } from 'node:timers/promises';
 import { Client, Connection, WorkflowFailedError, WorkflowNotFoundError } from '@temporalio/client';
-import { ACTIVITY_TO_AGENT, type PipelineState } from './scan/pipeline.js';
+import { ACTIVITY_TO_PROGRESS, type PipelineState } from './scan/pipeline.js';
 
 const ADDRESS = '127.0.0.1:7233';
 const NAMESPACE = 'default';
@@ -20,11 +20,30 @@ const TERMINAL_STATUSES: ReadonlySet<string> = new Set(['COMPLETED', 'FAILED', '
 
 export interface RunningAgent {
   readonly agent: string;
+  readonly label: string;
+  /** 'agent' rows join the static pipeline tree; 'operation' rows feed the background-work phase. */
+  readonly kind: 'agent' | 'operation';
+  /** Set when a persisted parent stage owns this row; the label then reads as that stage's step. */
+  readonly parentKey?: string;
   readonly attempt: number;
   readonly startedAt?: number;
   readonly lastFailure?: string;
 }
 
+/**
+ * The CLI's activity mirror does not know an activity type the running scan is using, so the
+ * progress tree cannot be rendered completely. Distinct from a Temporal connection failure.
+ */
+export class ActivityMirrorError extends Error {
+  override name = 'ActivityMirrorError' as const;
+
+  constructor(activityType: string) {
+    super(
+      `This version of the Shannon command line does not recognise part of the running scan\n(${activityType}). Update Shannon, or watch the scan with: shannon logs <workspace>`,
+    );
+  }
+}
+
 /** Convert a proto ITimestamp (seconds is a Long) to epoch millis. */
 function timestampMs(
   ts: { seconds?: { toString(): string } | number | null; nanos?: number | null } | null,
@@ -66,12 +85,19 @@ export async function describeScan(workflowId: string): Promise<ScanDescription
 
     const runningAgents: RunningAgent[] = [];
     for (const pending of desc.raw.pendingActivities ?? []) {
-      const agent = ACTIVITY_TO_AGENT[pending.activityType?.name ?? ''];
-      if (!agent) continue;
+      const activityType = pending.activityType?.name ?? '';
+      const progress = ACTIVITY_TO_PROGRESS[activityType];
+      // Fail closed: skipping an unknown activity would render a quietly incomplete tree.
+      if (!progress) {
+        throw new ActivityMirrorError(activityType || 'unknown activity');
+      }
       const lastFailure = pending.lastFailure?.message;
       const startedAt = timestampMs(pending.scheduledTime ?? pending.lastStartedTime ?? null);
       runningAgents.push({
-        agent,
+        agent: progress.key,
+        label: progress.label,
+        kind: progress.kind,
+        ...(progress.parentKey !== undefined ? { parentKey: progress.parentKey } : {}),
         attempt: pending.attempt ?? 1,
         ...(startedAt !== undefined ? { startedAt } : {}),
         ...(lastFailure ? { lastFailure } : {}),