@kuralle-syrinx/cli 4.4.0

package/src/fixture.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: MIT
+//
+// Fixture sidecar loading for `syrinx turn --in <fixture.json>`. Mirrors the
+// shape written by apps/studio/src/lib/fixture-export.ts ("Save as fixture") and
+// the check already proven in examples/02-hello-voice-headless/scripts/replay-fixture.ts:
+// honour the recorded capture config, refuse to replay when it cannot be
+// satisfied rather than silently changing the answer.
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { CliError, EXIT_CODES } from "./exit-codes.js";
+
+export const FIXTURE_FORMAT = "syrinx.fixture.v1";
+
+export interface FixtureSidecar {
+  readonly format: string;
+  readonly turnId?: string;
+  readonly expectedTranscript?: string;
+  readonly agentText?: string;
+  readonly audioFile: string;
+  readonly audio: { readonly sampleRateHz: number; readonly channels: number; readonly encoding: string };
+  readonly capture?: { readonly inputSampleRateHz?: number };
+}
+
+export interface LoadedFixture {
+  readonly sidecarPath: string;
+  readonly sidecar: FixtureSidecar;
+  /** The paired WAV file this fixture replays — prefers the sibling "captured.wav" the Studio actually wrote. */
+  readonly wavPath: string;
+}
+
+/**
+ * Parse and validate a fixture sidecar JSON file, refusing (CliError, USAGE) on
+ * anything this CLI cannot honestly replay: an unrecognised format, or capture
+ * conditions (sample rate / channel count) that would silently change the
+ * transcript if replayed as-is.
+ */
+export function loadFixture(sidecarPath: string): LoadedFixture {
+  let raw: string;
+  try {
+    raw = readFileSync(sidecarPath, "utf8");
+  } catch (err) {
+    throw new CliError(EXIT_CODES.USAGE, `fixture not found: ${sidecarPath}`, { cause: String(err) });
+  }
+
+  let sidecar: FixtureSidecar;
+  try {
+    sidecar = JSON.parse(raw) as FixtureSidecar;
+  } catch (err) {
+    throw new CliError(EXIT_CODES.USAGE, `fixture is not valid JSON: ${sidecarPath}`, { cause: String(err) });
+  }
+
+  if (sidecar.format !== FIXTURE_FORMAT) {
+    throw new CliError(EXIT_CODES.USAGE, `unsupported fixture format "${sidecar.format}" (expected "${FIXTURE_FORMAT}")`);
+  }
+  // The sidecar exists so replay conditions can be checked rather than assumed —
+  // replaying 24 kHz audio against a 16 kHz-mono expectation changes the transcript.
+  if (sidecar.audio.sampleRateHz !== 16000 || sidecar.audio.channels !== 1) {
+    throw new CliError(
+      EXIT_CODES.USAGE,
+      `this replay path needs mono 16 kHz audio; fixture is ${String(sidecar.audio.channels)}ch @ ${String(sidecar.audio.sampleRateHz)} Hz`,
+    );
+  }
+
+  const dir = dirname(sidecarPath);
+  const sibling = join(dir, "captured.wav");
+  let wavPath: string;
+  try {
+    readFileSync(sibling);
+    wavPath = sibling;
+  } catch {
+    wavPath = join(dir, sidecar.audioFile);
+  }
+
+  return { sidecarPath, sidecar, wavPath };
+}
+
+/** Compare on words, not punctuation — STT capitalises and punctuates inconsistently. */
+export function normalizeTranscript(text: string): string {
+  return text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").replace(/\s+/g, " ").trim();
+}
+
+export interface TranscriptAssertion {
+  readonly expectedTranscript: string;
+  readonly actualTranscript: string;
+  readonly match: boolean;
+}
+
+export function assertTranscript(expectedTranscript: string, actualTranscript: string): TranscriptAssertion {
+  return {
+    expectedTranscript,
+    actualTranscript,
+    match: normalizeTranscript(expectedTranscript) === normalizeTranscript(actualTranscript),
+  };
+}

