supipowers 1.5.3 → 2.0.1

package/src/harness/pipeline.ts

@@ -0,0 +1,348 @@
+/**
+ * Pipeline driver for the harness.
+ *
+ * Mirrors `src/ultraplan/authoring/pipeline.ts` but with harness's own stage list.
+ * Drives the pipeline forward stage-by-stage until either:
+ *  - the pipeline reaches Validate successfully (returns `promoted: true`),
+ *  - it lands at a gate stage (returns `awaiting-user`),
+ *  - or a stage returns `failed` / `blocked`.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { Platform, PlatformPaths } from "../platform/types.js";
+import type {
+  HarnessGateMode,
+  HarnessStage,
+  ModelConfig,
+} from "../types.js";
+import {
+  type HarnessStageRunResult,
+  type HarnessStageRunner,
+  type HarnessStageRunnerContext,
+} from "./stage-runner.js";
+import { HarnessDiscoverStage } from "./stages/discover.js";
+import { HarnessResearchStage } from "./stages/research.js";
+import {
+  HarnessDesignStage,
+  type DesignStageInput,
+  defaultDesignSpecFromDiscover,
+} from "./stages/design.js";
+import { HarnessPlanStage, type PlanStageInput } from "./stages/plan.js";
+import { HarnessImplementStage, type ImplementStageInput } from "./stages/implement.js";
+import { HarnessValidateStage, type ValidateStageInput } from "./stages/validate.js";
+import { loadHarnessDesignSpecJson, loadHarnessDiscover } from "./storage.js";
+import { buildBackendAdapter } from "./anti_slop/backend-factory.js";
+import { DEFAULT_HARNESS_CONFIG } from "./hooks/register.js";
+import { getProjectStatePath } from "../workspace/state-paths.js";
+
+/** Progress event emitted by the pipeline driver for UI feedback. */
+export type HarnessPipelineProgressEvent =
+  | { type: "stage-started"; stage: HarnessStage }
+  | { type: "stage-skipped"; stage: HarnessStage }
+  | { type: "stage-completed"; stage: HarnessStage; detail?: string }
+  | { type: "stage-blocked"; stage: HarnessStage; detail: string }
+  | { type: "stage-failed"; stage: HarnessStage; detail: string }
+  | { type: "awaiting-user"; stage: HarnessStage; detail?: string };
+
+const STAGE_ORDER: readonly HarnessStage[] = [
+  "discover",
+  "research",
+  "design",
+  "plan",
+  "implement",
+  "validate",
+];
+
+/** Default gate set per mode. */
+const GATE_STAGES_DEFAULT: ReadonlySet<HarnessStage> = new Set([
+  "discover",
+  "design",
+  "plan",
+  "validate",
+]);
+const GATE_STAGES_MANUAL: ReadonlySet<HarnessStage> = new Set([
+  "discover",
+  "research",
+  "design",
+  "plan",
+  "implement",
+  "validate",
+]);
+
+function gateStagesFor(mode: HarnessGateMode): ReadonlySet<HarnessStage> {
+  switch (mode) {
+    case "default":
+      return GATE_STAGES_DEFAULT;
+    case "auto":
+      return new Set();
+    case "manual":
+      return GATE_STAGES_MANUAL;
+  }
+}
+
+export interface BuildRunnerInput {
+  /** Required when running the design stage. */
+  designInput?: DesignStageInput;
+  /** Optional override for the plan stage (filename only). */
+  planInput?: PlanStageInput;
+  /** Required when running the implement stage. */
+  implementInput?: ImplementStageInput;
+  /** Required when running the validate stage. */
+  validateInput?: ValidateStageInput;
+}
+
+export function buildHarnessRunner(stage: HarnessStage, input: BuildRunnerInput): HarnessStageRunner {
+  switch (stage) {
+    case "discover":
+      return new HarnessDiscoverStage();
+    case "research":
+      return new HarnessResearchStage();
+    case "design":
+      if (!input.designInput) {
+        throw new Error("buildHarnessRunner: design stage requires designInput");
+      }
+      return new HarnessDesignStage(input.designInput);
+    case "plan":
+      return new HarnessPlanStage(input.planInput);
+    case "implement":
+      if (!input.implementInput) {
+        throw new Error("buildHarnessRunner: implement stage requires implementInput");
+      }
+      return new HarnessImplementStage(input.implementInput);
+    case "validate":
+      if (!input.validateInput) {
+        throw new Error("buildHarnessRunner: validate stage requires validateInput");
+      }
+      return new HarnessValidateStage(input.validateInput);
+  }
+}
+
+export interface PipelineRunOutcome {
+  stage: HarnessStage;
+  status: HarnessStageRunResult["status"];
+  /** True when the pipeline reached Validate with a passing report. */
+  promoted: boolean;
+  message?: string;
+  /** Trace of every stage visited this run. */
+  trace: { stage: HarnessStage; status: HarnessStageRunResult["status"] }[];
+}
+
+export interface PipelineDriverInput {
+  platform: Platform;
+  paths: PlatformPaths;
+  cwd: string;
+  sessionId: string;
+  modelConfig: ModelConfig;
+  gates: HarnessGateMode;
+  /** Stage-specific inputs supplied by the command handler. */
+  stageInputs: BuildRunnerInput;
+  /**
+   * When set, start the pipeline at this stage (skipping earlier stages even when not
+   * complete). Used by per-stage subcommands.
+   */
+  startStage?: HarnessStage;
+  /** Hard cap on stage iterations. */
+  safetyLimit?: number;
+  /** Optional callback for progress events (wire up a progress widget). */
+  onProgress?: (event: HarnessPipelineProgressEvent) => void;
+}
+
+// ── Stage input derivation ──────────────────────────────────────────
+
+function ensureStageInputs(
+  input: PipelineDriverInput,
+  stage: HarnessStage,
+): BuildRunnerInput {
+  const base = input.stageInputs;
+
+  switch (stage) {
+    case "design": {
+      if (base.designInput) return base;
+      const discover = loadHarnessDiscover(input.paths, input.cwd, input.sessionId);
+      if (!discover.ok) return base;
+      const spec = defaultDesignSpecFromDiscover(
+        discover.value,
+        input.sessionId,
+        new Date().toISOString(),
+      );
+      return { ...base, designInput: { spec } };
+    }
+    case "implement": {
+      if (base.implementInput) return base;
+      const planName = `harness-${input.sessionId}.md`;
+      const plansDir = getProjectStatePath(input.paths, input.cwd, "plans");
+      const planPath = path.join(plansDir, planName);
+      if (!fs.existsSync(planPath)) return base;
+      const threshold = DEFAULT_HARNESS_CONFIG.implement_in_session_threshold ?? 10;
+      return { ...base, implementInput: { planPath, threshold } };
+    }
+    case "validate": {
+      if (base.validateInput) return base;
+      const designResult = loadHarnessDesignSpecJson(
+        input.paths,
+        input.cwd,
+        input.sessionId,
+      );
+      if (!designResult.ok) return base;
+      const spec = designResult.value;
+      const adapter = buildBackendAdapter(spec.antiSlop.backend);
+      return {
+        ...base,
+        validateInput: {
+          backend: spec.antiSlop.backend,
+          adapter: adapter ?? undefined,
+          scoreFloor: spec.antiSlop.hooks.score_floor,
+          hooks: spec.antiSlop.hooks,
+        },
+      };
+    }
+    default:
+      return base;
+  }
+}
+
+function formatStageDetail(result: HarnessStageRunResult): string {
+  const d = result.details;
+  if (!d) return result.status;
+  if (result.stage === "discover" && Array.isArray(d.languages)) {
+    const langs = (d.languages as string[]).slice(0, 3).join(", ");
+    return `${langs}${d.languages.length > 3 ? ", …" : ""} · ${d.recommendedBackend ?? "?"}`;
+  }
+  if (result.stage === "design") {
+    const backend = d.backend ?? "?";
+    const layers = typeof d.layerCount === "number" ? `${d.layerCount} layers` : "";
+    return layers ? `${backend} · ${layers}` : `${backend}`;
+  }
+  if (result.stage === "validate" && typeof d.passed === "boolean") {
+    return d.passed ? "passed" : "issues found";
+  }
+  return result.status;
+}
+
+function awaitUserDetail(result: HarnessStageRunResult): string {
+  return formatStageDetail(result) || "awaiting review";
+}
+// ── Pipeline loop ───────────────────────────────────────────────────
+/**
+ * Run the pipeline forward until completion or a gate. Each stage:
+ *  - is skipped when its `isComplete` returns true;
+ *  - blocks/fails surface immediately;
+ *  - awaiting-user returns to the caller with the gate decision.
+ */
+export async function runHarnessPipelineUntilGate(
+  input: PipelineDriverInput,
+): Promise<PipelineRunOutcome> {
+  const trace: { stage: HarnessStage; status: HarnessStageRunResult["status"] }[] = [];
+  const gateStages = gateStagesFor(input.gates);
+  const safetyLimit = input.safetyLimit ?? 12;
+  let safety = 0;
+
+  let stageIndex = input.startStage ? STAGE_ORDER.indexOf(input.startStage) : 0;
+  if (stageIndex < 0) stageIndex = 0;
+
+  while (safety < safetyLimit) {
+    safety += 1;
+    if (stageIndex >= STAGE_ORDER.length) break;
+    const stage = STAGE_ORDER[stageIndex];
+
+    input.onProgress?.({ type: "stage-started", stage });
+
+    const stageInputs = ensureStageInputs(input, stage);
+    const runner = buildHarnessRunner(stage, stageInputs);
+
+    const isComplete = await runner.isComplete({
+      platform: input.platform,
+      paths: input.paths,
+      cwd: input.cwd,
+      sessionId: input.sessionId,
+      modelConfig: input.modelConfig,
+      gateMode: input.gates,
+    });
+
+    if (isComplete) {
+      input.onProgress?.({ type: "stage-skipped", stage });
+      trace.push({ stage, status: "skipped" });
+      stageIndex += 1;
+      continue;
+    }
+
+    const ctx: HarnessStageRunnerContext = {
+      platform: input.platform,
+      paths: input.paths,
+      cwd: input.cwd,
+      sessionId: input.sessionId,
+      modelConfig: input.modelConfig,
+      gateMode: input.gates,
+    };
+
+    const result = await runner.run(ctx);
+
+    // In auto mode, awaiting-user is equivalent to completed — normalize
+    // both the trace entry and any outcome derived from it so the UI never
+    // shows a confusing mix of checkmarks and "awaiting user".
+    const isGate = gateStages.has(stage);
+    const normalizedStatus: HarnessStageRunResult["status"] =
+      result.status === "awaiting-user" && !isGate
+        ? "completed"
+        : result.status;
+    trace.push({ stage, status: normalizedStatus });
+
+    const detail = formatStageDetail(result);
+
+    if (result.status === "failed") {
+      input.onProgress?.({ type: "stage-failed", stage, detail: result.error ?? detail });
+      return {
+        stage, status: result.status, promoted: false,
+        message: result.error, trace,
+      };
+    }
+
+    if (result.status === "blocked") {
+      input.onProgress?.({ type: "stage-blocked", stage, detail: result.blocker?.message ?? detail });
+      return {
+        stage, status: result.status, promoted: false,
+        message: result.blocker?.message, trace,
+      };
+    }
+
+    // In auto mode, awaiting-user is equivalent to completed — the pipeline
+    // continues without stopping. Only surface the distinction when gated.
+    if (normalizedStatus === "awaiting-user" && isGate) {
+      input.onProgress?.({ type: "awaiting-user", stage, detail: awaitUserDetail(result) });
+    } else {
+      input.onProgress?.({ type: "stage-completed", stage, detail });
+    }
+
+    if (isGate && normalizedStatus !== "skipped") {
+      return {
+        stage,
+        status: "awaiting-user",
+        promoted: false,
+        trace,
+      };
+    }
+
+    if (stage === "validate" && (normalizedStatus === "completed" || normalizedStatus === "skipped")) {
+      return {
+        stage: "validate",
+        status: normalizedStatus,
+        promoted: true,
+        trace,
+      };
+    }
+
+    stageIndex += 1;
+  }
+
+  return {
+    stage: "validate",
+    status: "failed",
+    promoted: false,
+    message: "harness pipeline exceeded its safety cap",
+    trace,
+  };
+}
+
+export const HARNESS_STAGE_ORDER = STAGE_ORDER;

