@databricks-solutions/lakebase-scm-utils 0.3.6 → 0.3.8

package/scripts/lakebase/scm-abandon-feature.ts

@@ -13,28 +13,19 @@
 // completes the state reset.
 
 import { deletePairedBranch } from "./paired-branch.js";
-import { getCurrentBranch } from "../git/inspect.js";
-import { isDirty } from "../git/status.js";
-import { exec } from "../util/exec.js";
+import { type ScmWorkflowState } from "./scm-workflow-state.js";
 import {
-  readWorkflowState,
-  writeWorkflowState,
-  type ScmWorkflowState,
-} from "./scm-workflow-state.js";
+  ScmReleaseError,
+  prepareClaimRelease,
+  resetToScaffoldComplete,
+} from "./scm-release-claim.js";
 
-export class ScmAbandonError extends Error {
-  constructor(
-    message: string,
-    public readonly code:
-      | "no-state-file"
-      | "bad-precondition"
-      | "dirty-working-tree"
-      | "missing-claim-fields",
-  ) {
-    super(message);
-    this.name = "ScmAbandonError";
-  }
-}
+export { ScmReleaseError };
+
+/** Back-compat alias: abandon historically threw its own error class. It is now a subclass of the
+ *  shared `ScmReleaseError` so existing `instanceof ScmAbandonError` checks still narrow, while the
+ *  shared release core (which both abandon and park use) throws the base. */
+export class ScmAbandonError extends ScmReleaseError {}
 
 export interface AbandonFeatureArgs {
   projectDir: string;
@@ -64,76 +55,21 @@ export interface AbandonFeatureResult {
 export async function abandonFeatureBranch(
   args: AbandonFeatureArgs,
 ): Promise<AbandonFeatureResult> {
-  const current = readWorkflowState(args.projectDir);
-  if (!current) {
-    throw new ScmAbandonError(
-      `No SCM workflow state found at ${args.projectDir}/.lakebase/workflow-state.json.`,
-      "no-state-file",
-    );
-  }
-  if (current.state !== "feature-claimed") {
-    throw new ScmAbandonError(
-      `abandon refuses state "${current.state}". Only feature-claimed is abandonable; later states must complete or be reverted via gh.`,
-      "bad-precondition",
-    );
-  }
-  if (
-    !current.feature_id ||
-    !current.branch ||
-    !current.parent_branch ||
-    !current.lakebase_branch_uid
-  ) {
-    throw new ScmAbandonError(
-      "feature-claimed row is missing required invariants. Cannot abandon safely; consider re-adopting state first.",
-      "missing-claim-fields",
-    );
-  }
-
-  if (!args.force) {
-    const dirty = await isDirty({ cwd: args.projectDir });
-    if (dirty) {
-      throw new ScmAbandonError(
-        "Working tree has uncommitted changes; refusing to abandon (the branch delete would lose them). Commit / stash / discard first, or pass --force.",
-        "dirty-working-tree",
-      );
-    }
-  }
-
-  const instance = args.instance ?? current.project_id;
-  const switchTo = args.switchTo ?? current.parent_branch;
-  const warnings: string[] = [];
-
-  // Switch HEAD off the feature branch first so deletePairedBranch can
-  // delete the local git branch (it skips when the branch is checked out).
-  const headBranch = await getCurrentBranch({ cwd: args.projectDir });
-  if (headBranch === current.branch) {
-    try {
-      await exec(`git checkout ${JSON.stringify(switchTo)}`, {
-        cwd: args.projectDir,
-        timeout: 10_000,
-      });
-    } catch (err) {
-      warnings.push(
-        `git checkout ${switchTo} failed: ${err instanceof Error ? err.message : String(err)}. Local branch delete may be skipped.`,
-      );
-    }
-  }
+  // Shared preamble: validate the claim is releasable + switch HEAD off the feature branch.
+  const { current, warnings } = await prepareClaimRelease(
+    { projectDir: args.projectDir, force: args.force, switchTo: args.switchTo },
+    "abandon",
+  );
 
+  // Abandon's distinguishing step: tear down the paired Lakebase + git branch.
   const del = await deletePairedBranch({
-    instance,
+    instance: args.instance ?? current.project_id,
     branch: current.branch,
     cwd: args.projectDir,
   });
   warnings.push(...del.warnings);
 
-  const reset: ScmWorkflowState = {
-    $schema: current.$schema,
-    version: 1,
-    state: "scaffold-complete",
-    tier_topology: current.tier_topology,
-    project_id: current.project_id,
-  };
-  writeWorkflowState(args.projectDir, reset);
+  const reset: ScmWorkflowState = resetToScaffoldComplete(args.projectDir, current);
 
   return {
     state: reset,

package/scripts/lakebase/scm-park-feature.cli.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// CLI: park the in-flight feature claim (free it, KEEP the branch) and reset to scaffold-complete.
+// The resume-later counterpart to abandon. phase B+.
+
+import * as path from "node:path";
+import { isCliEntry } from "../util/cli-entry.js";
+import { ScmReleaseError } from "./scm-release-claim.js";
+import {
+  parkFeatureBranch,
+  type ParkFeatureResult,
+} from "./scm-park-feature.js";
+
+interface ParsedArgs {
+  projectDir?: string;
+  switchTo?: string;
+  force?: boolean;
+  json?: boolean;
+  pretty?: boolean;
+  help?: boolean;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const out: ParsedArgs = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--project-dir":
+      case "--cwd":
+        out.projectDir = argv[++i];
+        break;
+      case "--switch-to":
+        out.switchTo = argv[++i];
+        break;
+      case "--force":
+        out.force = true;
+        break;
+      case "--json":
+        out.json = true;
+        break;
+      case "--pretty":
+        out.pretty = true;
+        break;
+      case "--help":
+      case "-h":
+        out.help = true;
+        break;
+    }
+  }
+  return out;
+}
+
+const HELP = `lakebase-scm-park-feature (phase B+)
+
+Release a feature claim but KEEP its paired branch: switch HEAD to the parent
+tier, reset workflow-state to scaffold-complete, leave the Lakebase + git
+branch intact. Frees the single SCM claim so another feature can be claimed
+and driven; resume the parked feature later with
+'lakebase-scm-claim-feature-branch <feature>' (it reuses the kept branch).
+
+Usage:
+  lakebase-scm-park-feature [flags]
+
+Flags:
+  --project-dir <dir>   Project root (default: cwd)
+  --switch-to <branch>  Branch to checkout after releasing (default: parent_branch)
+  --force               Allow park even with a dirty working tree
+                        (edits are kept but stranded on the feature branch)
+  --json                Machine-readable JSON output
+  --pretty              Pretty-print JSON (only with --json)
+  -h, --help            Show this help
+
+Exit codes:
+  0 = parked (claim freed, branch kept, state reset to scaffold-complete)
+  1 = no state file
+  2 = precondition refused (wrong state, dirty tree without --force, missing fields)
+  3 = substrate failure
+`;
+
+interface ParkReport {
+  ok: boolean;
+  result?: ParkFeatureResult;
+  error?: { code: string; message: string };
+}
+
+function renderHuman(report: ParkReport): string {
+  if (!report.ok) {
+    return `lakebase-scm-park-feature: ${report.error?.code}\n\n  ${report.error?.message}`;
+  }
+  const r = report.result!;
+  const lines: string[] = ["Feature parked (branch kept):"];
+  lines.push(`  state          : ${r.state.state}`);
+  lines.push(`  parked_feature : ${r.parkedFeatureId}`);
+  lines.push(`  kept_branch    : ${r.keptBranch}`);
+  lines.push(`  switched_to    : ${r.switchedTo}`);
+  lines.push("");
+  lines.push(`  resume with    : lakebase-scm-claim-feature-branch ${r.parkedFeatureId}`);
+  if (r.warnings.length > 0) {
+    lines.push("");
+    lines.push("warnings:");
+    for (const w of r.warnings) lines.push(`  - ${w}`);
+  }
+  return lines.join("\n");
+}
+
+function exitCodeForError(err: Error): number {
+  if (err instanceof ScmReleaseError) {
+    if (err.code === "no-state-file") return 1;
+    return 2;
+  }
+  return 3;
+}
+
+export async function runScmParkFeatureCli(argv: string[]): Promise<number> {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(`${HELP}\n`);
+    return 0;
+  }
+  const projectDir = path.resolve(args.projectDir ?? process.cwd());
+  try {
+    const result = await parkFeatureBranch({
+      projectDir,
+      switchTo: args.switchTo,
+      force: args.force,
+    });
+    const report: ParkReport = { ok: true, result };
+    if (args.json) {
+      const indent = args.pretty ? 2 : 0;
+      process.stdout.write(`${JSON.stringify(report, null, indent)}\n`);
+    } else {
+      process.stdout.write(`${renderHuman(report)}\n`);
+    }
+    return 0;
+  } catch (e) {
+    const err = e as Error;
+    const code = err instanceof ScmReleaseError ? err.code : "substrate-failure";
+    const report: ParkReport = { ok: false, error: { code, message: err.message } };
+    if (args.json) {
+      const indent = args.pretty ? 2 : 0;
+      process.stdout.write(`${JSON.stringify(report, null, indent)}\n`);
+    } else {
+      process.stderr.write(`${renderHuman(report)}\n`);
+    }
+    return exitCodeForError(err);
+  }
+}
+
+if (isCliEntry(import.meta.url)) {
+  void runScmParkFeatureCli(process.argv.slice(2)).then((c) => process.exit(c));
+}

package/scripts/lakebase/scm-park-feature.ts

@@ -0,0 +1,71 @@
+// SCM workflow park (phase B+): release a feature claim WITHOUT tearing down the branch.
+//
+// Transitions feature-claimed -> scaffold-complete and switches HEAD to the parent tier, but — unlike
+// abandon — KEEPS the paired Lakebase + git branch intact. This frees the single SCM claim so another
+// feature can be claimed and driven, while the parked feature's work sits safely on its branch. The
+// claim model makes RESUMING free: `lakebase-scm-claim-feature-branch <same-feature>` re-claims from
+// scaffold-complete and `createFeaturePairedBranch` reuses the existing paired branch as-is (DB and
+// all), picking the feature back up where it stopped.
+//
+// Use when a feature is built but NOT yet deployed/merged and you want to shelve it and go work on
+// another. (Abandon is the throwaway counterpart: it deletes the branch.) Refuses on a dirty working
+// tree by default (switching HEAD would strand uncommitted edits) unless --force.
+//
+// The preamble (precondition + dirty-guard + HEAD switch) and the scaffold-complete reset are the
+// shared release core in scm-release-claim.ts, so park and abandon cannot drift.
+
+import { type ScmWorkflowState } from "./scm-workflow-state.js";
+import {
+  ScmReleaseError,
+  prepareClaimRelease,
+  resetToScaffoldComplete,
+} from "./scm-release-claim.js";
+
+export { ScmReleaseError };
+
+export interface ParkFeatureArgs {
+  /** Project root (must contain .lakebase/workflow-state.json + .git/). */
+  projectDir: string;
+  /**
+   * Skip the dirty-working-tree refusal. Uncommitted edits are NOT lost (the branch is kept), but
+   * switching HEAD off the feature branch would leave them stranded on it, so the default refuses.
+   */
+  force?: boolean;
+  /**
+   * Switch HEAD to this branch after releasing the claim. Defaults to the workflow row's
+   * parent_branch (the tier the feature forked from).
+   */
+  switchTo?: string;
+}
+
+export interface ParkFeatureResult {
+  state: ScmWorkflowState;
+  /** The branch left intact (git name) — resume with `lakebase-scm-claim-feature-branch`. */
+  keptBranch: string;
+  /** The feature id that was parked (for logging / the consort bookkeeping repoint). */
+  parkedFeatureId: string;
+  switchedTo: string;
+  warnings: string[];
+}
+
+export async function parkFeatureBranch(
+  args: ParkFeatureArgs,
+): Promise<ParkFeatureResult> {
+  // Shared preamble: validate the claim is releasable + switch HEAD off the feature branch.
+  const { current, switchTo, warnings } = await prepareClaimRelease(
+    { projectDir: args.projectDir, force: args.force, switchTo: args.switchTo },
+    "park",
+  );
+
+  // Park's distinguishing (non-)step: the paired branch is DELIBERATELY left in place — this is the
+  // whole point. Just reset the claim row so the next feature can be claimed.
+  const reset = resetToScaffoldComplete(args.projectDir, current);
+
+  return {
+    state: reset,
+    keptBranch: current.branch,
+    parkedFeatureId: current.feature_id,
+    switchedTo: switchTo,
+    warnings,
+  };
+}

package/scripts/lakebase/scm-release-claim.ts

@@ -0,0 +1,146 @@
+// Shared core for the two ways to RELEASE an in-flight feature claim back to scaffold-complete:
+//   - abandon (scm-abandon-feature): free the claim AND tear down the paired branch.
+//   - park    (scm-park-feature):    free the claim but KEEP the paired branch, so the feature can
+//                                     be resumed later (a re-claim reuses the existing branch as-is).
+//
+// Both share the exact same preamble — read state, require feature-claimed, require the claim's
+// invariants, refuse a dirty tree (switching HEAD or deleting the branch would strand uncommitted
+// work) unless --force, then switch HEAD off the feature branch — and the exact same tail: reset the
+// workflow-state row to a bare scaffold-complete. The ONLY difference is whether the paired branch is
+// deleted in between. Factored here so the two commands cannot drift (DRY); each command owns only its
+// middle step and its own CLI surface.
+
+import { getCurrentBranch } from "../git/inspect.js";
+import { isDirty } from "../git/status.js";
+import { exec } from "../util/exec.js";
+import {
+  readWorkflowState,
+  writeWorkflowState,
+  type ScmWorkflowState,
+} from "./scm-workflow-state.js";
+
+export type ScmReleaseErrorCode =
+  | "no-state-file"
+  | "bad-precondition"
+  | "dirty-working-tree"
+  | "missing-claim-fields";
+
+/** The shared error for a claim release. `abandon` keeps its own `ScmAbandonError` as a subclass for
+ *  back-compat; CLIs that map codes to exit statuses check `instanceof ScmReleaseError` (the base). */
+export class ScmReleaseError extends Error {
+  constructor(
+    message: string,
+    public readonly code: ScmReleaseErrorCode,
+  ) {
+    super(message);
+    this.name = "ScmReleaseError";
+  }
+}
+
+export interface ReleaseClaimArgs {
+  /** Project root (must contain .lakebase/workflow-state.json + .git/). */
+  projectDir: string;
+  /** Skip the dirty-working-tree refusal. */
+  force?: boolean;
+  /** Branch to checkout before releasing. Defaults to the workflow row's parent_branch. */
+  switchTo?: string;
+}
+
+/** A feature-claimed row with its claim invariants proven present, plus the resolved HEAD target. */
+export interface PreparedRelease {
+  current: ScmWorkflowState & {
+    feature_id: string;
+    branch: string;
+    parent_branch: string;
+    lakebase_branch_uid: string;
+  };
+  switchTo: string;
+  warnings: string[];
+}
+
+/**
+ * The shared preamble for abandon + park: validate the claim is releasable and switch HEAD off the
+ * feature branch so the next step (delete, or just reset) is safe. `verb` ("abandon" | "park") only
+ * shapes the human-facing refusal messages. Throws `ScmReleaseError` on any precondition failure.
+ */
+export async function prepareClaimRelease(
+  args: ReleaseClaimArgs,
+  verb: "abandon" | "park",
+): Promise<PreparedRelease> {
+  const current = readWorkflowState(args.projectDir);
+  if (!current) {
+    throw new ScmReleaseError(
+      `No SCM workflow state found at ${args.projectDir}/.lakebase/workflow-state.json.`,
+      "no-state-file",
+    );
+  }
+  if (current.state !== "feature-claimed") {
+    throw new ScmReleaseError(
+      `${verb} refuses state "${current.state}". Only feature-claimed is ${verb}able; later states must complete or be reverted via gh.`,
+      "bad-precondition",
+    );
+  }
+  if (
+    !current.feature_id ||
+    !current.branch ||
+    !current.parent_branch ||
+    !current.lakebase_branch_uid
+  ) {
+    throw new ScmReleaseError(
+      `feature-claimed row is missing required invariants. Cannot ${verb} safely; consider re-adopting state first.`,
+      "missing-claim-fields",
+    );
+  }
+
+  if (!args.force) {
+    const dirty = await isDirty({ cwd: args.projectDir });
+    if (dirty) {
+      throw new ScmReleaseError(
+        `Working tree has uncommitted changes; refusing to ${verb} (switching HEAD off the feature branch would strand them). Commit / stash / discard first, or pass --force.`,
+        "dirty-working-tree",
+      );
+    }
+  }
+
+  const switchTo = args.switchTo ?? current.parent_branch;
+  const warnings: string[] = [];
+
+  // Switch HEAD off the feature branch first: abandon needs it so the local git branch can be
+  // deleted (delete skips a checked-out branch); park needs it so the tree sits on the tier, ready
+  // for the next claim. Best-effort — a checkout failure is a warning, not a hard stop.
+  const headBranch = await getCurrentBranch({ cwd: args.projectDir });
+  if (headBranch === current.branch) {
+    try {
+      await exec(`git checkout ${JSON.stringify(switchTo)}`, {
+        cwd: args.projectDir,
+        timeout: 10_000,
+      });
+    } catch (err) {
+      warnings.push(
+        `git checkout ${switchTo} failed: ${err instanceof Error ? err.message : String(err)}. Local branch state may be left on the feature branch.`,
+      );
+    }
+  }
+
+  return { current: current as PreparedRelease["current"], switchTo, warnings };
+}
+
+/**
+ * Reset the workflow-state row to a bare scaffold-complete (no feature in flight), preserving only
+ * the project-scoped facts (tier topology, project id). The shared tail of both abandon and park:
+ * after this the next claim can proceed.
+ */
+export function resetToScaffoldComplete(
+  projectDir: string,
+  current: ScmWorkflowState,
+): ScmWorkflowState {
+  const reset: ScmWorkflowState = {
+    $schema: current.$schema,
+    version: 1,
+    state: "scaffold-complete",
+    tier_topology: current.tier_topology,
+    project_id: current.project_id,
+  };
+  writeWorkflowState(projectDir, reset);
+  return reset;
+}

package/templates/project/common/consort-capture.ts

@@ -9,8 +9,8 @@
 // the client's bundler-resolution tsconfig. Importing these from here keeps the client Playwright-free.
 //
 // Pure observability: everything is wrapped so a write can NEVER fail a test/suite.
-import { appendFileSync, existsSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 
 /** Walk up from `start` to the project's `.consort` dir (tests run from root OR client/, so cwd
  *  varies); fall back to `<cwd>/.consort` (created on write) if none is found. */
@@ -33,15 +33,133 @@ export function emitTestRun(id: string, status: TestRunStatus, absFile: string,
     mkdirSync(dir, { recursive: true });
     const root = dirname(dir);
     const file = (absFile || "").replace(`${root}/`, "");
+    const ts = new Date().toISOString();
     appendFileSync(
       join(dir, "test-run.jsonl"),
-      JSON.stringify({ ts: new Date().toISOString(), test_id: id, status, file, kind }) + "\n",
+      JSON.stringify({ ts, test_id: id, status, file, kind }) + "\n",
     );
+    // RECORD a durable per-test `test.result` into the agent-log AT RUN TIME (not a cycle-end batch),
+    // so the dashboard lights each bubble the moment its test runs (live), scrubbing lights each test
+    // AT the point it actually ran (the event sits at its real position in the stream), and a REPLAY of
+    // the recording does the same — the per-test trail is part of the durable record, not a live-only
+    // overlay. Attributed to its story via the on-disk test-lists (the agent-log fold keys by
+    // feature|story|test). Best-effort: a reporter write must never fail the suite.
+    recordTestResultEvent(dir, id, status, file, ts);
   } catch {
     /* best-effort: a per-test reporter write must never fail the suite */
   }
 }
 
+/** Owner of a test id, resolved from the project's per-story test-lists (the attribution the reporter
+ *  lacks — it only sees id + file). Cached per process (a reporter process is one suite run). */
+interface TestOwner { feature_id: string; story_id: string; ac_id: string; scenario_file?: string }
+const ownerIndexCache = new Map<string, Map<string, TestOwner[]>>();
+
+function buildOwnerIndex(consortDir: string): Map<string, TestOwner[]> {
+  const cached = ownerIndexCache.get(consortDir);
+  if (cached) return cached;
+  const index = new Map<string, TestOwner[]>();
+  try {
+    const featuresDir = join(consortDir, "features");
+    for (const f of readdirSync(featuresDir)) {
+      const storiesDir = join(featuresDir, f, "stories");
+      let stories: string[];
+      try { stories = readdirSync(storiesDir); } catch { continue; }
+      for (const s of stories) {
+        const listFile = join(storiesDir, s, "test-list-per-story.json");
+        if (!existsSync(listFile)) continue;
+        let list: { feature_id?: string; story_id?: string; items?: unknown[] };
+        try { list = JSON.parse(readFileSync(listFile, "utf8")); } catch { continue; }
+        const featureId = typeof list.feature_id === "string" ? list.feature_id : f;
+        const storyId = typeof list.story_id === "string" ? list.story_id : s;
+        for (const raw of list.items ?? []) {
+          const it = raw as { id?: unknown; ac_id?: unknown; scenario_file?: unknown };
+          if (typeof it.id !== "string") continue;
+          const owners = index.get(it.id) ?? [];
+          owners.push({
+            feature_id: featureId,
+            story_id: storyId,
+            ac_id: typeof it.ac_id === "string" ? it.ac_id : "unknown",
+            ...(typeof it.scenario_file === "string" ? { scenario_file: it.scenario_file } : {}),
+          });
+          index.set(it.id, owners);
+        }
+      }
+    }
+  } catch {
+    /* no test-lists (pre-design project) — leave the index empty; the kit's cycle-scoped emit covers it */
+  }
+  ownerIndexCache.set(consortDir, index);
+  return index;
+}
+
+/** The feature currently on the build lane, from `.consort/next.json` — the disambiguator of last
+ *  resort when a reused T-id's file does not pin a single owner (e.g. a fitness/behavior test whose
+ *  test-list item carries no scenario_file). Null when unreadable. */
+function activeFeature(consortDir: string): string | null {
+  try {
+    const next = JSON.parse(readFileSync(join(consortDir, "next.json"), "utf8")) as { feature?: unknown };
+    return typeof next.feature === "string" ? next.feature : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve a (test id, file) to its single owning story. One owner -> it. Several (a T-id reused across
+ *  features — ids are unique only WITHIN a story) -> (1) the owner whose scenario_file basename matches
+ *  the running file (a client/e2e spec pins ITSELF, so a sibling feature's same-id spec resolves to its
+ *  own story); then (2) the owner in the feature currently on the build lane (next.json) — a
+ *  fitness/behavior test carries no scenario_file, so during THIS feature's build its reused id belongs
+ *  to the active feature's story, while another feature's same-id test already resolved via (1). Else
+ *  null (skip, never mis-attribute). */
+function resolveOwner(consortDir: string, id: string, file: string): TestOwner | null {
+  const base = /^(T\d+)/.exec(id)?.[1] ?? id;
+  const index = buildOwnerIndex(consortDir);
+  const owners = index.get(id) ?? index.get(base) ?? [];
+  if (owners.length === 0) return null;
+  if (owners.length === 1) return owners[0];
+  // (1) The owner whose scenario_file matches the running file (unique match).
+  const fileBase = basename(file || "");
+  if (fileBase) {
+    const byFile = owners.filter((o) => o.scenario_file && basename(o.scenario_file) === fileBase);
+    if (byFile.length === 1) return byFile[0];
+  }
+  // (2) Fall back to the owner in the currently-building feature (one match only).
+  const active = activeFeature(consortDir);
+  if (active) {
+    const byFeature = owners.filter((o) => o.feature_id === active);
+    if (byFeature.length === 1) return byFeature[0];
+  }
+  return null;
+}
+
+/** Append a durable, schema-valid `test.result` to the agent-log (+ the corpus mirror when a recording
+ *  is in flight), shaped exactly like the kit's emitAgentLogEvent output so the dashboard fold reads it
+ *  identically. Only emitted for an attributable test; best-effort. */
+export function recordTestResultEvent(consortDir: string, id: string, status: TestRunStatus, file: string, ts: string): void {
+  try {
+    const owner = resolveOwner(consortDir, id, file);
+    if (!owner) return; // cannot attribute (ambiguous reused id) — skip rather than mis-key a bubble
+    const line =
+      JSON.stringify({
+        timestamp: ts,
+        level: "info",
+        role: "driver",
+        event: "test.result",
+        message: `TEST ${id} ${status}`,
+        metadata: { feature_id: owner.feature_id, test_id: id, status, story_id: owner.story_id, ac_id: owner.ac_id },
+      }) + "\n";
+    appendFileSync(join(consortDir, "agent-log.jsonl"), line);
+    // Mirror into the corpus so a RECORDED run replays the per-test trail (same env the kit uses).
+    const recordDir = process.env.LAKEBASE_CONSORT_RECORD_DIR?.trim();
+    if (recordDir) {
+      try { mkdirSync(recordDir, { recursive: true }); appendFileSync(join(recordDir, "agent-log.jsonl"), line); } catch { /* mirror is best-effort */ }
+    }
+  } catch {
+    /* best-effort: recording a per-test result must never fail the suite */
+  }
+}
+
 /** Append a per-test TABLE snapshot (one line per table) to `.consort/table-snapshots.jsonl`, keyed
  *  by test id — parallel to `emitTestRun`. Best-effort. */
 export function emitTableSnapshot(id: string, absFile: string, table: string, rows: unknown[], rowCount: number | null): void {