@hegemonart/get-design-done 1.20.0 → 1.22.0

package/scripts/lib/pipeline-runner/stage-handlers.ts

@@ -0,0 +1,339 @@
+// scripts/lib/pipeline-runner/stage-handlers.ts — Plan 21-05 Task 3.
+//
+// Invokes a single pipeline stage. Wires together:
+//   * context-engine  → builds the per-stage file bundle + renders it
+//   * tool-scoping    → enforces the allowed-tools set
+//   * session-runner  → runs the headless Agent SDK session
+//
+// Stage-level retry-once is implemented here via recursion on a
+// `retries` budget. Test harnesses inject mocks via the override args.
+//
+// Mapping from `SessionResult.status` → `StageOutcome.status`:
+//   completed           → completed (OR halted-human-gate if AWAIT_USER_GATE)
+//   budget_exceeded     → halted-budget
+//   turn_cap_exceeded   → halted-turn-cap
+//   aborted             → halted-error (external cancel)
+//   error + retryable   → recurse with retries - 1
+//   error otherwise     → halted-error
+
+import type { Stage, PipelineConfig, StageOutcome, HumanGateInfo } from './types.ts';
+import type {
+  SessionResult,
+  SessionRunnerOptions,
+} from '../session-runner/types.ts';
+import type { ContextBundle, Stage as ContextStage } from '../context-engine/types.ts';
+import {
+  buildContextBundle as defaultBuildBundle,
+  renderBundle,
+} from '../context-engine/index.ts';
+import {
+  enforceScope,
+  parseAgentToolsByName,
+  type Stage as ScopeStage,
+} from '../tool-scoping/index.ts';
+import { run as defaultRun } from '../session-runner/index.ts';
+import { extractGateMarker } from './human-gate.ts';
+
+/**
+ * Test-injection overrides for `invokeStage`. Every override is
+ * optional; omitted overrides fall through to the real module.
+ */
+export interface InvokeStageOverrides {
+  /** Override session-runner.run — defaults to the real `run`. */
+  readonly runOverride?: (opts: SessionRunnerOptions) => Promise<SessionResult>;
+  /** Override context-engine.buildContextBundle — defaults to the real builder. */
+  readonly bundleOverride?: (stage: Stage, cwd?: string) => ContextBundle;
+  /**
+   * Override tool-scoping.enforceScope — defaults to real enforcement.
+   * Returns the final `allowedTools` list.
+   */
+  readonly scopeOverride?: (stage: Stage, agentPath?: string) => readonly string[];
+}
+
+export interface InvokeStageArgs extends InvokeStageOverrides {
+  readonly stage: Stage;
+  readonly config: PipelineConfig;
+  /** Remaining retry budget (0 or 1). */
+  readonly retries: 0 | 1;
+  /** Attempts already consumed (test hook; default 0). */
+  readonly _retriesConsumed?: number;
+  /**
+   * Optional prompt suffix to append (used by the driver to inject
+   * human-gate resume payloads into a retry).
+   */
+  readonly _promptSuffix?: string;
+}
+
+/**
+ * Build the sanitized context prompt by rendering the context-engine
+ * bundle and appending the stage's configured prompt.
+ */
+function buildStagePrompt(args: {
+  stage: Stage;
+  config: PipelineConfig;
+  bundle: ContextBundle;
+  promptSuffix?: string;
+}): string {
+  const rendered: string = renderBundle(args.bundle);
+  const stagePrompt: string = args.config.prompts[args.stage];
+  const parts: string[] = [rendered, '\n\n---\n\n', stagePrompt];
+  if (args.promptSuffix !== undefined && args.promptSuffix !== '') {
+    parts.push('\n\n---\n\n', args.promptSuffix);
+  }
+  return parts.join('');
+}
+
+/**
+ * Map a session-runner `SessionResult` onto the stage-level status.
+ * Human-gate detection runs on `final_text` only when the session
+ * itself completed cleanly — a failed session cannot also be gated.
+ */
+function mapSessionStatus(
+  session: SessionResult,
+): { status: StageOutcome['status']; gate?: { name: string; stdoutTail: string } } {
+  switch (session.status) {
+    case 'completed': {
+      const marker = extractGateMarker(session.final_text ?? '');
+      if (marker !== null) {
+        return {
+          status: 'halted-human-gate',
+          gate: {
+            name: marker.name,
+            stdoutTail: session.final_text ?? '',
+          },
+        };
+      }
+      return { status: 'completed' };
+    }
+    case 'budget_exceeded':
+      return { status: 'halted-budget' };
+    case 'turn_cap_exceeded':
+      return { status: 'halted-turn-cap' };
+    case 'aborted':
+      return { status: 'halted-error' };
+    case 'error':
+    default:
+      return { status: 'halted-error' };
+  }
+}
+
+/**
+ * Determine whether the stage-level retry budget permits a second
+ * attempt. Session-runner owns its own transport-level retry; the
+ * STAGE retry fires only when the session returns `status: 'error'`
+ * AND the mapped SDK error is `retryable`.
+ */
+function isRetryableStageError(session: SessionResult): boolean {
+  if (session.status !== 'error') return false;
+  if (session.error === undefined) return false;
+  // session-runner's `mapSdkError` already stamped the GDDError kind
+  // into session.error.kind. StateConflictError maps to retryable
+  // (rate-limited, overloaded, network-transient). OperationFailedError
+  // may or may not be retryable; we gate on the error code.
+  const kind = session.error.kind;
+  if (kind === 'state_conflict') return true;
+  // For operation_failed we consult the code explicitly — NETWORK_TRANSIENT
+  // and API_ERROR are retryable, everything else isn't.
+  if (kind === 'operation_failed') {
+    const code = session.error.code;
+    return code === 'NETWORK_TRANSIENT' || code === 'API_ERROR';
+  }
+  return false;
+}
+
+/**
+ * Cast the pipeline `Stage` into the context-engine's `Stage` union
+ * (which includes `init`). The pipeline stages are a strict subset of
+ * the context-engine's stages, so this cast is safe.
+ */
+function toContextStage(stage: Stage): ContextStage {
+  return stage as ContextStage;
+}
+
+/**
+ * Cast the pipeline `Stage` into the tool-scoping `Stage` union
+ * (which also includes `init` + `custom`).
+ */
+function toScopeStage(stage: Stage): ScopeStage {
+  return stage as ScopeStage;
+}
+
+/**
+ * Invoke one pipeline stage. Returns a StageOutcome describing what
+ * happened, including timing + retry count.
+ *
+ * Never throws — all failure modes surface via `outcome.status` plus
+ * (when relevant) `outcome.session.error`.
+ */
+export async function invokeStage(args: InvokeStageArgs): Promise<StageOutcome> {
+  const started_at: string = new Date().toISOString();
+  const retriesConsumed: number = args._retriesConsumed ?? 0;
+
+  // -- 1. Build the context bundle for this stage. ------------------------
+  let bundle: ContextBundle;
+  try {
+    if (args.bundleOverride !== undefined) {
+      bundle = args.bundleOverride(args.stage, args.config.cwd);
+    } else {
+      bundle = defaultBuildBundle(toContextStage(args.stage), {
+        ...(args.config.cwd !== undefined ? { cwd: args.config.cwd } : {}),
+      });
+    }
+  } catch (err) {
+    return {
+      stage: args.stage,
+      status: 'halted-error',
+      started_at,
+      ended_at: new Date().toISOString(),
+      retries: retriesConsumed,
+      session: makeErrorSession(err, 'bundle_build_failed'),
+    };
+  }
+
+  // -- 2. Resolve the agent frontmatter override + tool scope. ------------
+  let allowedTools: readonly string[];
+  try {
+    if (args.scopeOverride !== undefined) {
+      const agentPath = args.config.agentsByStage?.[args.stage];
+      if (agentPath !== undefined) {
+        allowedTools = args.scopeOverride(args.stage, agentPath);
+      } else {
+        allowedTools = args.scopeOverride(args.stage);
+      }
+    } else {
+      const agentPath = args.config.agentsByStage?.[args.stage];
+      const agentTools: readonly string[] | null =
+        agentPath !== undefined ? parseAgentToolsByName(agentPath) : null;
+      allowedTools = enforceScope({
+        stage: toScopeStage(args.stage),
+        ...(agentTools !== null ? { agentTools } : {}),
+      });
+    }
+  } catch (err) {
+    return {
+      stage: args.stage,
+      status: 'halted-error',
+      started_at,
+      ended_at: new Date().toISOString(),
+      retries: retriesConsumed,
+      session: makeErrorSession(err, 'scope_resolution_failed'),
+    };
+  }
+
+  // -- 3. Compose the session-runner options. -----------------------------
+  const prompt: string = buildStagePrompt({
+    stage: args.stage,
+    config: args.config,
+    bundle,
+    ...(args._promptSuffix !== undefined ? { promptSuffix: args._promptSuffix } : {}),
+  });
+
+  const systemPrompt: string | undefined = args.config.systemPrompts?.[args.stage];
+
+  const runOpts: SessionRunnerOptions = {
+    prompt,
+    ...(systemPrompt !== undefined ? { systemPrompt } : {}),
+    allowedTools: [...allowedTools],
+    budget: {
+      usdLimit: args.config.budget.usdLimit,
+      inputTokensLimit: args.config.budget.inputTokensLimit,
+      outputTokensLimit: args.config.budget.outputTokensLimit,
+    },
+    turnCap: { maxTurns: args.config.maxTurnsPerStage },
+    stage: toScopeStage(args.stage),
+  };
+
+  // -- 4. Invoke session-runner (or the override). ------------------------
+  const runImpl = args.runOverride ?? defaultRun;
+  let session: SessionResult;
+  try {
+    session = await runImpl(runOpts);
+  } catch (err) {
+    // session-runner contracts never to throw. If the override throws,
+    // we still surface a halted-error outcome with a synthetic session.
+    return {
+      stage: args.stage,
+      status: 'halted-error',
+      started_at,
+      ended_at: new Date().toISOString(),
+      retries: retriesConsumed,
+      session: makeErrorSession(err, 'session_run_threw'),
+    };
+  }
+
+  // -- 5. Map session status → stage status. ------------------------------
+  const mapped = mapSessionStatus(session);
+
+  // -- 6. Stage-level retry-once on retryable error. ----------------------
+  if (
+    mapped.status === 'halted-error' &&
+    args.retries > 0 &&
+    isRetryableStageError(session)
+  ) {
+    // Recurse with retries exhausted (0). The retry must reuse the
+    // same config + overrides so the test harness can observe it.
+    const nextArgs: InvokeStageArgs = {
+      stage: args.stage,
+      config: args.config,
+      retries: 0,
+      _retriesConsumed: retriesConsumed + 1,
+      ...(args._promptSuffix !== undefined ? { _promptSuffix: args._promptSuffix } : {}),
+      ...(args.runOverride !== undefined ? { runOverride: args.runOverride } : {}),
+      ...(args.bundleOverride !== undefined ? { bundleOverride: args.bundleOverride } : {}),
+      ...(args.scopeOverride !== undefined ? { scopeOverride: args.scopeOverride } : {}),
+    };
+    return invokeStage(nextArgs);
+  }
+
+  const ended_at: string = new Date().toISOString();
+
+  const gateInfo: HumanGateInfo | undefined =
+    mapped.status === 'halted-human-gate' && mapped.gate !== undefined
+      ? {
+          stage: args.stage,
+          gateName: mapped.gate.name,
+          stdoutTail: mapped.gate.stdoutTail,
+        }
+      : undefined;
+
+  return {
+    stage: args.stage,
+    status: mapped.status,
+    session,
+    started_at,
+    ended_at,
+    retries: retriesConsumed,
+    ...(gateInfo !== undefined ? { gate: gateInfo } : {}),
+  };
+}
+
+/**
+ * Build a synthetic `SessionResult` describing a failure that occurred
+ * outside the session (bundle build, scope resolution, or a thrown
+ * run override). The shape matches session-runner's `SessionResult` so
+ * downstream code treats it uniformly.
+ */
+function makeErrorSession(err: unknown, code: string): SessionResult {
+  const message: string =
+    err === null || err === undefined
+      ? 'unknown error'
+      : err instanceof Error
+        ? err.message
+        : typeof err === 'string'
+          ? err
+          : 'unknown error';
+  return {
+    status: 'error',
+    transcript_path: '',
+    turns: 0,
+    usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+    tool_calls: [],
+    sanitizer: { applied: [], removedSections: [] },
+    error: {
+      code,
+      message,
+      kind: 'operation_failed',
+      context: {},
+    },
+  };
+}

