@nathapp/nax 0.23.0 → 0.24.0

package/bin/nax.ts

@@ -62,6 +62,7 @@ import { generateCommand } from "../src/cli/generate";
 import { diagnose } from "../src/commands/diagnose";
 import { logsCommand } from "../src/commands/logs";
 import { precheckCommand } from "../src/commands/precheck";
+import { runsCommand } from "../src/commands/runs";
 import { unlockCommand } from "../src/commands/unlock";
 import { DEFAULT_CONFIG, findProjectDir, loadConfig, validateDirectory } from "../src/config";
 import { run } from "../src/execution";
@@ -685,7 +686,7 @@ program
   .option("-s, --story <id>", "Filter to specific story")
   .option("--level <level>", "Filter by log level (debug|info|warn|error)")
   .option("-l, --list", "List all runs in table format", false)
-  .option("-r, --run <timestamp>", "Select specific run by timestamp")
+  .option("-r, --run <runId>", "Select run by run ID from central registry (global)")
   .option("-j, --json", "Output raw JSONL", false)
   .action(async (options) => {
     let workdir: string;
@@ -773,7 +774,24 @@ program
   });
 
 // ── runs ─────────────────────────────────────────────
-const runs = program.command("runs").description("Manage and view run history");
+const runs = program
+  .command("runs")
+  .description("Show all registered runs from the central registry (~/.nax/runs/)")
+  .option("--project <name>", "Filter by project name")
+  .option("--last <N>", "Limit to N most recent runs (default: 20)")
+  .option("--status <status>", "Filter by status (running|completed|failed|crashed)")
+  .action(async (options) => {
+    try {
+      await runsCommand({
+        project: options.project,
+        last: options.last !== undefined ? Number.parseInt(options.last, 10) : undefined,
+        status: options.status,
+      });
+    } catch (err) {
+      console.error(chalk.red(`Error: ${(err as Error).message}`));
+      process.exit(1);
+    }
+  });
 
 runs
   .command("list")

package/nax/features/central-run-registry/prd.json