package/src/harness/project-paths.ts

@@ -0,0 +1,235 @@
+/**
+ * Path helpers for the harness pipeline.
+ *
+ * Mirrors the `src/ultraplan/project-paths.ts` pattern:
+ *  - per-session global state under `~/.omp/supipowers/projects/<slug>/harness/<sessionId>/`,
+ *  - repo-scoped marker + score files under `<repo>/.omp/supipowers/harness/`,
+ *  - persistent slop queue lives under the global path so concurrent worktrees of one repo
+ *    converge on a single queue (resolved through `resolveRepoIdentityRootFromFs`).
+ *
+ * Filename constants are exported so call sites never inline the strings — keeping the
+ * `getHarnessXxxPath` family as the only entry point makes the storage layout refactorable.
+ */
+
+import path from "node:path";
+
+import type { PlatformPaths } from "../platform/types.js";
+import { projectSlugFromRepoRoot } from "../workspace/project-slug.js";
+import { resolveRepoIdentityRootFromFs } from "../workspace/repo-root.js";
+
+// ---------------------------------------------------------------------------
+// Canonical directory + filename constants.
+// ---------------------------------------------------------------------------
+
+/** Root directory under the project slug for harness pipeline state. */
+const HARNESS_DIRNAME = "harness";
+
+/** Per-session subdirectory containing every artifact for one pipeline run. */
+const HARNESS_SESSIONS_DIRNAME = "sessions";
+
+/** Append-only slop-queue file. JSONL, one record per line. */
+export const HARNESS_QUEUE_FILENAME = "queue.jsonl";
+
+/** Aggregate score JSON. Computed at the end of Validate and every GC run. */
+export const HARNESS_SCORE_FILENAME = "score.json";
+
+/** Append-only score history. JSONL, one record per Validate / GC computation. */
+export const HARNESS_SCORE_HISTORY_FILENAME = "score-history.jsonl";
+
+/** Repo-local marker file. Presence means the harness is installed for this repo. */
+export const HARNESS_MARKER_FILENAME = "marker.json";
+
+/** Per-session manifest. Holds HarnessSession state. */
+export const HARNESS_MANIFEST_FILENAME = "manifest.json";
+
+/** Per-session artifact filenames. */
+export const HARNESS_DISCOVER_FILENAME = "discover.json";
+export const HARNESS_DESIGN_SPEC_FILENAME = "design-spec.md";
+export const HARNESS_DESIGN_SPEC_JSON_FILENAME = "design-spec.json";
+export const HARNESS_DECISIONS_FILENAME = "decisions.jsonl";
+export const HARNESS_VALIDATE_REPORT_FILENAME = "validate-report.json";
+export const HARNESS_IMPLEMENT_LOG_FILENAME = "implement-log.jsonl";
+export const HARNESS_PIPELINE_LOG_FILENAME = "pipeline-log.jsonl";
+export const HARNESS_RESEARCH_DIRNAME = "research";
+
+/** Tier 1 / Tier 2 output paths in the repo. */
+export const HARNESS_AGENTS_MD_FILENAME = "AGENTS.md";
+export const HARNESS_DOCS_DIRNAME = "docs";
+export const HARNESS_DOCS_ARCHITECTURE_FILENAME = "architecture.md";
+export const HARNESS_DOCS_GOLDEN_PRINCIPLES_FILENAME = "golden-principles.md";
+export const HARNESS_FALLOW_CONFIG_FILENAME = ".fallowrc.json";
+
+// ---------------------------------------------------------------------------
+// Internal resolution helpers.
+// ---------------------------------------------------------------------------
+
+function resolveProjectIdentityRoot(cwd: string): string {
+  return path.resolve(resolveRepoIdentityRootFromFs(cwd));
+}
+
+/**
+ * Canonical harness root: `~/.omp/supipowers/projects/<slug>/harness`.
+ */
+export function getHarnessProjectRoot(paths: PlatformPaths, cwd: string): string {
+  const repoIdentityRoot = resolveProjectIdentityRoot(cwd);
+  const slug = projectSlugFromRepoRoot(repoIdentityRoot);
+  return paths.global("projects", slug, HARNESS_DIRNAME);
+}
+
+// ---------------------------------------------------------------------------
+// Global per-project paths.
+// ---------------------------------------------------------------------------
+
+/** Project-scoped persistent slop queue (shared across worktrees). */
+export function getHarnessQueuePath(paths: PlatformPaths, cwd: string): string {
+  return path.join(getHarnessProjectRoot(paths, cwd), HARNESS_QUEUE_FILENAME);
+}
+
+/** Project-scoped score history (JSONL). */
+export function getHarnessScoreHistoryPath(paths: PlatformPaths, cwd: string): string {
+  return path.join(getHarnessProjectRoot(paths, cwd), HARNESS_SCORE_HISTORY_FILENAME);
+}
+
+/** Per-project sessions directory (parent of all per-session dirs). */
+export function getHarnessSessionsDir(paths: PlatformPaths, cwd: string): string {
+  return path.join(getHarnessProjectRoot(paths, cwd), HARNESS_SESSIONS_DIRNAME);
+}
+
+/** Per-session directory. */
+export function getHarnessSessionDir(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getHarnessSessionsDir(paths, cwd), sessionId);
+}
+
+export function getHarnessManifestPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getHarnessSessionDir(paths, cwd, sessionId), HARNESS_MANIFEST_FILENAME);
+}
+
+export function getHarnessDiscoverPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getHarnessSessionDir(paths, cwd, sessionId), HARNESS_DISCOVER_FILENAME);
+}
+
+export function getHarnessResearchDir(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getHarnessSessionDir(paths, cwd, sessionId), HARNESS_RESEARCH_DIRNAME);
+}
+
+/**
+ * Path to a single research topic markdown. Topic is sanitized for filesystem use; callers
+ * pass the already-canonical topic slug.
+ */
+export function getHarnessResearchTopicPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  topicSlug: string,
+): string {
+  return path.join(getHarnessResearchDir(paths, cwd, sessionId), `${topicSlug}.md`);
+}
+
+export function getHarnessDesignSpecPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getHarnessSessionDir(paths, cwd, sessionId), HARNESS_DESIGN_SPEC_FILENAME);
+}
+
+export function getHarnessDesignSpecJsonPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getHarnessSessionDir(paths, cwd, sessionId),
+    HARNESS_DESIGN_SPEC_JSON_FILENAME,
+  );
+}
+
+export function getHarnessDecisionsPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getHarnessSessionDir(paths, cwd, sessionId), HARNESS_DECISIONS_FILENAME);
+}
+
+export function getHarnessValidateReportPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getHarnessSessionDir(paths, cwd, sessionId),
+    HARNESS_VALIDATE_REPORT_FILENAME,
+  );
+}
+
+export function getHarnessImplementLogPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getHarnessSessionDir(paths, cwd, sessionId), HARNESS_IMPLEMENT_LOG_FILENAME);
+}
+
+export function getHarnessPipelineLogPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getHarnessSessionDir(paths, cwd, sessionId), HARNESS_PIPELINE_LOG_FILENAME);
+}
+
+// ---------------------------------------------------------------------------
+// Repo-local paths (committable subset under .omp/supipowers/harness/).
+// ---------------------------------------------------------------------------
+
+/** Repo-local harness directory: `<repo>/.omp/supipowers/harness/`. */
+export function getHarnessRepoLocalDir(paths: PlatformPaths, cwd: string): string {
+  return paths.project(cwd, "harness");
+}
+
+/** Marker file path. Presence registers the harness for this repo. */
+export function getHarnessMarkerPath(paths: PlatformPaths, cwd: string): string {
+  return path.join(getHarnessRepoLocalDir(paths, cwd), HARNESS_MARKER_FILENAME);
+}
+
+/** Repo-local score snapshot. Mirrors the global per-project score for committable artifacts. */
+export function getHarnessRepoScorePath(paths: PlatformPaths, cwd: string): string {
+  return path.join(getHarnessRepoLocalDir(paths, cwd), HARNESS_SCORE_FILENAME);
+}
+
+/** Tier 1 — repo-root AGENTS.md. */
+export function getHarnessAgentsMdPath(_paths: PlatformPaths, cwd: string): string {
+  return path.join(cwd, HARNESS_AGENTS_MD_FILENAME);
+}
+
+/** Tier 1 — repo-root docs/architecture.md. */
+export function getHarnessArchitectureDocPath(_paths: PlatformPaths, cwd: string): string {
+  return path.join(cwd, HARNESS_DOCS_DIRNAME, HARNESS_DOCS_ARCHITECTURE_FILENAME);
+}
+
+/** Tier 1 — repo-root docs/golden-principles.md. */
+export function getHarnessGoldenPrinciplesPath(_paths: PlatformPaths, cwd: string): string {
+  return path.join(cwd, HARNESS_DOCS_DIRNAME, HARNESS_DOCS_GOLDEN_PRINCIPLES_FILENAME);
+}
+
+/** Tier 1 — repo-root .fallowrc.json. */
+export function getHarnessFallowConfigPath(_paths: PlatformPaths, cwd: string): string {
+  return path.join(cwd, HARNESS_FALLOW_CONFIG_FILENAME);
+}