package/scripts/lib/pipeline-runner/state-machine.ts

@@ -0,0 +1,144 @@
+// scripts/lib/pipeline-runner/state-machine.ts — Plan 21-05 Task 2.
+//
+// Stage-ordering primitives. Pure — no I/O, no logging, no side effects.
+// Consumed by `index.ts` (to compute the run order) and `stage-handlers.ts`
+// indirectly via `nextStage()` for future lookahead hooks.
+//
+// Rules locked by Plan 21-05:
+//   * STAGE_ORDER is frozen — mutation attempts throw in strict mode.
+//   * `resolveStageOrder` must preserve STAGE_ORDER's relative ordering.
+//     Out-of-order user input (e.g., `stages: ['verify', 'brief']`) throws
+//     a `ValidationError` with code `INVALID_STAGE_ORDER`.
+//   * `resumeFrom` drops stages strictly before it (keeps self + after).
+//   * `stopAfter` drops stages strictly after it (keeps self + before).
+//   * `skipStages` is applied last, filtering any remaining stage whose
+//     name is in the set. Unknown stage names in `skipStages` are
+//     tolerated (no-op) — the filter is a membership check.
+
+import { ValidationError } from '../gdd-errors/index.ts';
+import type { Stage } from './types.ts';
+
+/**
+ * Canonical pipeline order. Frozen so downstream consumers cannot
+ * mutate it by accident. Every other ordering primitive derives from
+ * this array.
+ */
+export const STAGE_ORDER: readonly Stage[] = Object.freeze([
+  'brief',
+  'explore',
+  'plan',
+  'design',
+  'verify',
+] as const);
+
+/**
+ * Return the zero-based index of `stage` in `STAGE_ORDER`. Throws
+ * `ValidationError` for unknown stages — callers should have already
+ * narrowed the input to the `Stage` union, but runtime checks defend
+ * against `as` casts.
+ */
+export function stageIndex(stage: Stage): number {
+  const idx = STAGE_ORDER.indexOf(stage);
+  if (idx < 0) {
+    throw new ValidationError(
+      `unknown stage: ${String(stage)}`,
+      'INVALID_STAGE',
+      { stage, knownStages: [...STAGE_ORDER] },
+    );
+  }
+  return idx;
+}
+
+/**
+ * Return the stage that follows `current` in canonical order, or
+ * `null` when `current` is the terminal stage (`verify`).
+ */
+export function nextStage(current: Stage): Stage | null {
+  const idx = stageIndex(current);
+  if (idx === STAGE_ORDER.length - 1) return null;
+  const next = STAGE_ORDER[idx + 1];
+  // noUncheckedIndexedAccess narrows to `Stage | undefined`; we just
+  // proved it's defined because idx + 1 < length.
+  if (next === undefined) return null;
+  return next;
+}
+
+/**
+ * Configuration subset relevant to stage-order resolution.
+ */
+export interface ResolveStageOrderInput {
+  readonly stages?: readonly Stage[];
+  readonly skipStages?: readonly Stage[];
+  readonly resumeFrom?: Stage;
+  readonly stopAfter?: Stage;
+}
+
+/**
+ * Resolve the effective run order for a pipeline invocation, applying
+ * (in order) `stages` selection → `resumeFrom` → `stopAfter` →
+ * `skipStages`.
+ *
+ * Validates that the user-supplied `stages` array preserves the
+ * canonical relative ordering — out-of-order input throws a
+ * `ValidationError`.
+ *
+ * Validates that `resumeFrom` and `stopAfter` are mutually consistent
+ * when both are supplied (`resumeFrom` cannot be later than
+ * `stopAfter`).
+ *
+ * Returns a frozen, read-only array.
+ */
+export function resolveStageOrder(input: ResolveStageOrderInput = {}): readonly Stage[] {
+  // 1. Pick the initial set of stages.
+  const initial: readonly Stage[] = input.stages ?? STAGE_ORDER;
+
+  // 2. Validate relative order against STAGE_ORDER.
+  let lastIdx = -1;
+  for (const s of initial) {
+    const idx = stageIndex(s);
+    if (idx <= lastIdx) {
+      throw new ValidationError(
+        `stages array out of canonical order near "${s}"; expected ascending ${STAGE_ORDER.join(' → ')}`,
+        'INVALID_STAGE_ORDER',
+        { stages: [...initial], canonical: [...STAGE_ORDER] },
+      );
+    }
+    lastIdx = idx;
+  }
+
+  // 3. Validate resumeFrom / stopAfter consistency.
+  if (input.resumeFrom !== undefined && input.stopAfter !== undefined) {
+    const rIdx = stageIndex(input.resumeFrom);
+    const sIdx = stageIndex(input.stopAfter);
+    if (rIdx > sIdx) {
+      throw new ValidationError(
+        `resumeFrom="${input.resumeFrom}" is later than stopAfter="${input.stopAfter}"`,
+        'INVALID_STAGE_WINDOW',
+        { resumeFrom: input.resumeFrom, stopAfter: input.stopAfter },
+      );
+    }
+  }
+
+  // 4. Apply resumeFrom — drop stages strictly before it.
+  let working: Stage[] = [...initial];
+  if (input.resumeFrom !== undefined) {
+    const resume = input.resumeFrom;
+    const resumeIdx = stageIndex(resume);
+    working = working.filter((s) => stageIndex(s) >= resumeIdx);
+  }
+
+  // 5. Apply stopAfter — drop stages strictly after it.
+  if (input.stopAfter !== undefined) {
+    const stop = input.stopAfter;
+    const stopIdx = stageIndex(stop);
+    working = working.filter((s) => stageIndex(s) <= stopIdx);
+  }
+
+  // 6. Apply skipStages — membership filter.
+  if (input.skipStages !== undefined && input.skipStages.length > 0) {
+    const skip = new Set<string>(input.skipStages);
+    working = working.filter((s) => !skip.has(s));
+  }
+
+  return Object.freeze(working);
+}