package/src/help.ts

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: MIT
+
+import { EXIT_CODE_TABLE } from "./exit-codes.js";
+
+const EXIT_CODE_LINES = EXIT_CODE_TABLE.map((row) => `  ${String(row.code)}  ${row.name.padEnd(9)} ${row.meaning}`).join("\n");
+
+export const HELP_TEXT = `syrinx — the agent-facing CLI for a Syrinx voice agent.
+
+Not a console: no REPL, no chat loop, no microphone. Every command is a single
+deterministic invocation with a documented exit code, meant to be run by a
+coding agent (or a script), not a human at a prompt.
+
+This CLI brings no providers of its own — no Deepgram, no Cartesia, no OpenAI.
+--agent points it at YOUR agent module; that module owns its own providers.
+
+USAGE
+  syrinx <command> [options]
+
+AGENT RESOLUTION (--agent, required for turn and text)
+  --agent <module>[#namedExport]
+      <module> is a path (resolved relative to cwd unless absolute) to your
+      own code; the export must be a zero-arg factory returning a
+      VoiceAgentSession (or a Promise of one) — exactly the contract
+      examples/02-hello-voice-headless/scripts/dev-server.ts's --agent flag
+      uses. Omit #export for a default export (or a "createSession" export).
+      Resolution failures (module not found, no such export, export not
+      callable) exit USAGE and name the callable exports that were found.
+      If the export IS callable but throws when invoked, that exits CONFIG —
+      most plausibly the agent's own module is missing something it needs
+      (an env var, a key file, ...).
+
+COMMANDS
+  turn --in <fixture.wav|fixture.json> --agent <module>#<export> [options]
+      Run one turn through the resolved agent and report the transcript, the
+      reply, and per-stage timings. Given a fixture.json sidecar (produced by
+      the Studio's "Save as fixture"), honours its recorded capture config
+      and, when the sidecar carries an expected transcript, asserts the
+      replay matches it.
+    --in <path>              required. fixture.wav or fixture.json
+    --agent <module>#<export>  required.
+    --session-dir <dir>       where turn artifacts are written (default: a temp dir)
+    --json                    emit one parseable JSON object on stdout
+
+  text "<message>" --agent <module>#<export> [options]
+      Send a typed turn (no STT, no microphone) to the resolved agent and
+      report the reply.
+    --agent <module>#<export>  required.
+    --json                    emit one parseable JSON object on stdout
+
+  doctor [--agent <module>#<export>] [--json]
+      Report what is configured: the Node runtime, whether
+      @kuralle-syrinx/core is installed and its version, and — informational
+      only — which well-known provider keys are present in the environment
+      (never their values). This CLI does not require any specific provider
+      key; pass --agent to check whether a SPECIFIC agent module resolves.
+      Always exits 0 — this command diagnoses, it does not assert.
+
+  --help, -h                show this help
+  --version, -v              print the CLI version
+
+OUTPUT
+  --json is a first-class output mode: every command supports it and emits a
+  single parseable JSON object on stdout. Diagnostics (warnings, e.g. a
+  version-skew notice) always go to stderr, never stdout, so --json output
+  stays parseable. Without --json, commands print a short human-readable
+  summary to stdout and errors to stderr.
+
+EXIT CODES
+${EXIT_CODE_LINES}
+`;