package/src/harness/stage-runner.ts

@@ -0,0 +1,107 @@
+/**
+ * Stage runner abstraction for the harness pipeline.
+ *
+ * Mirrors `src/ultraplan/authoring/stage-runner.ts` shape so future tooling that introspects
+ * stage state (status renderers, debug loggers) can apply the same patterns to both pipelines
+ * without case analysis. We do NOT subclass the ultraplan stage runner — both implement the
+ * same abstract `StageRunner` shape independently because the artifact paths and stage
+ * identifiers are different.
+ *
+ * Each stage:
+ *  - resolves the model + agent prompt for the stage,
+ *  - builds the assignment prompt deterministically from prior artifacts on disk,
+ *  - spawns a fresh `platform.createAgentSession` and awaits its completion,
+ *  - validates the produced artifact (TypeBox / shape check),
+ *  - transitions the session manifest atomically.
+ *
+ * Stage runners are idempotent: if `isComplete` returns true, `run` returns
+ * `status: "skipped"` without spawning an agent.
+ */
+
+import type { Platform, PlatformPaths } from "../platform/types.js";
+import type {
+  HarnessGateMode,
+  HarnessStage,
+  HarnessStageStatus,
+  ModelConfig,
+} from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface HarnessStageRunnerContext {
+  platform: Platform;
+  paths: PlatformPaths;
+  cwd: string;
+  sessionId: string;
+  /** Loaded once at the start of the pipeline; passed in for model resolution. */
+  modelConfig: ModelConfig;
+  /** Gate mode currently in effect; stages may use it to short-circuit user prompts. */
+  gateMode: HarnessGateMode;
+  /**
+   * Optional override for `now()` so tests can produce deterministic timestamps. Production
+   * code defaults to `() => new Date().toISOString()`.
+   */
+  now?: () => string;
+  /** Optional override for the agent session model. Tests use this to bypass resolution. */
+  modelOverride?: { model: string; thinkingLevel: string | null };
+}
+
+export type HarnessStageRunStatus =
+  | "completed" // Stage ran to completion and persisted its artifact.
+  | "skipped" // Pre-conditions said the stage was already done.
+  | "blocked" // Structured blocker (e.g. validation failure with no recovery).
+  | "awaiting-user" // Stage produced output but needs a user gate before advancing.
+  | "failed"; // Programming-level failure surfaced for the operator.
+
+export interface HarnessStageRunResult {
+  status: HarnessStageRunStatus;
+  stage: HarnessStage;
+  /** Artifact paths touched (relative to <session>/). */
+  artifactPaths: string[];
+  blocker?: { code: string; message: string };
+  error?: string;
+  details?: Record<string, unknown>;
+}
+
+export interface HarnessStageRunner {
+  readonly stage: HarnessStage;
+  isReady(ctx: HarnessStageRunnerContext): Promise<boolean>;
+  isComplete(ctx: HarnessStageRunnerContext): Promise<boolean>;
+  run(ctx: HarnessStageRunnerContext): Promise<HarnessStageRunResult>;
+}
+
+// ---------------------------------------------------------------------------
+// Convenience helpers
+// ---------------------------------------------------------------------------
+
+export function nowIso(ctx: HarnessStageRunnerContext): string {
+  return (ctx.now ?? (() => new Date().toISOString()))();
+}
+
+export function buildHarnessAgentDisplayName(stage: HarnessStage, discriminator?: string): string {
+  return discriminator ? `harness-${stage}/${discriminator}` : `harness-${stage}`;
+}
+
+export function toHarnessStageStatus(status: HarnessStageRunStatus): HarnessStageStatus {
+  switch (status) {
+    case "completed":
+    case "skipped":
+      return "done";
+    case "blocked":
+    case "failed":
+      return "blocked";
+    case "awaiting-user":
+      return "awaiting-user";
+  }
+}
+
+/** Generate a deterministic session id: `harness-<base36 ms>-<6-hex random>`. */
+export function newHarnessSessionId(now: () => Date = () => new Date()): string {
+  const ms = now().getTime();
+  const rand = Math.floor(Math.random() * 0xffffff)
+    .toString(16)
+    .padStart(6, "0");
+  return `harness-${ms.toString(36)}-${rand}`;
+}