@@ -0,0 +1,105 @@
+{
+  "project": "nax",
+  "branchName": "feat/central-run-registry",
+  "feature": "central-run-registry",
+  "version": "0.24.0",
+  "description": "Global run index across all projects. Events file writer for machine-readable lifecycle events, registry subscriber that indexes every run to ~/.nax/runs/, nax runs CLI for cross-project run history, and nax logs --run <runId> for global log resolution.",
+  "userStories": [
+    {
+      "id": "CRR-000",
+      "title": "Events file writer subscriber",
+      "description": "New subscriber: src/pipeline/subscribers/events-writer.ts \u2014 wireEventsWriter(bus, project, feature, runId, workdir). Listens to run:started, story:started, story:completed, story:failed, run:completed, run:paused. Writes one JSON line per event to ~/.nax/events/<project>/events.jsonl (append mode). Each line: {\"ts\": ISO8601, \"event\": string, \"runId\": string, \"feature\": string, \"project\": string, \"storyId\"?: string, \"data\"?: object}. The run:completed event writes an 'on-complete' entry \u2014 the machine-readable signal that nax exited gracefully (fixes watchdog false crash reports). Best-effort: wrap all writes in try/catch, log warnings on failure, never throw or block the pipeline. Create ~/.nax/events/<project>/ on first write via mkdir recursive. Derive project name from path.basename(workdir). Wire in sequential-executor.ts alongside existing wireHooks/wireReporters/wireInteraction calls. Return UnsubscribeFn matching existing subscriber pattern.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "After a run, ~/.nax/events/<project>/events.jsonl exists with JSONL entries",
+        "Each line is valid JSON with ts, event, runId, feature, project fields",
+        "run:completed produces an entry with event=on-complete",
+        "story:started/completed/failed events include storyId",
+        "Write failure does not crash or block the nax run",
+        "Directory is created automatically on first write",
+        "wireEventsWriter is called in sequential-executor.ts",
+        "Returns UnsubscribeFn consistent with wireHooks/wireReporters pattern"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 2
+    },
+    {
+      "id": "CRR-001",
+      "title": "Registry writer subscriber",
+      "description": "New subscriber: src/pipeline/subscribers/registry.ts \u2014 wireRegistry(bus, project, feature, runId, workdir). Listens to run:started. On event, creates ~/.nax/runs/<project>-<feature>-<runId>/meta.json with fields: {runId, project, feature, workdir, statusPath: join(workdir, 'nax/features', feature, 'status.json'), eventsDir: join(workdir, 'nax/features', feature, 'runs'), registeredAt: ISO8601}. meta.json schema exported as MetaJson interface. Written once, never updated. Best-effort: try/catch + warn log, never throw/block. Create ~/.nax/runs/ directory on first call via mkdir recursive. Derive project from path.basename(workdir). Wire in sequential-executor.ts alongside wireEventsWriter. Return UnsubscribeFn.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "After run start, ~/.nax/runs/<project>-<feature>-<runId>/meta.json exists",
+        "meta.json contains runId, project, feature, workdir, statusPath, eventsDir, registeredAt",
+        "statusPath points to <workdir>/nax/features/<feature>/status.json",
+        "eventsDir points to <workdir>/nax/features/<feature>/runs",
+        "MetaJson interface is exported from the module",
+        "Write failure does not crash or block the nax run",
+        "wireRegistry is called in sequential-executor.ts"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 2
+    },
+    {
+      "id": "CRR-002",
+      "title": "nax runs CLI command",
+      "description": "New command: src/commands/runs.ts \u2014 runsCommand(options). Reads all ~/.nax/runs/*/meta.json, resolves each statusPath to read the live NaxStatusFile for current state. Displays a table sorted by registeredAt desc. Columns: RUN ID, PROJECT, FEATURE, STATUS, STORIES (passed/total), DURATION, DATE. Default limit: 20. Options: --project <name> (filter), --last <N> (limit), --status <running|completed|failed|crashed> (filter). If statusPath missing, show status as '[unavailable]'. Register in src/commands/index.ts and wire in bin/nax.ts CLI arg parser (match pattern of existing diagnose/logs/status commands). Use chalk for colored output. Green for completed, red for failed, yellow for running, dim for unavailable.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "nax runs displays a table of all registered runs sorted newest-first",
+        "nax runs --project <name> filters by project name",
+        "nax runs --last <N> limits output to N runs",
+        "nax runs --status <status> filters by run status",
+        "Runs with missing statusPath show '[unavailable]' status gracefully",
+        "Empty registry shows 'No runs found' message",
+        "Command is registered in CLI help output and bin/nax.ts"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [
+        "CRR-001"
+      ],
+      "tags": [],
+      "storyPoints": 3
+    },
+    {
+      "id": "CRR-003",
+      "title": "nax logs --run <runId> global resolution",
+      "description": "Enhance src/commands/logs.ts logsCommand: when --run <runId> is provided, scan ~/.nax/runs/*/meta.json for matching runId (exact or prefix match). Read eventsDir from meta.json, locate the JSONL log file in that directory (newest .jsonl file), then display using existing displayLogs/followLogs functions. Falls back to current behavior (local feature context) when --run is not specified. If runId not found in registry, throw error Run not found in registry: <runId>. If eventsDir or log file missing, show unavailable message. Update LogsOptions interface to accept run?: string. Update bin/nax.ts to pass --run option through.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "nax logs --run <runId> displays logs from the matching run regardless of cwd",
+        "Resolution uses ~/.nax/runs/*/meta.json to find eventsDir path",
+        "Unknown runId shows clear error message",
+        "Missing log files show unavailable message",
+        "Without --run flag, existing local behavior is unchanged",
+        "Partial runId matching works (prefix match on runId field)"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [
+        "CRR-001"
+      ],
+      "tags": [],
+      "storyPoints": 2
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.23.0",
-  "description": "AI Coding Agent Orchestrator — loops until done",
+  "version": "0.24.0",
+  "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
     "nax": "./bin/nax.ts"

package/src/commands/index.ts

@@ -5,4 +5,5 @@
 export { resolveProject, type ResolveProjectOptions, type ResolvedProject } from "./common";
 export { logsCommand, type LogsOptions } from "./logs";
 export { precheckCommand, type PrecheckOptions } from "./precheck";
+export { runsCommand, type RunsOptions } from "./runs";
 export { unlockCommand, type UnlockOptions } from "./unlock";

package/src/commands/logs.ts

@@ -6,13 +6,23 @@
  */
 
 import { existsSync, readdirSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import chalk from "chalk";
 import type { LogEntry, LogLevel } from "../logger/types";
 import { type FormattedEntry, formatLogEntry, formatRunSummary } from "../logging/formatter";
 import type { RunSummary, VerbosityMode } from "../logging/types";
+import type { MetaJson } from "../pipeline/subscribers/registry";
 import { type ResolveProjectOptions, resolveProject } from "./common";
 
+/**
+ * Swappable dependencies for testing (project convention: _deps over mock.module).
+ */
+export const _deps = {
+  getRunsDir: () => process.env.NAX_RUNS_DIR ?? join(homedir(), ".nax", "runs"),
+};
+
 /**
  * Options for logs command
  */
@@ -43,12 +53,84 @@ const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
   error: 3,
 };
 
+/**
+ * Resolve log file path for a runId from the central registry (~/.nax/runs/).
+ *
+ * Scans all ~/.nax/runs/*\/meta.json entries for an exact or prefix match on runId.
+ * Returns the path to the matching run's JSONL file, or null if eventsDir/file is unavailable.
+ * Throws if the runId is not found in the registry at all.
+ *
+ * @param runId - Full or prefix run ID to look up
+ * @returns Absolute path to the JSONL log file, or null if unavailable
+ */
+async function resolveRunFileFromRegistry(runId: string): Promise<string | null> {
+  const runsDir = _deps.getRunsDir();
+
+  let entries: string[];
+  try {
+    entries = await readdir(runsDir);
+  } catch {
+    throw new Error(`Run not found in registry: ${runId}`);
+  }
+
+  let matched: MetaJson | null = null;
+  for (const entry of entries) {
+    const metaPath = join(runsDir, entry, "meta.json");
+    try {
+      const meta: MetaJson = await Bun.file(metaPath).json();
+      if (meta.runId === runId || meta.runId.startsWith(runId)) {
+        matched = meta;
+        break;
+      }
+    } catch {
+      // skip unreadable meta.json entries
+    }
+  }
+
+  if (!matched) {
+    throw new Error(`Run not found in registry: ${runId}`);
+  }
+
+  if (!existsSync(matched.eventsDir)) {
+    console.log(`Log directory unavailable for run: ${runId}`);
+    return null;
+  }
+
+  const files = readdirSync(matched.eventsDir)
+    .filter((f) => f.endsWith(".jsonl") && f !== "latest.jsonl")
+    .sort()
+    .reverse();
+
+  if (files.length === 0) {
+    console.log(`No log files found for run: ${runId}`);
+    return null;
+  }
+
+  // Look for the specific run file by runId, fall back to newest
+  const specificFile = files.find((f) => f === `${matched.runId}.jsonl`);
+  return join(matched.eventsDir, specificFile ?? files[0]);
+}
+
 /**
  * Display logs with filtering and formatting
  *
  * @param options - Command options
  */
 export async function logsCommand(options: LogsOptions): Promise<void> {
+  // When --run <runId> is provided, resolve via central registry
+  if (options.run) {
+    const runFile = await resolveRunFileFromRegistry(options.run);
+    if (!runFile) {
+      return;
+    }
+    if (options.follow) {
+      await followLogs(runFile, options);
+    } else {
+      await displayLogs(runFile, options);
+    }
+    return;
+  }
+
   // Resolve project directory
   const resolved = resolveProject({ dir: options.dir });
   const naxDir = join(resolved.projectDir, "nax");
@@ -77,8 +159,8 @@ export async function logsCommand(options: LogsOptions): Promise<void> {
     return;
   }
 
-  // Determine which run to display
-  const runFile = await selectRunFile(runsDir, options.run);
+  // Determine which run to display (latest by default — --run handled above via registry)
+  const runFile = await selectRunFile(runsDir);
 
   if (!runFile) {
     throw new Error("No runs found for this feature");
@@ -95,9 +177,9 @@ export async function logsCommand(options: LogsOptions): Promise<void> {
 }
 
 /**
- * Select which run file to display
+ * Select which run file to display (always returns the latest run)
  */
-async function selectRunFile(runsDir: string, runTimestamp?: string): Promise<string | null> {
+async function selectRunFile(runsDir: string): Promise<string | null> {
   const files = readdirSync(runsDir)
     .filter((f) => f.endsWith(".jsonl") && f !== "latest.jsonl")
     .sort()
@@ -107,19 +189,7 @@ async function selectRunFile(runsDir: string, runTimestamp?: string): Promise<st
     return null;
   }
 
-  // If no specific run requested, use latest
-  if (!runTimestamp) {
-    return join(runsDir, files[0]);
-  }
-
-  // Find matching run by partial timestamp
-  const matchingFile = files.find((f) => f.startsWith(runTimestamp));
-
-  if (!matchingFile) {
-    throw new Error(`Run not found: ${runTimestamp}`);
-  }
-
-  return join(runsDir, matchingFile);
+  return join(runsDir, files[0]);
 }
 
 /**

package/src/commands/runs.ts

@@ -0,0 +1,220 @@
+/**
+ * Runs Command
+ *
+ * Reads all ~/.nax/runs/*\/meta.json entries and displays a table of runs
+ * sorted by registeredAt descending. Resolves each statusPath to read the
+ * live NaxStatusFile for current state. Falls back to '[unavailable]' if
+ * the status file is missing or unreadable.
+ *
+ * Usage:
+ *   nax runs [--project <name>] [--last <N>] [--status <status>]
+ */
+
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import chalk from "chalk";
+import type { NaxStatusFile } from "../execution/status-file";
+import type { MetaJson } from "../pipeline/subscribers/registry";
+
+const DEFAULT_LIMIT = 20;
+
+/**
+ * Swappable dependencies for testing (project convention: _deps over mock.module).
+ */
+export const _deps = {
+  getRunsDir: () => join(homedir(), ".nax", "runs"),
+};
+
+export interface RunsOptions {
+  /** Filter by project name */
+  project?: string;
+  /** Limit number of runs displayed (default: 20) */
+  last?: number;
+  /** Filter by run status */
+  status?: "running" | "completed" | "failed" | "crashed";
+}
+
+interface RunRow {
+  runId: string;
+  project: string;
+  feature: string;
+  status: string;
+  passed: number;
+  total: number;
+  durationMs: number;
+  registeredAt: string;
+}
+
+/**
+ * Format duration in milliseconds to human-readable string.
+ */
+function formatDuration(ms: number): string {
+  if (ms <= 0) return "-";
+  const minutes = Math.floor(ms / 60000);
+  const seconds = Math.floor((ms % 60000) / 1000);
+  if (minutes === 0) return `${seconds}s`;
+  return `${minutes}m ${seconds}s`;
+}
+
+/**
+ * Format ISO date to short local date string.
+ */
+function formatDate(iso: string): string {
+  try {
+    const d = new Date(iso);
+    return d.toLocaleDateString(undefined, { month: "short", day: "numeric", year: "numeric" });
+  } catch {
+    return iso;
+  }
+}
+
+/**
+ * Color a status string for terminal output.
+ */
+function colorStatus(status: string): string {
+  switch (status) {
+    case "completed":
+      return chalk.green(status);
+    case "failed":
+      return chalk.red(status);
+    case "running":
+      return chalk.yellow(status);
+    case "[unavailable]":
+      return chalk.dim(status);
+    default:
+      return chalk.dim(status);
+  }
+}
+
+/** Regex that matches ANSI escape sequences. */
+const ANSI_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+
+/** Strip ANSI escape codes to compute visible string length. */
+function visibleLength(str: string): number {
+  return str.replace(ANSI_RE, "").length;
+}
+
+/**
+ * Pad a string to a fixed width (left-aligned).
+ */
+function pad(str: string, width: number): string {
+  const padding = Math.max(0, width - visibleLength(str));
+  return str + " ".repeat(padding);
+}
+
+/**
+ * Display all registered runs from ~/.nax/runs/ as a table.
+ *
+ * @param options - Filter and limit options
+ */
+export async function runsCommand(options: RunsOptions = {}): Promise<void> {
+  const runsDir = _deps.getRunsDir();
+
+  let entries: string[];
+  try {
+    entries = await readdir(runsDir);
+  } catch {
+    console.log("No runs found.");
+    return;
+  }
+
+  const rows: RunRow[] = [];
+
+  for (const entry of entries) {
+    const metaPath = join(runsDir, entry, "meta.json");
+    let meta: MetaJson;
+    try {
+      meta = await Bun.file(metaPath).json();
+    } catch {
+      continue;
+    }
+
+    // Apply project filter early
+    if (options.project && meta.project !== options.project) continue;
+
+    // Read live status file
+    let statusData: NaxStatusFile | null = null;
+    try {
+      statusData = await Bun.file(meta.statusPath).json();
+    } catch {
+      // statusPath missing or unreadable — handled gracefully below
+    }
+
+    const runStatus = statusData ? statusData.run.status : "[unavailable]";
+
+    // Apply status filter
+    if (options.status && runStatus !== options.status) continue;
+
+    rows.push({
+      runId: meta.runId,
+      project: meta.project,
+      feature: meta.feature,
+      status: runStatus,
+      passed: statusData?.progress.passed ?? 0,
+      total: statusData?.progress.total ?? 0,
+      durationMs: statusData?.durationMs ?? 0,
+      registeredAt: meta.registeredAt,
+    });
+  }
+
+  // Sort newest first
+  rows.sort((a, b) => new Date(b.registeredAt).getTime() - new Date(a.registeredAt).getTime());
+
+  // Apply limit
+  const limit = options.last ?? DEFAULT_LIMIT;
+  const displayed = rows.slice(0, limit);
+
+  if (displayed.length === 0) {
+    console.log("No runs found.");
+    return;
+  }
+
+  // Column widths (minimum per header)
+  const COL = {
+    runId: Math.max(6, ...displayed.map((r) => r.runId.length)),
+    project: Math.max(7, ...displayed.map((r) => r.project.length)),
+    feature: Math.max(7, ...displayed.map((r) => r.feature.length)),
+    status: Math.max(6, ...displayed.map((r) => visibleLength(r.status))),
+    stories: 7,
+    duration: 8,
+    date: 11,
+  };
+
+  // Header
+  const header = [
+    pad(chalk.bold("RUN ID"), COL.runId),
+    pad(chalk.bold("PROJECT"), COL.project),
+    pad(chalk.bold("FEATURE"), COL.feature),
+    pad(chalk.bold("STATUS"), COL.status),
+    pad(chalk.bold("STORIES"), COL.stories),
+    pad(chalk.bold("DURATION"), COL.duration),
+    chalk.bold("DATE"),
+  ].join("  ");
+
+  console.log();
+  console.log(header);
+  console.log(
+    chalk.dim("-".repeat(COL.runId + COL.project + COL.feature + COL.status + COL.stories + COL.duration + 11 + 12)),
+  );
+
+  for (const row of displayed) {
+    const colored = colorStatus(row.status);
+    const line = [
+      pad(row.runId, COL.runId),
+      pad(row.project, COL.project),
+      pad(row.feature, COL.feature),
+      pad(colored, COL.status + (colored.length - visibleLength(colored))),
+      pad(`${row.passed}/${row.total}`, COL.stories),
+      pad(formatDuration(row.durationMs), COL.duration),
+      formatDate(row.registeredAt),
+    ].join("  ");
+    console.log(line);
+  }
+
+  console.log();
+  if (rows.length > limit) {
+    console.log(chalk.dim(`Showing ${limit} of ${rows.length} runs. Use --last <N> to see more.`));
+    console.log();
+  }
+}

package/src/execution/sequential-executor.ts

@@ -5,8 +5,10 @@ import type { StoryMetrics } from "../metrics";
 import { pipelineEventBus } from "../pipeline/event-bus";
 import { runPipeline } from "../pipeline/runner";
 import { postRunPipeline } from "../pipeline/stages";
+import { wireEventsWriter } from "../pipeline/subscribers/events-writer";
 import { wireHooks } from "../pipeline/subscribers/hooks";
 import { wireInteraction } from "../pipeline/subscribers/interaction";
+import { wireRegistry } from "../pipeline/subscribers/registry";
 import { wireReporters } from "../pipeline/subscribers/reporters";
 import type { PipelineContext } from "../pipeline/types";
 import { generateHumanHaltSummary, isComplete, isStalled, loadPRD } from "../prd";
@@ -38,6 +40,8 @@ export async function executeSequential(
   wireHooks(pipelineEventBus, ctx.hooks, ctx.workdir, ctx.feature);
   wireReporters(pipelineEventBus, ctx.pluginRegistry, ctx.runId, ctx.startTime);
   wireInteraction(pipelineEventBus, ctx.interactionChain, ctx.config);
+  wireEventsWriter(pipelineEventBus, ctx.feature, ctx.runId, ctx.workdir);
+  wireRegistry(pipelineEventBus, ctx.feature, ctx.runId, ctx.workdir);
 
   const buildResult = (exitReason: SequentialExecutionResult["exitReason"]): SequentialExecutionResult => ({
     prd,

package/src/pipeline/subscribers/events-writer.ts

@@ -0,0 +1,121 @@
+/**
+ * Events Writer Subscriber
+ *
+ * Appends one JSON line per pipeline lifecycle event to
+ * ~/.nax/events/<project>/events.jsonl. Provides a machine-readable
+ * signal that nax exited gracefully (run:completed → event=on-complete),
+ * fixing watchdog false crash reports.
+ *
+ * Design:
+ * - Best-effort: all writes are wrapped in try/catch; never throws or blocks
+ * - Directory is created on first write via mkdir recursive
+ * - Returns UnsubscribeFn matching wireHooks/wireReporters pattern
+ */
+
+import { appendFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { getSafeLogger } from "../../logger";
+import type { PipelineEventBus } from "../event-bus";
+import type { UnsubscribeFn } from "./hooks";
+
+interface EventLine {
+  ts: string;
+  event: string;
+  runId: string;
+  feature: string;
+  project: string;
+  storyId?: string;
+  data?: object;
+}
+
+/**
+ * Wire events file writer to the pipeline event bus.
+ *
+ * Listens to run:started, story:started, story:completed, story:failed,
+ * run:completed, run:paused and appends one JSONL entry per event.
+ *
+ * @param bus     - The pipeline event bus
+ * @param feature - Feature name
+ * @param runId   - Current run ID
+ * @param workdir - Working directory (project name derived via basename)
+ * @returns Unsubscribe function
+ */
+export function wireEventsWriter(
+  bus: PipelineEventBus,
+  feature: string,
+  runId: string,
+  workdir: string,
+): UnsubscribeFn {
+  const logger = getSafeLogger();
+  const project = basename(workdir);
+  const eventsDir = join(homedir(), ".nax", "events", project);
+  const eventsFile = join(eventsDir, "events.jsonl");
+  let dirReady = false;
+
+  const write = (line: EventLine): void => {
+    (async () => {
+      try {
+        if (!dirReady) {
+          await mkdir(eventsDir, { recursive: true });
+          dirReady = true;
+        }
+        await appendFile(eventsFile, `${JSON.stringify(line)}\n`);
+      } catch (err) {
+        logger?.warn("events-writer", "Failed to write event line (non-fatal)", {
+          event: line.event,
+          error: String(err),
+        });
+      }
+    })();
+  };
+
+  const unsubs: UnsubscribeFn[] = [];
+
+  unsubs.push(
+    bus.on("run:started", (_ev) => {
+      write({ ts: new Date().toISOString(), event: "run:started", runId, feature, project });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("story:started", (ev) => {
+      write({ ts: new Date().toISOString(), event: "story:started", runId, feature, project, storyId: ev.storyId });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("story:completed", (ev) => {
+      write({ ts: new Date().toISOString(), event: "story:completed", runId, feature, project, storyId: ev.storyId });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("story:failed", (ev) => {
+      write({ ts: new Date().toISOString(), event: "story:failed", runId, feature, project, storyId: ev.storyId });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("run:completed", (_ev) => {
+      write({ ts: new Date().toISOString(), event: "on-complete", runId, feature, project });
+    }),
+  );
+
+  unsubs.push(
+    bus.on("run:paused", (ev) => {
+      write({
+        ts: new Date().toISOString(),
+        event: "run:paused",
+        runId,
+        feature,
+        project,
+        ...(ev.storyId !== undefined && { storyId: ev.storyId }),
+      });
+    }),
+  );
+
+  return () => {
+    for (const u of unsubs) u();
+  };
+}