@hegemonart/get-design-done 1.19.6 → 1.21.0

package/scripts/lib/init-runner/researchers.ts

@@ -0,0 +1,245 @@
+// scripts/lib/init-runner/researchers.ts — researcher dispatch for the
+// `gdd-sdk init` runner (Plan 21-08, SDK-20).
+//
+// Two exports:
+//
+//   * spawnResearcher(spec, opts)       — one session, returns ResearcherOutcome.
+//   * spawnResearchersParallel(specs, opts) — semaphore-bound concurrent dispatch.
+//
+// Each researcher runs through `session-runner.run()` so the session
+// layer owns budget + turn-cap + sanitizer + transcript policy. This
+// module only orchestrates and packages outcomes.
+//
+// Tool scope resolution:
+//   * If `spec.agentPath` is set and the file exists, parse its
+//     frontmatter tools list via `parseAgentTools`.
+//   * Otherwise (or if parse returns `null` meaning wildcard/absent),
+//     use the `init` stage scope from `tool-scoping`.
+//
+// Never-throws contract: a thrown session + a session with `status !==
+// 'completed'` both land as `ResearcherOutcome.status = 'error'`. The
+// outer `spawnResearchersParallel` therefore never rejects even if
+// every researcher explodes.
+
+import { existsSync } from 'node:fs';
+
+import { run as runSession } from '../session-runner/index.ts';
+import type {
+  BudgetCap,
+  QueryOverride,
+  SessionResult,
+} from '../session-runner/types.ts';
+import { enforceScope, parseAgentTools } from '../tool-scoping/index.ts';
+import type { ResearcherOutcome, ResearcherSpec } from './types.ts';
+import { fileSize } from './scaffold.ts';
+
+/** Monotonic-enough wall-clock helper. Used for duration_ms measurement.
+ *  We use `Date.now()` rather than `performance.now()` because the Node
+ *  `perf_hooks` module is unavailable in some sandboxed test runners;
+ *  ms-precision is plenty for a researcher that runs for seconds. */
+function nowMs(): number {
+  return Date.now();
+}
+
+// ---------------------------------------------------------------------------
+// spawnResearcher — single researcher session
+// ---------------------------------------------------------------------------
+
+export interface SpawnResearcherOptions {
+  readonly budget: BudgetCap;
+  readonly maxTurns: number;
+  /** Test-injectable `queryOverride` forwarded into session-runner. */
+  readonly runOverride?: QueryOverride;
+  readonly cwd: string;
+}
+
+/**
+ * Spawn one researcher session through `session-runner.run()`. Returns
+ * a structured `ResearcherOutcome` regardless of outcome; never throws
+ * for any session-level failure mode.
+ *
+ * Dual measurement:
+ *   * `output_exists` + `output_bytes` — measured on disk AFTER the
+ *     session returns; a session that claimed success but failed to
+ *     call the Write tool lands with `output_exists: false`.
+ *   * `usage`, `duration_ms`, `error` — read off the `SessionResult`.
+ */
+export async function spawnResearcher(
+  spec: ResearcherSpec,
+  opts: SpawnResearcherOptions,
+): Promise<ResearcherOutcome> {
+  const start = nowMs();
+
+  // Resolve allowed tool list via tool-scoping.
+  //
+  // `parseAgentTools` returns:
+  //   null      — file missing, no frontmatter, tools absent, or wildcard
+  //   []        — explicit MCP-only (tools: [])
+  //   string[]  — declared list
+  //
+  // Pass `agentTools` to `enforceScope` ONLY when we got a concrete list
+  // or an explicit empty array; `null` → omit so the stage default wins.
+  let agentTools: readonly string[] | null = null;
+  if (spec.agentPath !== undefined && existsSync(spec.agentPath)) {
+    agentTools = parseAgentTools(spec.agentPath);
+  }
+
+  let allowedTools: readonly string[];
+  try {
+    allowedTools = enforceScope({
+      stage: 'init',
+      ...(agentTools !== null ? { agentTools } : {}),
+    });
+  } catch (err) {
+    // Scope enforcement failure — package as a researcher error without
+    // throwing. This is a precondition bug; the caller can present it
+    // alongside any other researcher failures.
+    return packageErrorOutcome(spec, start, 'SCOPE_ENFORCEMENT', err);
+  }
+
+  // Build the session options. `runOverride` is forwarded as the
+  // session-runner's `queryOverride` (same shape).
+  let session: SessionResult;
+  try {
+    session = await runSession({
+      prompt: spec.prompt,
+      stage: 'init',
+      budget: opts.budget,
+      turnCap: { maxTurns: opts.maxTurns },
+      allowedTools: [...allowedTools],
+      ...(opts.runOverride !== undefined
+        ? { queryOverride: opts.runOverride }
+        : {}),
+    });
+  } catch (err) {
+    // session-runner.run() is documented to never throw — but be
+    // defensive: if a test injects a runOverride that throws during
+    // setup we still package a clean outcome.
+    return packageErrorOutcome(spec, start, 'SESSION_THREW', err);
+  }
+
+  const duration = nowMs() - start;
+  const outputExists = existsSync(spec.outputPath);
+  const outputBytes = outputExists ? fileSize(spec.outputPath) : 0;
+
+  if (session.status === 'completed') {
+    return Object.freeze({
+      name: spec.name,
+      status: 'completed' as const,
+      output_exists: outputExists,
+      output_bytes: outputBytes,
+      usage: {
+        input_tokens: session.usage.input_tokens,
+        output_tokens: session.usage.output_tokens,
+        usd_cost: session.usage.usd_cost,
+      },
+      duration_ms: duration,
+    });
+  }
+
+  // Non-completed statuses (budget_exceeded, turn_cap_exceeded,
+  // aborted, error) all land here as researcher errors. Preserve the
+  // session-runner's error code/message when present, otherwise
+  // synthesize one from the status.
+  const code = session.error?.code ?? session.status.toUpperCase();
+  const message = session.error?.message ?? `session ended: ${session.status}`;
+  return Object.freeze({
+    name: spec.name,
+    status: 'error' as const,
+    output_exists: outputExists,
+    output_bytes: outputBytes,
+    usage: {
+      input_tokens: session.usage.input_tokens,
+      output_tokens: session.usage.output_tokens,
+      usd_cost: session.usage.usd_cost,
+    },
+    duration_ms: duration,
+    error: { code, message },
+  });
+}
+
+/** Build a ResearcherOutcome for a local (non-session) error. */
+function packageErrorOutcome(
+  spec: ResearcherSpec,
+  start: number,
+  code: string,
+  err: unknown,
+): ResearcherOutcome {
+  const message = err instanceof Error ? err.message : String(err);
+  const outputExists = existsSync(spec.outputPath);
+  const outputBytes = outputExists ? fileSize(spec.outputPath) : 0;
+  return Object.freeze({
+    name: spec.name,
+    status: 'error' as const,
+    output_exists: outputExists,
+    output_bytes: outputBytes,
+    usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+    duration_ms: nowMs() - start,
+    error: { code, message },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// spawnResearchersParallel — semaphore-bound dispatch
+// ---------------------------------------------------------------------------
+
+export interface SpawnParallelOptions {
+  readonly concurrency: number;
+  readonly budget: BudgetCap;
+  readonly maxTurns: number;
+  readonly runOverride?: QueryOverride;
+  readonly cwd: string;
+}
+
+/**
+ * Run all `specs` in parallel with a semaphore cap of
+ * `opts.concurrency`. The returned outcomes are ordered to match the
+ * input `specs` order so consumers can zip the two arrays directly;
+ * completion ordering within a batch is timing-dependent and not
+ * stable.
+ *
+ * Never rejects: every outcome is packaged via `spawnResearcher`, which
+ * itself never throws.
+ */
+export async function spawnResearchersParallel(
+  specs: readonly ResearcherSpec[],
+  opts: SpawnParallelOptions,
+): Promise<readonly ResearcherOutcome[]> {
+  const concurrency = Math.max(1, Math.floor(opts.concurrency));
+  const outcomes: ResearcherOutcome[] = new Array<ResearcherOutcome>(
+    specs.length,
+  );
+
+  // Simple index-based worker pool. Workers race for the next slot
+  // until all indices are claimed.
+  let next = 0;
+  async function worker(): Promise<void> {
+    for (;;) {
+      const i = next;
+      next += 1;
+      if (i >= specs.length) return;
+      const spec = specs[i];
+      // specs[i] is guaranteed present (i < specs.length) but the
+      // noUncheckedIndexedAccess flag forces the guard.
+      if (spec === undefined) return;
+      outcomes[i] = await spawnResearcher(spec, {
+        budget: opts.budget,
+        maxTurns: opts.maxTurns,
+        cwd: opts.cwd,
+        ...(opts.runOverride !== undefined
+          ? { runOverride: opts.runOverride }
+          : {}),
+      });
+    }
+  }
+
+  // Launch `concurrency` workers and await all.
+  const workers: Promise<void>[] = [];
+  const workerCount = Math.min(concurrency, specs.length);
+  for (let w = 0; w < workerCount; w += 1) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+
+  return outcomes;
+}

package/scripts/lib/init-runner/scaffold.ts

@@ -0,0 +1,224 @@
+// scripts/lib/init-runner/scaffold.ts — filesystem helpers for the
+// `gdd-sdk init` runner (Plan 21-08, SDK-20).
+//
+// This module is synchronous + side-effectful; every helper either
+// mutates disk in a well-defined way or reports a boolean/null/string
+// result. No session-runner / SDK dependencies — keep it cheap to test.
+//
+// Helpers exported:
+//
+//   * writeStateFromTemplate   — copy reference/STATE-TEMPLATE.md →
+//                                .design/STATE.md with `{TODAY}` replaced.
+//   * backupExistingDesignDir  — rename `.design/` to `.design.backup.<ISO>/`.
+//   * resolveStateTemplatePath — walk up from process.argv[1]/cwd to find
+//                                the plugin package root, then join
+//                                reference/STATE-TEMPLATE.md.
+//   * ensureDesignDirs         — `mkdir -p` both `.design/` and
+//                                `.design/research/`.
+//
+// All helpers are pure w.r.t. filesystem ordering — every caller can
+// invoke them in any order without corrupting a concurrent init.
+
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/** The plugin's package.json `name` field used to anchor the walk-up in
+ *  `resolveStateTemplatePath`. */
+const PLUGIN_PACKAGE_NAME = '@hegemonart/get-design-done';
+
+/** Maximum directories to climb looking for the plugin root. Eight
+ *  matches session-runner's repo-root discovery depth — a forgiving
+ *  upper bound without being pathological. */
+const MAX_WALKUP_DEPTH = 8;
+
+// ---------------------------------------------------------------------------
+// writeStateFromTemplate
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy `templatePath` to `destPath`, replacing every `{TODAY}` token
+ * with today's ISO date (`YYYY-MM-DD`). Other placeholders (e.g.,
+ * `{PROJECT_NAME}`) are left verbatim for the user to fill in later.
+ *
+ * Returns `true` on success, `false` when the template is missing.
+ * Never throws for expected failure modes; unexpected errors (permission
+ * denied, out of disk) surface as thrown errors since the caller cannot
+ * meaningfully recover.
+ */
+export function writeStateFromTemplate(args: {
+  readonly cwd: string;
+  readonly templatePath: string;
+  readonly destPath: string;
+}): boolean {
+  const { templatePath, destPath } = args;
+
+  if (!existsSync(templatePath)) return false;
+
+  // Read template → substitute `{TODAY}` → write to dest. If the template
+  // has no `{TODAY}` token we write it verbatim (plan spec: "Template
+  // without placeholder → copied verbatim").
+  const raw = readFileSync(templatePath, 'utf8');
+  const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+  const body = raw.includes('{TODAY}')
+    ? raw.split('{TODAY}').join(today)
+    : raw;
+
+  // Ensure destination directory exists before writing.
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, body, 'utf8');
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// backupExistingDesignDir
+// ---------------------------------------------------------------------------
+
+/**
+ * If `.design/` exists inside `cwd`, move it aside to
+ * `.design.backup.<ISO>/` (ISO safe-for-filename form) and return the
+ * backup directory path. Returns `null` when nothing exists to back up.
+ *
+ * Rename is the default (atomic on same filesystem); on EXDEV or any
+ * other rename error we fall back to recursive copy + rm.
+ */
+export function backupExistingDesignDir(cwd: string): string | null {
+  const designDir = resolve(cwd, '.design');
+  if (!existsSync(designDir)) return null;
+
+  // ISO → filesystem-safe: replace ':' and '.' (e.g. 2026-04-24T10:15:30.123Z
+  // → 2026-04-24T10-15-30-123Z) so Windows accepts the directory name.
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  let backupDir = resolve(cwd, `.design.backup.${stamp}`);
+
+  // Collision guard — sub-millisecond double-invoke could land on the
+  // same ISO stamp. Append a numeric suffix until the path is free.
+  let suffix = 0;
+  while (existsSync(backupDir)) {
+    suffix += 1;
+    backupDir = resolve(cwd, `.design.backup.${stamp}-${suffix}`);
+    if (suffix > 1000) {
+      // Pathological — bail rather than loop forever.
+      throw new Error(`backupExistingDesignDir: could not find a free backup directory after ${suffix} attempts`);
+    }
+  }
+
+  try {
+    renameSync(designDir, backupDir);
+  } catch (err) {
+    // EXDEV (cross-volume), EPERM (Windows permissions), or anything
+    // else — try recursive copy + rm as a slower fallback.
+    const code = (err as NodeJS.ErrnoException | null)?.code;
+    if (code === 'EXDEV' || code === 'EPERM' || code === 'ENOTEMPTY') {
+      cpSync(designDir, backupDir, { recursive: true });
+      rmSync(designDir, { recursive: true, force: true });
+    } else {
+      throw err;
+    }
+  }
+
+  return backupDir;
+}
+
+// ---------------------------------------------------------------------------
+// ensureDesignDirs
+// ---------------------------------------------------------------------------
+
+/**
+ * Create `.design/` and `.design/research/` inside `cwd` (`mkdir -p`).
+ * Idempotent — safe to call on an already-initialized project. Returns
+ * the resolved absolute paths so callers can drop them directly into
+ * `writeStateFromTemplate({destPath: ...})`.
+ */
+export function ensureDesignDirs(cwd: string): {
+  readonly design_dir: string;
+  readonly research_dir: string;
+} {
+  const designDir = resolve(cwd, '.design');
+  const researchDir = join(designDir, 'research');
+  mkdirSync(designDir, { recursive: true });
+  mkdirSync(researchDir, { recursive: true });
+  return Object.freeze({ design_dir: designDir, research_dir: researchDir });
+}
+
+// ---------------------------------------------------------------------------
+// resolveStateTemplatePath
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk up from `process.argv[1]`'s directory (falling back to cwd if
+ * argv[1] isn't a real path) looking for a `package.json` whose `name`
+ * field matches `@hegemonart/get-design-done`. When found, return
+ * `<pkg-root>/reference/STATE-TEMPLATE.md`. Return `null` if we run out
+ * of parent directories without finding the plugin root — e.g., when
+ * invoked from a fork that has renamed the package.
+ *
+ * The walk is bounded to `MAX_WALKUP_DEPTH` (8) to stop us from
+ * traversing the entire filesystem on pathological inputs.
+ */
+export function resolveStateTemplatePath(): string | null {
+  const startCandidates: string[] = [];
+  // argv[1] is the executing script's path (e.g., bin wrapper).
+  const argv1 = process.argv[1];
+  if (argv1 !== undefined && argv1.length > 0 && existsSync(argv1)) {
+    startCandidates.push(dirname(resolve(argv1)));
+  }
+  // Fall back to cwd for cases where argv[1] isn't meaningful (tests,
+  // repl, etc.).
+  startCandidates.push(process.cwd());
+
+  for (const start of startCandidates) {
+    let dir = start;
+    for (let depth = 0; depth < MAX_WALKUP_DEPTH; depth += 1) {
+      const pkgPath = join(dir, 'package.json');
+      if (existsSync(pkgPath)) {
+        try {
+          const raw = readFileSync(pkgPath, 'utf8');
+          const parsed = JSON.parse(raw) as { name?: unknown };
+          if (parsed.name === PLUGIN_PACKAGE_NAME) {
+            const tpl = join(dir, 'reference', 'STATE-TEMPLATE.md');
+            if (existsSync(tpl)) return tpl;
+          }
+        } catch {
+          // Malformed package.json — keep walking; maybe a parent has it.
+        }
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers (kept exported for tests that want to drill in)
+// ---------------------------------------------------------------------------
+
+/** Expose copy-then-write as a unit for tests that want to bypass the
+ *  template-path existence check. Public but undocumented in the index. */
+export function _copyTemplateVerbatim(src: string, dest: string): void {
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(src, dest);
+}
+
+/** Size of a file on disk, or 0 if missing. Used by the researcher
+ *  dispatcher to measure `output_bytes` without bubbling up EEXIST /
+ *  ENOENT. */
+export function fileSize(p: string): number {
+  try {
+    return statSync(p).size;
+  } catch {
+    return 0;
+  }
+}

package/scripts/lib/init-runner/synthesizer.ts

@@ -0,0 +1,224 @@
+// scripts/lib/init-runner/synthesizer.ts — composes
+// `.design/DESIGN-CONTEXT.md` from researcher outputs (Plan 21-08, SDK-20).
+//
+// The synthesizer is a single headless session spawned through
+// `session-runner.run()` with a prompt that embeds every researcher's
+// content. Its success contract is simple: did the agent write
+// `.design/DESIGN-CONTEXT.md` to disk? We don't parse its text output —
+// the file's presence is the sole pass/fail signal.
+//
+// Exports:
+//   * DEFAULT_SYNTHESIZER_PROMPT  — the embedded prompt (frozen string).
+//   * buildSynthesizerPrompt       — splice researcher bodies into the prompt.
+//   * spawnSynthesizer             — session dispatch + file-presence check.
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { run as runSession } from '../session-runner/index.ts';
+import type {
+  BudgetCap,
+  QueryOverride,
+} from '../session-runner/types.ts';
+import { enforceScope } from '../tool-scoping/index.ts';
+import type { ResearcherName } from './types.ts';
+
+/**
+ * Default synthesizer prompt with a `{{RESEARCH_BLOCKS}}` placeholder
+ * that `buildSynthesizerPrompt` substitutes with the researcher
+ * content. The template encodes the DESIGN-CONTEXT.md schema the
+ * downstream discuss stage expects (decisions, must-haves, connections,
+ * ARM, flow diagram, open questions).
+ *
+ * The prompt is explicit about "write file; emit no prose" because the
+ * synthesizer's success is measured by file-on-disk — we don't need the
+ * agent's text stream in the transcript.
+ */
+export const DEFAULT_SYNTHESIZER_PROMPT: string = Object.freeze(
+  `You are the init-synthesizer. Four researchers have produced these outputs:
+
+{{RESEARCH_BLOCKS}}
+
+Compose .design/DESIGN-CONTEXT.md following this schema:
+
+---
+cycle: init
+generated_at: <ISO>
+---
+
+# Design Context (Draft)
+
+## Decisions
+(Draft as D-01, D-02, … from researcher outputs. Each decision gets id,
+ rationale, source researcher.)
+
+## Must-Haves
+(Draft as M-01, M-02, … from researcher blockers. Each must-have gets id,
+ stakeholder, test.)
+
+## Connections
+(Which AI-design-tool connections the project's tech stack recommends.)
+
+## Architectural Responsibility Map
+(ARM tiers inferred from the codebase.)
+
+## Flow Diagram
+\`\`\`mermaid
+flowchart TD
+  ...
+\`\`\`
+
+## Open Questions
+(Anything that requires the user to answer before brief can start.)
+
+Write the final content to .design/DESIGN-CONTEXT.md via Write tool.
+Do NOT emit any prose response — only write the file.
+`,
+) as string;
+
+export interface SynthesizerInput {
+  readonly name: ResearcherName;
+  readonly path: string;
+  readonly content: string;
+}
+
+/**
+ * Build the synthesizer prompt by substituting `{{RESEARCH_BLOCKS}}`
+ * with concatenated research bodies. Each block is wrapped in an HTML
+ * comment header so the agent can parse the boundaries deterministically.
+ *
+ * Exported for tests + for callers that want to assert prompt content
+ * without running a session.
+ */
+export function buildSynthesizerPrompt(
+  inputs: readonly SynthesizerInput[],
+  override?: string,
+): string {
+  const template = override ?? DEFAULT_SYNTHESIZER_PROMPT;
+  const blocks = inputs
+    .map((inp) => `<!-- ${inp.name} -->\n${inp.content}`)
+    .join('\n\n');
+  // If the caller's override doesn't include the placeholder, append
+  // the blocks. This keeps custom prompts functional without forcing
+  // them to adopt our template marker.
+  if (!template.includes('{{RESEARCH_BLOCKS}}')) {
+    return `${template}\n\n${blocks}`;
+  }
+  return template.split('{{RESEARCH_BLOCKS}}').join(blocks);
+}
+
+export interface SpawnSynthesizerArgs {
+  readonly researcherOutputs: readonly SynthesizerInput[];
+  readonly cwd: string;
+  readonly budget: BudgetCap;
+  readonly maxTurns: number;
+  readonly runOverride?: QueryOverride;
+  readonly promptOverride?: string;
+}
+
+export interface SpawnSynthesizerResult {
+  readonly status: 'completed' | 'error';
+  /** Absolute path to where .design/DESIGN-CONTEXT.md should live. */
+  readonly design_context_path: string;
+  readonly usage: {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+    readonly usd_cost: number;
+  };
+  readonly error?: string;
+}
+
+/**
+ * Spawn one synthesizer session. Success is determined by the presence
+ * of `.design/DESIGN-CONTEXT.md` inside `cwd` after the session ends —
+ * we do NOT inspect the session's text output.
+ *
+ * Never throws; session-level errors and missing-file outcomes both
+ * land as `status: 'error'` with `error` populated.
+ */
+export async function spawnSynthesizer(
+  args: SpawnSynthesizerArgs,
+): Promise<SpawnSynthesizerResult> {
+  const designContextPath = resolve(
+    args.cwd,
+    '.design',
+    'DESIGN-CONTEXT.md',
+  );
+
+  // Resolve allowed tools. The synthesizer only needs Read (to load
+  // research outputs if the prompt drops the inline bodies) and Write
+  // (to produce DESIGN-CONTEXT.md). The init stage scope covers both.
+  let allowedTools: readonly string[];
+  try {
+    allowedTools = enforceScope({ stage: 'init' });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return Object.freeze({
+      status: 'error' as const,
+      design_context_path: designContextPath,
+      usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+      error: `scope enforcement failed: ${message}`,
+    });
+  }
+
+  const prompt = buildSynthesizerPrompt(
+    args.researcherOutputs,
+    args.promptOverride,
+  );
+
+  let usage = { input_tokens: 0, output_tokens: 0, usd_cost: 0 };
+  try {
+    const session = await runSession({
+      prompt,
+      stage: 'init',
+      budget: args.budget,
+      turnCap: { maxTurns: args.maxTurns },
+      allowedTools: [...allowedTools],
+      ...(args.runOverride !== undefined
+        ? { queryOverride: args.runOverride }
+        : {}),
+    });
+    usage = {
+      input_tokens: session.usage.input_tokens,
+      output_tokens: session.usage.output_tokens,
+      usd_cost: session.usage.usd_cost,
+    };
+
+    if (session.status !== 'completed') {
+      const code = session.error?.code ?? session.status.toUpperCase();
+      const msg = session.error?.message ?? `session ended: ${session.status}`;
+      return Object.freeze({
+        status: 'error' as const,
+        design_context_path: designContextPath,
+        usage,
+        error: `${code}: ${msg}`,
+      });
+    }
+  } catch (err) {
+    // session-runner is documented never-throws, but a test-injected
+    // runOverride could throw during setup. Package gracefully.
+    const message = err instanceof Error ? err.message : String(err);
+    return Object.freeze({
+      status: 'error' as const,
+      design_context_path: designContextPath,
+      usage,
+      error: `session threw: ${message}`,
+    });
+  }
+
+  // Success is file-on-disk, NOT session.status.
+  if (!existsSync(designContextPath)) {
+    return Object.freeze({
+      status: 'error' as const,
+      design_context_path: designContextPath,
+      usage,
+      error: 'synthesizer did not produce .design/DESIGN-CONTEXT.md',
+    });
+  }
+
+  return Object.freeze({
+    status: 'completed' as const,
+    design_context_path: designContextPath,
+    usage,
+  });
+}