package/src/index.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+//
+// Bin entry point. The shebang is injected by the esbuild banner at build time
+// (see scripts/build.mjs) so the raw TypeScript source stays a plain module.
+
+import { main } from "./cli.js";
+import { CliError, EXIT_CODES } from "./exit-codes.js";
+
+/**
+ * Report a failure the way the contract promises: one line on stderr, the
+ * documented code on exit. Never a stack trace — stdout may already hold a
+ * `--json` object, and a stack after it corrupts what a caller parses.
+ * A stack is only useful for an unexpected internal fault, which is what
+ * INTERNAL means.
+ */
+function fail(err: unknown): number {
+  if (err instanceof CliError) {
+    console.error(err.message);
+    return err.exitCode;
+  }
+  console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+  return EXIT_CODES.INTERNAL;
+}
+
+// A rejection that escapes the command — e.g. a listener that settles after the
+// command already returned — must not print a stack over a written JSON object.
+process.on("unhandledRejection", (reason) => {
+  process.exitCode = fail(reason);
+});
+
+main(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((err: unknown) => {
+    process.exitCode = fail(err);
+  });

package/src/text-command.test.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { CliError, EXIT_CODES } from "./exit-codes.js";
+import { runTextCommand } from "./text-command.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FIXTURES = join(HERE, "__fixtures__");
+
+describe("runTextCommand", () => {
+  it("resolves --agent and drives a real turn end to end, with no live provider", async () => {
+    const result = await runTextCommand({ message: "hi", agentSpec: `${join(FIXTURES, "good-text-agent.mjs")}#createSession` });
+    expect(result.reply).toBe("Hello from the fake agent.");
+    expect(result.agent).toContain("createSession");
+  });
+
+  it("refuses an unresolvable --agent as USAGE", async () => {
+    const err = await runTextCommand({ message: "hi", agentSpec: join(FIXTURES, "does-not-exist.mjs") }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(CliError);
+    expect((err as CliError).exitCode).toBe(EXIT_CODES.USAGE);
+  });
+
+  it("reports CONFIG when the agent module throws constructing a session", async () => {
+    const err = await runTextCommand({ message: "hi", agentSpec: join(FIXTURES, "throwing-agent.mjs") }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(CliError);
+    expect((err as CliError).exitCode).toBe(EXIT_CODES.CONFIG);
+  });
+});

package/src/text-command.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+//
+// `syrinx text "<message>" --agent <module>#<export>` — resolves the caller's
+// own agent and drives one typed turn through it. The CLI brings no reasoner.
+
+import { resolveAgentFactory } from "./agent-resolve.js";
+import { CliError, EXIT_CODES } from "./exit-codes.js";
+import { driveText, type TextTurnResult } from "./text-turn.js";
+
+export interface RunTextCommandOptions {
+  readonly message: string;
+  readonly agentSpec: string;
+  readonly cwd?: string;
+}
+
+export interface TextCommandResult extends TextTurnResult {
+  readonly agent: string;
+}
+
+export async function runTextCommand(opts: RunTextCommandOptions): Promise<TextCommandResult> {
+  const resolvedAgent = await resolveAgentFactory(opts.agentSpec, opts.cwd ?? process.cwd());
+
+  let result: TextTurnResult;
+  try {
+    result = await driveText({ session: resolvedAgent.factory, message: opts.message });
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    throw new CliError(EXIT_CODES.BACKEND, `text turn failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  return { ...result, agent: resolvedAgent.label };
+}

package/src/text-turn.test.ts

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: MIT
+
+import { VoiceAgentSession } from "@kuralle-syrinx/core";
+import { FakeBridge, type FakeBridgeConfig } from "@kuralle-syrinx/test";
+import { describe, expect, it } from "vitest";
+
+import { CliError, EXIT_CODES } from "./exit-codes.js";
+import { driveText } from "./text-turn.js";
+
+function buildBridgeOnlySession(scriptedEvents: FakeBridgeConfig["scriptedEvents"]): VoiceAgentSession {
+  const session = new VoiceAgentSession({ plugins: { bridge: { scriptedEvents } } });
+  session.registerPlugin("bridge", new FakeBridge());
+  return session;
+}
+
+describe("driveText", () => {
+  it("returns the concatenated reply and a ttft from the first delta (no live provider)", async () => {
+    const session = buildBridgeOnlySession([{ kind: "text", delta: "It is " }, { kind: "text", delta: "seventy degrees." }, { kind: "done" }]);
+    const result = await driveText({ session, message: "what's the weather?" });
+    expect(result.reply).toBe("It is seventy degrees.");
+    expect(result.toolCalls).toBe(0);
+    expect(result.totalMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it("counts tool-call parts", async () => {
+    const session = buildBridgeOnlySession([
+      { kind: "tool_call", id: "1", name: "lookup", args: {} },
+      { kind: "text", delta: "done" },
+      { kind: "done" },
+    ]);
+    const result = await driveText({ session, message: "hi" });
+    expect(result.toolCalls).toBe(1);
+    expect(result.reply).toBe("done");
+  });
+
+  it("accepts a zero-arg session factory (the --agent contract)", async () => {
+    const factory = (): VoiceAgentSession => buildBridgeOnlySession([{ kind: "text", delta: "ok" }, { kind: "done" }]);
+    const result = await driveText({ session: factory, message: "hi" });
+    expect(result.reply).toBe("ok");
+  });
+
+  it("times out as a BACKEND CliError if the agent never finishes", async () => {
+    // No "done" event scripted, and no text either — agent_finished never fires.
+    const session = buildBridgeOnlySession([]);
+    const err = await driveText({ session, message: "hi", timeoutMs: 50 }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(CliError);
+    expect((err as CliError).exitCode).toBe(EXIT_CODES.BACKEND);
+  });
+});

package/src/text-turn.ts

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: MIT
+//
+// `syrinx text "<message>"` — a typed turn against an already-built
+// VoiceAgentSession (the same `--agent`-supplied session `driveTurn` runs
+// audio through). Pushes the real shipped path — `user.text_received` — the
+// same packet examples/02-hello-voice-headless/scripts/run-realtime-gemini-sendtext-smoke.ts
+// drives, so a typed turn exercises exactly the pipeline a spoken one would,
+// minus STT. This module never constructs a reasoner/provider itself; the
+// session (and everything it can do) is entirely the caller's.
+
+import { randomUUID } from "node:crypto";
+
+import { Route, type VoiceAgentSession, type VoiceAgentSessionEvents } from "@kuralle-syrinx/core";
+
+import { CliError, EXIT_CODES } from "./exit-codes.js";
+import type { SessionFactory } from "./turn-runner.js";
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+export interface DriveTextOptions {
+  /** An already-registered VoiceAgentSession, or a factory producing one. Built by the caller — this module never constructs a reasoner. */
+  readonly session: VoiceAgentSession | SessionFactory;
+  readonly message: string;
+  readonly timeoutMs?: number;
+}
+
+export interface TextTurnResult {
+  readonly reply: string;
+  readonly ttftMs: number;
+  readonly totalMs: number;
+  readonly toolCalls: number;
+}
+
+async function resolveSession(session: VoiceAgentSession | SessionFactory): Promise<VoiceAgentSession> {
+  return typeof session === "function" ? session() : session;
+}
+
+/** Send one typed turn to an already-built session and report the reply. */
+export async function driveText(opts: DriveTextOptions): Promise<TextTurnResult> {
+  const session = await resolveSession(opts.session);
+  const contextId = randomUUID();
+
+  const t0 = performance.now();
+  let ttftMs = -1;
+  let reply = "";
+  let toolCalls = 0;
+
+  const on = <K extends keyof VoiceAgentSessionEvents>(event: K, handler: VoiceAgentSessionEvents[K]): void => {
+    session.on(event, handler);
+  };
+
+  const finished = new Promise<void>((resolveFinished, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new CliError(EXIT_CODES.BACKEND, `agent did not finish within ${String(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS)}ms`));
+    }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+
+    on("agent_text_delta", (event) => {
+      if (event.turnId !== contextId) return;
+      if (ttftMs < 0) ttftMs = performance.now() - t0;
+      reply += event.delta;
+    });
+    on("agent_tool_call", (event) => {
+      if (event.turnId !== contextId) return;
+      toolCalls += 1;
+    });
+    on("agent_finished", (event) => {
+      if (event.turnId !== contextId) return;
+      clearTimeout(timeout);
+      resolveFinished();
+    });
+    on("error", (event) => {
+      clearTimeout(timeout);
+      reject(new CliError(EXIT_CODES.BACKEND, `agent failed: ${event.message} (${event.stage}/${event.category})`));
+    });
+  });
+
+  // `session.start()` below can throw before `await finished` is ever reached — an
+  // init failure raises BOTH. In that case the `error` handler still rejects this
+  // promise, and with nothing awaiting it Node reports an unhandled rejection and
+  // prints a stack trace AFTER the command has already written its clean `--json`
+  // object. Attaching a no-op handler marks it handled; `await finished` below still
+  // observes the rejection, because `.catch()` returns a new promise and does not
+  // consume this one.
+  void finished.catch(() => {});
+
+  try {
+    await session.start();
+    session.bus.push(Route.Main, {
+      kind: "user.text_received",
+      contextId,
+      timestampMs: Date.now(),
+      text: opts.message,
+    });
+    await finished;
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    throw new CliError(EXIT_CODES.BACKEND, `agent failed: ${err instanceof Error ? err.message : String(err)}`);
+  } finally {
+    await session.close().catch(() => {});
+  }
+
+  return {
+    reply,
+    ttftMs: ttftMs < 0 ? 0 : Math.round(ttftMs),
+    totalMs: Math.round(performance.now() - t0),
+    toolCalls,
+  };
+}

package/src/turn-command.test.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: MIT
+
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { CliError, EXIT_CODES } from "./exit-codes.js";
+import { runTurnCommand } from "./turn-command.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FIXTURES = join(HERE, "__fixtures__");
+const UNUSED_AGENT_SPEC = "unresolved-if-reached#nope"; // fixture validation must reject before this is ever imported
+
+let root: string;
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), "syrinx-cli-turn-cmd-"));
+});
+afterEach(async () => {
+  await rm(root, { recursive: true, maxRetries: 3, force: true }).catch(() => {});
+});
+
+describe("runTurnCommand — fixture validation runs before agent resolution", () => {
+  it("refuses an unsupported fixture format as USAGE, without ever resolving --agent", async () => {
+    const p = join(root, "bad-format.json");
+    await writeFile(
+      p,
+      JSON.stringify({ format: "not.the.right.format", audioFile: "captured.wav", audio: { sampleRateHz: 16000, channels: 1, encoding: "pcm_s16le" } }),
+    );
+    const err = await runTurnCommand({ inputPath: p, agentSpec: UNUSED_AGENT_SPEC }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(CliError);
+    expect((err as CliError).exitCode).toBe(EXIT_CODES.USAGE);
+    expect((err as CliError).message).toContain("unsupported fixture format"); // proves the FIXTURE check fired, not agent resolution
+  });
+
+  it("refuses a capture-config mismatch as USAGE", async () => {
+    const p = join(root, "bad-rate.json");
+    await writeFile(
+      p,
+      JSON.stringify({
+        format: "syrinx.fixture.v1",
+        audioFile: "captured.wav",
+        audio: { sampleRateHz: 24000, channels: 1, encoding: "pcm_s16le" },
+        expectedTranscript: "hello there",
+      }),
+    );
+    const err = await runTurnCommand({ inputPath: p, agentSpec: UNUSED_AGENT_SPEC }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(CliError);
+    expect((err as CliError).exitCode).toBe(EXIT_CODES.USAGE);
+    expect((err as CliError).message).toContain("mono 16 kHz");
+  });
+
+  it("refuses a missing fixture file as USAGE", async () => {
+    const err = await runTurnCommand({ inputPath: join(root, "does-not-exist.json"), agentSpec: UNUSED_AGENT_SPEC }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(CliError);
+    expect((err as CliError).exitCode).toBe(EXIT_CODES.USAGE);
+    expect((err as CliError).message).toContain("fixture not found");
+  });
+});
+
+describe("runTurnCommand — --agent resolution", () => {
+  it("refuses an unresolvable --agent module as USAGE once the fixture itself is fine", async () => {
+    const wavPath = join(root, "input.wav");
+    await writeFile(wavPath, Buffer.from([]));
+    const err = await runTurnCommand({ inputPath: wavPath, agentSpec: join(FIXTURES, "does-not-exist.mjs") }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(CliError);
+    expect((err as CliError).exitCode).toBe(EXIT_CODES.USAGE);
+  });
+
+  it("reports CONFIG when the --agent module resolves but throws constructing a session", async () => {
+    const wavPath = join(root, "input.wav");
+    await writeFile(wavPath, Buffer.from([]));
+    const err = await runTurnCommand({ inputPath: wavPath, agentSpec: join(FIXTURES, "throwing-agent.mjs") }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(CliError);
+    expect((err as CliError).exitCode).toBe(EXIT_CODES.CONFIG);
+    expect((err as CliError).message).toContain("FAKE_AGENT_API_KEY");
+  });
+});

package/src/turn-command.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: MIT
+//
+// `syrinx turn --in <fixture.wav|fixture.json> --agent <module>#<export>` —
+// resolves the caller's own agent (the CLI brings no providers) and drives it
+// through the shared, provider-agnostic turn driver, mirroring
+// examples/02-hello-voice-headless/scripts/replay-fixture.ts's fixture-replay
+// contract but as a first-class CLI verb with --json output and typed exit
+// codes instead of a throwaway script's console.log/process.exit.
+
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { extname, join, resolve } from "node:path";
+
+import { resolveAgentFactory } from "./agent-resolve.js";
+import { CliError, EXIT_CODES } from "./exit-codes.js";
+import { assertTranscript, loadFixture, type TranscriptAssertion } from "./fixture.js";
+import { driveTurn, type PerTurnMetrics } from "./turn-runner.js";
+
+export interface RunTurnCommandOptions {
+  readonly inputPath: string;
+  readonly agentSpec: string;
+  readonly sessionDir?: string;
+  readonly cwd?: string;
+}
+
+export interface TurnCommandResult {
+  readonly input: string;
+  readonly agent: string;
+  readonly sessionDir: string;
+  readonly transcript: string;
+  readonly reply: string;
+  readonly timings: PerTurnMetrics;
+  readonly durationMs: number;
+  readonly assertion: TranscriptAssertion | null;
+}
+
+export async function runTurnCommand(opts: RunTurnCommandOptions): Promise<TurnCommandResult> {
+  // Validate the input itself before resolving the agent: a malformed/unreplayable
+  // fixture is a usage problem an agent should see regardless of whether the
+  // --agent module even resolves.
+  const inputPath = resolve(opts.inputPath);
+  const isFixtureSidecar = extname(inputPath).toLowerCase() === ".json";
+  const fixture = isFixtureSidecar ? loadFixture(inputPath) : undefined;
+  const wavPath = fixture ? fixture.wavPath : inputPath;
+
+  const resolvedAgent = await resolveAgentFactory(opts.agentSpec, opts.cwd ?? process.cwd());
+  const sessionDir = opts.sessionDir ?? mkdtempSync(join(tmpdir(), "syrinx-turn-"));
+
+  let result;
+  try {
+    result = await driveTurn({
+      session: resolvedAgent.factory,
+      inputWavPath: wavPath,
+      sessionDir,
+    });
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    throw new CliError(EXIT_CODES.BACKEND, `turn failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  let assertion: TranscriptAssertion | null = null;
+  if (fixture?.sidecar.expectedTranscript !== undefined) {
+    assertion = assertTranscript(fixture.sidecar.expectedTranscript, result.finalTranscript);
+    if (!assertion.match) {
+      throw new CliError(EXIT_CODES.ASSERTION, "replayed fixture's transcript drifted from the expected transcript", {
+        assertion,
+      });
+    }
+  }
+
+  return {
+    input: inputPath,
+    agent: resolvedAgent.label,
+    sessionDir: result.sessionDir,
+    transcript: result.finalTranscript,
+    reply: result.agentReply,
+    timings: result.metrics,
+    durationMs: result.durationMs,
+    assertion,
+  };
+}