package/scripts/lib/pipeline-runner/types.ts

@@ -0,0 +1,183 @@
+// scripts/lib/pipeline-runner/types.ts — Plan 21-05 (SDK-17).
+//
+// Typed surface for the Brief → Verify state machine that drives the
+// full headless Phase-21 pipeline. Consumed by `state-machine.ts`,
+// `stage-handlers.ts`, `human-gate.ts`, and `index.ts` (the `run()`
+// driver).
+//
+// Design notes:
+//   * `Stage` is the 5-stage design pipeline (brief → explore → plan →
+//     design → verify). It is intentionally NARROWER than the session-
+//     runner's Stage union (which also carries `init` + `custom`) —
+//     the pipeline runner orchestrates only the design stages. `init`
+//     is owned by Plan 21-08; `custom` is a one-off escape valve.
+//   * `StageStatus` encodes terminal outcomes at the stage level. Any
+//     status beginning with `halted-*` aborts the pipeline (except
+//     `halted-human-gate`, which the driver disambiguates via the
+//     `onHumanGate` callback).
+//   * `PipelineStatus` is the pipeline-level terminal state. The driver
+//     NEVER throws — all failure modes land here.
+//   * Budget + turn caps apply per-stage. `BudgetCap.perStage` is
+//     advisory for future aggregate-mode support (not used in this
+//     plan — Plan 21-11's real-SDK E2E may revisit).
+
+/**
+ * The 5 stages of the design pipeline. Mirrors `.design/STATE.md`'s
+ * stage field (Plan 20-01's gdd-state contract).
+ */
+export type Stage = 'brief' | 'explore' | 'plan' | 'design' | 'verify';
+
+/**
+ * Terminal outcome for a single stage. `completed` and `skipped` are
+ * non-halting; every `halted-*` status aborts the pipeline — except
+ * `halted-human-gate`, which the driver may resolve by invoking the
+ * caller's `onHumanGate` callback.
+ */
+export type StageStatus =
+  | 'completed'
+  | 'skipped'
+  | 'halted-gate-veto'
+  | 'halted-budget'
+  | 'halted-turn-cap'
+  | 'halted-error'
+  | 'halted-human-gate';
+
+/**
+ * Terminal state for the whole pipeline. `awaiting-gate` means a
+ * human-gate paused execution; the caller may resume via a new `run()`
+ * invocation with `resumeFrom` set to the paused stage.
+ */
+export type PipelineStatus =
+  | 'completed'
+  | 'halted'
+  | 'stopped-after'
+  | 'awaiting-gate';
+
+/**
+ * Hard caps on cost that apply to every stage's session. See
+ * `session-runner/types.ts` for per-attempt semantics; `perStage=true`
+ * means these caps fire independently per stage, not aggregated across
+ * the pipeline.
+ */
+export interface BudgetCap {
+  readonly usdLimit: number;
+  readonly inputTokensLimit: number;
+  readonly outputTokensLimit: number;
+  /**
+   * When `true`, the budget applies individually to each stage (default).
+   * When `false`, the aggregate pipeline budget is split evenly across
+   * the targeted stages — advisory; implementation still treats each
+   * session's cap as a full `usdLimit` because session-runner owns the
+   * per-session envelope.
+   */
+  readonly perStage: boolean;
+}
+
+/**
+ * Information surfaced to the caller when a stage pauses at a
+ * recognized `AWAIT_USER_GATE` marker. `stdoutTail` is bounded by
+ * `session-runner`'s transcript capture — typically the last few KiB.
+ */
+export interface HumanGateInfo {
+  readonly stage: Stage;
+  readonly gateName: string;
+  readonly stdoutTail: string;
+}
+
+/**
+ * Caller's decision after inspecting a `HumanGateInfo`. `resume`
+ * re-invokes the same stage with the optional `payload` appended to
+ * the prompt (so the caller can inject a directive like "approve and
+ * proceed"). `stop` halts the pipeline with `status: awaiting-gate`.
+ */
+export interface HumanGateDecision {
+  readonly decision: 'resume' | 'stop';
+  readonly payload?: string;
+}
+
+/**
+ * Per-stage agent-frontmatter override. Maps a stage to an
+ * `agents/<name>.md` path whose YAML `tools:` field overrides the
+ * stage's default tool scope. See tool-scoping (Plan 21-03).
+ */
+export type AgentsByStage = Readonly<Partial<Record<Stage, string>>>;
+
+/**
+ * Per-stage prompt + system-prompt maps. `prompts` is required for every
+ * stage in the run order; missing keys throw a `ValidationError` at
+ * driver entry. `systemPrompts` are optional.
+ */
+export interface PipelineConfig {
+  /** Stages to run, defaulting to the full 5. */
+  readonly stages?: readonly Stage[];
+  /** Stages to skip (subset of stages). */
+  readonly skipStages?: readonly Stage[];
+  /** Resume from this stage (earlier stages are no-ops). */
+  readonly resumeFrom?: Stage;
+  /** Stop after completing this stage. */
+  readonly stopAfter?: Stage;
+  /** Per-stage prompt templates. Keys: stage name. Value: prompt body. */
+  readonly prompts: Readonly<Record<Stage, string>>;
+  /** Per-stage system prompts (optional). */
+  readonly systemPrompts?: Readonly<Partial<Record<Stage, string>>>;
+  /** Budget applied to every stage's session. */
+  readonly budget: BudgetCap;
+  /** Turn cap applied to every stage's session. */
+  readonly maxTurnsPerStage: number;
+  /** Max stage-level retry attempts. Must be 0 or 1; default 1. */
+  readonly stageRetries?: 0 | 1;
+  /** Callback invoked when a stage hits a human-verify gate. */
+  readonly onHumanGate?: (info: HumanGateInfo) => Promise<HumanGateDecision>;
+  /** Per-stage agent-frontmatter override map. */
+  readonly agentsByStage?: AgentsByStage;
+  /** Working directory (repo root); defaults to process.cwd(). */
+  readonly cwd?: string;
+}
+
+/**
+ * Per-stage outcome inside a `PipelineResult`. The `session` field is
+ * absent when the stage was skipped (never entered session-runner).
+ *
+ * `retries` is the number of stage-level re-invocations actually
+ * performed. `0` means the first attempt completed (or failed
+ * non-retryably); `1` means the first attempt failed with a retryable
+ * error and the second attempt terminated the stage.
+ */
+export interface StageOutcome {
+  readonly stage: Stage;
+  readonly status: StageStatus;
+  /** SessionResult from the stage's run (absent if skipped). */
+  readonly session?: import('../session-runner/types.ts').SessionResult;
+  /** Blockers if `status === 'halted-gate-veto'`. */
+  readonly blockers?: readonly string[];
+  /** ISO timestamp when the stage started; absent if skipped. */
+  readonly started_at?: string;
+  /** ISO timestamp when the stage ended; absent if skipped. */
+  readonly ended_at?: string;
+  /** Number of stage-level retry attempts actually performed. */
+  readonly retries: number;
+  /** Human-gate info when `status === 'halted-human-gate'`. */
+  readonly gate?: HumanGateInfo;
+}
+
+/**
+ * Final, terminal shape returned by `run()`. Includes per-stage
+ * outcomes, aggregate usage, and the stage where execution halted
+ * (if any).
+ */
+export interface PipelineResult {
+  readonly status: PipelineStatus;
+  readonly cycle_start: string;
+  readonly cycle_end: string;
+  readonly outcomes: readonly StageOutcome[];
+  /** Aggregate usage across all attempted stages. */
+  readonly total_usage: {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+    readonly usd_cost: number;
+  };
+  /** Stage at which the pipeline halted (if any). */
+  readonly halted_at?: Stage;
+  /** Human-gate pause info when `status === 'awaiting-gate'`. */
+  readonly gate?: HumanGateInfo;
+}